아그거뭐였지?

mongoDB - Time-Series Collection 와 Aggregation Pipeline

wave35 — Wed, 30 Jul 2025 22:54:28 +0900

[ Time-Series Collection ]

1. 개요

MongoDB 5.0부터 도입된 시계열 전용 컬렉션 타입입니다.
“같은 시계열(센서·채널 등)에 속하는 여러 측정값을

‘버킷(bucket)’이라는 큰 문서에 압축·열 지향 포맷으로 묶어서 보관해

쓰기·저장·조회 효율을 극대화한 컬렉션” 입니다.

필수 필드

timeField : 시간 값(ISODate)
metaField : 동일 시계열을 구분하는 태그(ID·채널·센서 등, 선택)

추가 옵션

granularity : 데이터 입력 주기 힌트("seconds", "minutes", "hours")
TTL·샤딩도 그대로 사용 가능

2. 간단한 구조 살펴보기

예시 시나리오 : YouTube 라이브 채널에서 1초마다 “동시시청자(viewers)” 수치를 수집

1) 컬렉션 생성

db.createCollection("channelViewers", {
  timeseries: {
    timeField : "ts",          // 1초 주기의 타임스탬프
    metaField : "channelId",   // 채널 ID별로 시계열 구분
    granularity: "seconds"
  },
  expireAfterSeconds: 60*60*24*30   // 30일 보존(선택)
})

2) 데이터 삽입

db.channelViewers.insertMany([
  { channelId: "LIVE_abc", ts: ISODate("2024-07-30T10:15:04Z"), viewers: 731 },
  { channelId: "LIVE_abc", ts: ISODate("2024-07-30T10:15:05Z"), viewers: 742 },
  { channelId: "LIVE_xyz", ts: ISODate("2024-07-30T10:15:05Z"), viewers: 189 }
])

동일 channelId(metaField)에 해당하는 레코드들은 내부적으로 같은 버킷에 차곡차곡 기록됩니다.
_id 인덱스를 만들지 않으므로 쓰기 오버헤드가 작습니다.

3) 기본 조회 (특정 채널 1분치 찾기)

db.channelViewers.find({
  channelId: "LIVE_abc",
  ts: { $gte: ISODate("2024-07-30T10:15:00Z"),
        $lt : ISODate("2024-07-30T10:16:00Z") }
})

MongoDB는 버킷 메타데이터를 먼저 찾아 필요한 버킷만 스캔합니다.

3. 집계( Aggregation Pipeline ) 예제

[목표] 유튜브 채널별 1분 평균 시청자수를 구해보자.

db.channelViewers.aggregate([
  // ① 5분 범위로 한정(옵션)
  { $match: {
      ts: { $gte: ISODate("2024-07-30T10:15:00Z"),
            $lt : ISODate("2024-07-30T10:20:00Z") }
  }},

  // ② 1분 단위로 버킷 키 만들기
  { $group: {
      _id: {
        channelId: "$channelId",
        minute: { $dateTrunc: { date: "$ts", unit: "minute" } }
      },
      avgViewers: { $avg: "$viewers" }
  }},

  { $sort: { "_id.channelId": 1, "_id.minute": 1 } }
])

특징

버킷(열 지향) 저장 덕분에 $match 와 $group 단계에서 버킷 단위 블록 프로세싱이 적용되어 CPU·디스크 I/O가 매우 적음.
channelId 로 샤딩하면 채널별 스케일-아웃도 간단.

4. TTL·아카이빙: 오래된 데이터 자동 삭제

앞서 설정한 expireAfterSeconds 옵션 = TTL 인덱스 역할

→ 30일이 지난 버킷은 백그라운드에서 자동 삭제되어 스토리지를 깔끔하게 유지.

5. Materialized View(요약 컬렉션)로 선집계

자주 쓰는 1분 요약을 미리 저장하면 실시간 대시보드가 훨씬 빨라집니다.

db.channelViewers.aggregate([
  { $match: { ts: { $gte: /*당일 1분 전*/ } } },
  { $group: {
      _id: {
        channelId: "$channelId",
        minute: { $dateTrunc: { date: "$ts", unit: "minute" } }
      },
      avgViewers: { $avg: "$viewers" }
  }},
  { $merge: {
      into: "channelViewers_1min",
      on:   ["_id.channelId", "_id.minute"],
      whenMatched: "replace",
      whenNotMatched: "insert"
  }}
])

이 파이프라인을 1분마다 크론/Trigger로 실행 → channelViewers_1min 컬렉션에 upsert
대시보드는 요약 컬렉션만 조회하면 되므로 응답이 몇 ms 수준

6. 요약

1. createCollection() 시 timeseries 옵션만 지정하면 시계열 특화 저장 구조가 자동 적용

2. 동일 시계열(채널·센서 등) 데이터가 한 버킷-문서에 모여 쓰기·저장·조회가 모두 빨라짐

3. Aggregation Pipeline, 윈도 함수, $merge 를 이용해

초 → 분 → 시 단위 집계
누적합·랭킹·롤링 평균
Materialized View 생성

등을 별도 데이터베이스 없이 몽고 내부에서 처리

[ Aggregation Pipeline ]

MongoDB 서버 내부에서

“데이터를 흐름(Stream)처럼 흘려보내며, 여러 단계(stage)로 변환·필터·집계”

하도록 설계된 데이터 가공 엔진입니다.

SQL의 SELECT … GROUP BY … HAVING … 을 MongoDB 한곳에서 구현한다고 보면 됩니다.

1. 핵심 개념

파이프라인은 배열 형태로, 각 요소가 하나의 stage - [ { $stage1: {...} }, { $stage2: {...} }, … ]
앞 단계의 출력이 바로 다음 단계의 입력이 되어 스트림처럼 흐름을 이룹니다.
모든 stage는 서버 메모리에서 실행되므로 애플리케이션이 데이터를 꺼내서 따로 가공할 필요가 없습니다.

2. 대표 Stage와 용도

Stage | 설명 (SQL에 비유)

$match | WHERE 절 : 조건 필터, 인덱스 사용
$project | SELECT 절 : 필드 선택·변환
$group | GROUP BY : 키별 집계(sum, avg …)
$sort | ORDER BY
$unwind | 배열을 행으로 펼치기
$bucket/$bucketAuto | 구간 히스토그램
$lookup | JOIN (다른 컬렉션 결합)
$setWindowFields | 윈도 함수(누적합, 이동평균 등)
$merge | 결과를 컬렉션에 upsert ⇒ Materialized View 생성

3. 예제 시나리오

가상의 컬렉션 userActions

{
  channelId : "LIVE_abc",
  ts        : ISODate("2024-07-30T14:23:05Z"),
  userId    : "U_123",
  action    : "donate",          // like | subscribe | donate
  amount    : NumberDecimal("5")
}

목표:

1) 채널별·1시간 단위 기부 합계 / 건수

2) “기부액 누적합” 그래프용 데이터

3) 위 결과를 요약 컬렉션에 upsert

db.userActions.aggregate([

  /* ① 관심 기간·액션만 선별 ------------ */
  { $match: {
      action: "donate",                                   // 필터
      ts: { $gte: ISODate("2024-07-30T00:00:00Z") }       // 인덱스 사용
  }},

  /* ② 키 생성: 채널 + 1시간 ------------ */
  { $group: {                                             // GROUP BY
      _id: {
        channelId: "$channelId",
        hour: { $dateTrunc: { date: "$ts", unit: "hour" } }
      },
      totalDonation : { $sum: "$amount" },                // SUM(amount)
      donationCnt   : { $sum: 1 }                         // COUNT(*)
  }},

  /* ③ 정렬 ---------------------------- */
  { $sort: { "_id.channelId": 1, "_id.hour": 1 } },

  /* ④ 결과를 요약 컬렉션에 upsert ------ */
  { $merge: {
      into: "donationHourlySummary",                      // 대상 테이블
      on:   ["_id.channelId", "_id.hour"],                // PK
      whenMatched: "replace",
      whenNotMatched: "insert"
  }}

])

Kafka Connect - 7장 Rest API 활용하여 관리

wave35 — Mon, 30 Jun 2025 17:58:17 +0900

기본적으로 REST API는 8083 포트에서 사용할 수 있으며 보안되지 않습니다. ( 인증 기능 추가 가능 )

REST API는 모든 요청 본문이 콘텐츠 유형 application/json 을 사용할 것으로 예상하며

모든 응답도 해당 콘텐츠 유형을 사용하여 보냅니다.

커넥터 생성 및 삭제하기
커넥터 구성
커넥터의 수명 주기 제어
커넥터 오프셋 나열
문제 디버깅

커넥터 생성 및 삭제

클러스터의 버전을 확인

$ curl localhost:8083
{
  "version": "3.5.0",
  "commit": "c97b88d5db4de28d",
  "kafka_cluster_id": "PSCn87RpRoqhfjAs9KYtuw"
}

사용할 수 있는 커넥터 플러그인 확인

기본적으로 여기에는 Kafka Connect 클러스터에 설치된 소스 및 싱크 커넥터 플러그인만 나열됩니다.

$ curl localhost:8083/connector-plugins
[{
    "class": "org.apache.kafka.connect.mirror.MirrorCheckpointConnector",
    "type": "source",
    "version": "3.5.0"
}, {
    "class": "org.apache.kafka.connect.mirror.MirrorHeartbeatConnector",
    "type": "source",
    "version": "3.5.0"
}, {
    "class": "org.apache.kafka.connect.mirror.MirrorSourceConnector",
    "type": "source",
    "version": "3.5.0"
}]

실행 중인 커넥터 확인

$ curl localhost:8083/connectors
[]

커넥터 생성

# 예: PUT 요청:
$ curl -X PUT -H "Content-Type: application/json" \
  -d "@sink-config.json" \
  localhost:8083/connectors/file-sink/config 
{
  "name":"file-sink",
  "config":{
    "connector.class":"org.apache.kafka.connect.file.FileStreamSinkConnector",
    "tasks.max":"1",
    "topics":"topic-to-export",
    "file":"/tmp/sink.out",
    "value.converter":"org.apache.kafka.connect.storage.StringConverter",
    "name":"file-sink"
  },
  "tasks":[],"type":"sink"
}

sink-config.json 파일

{
  "connector.class":"org.apache.kafka.connect.file.FileStreamSinkConnector",
  "tasks.max": "1",
  "topics": "topic-to-export",
  "file": "/tmp/sink.out",
  "value.converter": "org.apache.kafka.connect.storage.StringConverter"
}

생성 확인

$ curl localhost:8083/connectors
["file-sink"]

쿼리 매개변수를 통해 자세히 확인

GET /connectors?expand=info 을 호출하면 구성 및 모든 작업 등이 나열
GET /connectors?expand=status 은 커넥터의 상태 및 관련 작업을 확인

$ curl "localhost:8083/connectors?expand=status&expand=info"
{
  "file-sink": {
    "status": {
      "name": "file-sink",
      "connector": {
        "state": "RUNNING",
        "worker_id": "192.168.1.110:8083"
      },
      "tasks": [
        {
          "id": 0,
          "state": "RUNNING",
          "worker_id": "192.168.1.110:8083"
        }
      ],
      "type": "sink"
    },
    "info": {
      "name": "file-sink",
      "config": {
        "connector.class": 
          "org.apache.kafka.connect.file.FileStreamSinkConnector",
        "file": "/tmp/sink.out",
        "tasks.max": "1",
        "topics": "topic-to-export",
        "name": "file-sink",
        "value.converter": "org.apache.kafka.connect.storage.StringConverter"
      },
      "tasks": [
        {
          "connector": "file-sink",
          "task": 0
        }
      ],
      "type": "sink"
    }
  }
}

특정 커넥터 상태 확인

GET /connectors/<CONNECTOR>/status

특정 커넥터 태스크 확인

GET /connectors/<CONNECTOR>/tasks

커넥터와 연동되는 토픽 확인

Kafka Connect 파이프라인의 관리자는 특정 커넥터가 어떤 토픽과 상호 작용했는지 파악하는 것이 유용할 수 있습니다.

이를 돕기 위해 Kafka Connect는 커넥터가 상호 작용한 모든 토픽을 검색할 수 있는 메커니즘을 제공합니다.

예를 들어, 방금 만든 file-sink 커넥터의 경우, 이 커넥터가 상호작용한 단일 토픽을 볼 수 있습니다.

$ curl localhost:8083/connectors/file-sink/topics
{
  "file-sink": {
    "topics": [
      "topic-to-export"
    ]
  }
}

커넥터와 토픽 연동 해제

Kafka Connect가 이전 상호 작용을 '잊어버리도록' 할 수 있습니다:

$ curl localhost:8083/connectors/file-sink/topics
{
  "file-sink": {
    "topics": [
      "topic-to-export"
    ]
  }
}

주제 목록을 다시 확인하면 이제 비어 있는 것을 볼 수 있습니다:

$ curl localhost:8083/connectors/file-sink/topics
{
  "file-sink": {
    "topics": []
  }
}

커넥터 삭제

커넥터가 삭제되면 그 아래의 모든 작업도 제거됩니다.

그러나 커넥터의 오프셋은 재설정되지 않으므로 같은 이름의 새 커넥터가 만들어지면 해당 오프셋을 사용하여 읽기를 시도하게 됩니다.

이를 방지하려면 커넥터를 삭제한 후에는 커넥터의 오프셋을 재설정하는 것이 가장 좋습니다.

$ curl -X DELETE localhost:8083/connectors/file-sink

커넥터 및 작업 구성

플러그인 설정 확인

REST API는 특정 플러그인의 구성 설정을 나열하고 검증하는 데 도움이 되는 옵션을 제공합니다.

예를 들어 다음과 같이 FileStreamSinkCon⁠nector 에 대한 구성 설정 목록을 얻을 수 있습니다:

$ curl localhost:8083/connector-plugins/org.apache.kafka.connect.file.FileStreamS
inkConnector/config
[
  {
    "name": "file", 1
    "type": "STRING", 2
    "required": false, 3
    "default_value": null, 4
    "importance": "HIGH", 5
    "documentation": "Destination filename. If not specified, the standard output 
 will be used", 6
    "group": null, 7
    "width": "NONE", 8
    "display_name": "file", 9
    "dependents": [], 10
    "order": -1 11
  }
]

1 - 이 구성 설정의 이름입니다.

2 - 구성 값의 예상 유형, BOOLEAN, STRING, INT, SHORT, LONG, DOUBLE, LIST, CLASS, PASSWORD 중 하나입니다.

3 - 이 구성 값이 필요한지 여부를 나타냅니다.

4 - 기본값, required 이 true 인 경우 기본값은 null 입니다.

5 - 구성 설정의 중요도 수준입니다. HIGH , MEDIUM, LOW 중 하나입니다.

6 - 구성 설정에 대한 정보입니다.

7 - 이 구성 설정이 어느 group 에 속하는지를 나타냅니다. 플러그인은 자체 설정에 대해 자체 그룹을 도입할 수 있습니다.
8 - 구성 설정의 width. NONE , SHORT, MEDIUM, LONG 중 하나.
9 - 구성 설정의 표시 이름(이름과 일치할 수 있음)입니다.
10 - 이 설정에 의존하는 다른 구성 설정 목록입니다.
11 - 구성 값의 정수 순서 번호(설정하지 않은 경우 -1 )입니다.

플러그인 설정 유효성 검사

사용할 구성을 결정한 후에는 PUT 요청을 보내 유효성을 검사할 수 있습니다.

구성에서 커넥터 이름이 누락된 경우 FileStreamSinkConnector 의 예를 살펴보겠습니다.

$ curl -X PUT -H "Content-Type: application/json" \
  -d '{"connector.class": "org.apache.kafka.connect.file.FileStreamSinkConnector"
, "tasks.max": "1", "topics": "sink-topic"}' \
  localhost:8083/connector-plugins/org.apache.kafka.connect.file.FileStreamSinkCo
nnector/config/validate 
{
  "name": "org.apache.kafka.connect.file.FileStreamSinkConnector", 1
  "error_count": 1, 2
  "groups": [  3
    "Common",
    "Transforms",
    "Predicates",
    "Error Handling"
  ],
  "configs": [
    {
      "definition": {  4
        "name": "name",
        "type": "STRING",
        "required": true,
        "default_value": null,
        "importance": "HIGH",
        "documentation": "Globally unique name to use...",
        "group": "Common",
        "width": "MEDIUM",
        "display_name": "Connector name",
        "dependents": [],
        "order": 1
      },
      "value": {
        "name": "name", 5
        "value": null,  6
        "recommended_values": [],  7
        "errors": [  8
          "Missing required configuration \"name\" which has no default value."
        ],
        "visible": true  9
      }
    },
 ...
  ]
}

1 - 플러그인을 제공하는 클래스의 이름입니다.

2 - 제공된 구성의 유효성을 검사하는 동안 발견된 오류의 수입니다.

3 - 구성 설정에 있는 그룹이 반환됩니다.

4 - 이 구성 설정의 정의입니다. 엔드포인트의 출력과 일치합니다. /connector-plugins/<CONNECTOR_PLUGIN>/config 엔드포인트의 출력과 일치합니다.

5 - 이 구성 설정의 이름입니다.

6 - 구성 설정에 제공된 값(제공되지 않은 경우 null )입니다.

7 - 제공된 다른 구성 값을 고려할 때 구성 설정에 유효한 값입니다.

8 - 오류가 없는 경우 빈 배열, 또는 이 값이 구성 설정에 허용되지 않는 이유에 대한 오류 메시지 배열입니다.

9 - 이 구성 값을 나열할지 여부를 나타냅니다.

커넥터의 수명 주기 제어

실패 커넥터 재실행

특정 커넥터에서 실패한 모든 작업을 다시 시작할 수 있습니다

$ curl -X POST "localhost:8083/connectors/file-source/restart?includeTasks=true&onlyFailed=true"

커넥터 일시중지(PAUSED) 와 중지(STOPPED)

실행 중인 커넥터를 일시 중지하거나 중지할 수도 있습니다.

이 기능은 커넥터의 데이터 흐름을 일시적으로 중지하고 나중에 중단한 지점부터 다시 시작하고 싶을 때 유용합니다.

외부 시스템에 과부하가 걸리는 경우, config 업데이트를 적용할 때 그 시간 동안 트래픽을 원하지 않는 경우 등에 사용할 수 있습니다.

PAUSED 와 STOPPED 의 차이점은

STOPPED 상태에서는 모든 작업이 종료되어 리소스를 사용하지 않는다는 것입니다.

즉, STOPPED 상태보다 PAUSED 상태에서 커넥터가 다시 시작되는 데 걸리는 시간이 더 짧습니다.

실행 중인 커넥터를 일시 중지

$ curl -X PUT localhost:8083/connectors/file-sink/pause

이제 상태 엔드포인트에 커넥터와 모든 작업이 PAUSED 상태로 표시됩니다.

$ curl localhost:8083/connectors/file-sink/status
{
  "name": "file-sink",
  "connector": {
    "state": "PAUSED",
    "worker_id": "192.168.1.110:8083"
  },
  "tasks": [
    {
      "id": 0,
      "state": "PAUSED",
      "worker_id": "192.168.1.110:8083"
    }
  ],
  "type": "sink"
}

커넥터를 다시 시작하려면 비슷한 명령을 사용하되 pause 대신 resume 를 사용합니다.

$ curl -X PUT localhost:8083/connectors/file-sink/resume

커넥터 및 작업의 상태가 RUNNING 상태로 돌아갑니다.

커넥터를 완전히 중지

$ curl -X PUT localhost:8083/connectors/file-sink/stop

이제 상태 엔드포인트에 커넥터가 STOPPED 상태로 표시됩니다.

$ curl localhost:8083/connectors/file-sink/status
{
  "name": "file-sink",
  "connector": {
    "state": "STOPPED",
    "worker_id": "192.168.1.110:8083"
  },
  "tasks": [],
  "type": "sink"
}

일단 중지되면 PUT /connectors/<CONNECTOR>/resume 엔드포인트를 사용하여 RUNNING 상태로 돌아갑니다.

커넥터 오프셋 나열

특정 커넥터에 대한 오프셋을 나열 ( 소스 커넥터 )

이 엔드포인트의 응답 형식은 소스 및 싱크 커넥터에 따라 다릅니다.

커밋된 오프셋이 없는 커넥터의 엔드포인트를 호출하면 빈 목록이 반환됩니다.

$ curl localhost:8083/connectors/file-sink/offsets
{
  "offsets": [
    {
      "partition": {
        "kafka_partition": 0,  1
        "kafka_topic": "topic-to-export"  2
      },
      "offset": {
        "kafka_offset": 3  3
      }
    }
  ]
}

1 - 이 예제에서는 커넥터에 단일 파티션인 0 이 있습니다.
2 - 커넥터가 topic-to-export 토픽의 레코드를 소비하고 있습니다.
3 - 커넥터가 오프셋까지 소모되었습니다 3.

특정 커넥터에 대한 오프셋을 나열 ( 싱크 커넥터 )

소스 커넥터의 출력은 약간 다르며 특정 커넥터에 따라 다릅니다.

예를 들어 FileStreamSource 커넥터를 실행하면 다음과 같은 내용이 표시될 수 있습니다.

$ curl localhost:8083/connectors/file-source/offsets
{
  "offsets": [
    {
      "partition": {
        "filename": "/tmp/source.txt"
      },
      "offset": {
        "position": 41
      }
    }
  ]
}

offsets, partition, offset 키는 모든 소스 커넥터에 공통이지만,

partition 및 offset JSON 객체 내부의 내용은 개별 커넥터에 의해 결정됩니다.

FileStreamSource 커넥터는 파티션을 {"filename": "/path/to/file"} 으로,

오프셋을 {"position": <BYTES>} 으로 저장하며, 여기서 <BYTES> 은 파일에서 읽은 바이트 수입니다.

문제 디버깅

Kafka Connect의 문제를 조사하고 디버깅할 때는 런타임 또는 커넥터의 로그를 사용하는 것이 중요합니다.

Kafka Connect는 관리자가 런타임에 logger 수준을 보고 업데이트할 수 있도록

/admin 아래에 몇 개의 엔드포인트를 노출합니다.

현재 logger 레벨 확인

$ curl localhost:8083/admin/loggers
{
  "org.apache.zookeeper": {
    "level": "ERROR"
  },
  "org.reflections": {
    "level": "ERROR"
  },
  "root": {
    "level": "INFO"
  }
}

logger 레벨 변경

가장 낮은 수준부터 가장 자세한 수준까지 유효한 로그 수준은 FATAL, ERROR, WARN, INFO, DEBUG, TRACE 입니다.

$ curl -X PUT -H "Content-Type: application/json" \
  -d '{"level": "DEBUG"}' \
  localhost:8083/admin/loggers/org.apache.kafka.connect.mirror
[
  "org.apache.kafka.connect.mirror",
  "org.apache.kafka.connect.mirror.MirrorCheckpointConnector",
  "org.apache.kafka.connect.mirror.MirrorSourceConnector"
]

logger를 다시 나열하면 방금 추가한 새 로거를 볼 수 있습니다.

$ curl localhost:8083/admin/loggers
{
  "org.apache.kafka.connect.mirror": {
    "level": "DEBUG"
  },
  "org.apache.kafka.connect.mirror.MirrorCheckpointConnector": {
    "level": "DEBUG"
  },
  "org.apache.kafka.connect.mirror.MirrorSourceConnector": {
    "level": "DEBUG"
  },
  "org.apache.zookeeper": {
    "level": "ERROR"
  },
  "org.reflections": {
    "level": "ERROR"
  },
  "root": {
    "level": "INFO"
  }
}

문제를 디버깅한 후에는 로그 수준을 INFO 로 다시 변경해야 합니다.

그렇지 않으면 로그가 이러한 메시지로 희석되어 다른 커넥터의 문제를 진단하기 어려울 수 있습니다.

가능하면 root 로그 레벨을 변경하지 말고 항상 보다 구체적인 로거를 구성하는 것이 좋습니다.

Kafka Connect - 4장 효과적인 데이터 파이프라인 설계

wave35 — Mon, 30 Jun 2025 16:04:02 +0900

데이터 변환

데이터 파이프라인을 통해 데이터가 흐를 때 두가지 패턴을 사용한다.

ETL: 저장 공간이 제한된 시스템
ELT: 오랫동안 데이터가 원본을 유지하여 다른 목적으로 재사용 용이

카프카 커넥트는 이동중에 데이터를 변환할 수 있는 트랜스포메이션이 있으며 이는 ETL에 적합하다.

아래는 민감한 개인정보를 숨김 처리하는 카프카커넥트 예시이다.

시스템간 데이터 맵핑

데이터파이프라인을 구축할 때 서로 시스템간의 데이터를 맵핑을 꼼꼼히 따져봐야하며

이를 위해 카프카커넥트 태스크와 카프카의 파티션 사이의 상호작용을 고려해야 한다.

단일 태스크와 단일 파티션은 순서를 보장한다.

중복을 방지하기 위해 각각의 데이터를 읽는 복수의 태스크

개별 소스 커넥터는 어느 파티션으로 보낼지 직접 선택하거나 이미 정의된 파티셔닝 전략을 따른다.

커넥터는 동일한 파티션으로 보내야하므로 키를 통해 식별한다.

소스 작업은 데이터를 하나 이상의 파티션으로 전송할 수 있다.

싱크 커넥터에서도 병렬로 실행된다.

싱크 작업이 파티션과 상호 작용하는 방식도 실행할 수 있는 싱크 작업의 수에 영향을 준다.

각 파티션은 특정 커넥터에 대해 하나의 싱크 작업에서만 읽을 수 있으므로,

싱크 커넥터로 데이터 파이프라인을 만들 때는 커넥터가 읽는 토픽의 파티션 수를 염두에 두어야 한다.

3개의 파티션에서 데이터를 읽는 두 개의 싱크 작업을 보여줍니다.

따라서 Kafka Connect 데이터 파이프라인을 설계할 때,

tasks.max 옵션 및 파티션 구성 옵션을 미리 설계하는 것이 좋다.

스키마

Kafka Connect 파이프라인은 스키마를 사용하여 Kafka에 저장된 데이터를 설명할 수 있다. ( 옵션 수정을 통해 )

{"schema":{"type":"string","optional":false},"payload":"This is a string"}
{"schema":{"type":"string","optional":false},"payload":"Another string"}
{"schema":{"type":"string","optional":false},"payload":"A third string"}
{"schema":{"type":"string","optional":false},"payload":"The final string"}

모든 레코드에 대해 스키마 정보를 전송하면 오버헤드가 커지므로, 스키마 레지스트리를 사용한다.

가장 일반적으로 사용되는 두 가지는 Confluent 스키마 레지스트리와 Apicurio 레지스트리이다.

내부 사용 토픽

분산 모드의 Kafka Connect는 토픽을 사용하여 상태를 저장한다.

커넥터를 시작할 때 토픽이 아직 없는 경우 자동으로 생성한다.

구성 : config.storage.topic
오프셋 : offset.storage.topic
상태 : status.storage.topic

config.storage.topic

사용자가 시작한 모든 커넥터 및 작업의 구성이 저장된다.

사용자가 커넥터의 구성을 업데이트하거나 커넥터가 재구성을 요청할 때마다 이 토픽에 레코드가 전송된다.

각 엔티티의 마지막 상태를 항상 유지하여 많은 저장 공간을 사용하지 않는다.

offset.storage.topic

소스 커넥터의 오프셋을 저장한다.

각 소스 커넥터 작업이 정기적으로 이 토픽을 사용하여 위치를 기록하기 때문에,

여러 개의 파티션으로 토픽이 구성된다.

status.storage.topic

커넥터 및 작업의 현재 상태를 에 저장한다.

REST API 사용자가 쿼리하는 데이터의 중심이 되는 곳이다.

이를 통해 사용자는 모든 워커를 쿼리하고 실행 중인 모든 플러그인의 상태를 확인할 수 있다.

또한 압축되어 있으며 여러 개의 파티션을 사용한다.

Kafka Connect

4장. 효과적인 데이터 파이프라인 설계 이 작품은 AI를 사용하여 번역되었습니다. 여러분의 피드백과 의견을 환영합니다: translation-feedback@oreilly.com 이 장에서는 Kafka Connect를 사용해 탄력적이고

www.oreilly.com

Elasticsearch 바이블 - 6장 클러스터 운영

wave35 — Sun, 25 May 2025 10:32:50 +0900

[ 클러스터 설정 API ]

클러스터 설정 조회

GET /_cluster/settings

클러스터 설정 업데이트

- persistent : 클러스터를 재시작해도 유지되는 영구 설정

- transient : 클러스터 재시작시 초기화되는 임시 설정

- 설정 적용 우선 순위는 transient > persistent > config/elasticsearch.yml

- persistent 설정은 모든 마스터 후보 노드의 path.data 경로 내 파일로 지정된다.

PUT /_cluster/settings
{
	"persistent": {
  	"설정_키": "설정_값"
 },
 	"transient": {
   	"설정_키": "설정_값"
 	}
}

[ _cat API를 통한 클러스터 관리와 모니터링 ]

GET _cat/health
클러스터의 전반적인 상태를 빠르게 조회한다. (green, yellow, red 구분)

GET _cat/indices
인덱스의 종류와 상태를 조회한다.
인덱스가 몇개의 샤드로 배치되었는지 복제본, 용량 등을 확인한다.

GET _cat/nodes
각 노드의 상태를 조회한다.
노드 역할, IP, heap 사용량 등을 확인한다.

GET _cat/shards
샤드의 상태를 조회한다.
샤드에 문서가 몇개 있는지, 크기와 배치된 노드 등을 파악한다.

GET _cat/stats
클러스터의 노드, 샤드, 인덱스에 대한 통계정보를 제공한다.

[ 인덱스 운영 전략 ]

템플릿과 명시적 매핑 활용

mapping이 자동으로 생성되는 것보단 최대한 명시적으로 mapping을 지정하는 것이 좋다.

라우팅 활용

라우팅 지정은 성능을 상승시킨다.

시계열 인덱스 이름

시계열 데이터를 색인한다면 인덱스 이름에도 시간 값을 넣는 것을 고려

예시) api-history-20250514

날짜를 기준으로 오래된 데이터를 백업하고 삭제하기 편하며

인덱스 생명 주기 등 관리적인 측면에서 편리하다.

alias

이미 존재하는 인덱스를 다른 이름으로도 가리키도록 하는 기능이다.

여러 인덱스를 하나의 이름으로 묶어 쿼리할 수 있다.

다만 여러 인덱스를 가리키는 alias는 단건 문서 조회 작업이 불가능하다.

alias 생성

POST _aliases
{
  "actions": [
    {
      "add": {
        "index": "logs-nginx-access-prod",
        "alias": "logs"
      },
      "add": {
        "index": "logs-nginx-access-prod-2",
        "alias": "logs"
      }
    }
  ]
}

와일드 카드 사용

POST _aliases
{
  "actions": [
    {
      "add": {
        "index": "logs-*",
        "alias": "all-logs"
      }
    }
  ]
}

ailas 삭제

POST _aliases
{
  "actions": [
    {
      "remove": {
        "index": "logs-nginx-access-prod",
        "alias": "logs"
      }
    }
  ]
}

롤오버

특정 조건이 충족되면 새로운 인덱스를 생성하고 쓰기 작업을 새 인덱스로 전환하는 기능이다.

단일 인덱스가 크기가 너무 커져 성능을 저하하는 것을 막고,

시계열 데이터 저장시 특정 기간의 데이터를 구분하여 저장할 수 있다.

롤오버 조건

max_age: 인덱스가 특정 시간 이상 됨 (예: "7d" - 7일)
max_docs: 인덱스에 포함된 문서 수가 특정 숫자를 초과함 (예: 1,000,000)
max_primary_shard_size: 프라이머리 샤드 크기가 특정 크기를 초과함 (예: "50gb")
max_primary_shard_docs: 프라이머리 샤드 당 문서 수가 특정 숫자를 초과함 (예: 2,000)

롤오버 방식

데이터 스트림 사용
인덱스 별칭 사용

롤오버 요청

logs-alias가 가리키는 인덱스가 7일 이상이거나, 100만개 이상이거나, primary shardzmrlrk 50gb를 초과할 때

새 인덱스(logs-000002)로 롤오버 실행

POST /logs-alias/_rollover/logs-000002
{
  "conditions": {
    "max_age": "7d",
    "max_docs": 1000000,
    "max_primary_shard_size": "50gb"
  }
}

Dry Run 테스트

롤오버를 실제로 적용하지 않고 테스트만 실행

POST /logs-alias/_rollover?dry_run
{
  "conditions": {
    "max_age": "7d"
  }
}

reindex

reindex는 원본 인덱스 내 문서의 _source를 읽어서 대상 인덱스에 새로 색인하는 작업이다.

기본 요청

POST _reindex
{
  "source": {
    "index": "my-index-000001"
  },
  "dest": {
    "index": "my-new-index-000001"
  }
}

여러 인덱스에서 재인덱싱

POST _reindex
{
  "source": {
    "index": ["my-index-000001", "my-index-000002"]
  },
  "dest": {
    "index": "my-new-index-000002"
  }
}

쿼리를 사용한 선택적 재인덱싱

POST _reindex
{
  "source": {
    "index": "my-index-000001",
    "query": {
      "term": {
        "user.id": "developer"
      }
    }
  },
  "dest": {
    "index": "my-new-index-000001"
  }
}

스냅샷과 복구

동작 중인 엘라스틱서치의 데이터 백업을 복구하는 데이터는 스냅샷을 사용한다.

스냅샷이 진행 중일 때는 샤드가 다른 노드로 이동하지 않는다.

스냅샷 저장소 등록

파일 시스템 저장소

- fs는 공유 파일 시스템을 저장소로 사용할 때 지정한다.

- location 경로는 사전에 elasticsearch.yml에 path.reop 설정으로 등록되어야 한다.

PUT _snapshot/my_backup
{
  "type": "fs",
  "settings": {
    "location": "/mount/backups",
    "compress": true
  }
}

Amazon S3 저장소

PUT _snapshot/s3_backup
{
  "type": "s3",
  "settings": {
    "bucket": "my-es-snapshots",
    "region": "ap-northeast-2",
    "client": "default"
  }
}

스냅샷 생성

전체 스냅샷

PUT _snapshot/my_backup/snapshot_1

특정 인덱스만 포함하는 스냅샷

PUT _snapshot/my_backup/snapshot_2
{
  "indices": "index_1,index_2*",
  "ignore_unavailable": true,
  "include_global_state": false
}

ignore_unavailable

true: 존재하는 인덱스만 처리하고 존재하지 않는 인덱스는 무시합니다.
false: (기본값) 지정한 인덱스가 하나라도 존재하지 않으면 오류를 발생시키고 전체 작업이 실패

include_global_state : 스냅샷에 클러스터 전역 상태를 포함할지 여부를 결정합니다. (기본 true)

스냅샷 상태 확인

GET _snapshot/my_backup/snapshot_1/_status

스냅샷 목록 조회

GET _snapshot/my_backup/_all

스냅샷에서 인덱스 복원

POST _snapshot/my_backup/snapshot_1/_restore

스냅샷 삭제

DELETE _snapshot/my_backup/snapshot_1

스냅샷 생명 주기 관리 (SLM)

자동화된 스냅샷 관리를 위해 스냅샷 생명 주기 관리(snapshot lifecycle management, SLM)를 사용합니다.

SLM 정책 생성

PUT _slm/policy/daily-snapshots
{
  "schedule": "0 30 1 * * ?", 
  "name": "<daily-snap-{now/d}>", 
  "repository": "my_backup", 
  "config": { 
    "indices": ["*"],
    "ignore_unavailable": true,
    "include_global_state": true
  },
  "retention": { 
    "expire_after": "30d", 
    "min_count": 5, 
    "max_count": 50 
  }
}

schedule : 스냅샷을 찍는 시간 지정 (UTC)
name : 스냅샷 이름 지정
repository : 스냅샷 저장소의 이름을 지정
config.indices : 어떤 인덱스의 스냅샷을 찍을지 지정
retention : 스냅샷 유지정책을 지정

SLM 정책 실행

POST _slm/policy/daily-snapshots/_execute

SLM 정책 확인

GET _slm/policy/daily-snapshots

인덱스 생명 주기 관리 (ILM)

Index Lifecycle Management (ILM)은 인덱스를 hot-warm-cold-frozen-delete 페이즈로 구분해서

지정한 기간이 지나면 다음 페이즈로 전환시키는 작업을 수행하는 기능이다.

이를 통해 저장 비용을 최적화하며 또한 아래와 같은 작업을 자동으로 수행할 수 있다.

인덱스가 특정 크기나 문서 수에 도달했을 때 새 인덱스로 전환(롤오버)
일별, 주별, 월별로 새 인덱스를 생성하고 이전 인덱스 보관
더 이상 필요하지 않은 인덱스를 삭제하여 데이터 보존 정책 적용
인덱스를 사용 패턴에 따라 적합한 데이터 계층으로 이동

생명주기 단계

핫(Hot) 단계

특징: 활발한 쓰기 및 조회가 이루어지는 단계

노드 배치: 성능이 가장 좋은 노드에 배치

가능한 작업:
우선순위 설정(Set Priority)
언팔로우(Unfollow)
롤오버(Rollover)
읽기 전용 설정(Read-Only)
다운샘플링(Downsample)
축소(Shrink)
강제 병합(Force Merge)
검색 가능 스냅샷(Searchable Snapshot)

웜(Warm) 단계

특징: 업데이트가 거의 없고 조회 빈도가 낮아진 단계

노드 배치: 중간 성능의 노드에 배치

가능한 작업:
우선순위 설정
언팔로우
읽기 전용 설정
다운샘플링
할당(Allocate)
마이그레이션(Migrate)
축소
강제 병합

콜드(Cold) 단계

특징: 더 이상 업데이트되지 않고 가끔 조회되는 단계

노드 배치: 저비용 스토리지 노드에 배치

가능한 작업:
우선순위 설정
언팔로우
읽기 전용 설정
다운샘플링
검색 가능 스냅샷
할당
마이그레이션

프로즌(Frozen) 단계

특징: 거의 조회되지 않는 데이터를 위한 단계

노드 배치: 가장 저비용 스토리지에 배치

가능한 작업:
언팔로우
검색 가능 스냅샷

삭제(Delete) 단계

특징: 데이터를 영구적으로 제거하는 단계

가능한 작업:
스냅샷 대기(Wait For Snapshot)
삭제(Delete)

페이즈 전환 예시

다음과 같은 시나리오로 인덱스를 자동 운영할 수 있다.

페이즈 전환에는 시간 조건을 사용하였다.

처음 hot 페이즈에서는 매일 자동으로 롤오버를 수행하고, 3일이 지난 인덱스는 warm 페이즈로 전환된다.

warm 페이즈는 읽기 전용 인덱스로 바꾸고 단일 세그먼트로 강제 병합한다.

7일지난 인덱스는 cold 페이즈로 전환되고 성능이 떨어지느 노드로 이동시킨 후 샤드 복구 우선순위를 낮춘다.

30일이 지난 인덱스는 delete 페이즈로 이동시킨다. 스냅샷으로 백업을 진행한다.

ILM 정책 생성과 적용

인덱스 크기가 50GB에 도달하거나 30일이 경과하면 롤오버
롤오버 후 2일이 지나면 warm 단계로 이동, 샤드 수를 1개로 줄이고 세그먼트 병한
롤오버 후 7일이 지나면 cold 단계로 이동, cold node로 이동
롤오버 후 30일이 지나면 인덱스 삭제

PUT _ilm/policy/metrics_policy
{
  "policy": {
    "phases": {
      "hot": {
        "actions": {
          "rollover": {
            "max_size": "50GB",
            "max_age": "30d"
          }
        }
      },
      "warm": {
        "min_age": "2d",
        "actions": {
          "shrink": {
            "number_of_shards": 1
          },
          "forcemerge": {
            "max_num_segments": 1
          }
        }
      },
      "cold": {
        "min_age": "7d",
        "actions": {
          "allocate": {
            "require": {
              "data": "cold"
            }
          }
        }
      },
      "delete": {
        "min_age": "30d",
        "actions": {
          "delete": {}
        }
      }
    }
  }
}

[ 서킷 브레이커 ]

노드가 중단되는 문제를 발생시킬만한 무거운 작업의 수행을 미리 차단하는 역할을 한다.

특정 작업이 너무 많은 메모리를 사용하는 것을 방지
JVM 힙 메모리 부족으로 인한 노드 실패 예방
클러스터의 안정적인 성능 저하 방지

필드 데이터 서킷 브레이커

indices.breaker.fielddata.limit (default 40%)
fielddata가 메모리에 올라갈 때 얼마만큼 메모리를 사용할지 예상

요청 서킷 브레이커

Indices.breaker.request.limit (default 60%)
요청 하나의 데이터 구조가 메모리를 과다하게 사용하는지 계산

부모 서킷 브레이커

모든 서킷 브레이커의 총 메모리 사용량 제어
indices.breaker.total.use_real_memory: true 면 indices.breaker.total.limit: 95%
indices.breaker.total.use_real_memory: false 면 indices.breaker.total.limit: 70%

서킷 브레이커 설정

PUT /_cluster/settings
{
  "persistent": {
    // 부모 서킷 브레이커 설정
    "indices.breaker.total.use_real_memory": true,
    "indices.breaker.total.limit": "95%",
    
    // 필드 데이터 서킷 브레이커 설정
    "indices.breaker.fielddata.limit": "40%",
    "indices.breaker.fielddata.overhead": 1.03,
    
    // 요청 서킷 브레이커 설정
    "indices.breaker.request.limit": "60%",
    "indices.breaker.request.overhead": 1.0
  }
}

indices.breaker.total.use_real_memory는 정적 설정이므로 노드 재시작이 필요
다른 설정들은 동적으로 변경 가능
하위 브레이커들의 합(40% + 60% = 100%)이 부모 브레이커 제한(95%)을 초과하지 않도록 주의

현재 서킷 브레이커 상태 확인

GET /_nodes/stats/breaker

[ 슬로우 로그 설정 ]

검색이나 색인 작업 시 너무 오랜 시간이 소요되면 별도로 로그를 남기도록 설정한다.

성능 문제를 진단하고 최적화가 필요한 쿼리를 식별하는데 유용하다.

기본값은 어떤 설정도 되어 있지 않다.

설정 이후에 {Cluster_name}_index_search_slowlog.log 파일이 생서된다.

모든 인덱스에 대한 슬로우 로그 설정

PUT /_all/_settings
{
  "index.search.slowlog.threshold.query.warn": "10s",
  "index.search.slowlog.threshold.fetch.warn": "1s",
  "index.indexing.slowlog.threshold.index.warn": "10s",
  "index.search.slowlog.include.user": true
}

검색 슬로우 로그 예시

{
  "@timestamp": "2024-12-11T22:34:22.613Z",
  "elasticsearch.cluster.name": "my-cluster",
  "elasticsearch.node.name": "node-1",
  "elasticsearch.slowlog.id": "search-123",
  "elasticsearch.slowlog.search_type": "QUERY_THEN_FETCH",
  "elasticsearch.slowlog.source": "{\"query\":{\"match_all\":{}}}",
  "elasticsearch.slowlog.took": "747.3micros",
  "elasticsearch.slowlog.total_hits": "1000 hits",
  "log.level": "WARN",
  "user.name": "elastic"
}

query: 쿼리 실행 단계의 임계값
fetch: 결과 가져오기 단계의 임계값
각 단계별로 4가지 로그 레벨(warn, info, debug, trace) 설정 가능
include.user: 사용자 정보 포함 여부

인덱싱 슬로우 로그 예시

{
  "@timestamp": "2024-12-11T22:34:22.613Z",
  "elasticsearch.index.name": "my-index-000001",
  "elasticsearch.slowlog.source": "{\"key\":\"value\"}",
  "elasticsearch.slowlog.took": "0.01ms",
  "log.level": "WARN",
  "user.name": "elastic"
}

index: 문서 인덱싱 작업의 임계값
source: 로그에 포함할 문서 소스의 최대 문자 수
reformat: 소스 포맷팅 여부

Elasticsearch 바이블 - 4장 검색 및 집계 API

wave35 — Sun, 11 May 2025 10:57:24 +0900

[ 문서 API ]

색인 API

문서 단건을 색인한다.

PUT /my_index/_doc/1
{
  "title": "Elasticsearch Guide",
  "author": "John Doe",
  "published_date": "2023-01-01"
}

# 라우팅지정
PUT /my_index/_doc/2?routing=myid2

조회 API

문서 단건을 조회한다.

GET /my_index/_doc/1
>>>
{
  "_index": "my_index",
  "_id": "1",
  "_version": 1,
  "_seq_no": 0,
  "_primary_term": 1,
  "found": true,
  "_source": {
    "title": "Elasticsearch Guide"
  }
}

# 필드 필터링 : _source_includes, _source_excludes 옵션을 사용
GET /my_index/_doc/1?_source_includes=t*&_source_excludes=author
{
  ...
  "_source": {
    "title": "Elasticsearch Guide"
  }
}

업데이트 API

요청 본문에 doc이나 script를 지정하여 업데이트할 내용을 기술한다.

루씬의 세그먼트는 불변이라 내부적으로는 새로운 문서를 만들어 색인하는 형태이다.

POST /my_index/_update/1
{
  "doc": {
    "author": "Jane Doe"
  }
}

doc_as_upsert

기존 문서가 없다면 요청은 실패한다.

위의 케이스에도 새로 문서를 추가하는 upsert 기능이 필요하다면 doc_as_upsert 옵션을 지정한다.

POST /my_index/_update/2
{
  "doc": {
    "author": "mike tyson"
  },
  "doc_as_upsert": true
}

삭제 API

지정한 문서 하나를 삭제한다.

DELETE /my_index/_doc/2

[ bulk API ]

여러 문서에 대한 색인, 업데이트, 삭제 작업을 한번에 수행 할 수 있다.

다른 API와는 다르게 요청 본문을 NDJSON 형태로 만들어서 보낸다.( 여러줄의 JSON )

Content-Type 헤더도 application/json 대신 application/x-ndjson을 사용해야 한다.

POST /_bulk
{ "index" : { "_index" : "test", "_id" : "1" } }
{ "field1" : "value1" }
{ "delete" : { "_index" : "test", "_id" : "2" } }
{ "create" : { "_index" : "test", "_id" : "3" } }
{ "field1" : "value3" }
{ "update" : { "_id" : "1", "_index" : "test" } }
{ "doc" : { "field2" : "value2" } }
{ "index" : { "_index" : "test", "_id" : "4" } }
{ "field1" : "value4" }
{ "create" : { "_index" : "test", "_id" : "5" } }
{ "field1" : "value5" }

요청의 순서를 보장하지는 않지만,

동인한 index, _id, routing 조합이 가진 요청은 bulk API에 기술된 순서로 동작한다.

[ muti get API ]

_id를 여럿 지정하여 한번에 문서를 조회하는 API 이다.

GET /_mget
{
  "docs": [
    {
      "_index": "my_index",
      "_id": "1"
    },
    {
      "_index": "my_index",
      "_id": "2"
    },
    {
      "_index": "my_index",
      "_id": "3"
    }
  ]
}

또는

GET my_index/_mget
{
	"ids": ["1", "2", "3"]
}

>>> 출력
{
  "docs": [
    {
      "_index": "my_index",
      "_id": "1",
      "_version": 2,
      "_seq_no": 1,
      "_primary_term": 1,
      "found": true,
      "_source": {
        "title": "Elasticsearch Guide",
        "author": "John Doe",
        "published_date": "2023-01-01"
      }
    },
    {
      "_index": "my_index",
      "_id": "2",
      "_version": 1,
      "_seq_no": 2,
      "_primary_term": 1,
      "found": true,
      "_source": {
        "title": "Elasticsearch Guide",
        "author": "Jame Dom",
        "published_date": "2024-01-01"
      }
    },
    {
      "_index": "my_index",
      "_id": "3",
      "found": false
    }
  ]
}

[ 검색 API ]

인덱스 이름을 지정하지 않으면 전체 인덱스에 대해서 검색하며

와일드카드를 사용할 수 있다.

GET _search
GET my_index/_search
GET my_inde*,test*/_search

match

지정한 필드의 내용이 질의와 매치되는 문서를 찾는다.

필드가 text 타입이라면 필드의 값도 질의어도 모두 애널라이저로 분석된다.

GET /korean_data/_search
{
    "query":{
        "match":{
            "address":{
                "query":"도산대거리"
            }
        }
    }
}

term

지정한 필드와 값이 정확히 일치하는 문서를 찾는다.

keyword 타입과 잘 맞는다.

GET /korean_data/_search
{
    "query":{
        "term":{
            "address_district":{
                "value":"세종특별자치시 동구"
            }
        }
    }
}

terms

질의어와 정확히 일치하는 문서를 찾는 것은 term과 유사하며

질의어를 여러 개 지정할 수 있다. 하나 이상의 질의어가 일치하면 검색된다.

range

지정한 필드이 값이 특정 범위 내에 있는 문서를 찾는 쿼리이다.

GET /korean_data/_search
{
    "query":{
        "range":{
            "generated_at":{
                "gte":"2025-05-06T09:38",
                "lt":"2025-05-06T09:40"
            }
        }
    }
}

prefix

필드 값이 지정한 질의어로 시작하는 문서를 찾느 ㄴ쿼리.

무거운 쿼리로 분류된다.

GET /korean_data/_search
{
    "query":{
        "prefix":{
            "name":{
                "value":"김경"
            }
        }
    }
}

bool

여러 쿼리를 조합하여 검색하는 쿼리이다.

must, must_not, filter, should 4가지의 조건절을 조합한다.

must 절과 filter절에 들어간 하위 쿼리는 AND 조건을 만족해야 하며,

should 절의 하위쿼리는 OR 조건으로 검색하는 것과 같다.

GET /korean_data/_search
{
  "query": {
    "bool": {
      "must": [
        {
          "match": {
            "address": "서울특별시"
          }
        }
      ],
      "must_not": [
        {
          "match": {
            "address": "서초구"
          }
        }
      ],
      "filter": [
        {
          "range": {
            "publish_date": {
              "gte": "2025-05-06T09:38:00",
              "lte": "2025-05-06T10:40:00"
            }
          }
        }
      ],
      "should": [
        {
          "match": {
            "name": "권종수"
          }
        },
        {
          "match": {
            "job": "화학"
          }
        }
      ],
      "minimum_should_match": 1
    }
  }
}

[ 그외매개변수 ]

라우팅

검색 API도 마찬가지로 라우팅을 지정해 주는 것이 좋다.

GET korean_data/_search?routing=r12
{
	...
}

explain

검색을 수행하는 동안 각 하위 부분에서 점수가 어떻게 계산됬는지 설명한다.

디버깅 용도로 사용할 수 있다.

GET /korean_data/_search?explain=true
{
	...
}

검색결과 정렬

GET /korean_data/_search
{
  "size": 3,
  "sort": [
    {
      "generated_at": {
        "order": "desc"
      }
    },
    {
      "job.keyword": {
        "order": "asc"
      }
    }
  ],
  "query": {
    "match_all": {}
  }
}

[ 집계 API ]

매트릭 집계

문서에 대한 산술적인 연산을 수행한다.

size = 0 으로 지정하면 집계 연산의 결과만 받아 볼 수 있다.

stats 집계

GET /korean_data/_search
{
    "size": 0,
    "aggs": {
        "stats_agg": {
            "stats": {
            "field": "generated_at"
            }
        }
    }
}

cardinality 집계

지정한 필드가 가진 고유한 값의 개수를 계산해서 반환한다.

GET /korean_data/_search
{
    "size": 0,
    "aggs": {
        "cardinality_agg": {
            "cardinality": {
            "field": "job.keyword"
            }
        }
    }
}
# >>> 출력
{
	...
    "aggregations": {
    "cardinality_agg": {
      "value": 97
    }
  }
}

버킷집계

문서를 특정 기준으로 쪼개어 여러 부분 집합으로 나눈다.

각 버킷에 포함된 문서를 대상으로 별도의 하위 집계를 수행할 수 있다.

range 집계

GET /korean_data/_search
{
    "size": 0,
    "aggs": {
        "range_agg": {
            "range": {
            "field": "generated_at",
            "ranges": [
                { "to": "2025-05-11T10:43:00" },
                { "from": "2025-05-11T10:43:00", "to": "2025-05-11T10:44:00" },
                { "from": "2025-05-11T10:43:00" }
            ]
            }
        }
    }
}

data_range 집계

- 간단한 날짜 시간 계산식을 사용할 수 있다.

GET /korean_data/_search
{
    "size": 0,
    "aggs": {
        "date_range_agg": {
            "date_range": {
            "field": "timestamp",
            "ranges": [
                { "to": "now-1M/M" },
                { "from": "now-1M/M", "to": "now/M" },
                { "from": "now/M" }
            ]
            }
        }
    }
}

terms 집계

- 지정한 필드에 대해 가장 빈도수가 높은 term 순서대로 버킷을 생성한다.

- size로 최대 몇개까지 버킷을 생성할지 지정한다.

GET /korean_data/_search
{
    "size": 0,
    "aggs": {
        "terms_agg": {
            "terms": {
            "field": "job.keyword",
            "size": 10
            }
        }
    }
}
# >>> 출력
{
	...
    "aggregations": {
        "terms_agg": {
          "doc_count_error_upper_bound": 0,
          "sum_other_doc_count": 127,
          "buckets": [
            {
              "key": "비파괴 검사원",
              "doc_count": 3
            },
            {
              "key": "양식 주방장 및 조리사",
              "doc_count": 3
            },
            ...
          ]
     }
   }
}

SideProject - 카프카 시스템 구성 (아자르 비즈니스 메트릭 참조)

wave35 — Sun, 27 Apr 2025 22:49:03 +0900

[ 프로젝트 목적 아키텍처 ]

이 프로젝트는 카프카(Kafka) 기반의 분산 메시징 시스템을 구축하고 운영하고 있는,

아자르(Azar) 비즈니스 메트릭을 생성하는 프로세스를 흉내내어본 것입니다.

Git 참조 : https://github.com/ehdrn3020/kafka_system_with_azar

Azar 참조 : https://hyperconnect.github.io/2022/10/14/grafana-with-ksqlDB.html

AWS 환경에서 Kafka 클러스터 구성
Zookeeper를 통한 분산 코디네이션
Schema Registry를 활용한 데이터 스키마 관리
Kafka Connect를 활용한 데이터 파이프라인 구성
ElasticSearch(OpenSearch)를 통한 데이터 저장 및 검색

아키텍처는 3대의 서버로 구성된 Kafka 클러스터를 중심으로,

데이터 생성부터 저장까지의 전체 파이프라인을 Ansible을 통해 자동화하여 구축할 수 있도록 설계되었습니다.

[ 파일 구조 ]

kafka_system_with_azar/
├── .git/                     # Git 저장소 정보
├── .idea/                    # IDE 설정 파일
├── README.md                 # 프로젝트 설명 및 사용법
├── schema_registry/          # 스키마 레지스트리 관련 코드
│   ├── opensearch_sink_example.py  # OpenSearch 싱크 예제
│   ├── producer_avro.py      # Avro 형식 데이터 생성자
│   ├── consumer_avro.py      # Avro 형식 데이터 소비자
│   ├── README.md             # 스키마 레지스트리 설명
│   └── single_mode/          # 단일 모드 구성 파일
├── ansible/                  # Ansible 자동화 스크립트
│   ├── inventory/            # 서버 인벤토리 정보
│   ├── group_vars/           # 그룹 변수 설정
│   ├── roles/                # Ansible 역할 정의
│   ├── connector.yml         # Connector 설치 플레이북
│   ├── opensearch.yml        # OpenSearch 설치 플레이북
│   ├── schema_registry.yml   # 스키마 레지스트리 설치 플레이북
│   ├── kafka.yml             # Kafka 설치 플레이북
│   └── zookeeper.yml         # Zookeeper 설치 플레이북
├── setting_aws/              # AWS 환경 설정 스크립트
│   └── setup_server.sh       # EC2 서버 설정 스크립트

[ 시스템 설정 ]

AWS Server Setting

### .env 파일 생성
- setting_aws/env_example 참조하여 생성

### keypair.pem 키 생성
- ec2 접속을 위해 keypair.pem 키를 setting_aws 폴더에 생성
- 파일 권한 수정 : sudo chmod 600 setting_aws/keypair.pem

### EC2 서버 실행
```commandline
sh setting_aws/setup_server.sh server_1
sh setting_aws/setup_server.sh server_2
sh setting_aws/setup_server.sh server_3
```

### scp keypair.pem
```commandline
scp -i setting_aws/keypair.pem setting_aws/keypair.pem ec2-user@server_1_ip:~
```

### SSH 접속
```commandline
ssh -i setting_aws/keypair.pem ec2-user@server_1_ip
```

### group_var host 관련 수정
```commandline
inventory/hosts 파일의 ansible_host 변수 수정
git push
cd /home/ec2-user/kafka_system_with_azar/
git pull  ( server_1 에서 실행 )
```

Zookeeper Setting

### zookeeper 설치
```commandline
cd /home/ec2-user/kafka_system_with_azar/ansible/
ansible-playbook -i inventory/hosts zookeeper.yml
```

### zookeeper 실행 확인
```commandline
systemctl status zookeeper
cat /data/zookeeper/myid
```

Kafka Setting

### kafka 설치
```commandline
ansible-playbook -i inventory/hosts kafka.yml
```
### kafka 실행 확인
```commandline
# server_1에서 토픽생성 ( 자동토픽생성(Auto Topic Creation)으로 토픽 생성 생략가능 )
/usr/local/kafka/bin/kafka-topics.sh --bootstrap-server kafka_01.com:9092 --create --topic test-overview01 --partitions 1 --replication-factor 3

# server_2에서 consumer 실행 
/usr/local/kafka/bin/kafka-console-consumer.sh --bootstrap-server kafka_01.com:9092 --topic test-overview01

# server_1 producer로 메세지 전송
/usr/local/kafka/bin/kafka-console-producer.sh --bootstrap-server kafka_02.com:9092 --topic test-overview01

# server_2에서 전송 된 메세지 확인
```

Schema Registery

# Schema Registry
### 설치
```commandline
cd ~
sudo wget http://packages.confluent.io/archive/6.1/confluent-community-6.1.0.tar.gz -O /opt/confluent-community-6.1.0.tar.gz
sudo tar zxf /opt/confluent-community-6.1.0.tar.gz -C /usr/local/
sudo ln -s /usr/local/confluent-6.1.0 /usr/local/confluent
```

### 설정
```commandline
vi /usr/local/confluent/etc/schema-registry/schema-registry.properties
프로젝트의 schema_registry/schema-registry.properties 참조하여 업데이트
```

### 실행
```commandline
sudo vi /etc/systemd/system/schema-registry.service
프로젝트의 schema_registry/schema-registry.properties 참조하여 업데이트
sudo systemctl daemon-reload
sudo systemctl start schema-registry
sudo systemctl status schema-registry
```

### 호환성 확인
```commandline
curl -X GET http://kafka_01.com:8081/config
>>> 출력 값
{"compatibilityLevel":"FULL"}
```

### 예시 - python 파일을 통해 메세지 전송
```commandline
# 가상환경에 필요한 모듈 설치
cd /home/ec2-user/kafka_system_with_azar/schema_registry
python -m venv venv
source  venv/bin/activate
pip install confluent-kafka[avro]

# 모듈 설치시 호환성
- 해당 예제는 confluent-kafka==2.8.0 설치하여 librdkafka 1.8.2 이상의 버전이 필요합니다.
- confluent-kafka Python라이브러리는 librdkafka를 래핑(wrapping)한 라이브러리입니다.
- librdkafka는 Apache Kafka 브로커와 통신하는 역할을 하며, Kafka 브로커의 버전과 호환성이 있습니다.
- python3.9 이상에서는 librdkafka 1.x.x 이상이 설치되지만, python3.7은 librdkafka 0.11.x 버전이 설치됩니다.
- librdkafka 0.11.x 버전은 confluent-kafka 1.0.0 이하와 호환되므로, 아래 py파일의 코드가 실행되지 않을 수 있습니다. 

# 메세지 전송 ( Schema Registry가 실행 중인 서버 )
python producer_avro.py
>>> Message delivered to kafka-avro2 [0]

# 메세지 확인
python consumer_avro.py
>>> {'name': 'Peter', 'class': 1}
```

### 스키마 적용 확인
```commandline
curl http://kafka_01.com:8081/schemas | python -m json.tool
>>>
  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
100   375  100   375    0     0  16769      0 --:--:-- --:--:-- --:--:-- 17045
[
    {
        "subject": "kafka-avro2-value",
        "version": 1,
        "id": 1,
        "schema": "{
            \"type\":\"record\",
            \"name\":\"Student\",
            \"namespace\":\"student.avro\",
            \"doc\":\"This is an example of Avro.\",
            \"fields\":[
                {\"name\":\"name\",\"type\":[\"null\",\"string\"],\"doc\":\"Name of the student\",\"default\":null},
                {\"name\":\"class\",\"type\":\"int\",\"doc\":\"Class of the student\",\"default\":1}
            ]
        }"
    }
]
```

위 내용을 ansible을 통해 자동화

```
# 설치, 설정파일 수정 및 실행
ansible-playbook -i inventory/hosts schema_registry.yml

# 데몬 확인
sudo systemctl status schema-registry

# 호환성 확인
curl -X GET http://kafka_01.com:8081/config
>>> 출력 값
{"compatibilityLevel":"FULL"}
```

ElasticSearch

### opensearch 설치
```commandline
# kafka01 호스트에 싱글 노드로 설치
ansible-playbook -i inventory/hosts opensearch.yml
```

### opensearch 확인
```commandline
sudo systemctl status opensearch

# 클러스터 내 각 노드의 정보
curl -X GET "http://kafka_01.com:9200/_cat/nodes?v"
# 클러스터의 전체 상태(Health) 를 조회
curl -X GET "http://kafka_01.com:9200/_cluster/health?pretty"
```

Connector Sink

### 커넥터 설치
```commandline
ansible-playbook -i inventory/hosts connector.yml
```

### 커넥터 확인
```commandline
# 실행 확인
sudo systemctl status kafka-connect
# 에러시 로그 확인
journalctl -u kafka-connect -f

# 클러스터에 현재 등록된 커넥터 목록을 확인
curl http://localhost:8083/connectors | python -m json.tool
# 커넥터 플러그인 확인
curl http://localhost:8083/connector-plugins | jq
[
  {
    "class": "io.aiven.kafka.connect.opensearch.OpensearchSinkConnector",
    "type": "sink",
    "version": "3.1.1"
  },
...]
```

### 토픽 생성
```commandline
# 생성
/usr/local/kafka/bin/kafka-topics.sh --create \
    --bootstrap-server kafka_01.com:9092,kafka_02.com:9092,kafka_03.com:9092 \
    --replication-factor 3 \
    --partitions 3 \
    --topic opensearch-sink
/usr/local/kafka/bin/kafka-topics.sh --list --bootstrap-server kafka_01.com:9092,kafka_02.com:9092,kafka_03.com:9092

# 확인
/usr/local/kafka/bin/kafka-topics.sh --list --bootstrap-server kafka_01.com:9092
```

### 컨넥터 등록
```commandline
# API로 opensearch sink connector 등록
curl -X POST http://kafka_01.com:8083/connectors -H "Content-Type: application/json" -d '{
  "name": "opensearch-sink",
  "config": {
    "connector.class": "io.aiven.kafka.connect.opensearch.OpensearchSinkConnector",
    "tasks.max": "1",
    "topics": "opensearch-sink",
    "connection.url": "http://kafka_01.com:9200",

    "key.converter": "io.confluent.connect.avro.AvroConverter",
    "value.converter": "io.confluent.connect.avro.AvroConverter",
    "key.converter.schema.registry.url": "http://kafka_01.com:8081",
    "value.converter.schema.registry.url": "http://kafka_01.com:8081",

    "schema.registry.url": "http://kafka_01.com:8081",
    "value.converter.schemas.enable": "false",
    "schema.ignore": "true",
    "type.name": "kafka-connect"
  }
}'

# 등록 확인
curl http://localhost:8083/connectors | python -m json.tool
...
[
    "opensearch-sink"
]

# 상태 확인
curl -X GET http://kafka_01.com:8083/connectors/opensearch-sink/status | jq

# 커넥터 삭제
curl -X DELETE http://localhost:8083/connectors/opensearch-sink
```

[ kafka 데이터 전송 ]

```commandline
# 가상환경에 필요한 모듈 설치 ( kafka_01.com 호스트에서 실행 )
cd /home/ec2-user/kafka_system_with_azar/schema_registry
python -m venv venv
source  venv/bin/activate
pip install confluent-kafka[avro]

# 메세지 전송 ( Schema Registry가 실행 중인 서버 )
python opensearch_sink_example.py
>>> Message delivered to kafka-avro2 [0]
```

### schema 등록확인
```commandline
# subjects list 확인
curl http://kafka_01.com:8081/subjects
>>> ["opensearch-sink-value"]

# subject 버전 확인
curl http://kafka_01.com:8081/subjects/opensearch-sink-value/versions
>>> [1]

```

### opensearch index store 확인
```commandline
curl -X GET "http://kafka_01.com:9200/_cat/indices?v"
curl -X GET "http://kafka_01.com:9200/opensearch-sink*/_search?pretty"
```

Elasticsearch 바이블 - 3장 인덱스 설계

wave35 — Sun, 27 Apr 2025 22:13:19 +0900

[ 인덱스 설정 ]

GET [index_name]/_settings

인덱스 설정은 인덱스명 뒤에 _settings를 넣어 GET 메서드로 호출한다.

예제

PUT /my_index
{
    "settings": {
        "number_of_shards": 2,
        "number_of_replicas": 2
    }
}
>>> 
{
  "acknowledged": true,
  "shards_acknowledged": true,
  "index": "my_index"
}


GET my_index
>>>
{
  "my_index": {
    "aliases": {},
    "mappings": {},
    "settings": {
      "index": {
        "routing": {
          "allocation": {
            "include": {
              "_tier_preference": "data_content"
            }
          }
        },
        "number_of_shards": "2",
        "provided_name": "my_index",
        "creation_date": "1745115115705",
        "number_of_replicas": "2",
        "uuid": "3XaOBSOKTmi-PfcTLvPjiw",
        "version": {
          "created": "8521000"
        }
      }
    }
  }
}

number_of_shards

인덱스 데이터를 몇 개의 샤드로 쪼갤 것인지 지정하는 값
한번 지정하면 바꾸기가 쉽지 않음
샤드 당 루씬 인덱스가 하나씩 더 생성되어 너무 크게 설정하면 클러스터 성능이 떨어짐
너무 적게 설정하면 샤드 크기가 커져 복구시간이 오래 걸리고 안정성이 떨어짐
기본 값은 1

number_of_replicas

주 샤드 하나당 본제본 샤드를 몇 개 생성할 것인지 지정하는 값
인덱스 생성 후에도 동적으로 변경 가능

refresh_interval

엘라스틱서치가 인덱스 대상으로 refresh를 얼마나 자주 수행할 것인지 지정하는 값
기본 값은 "1s", 1초

[ 맵핑 필드와 타입 ]

동적 맵핑

아무 내용이 없던 mappings 항목에 필드의 타입과 정보가 추가된 것을 확인할 수 있다.

인덱스에 문서가 색인 될 때, 기존에 매핑 정보가 없으면 자동으로 적당한 필드 타입을 지정하며 생성한다.

POST /my_index/_doc/1
{
    "title": "hellow!",
    "views": 1234,
    "public": true,
    "point": 4.5,
    "created": "2025-04-20T14:00:54.123Z"
}

>>>
{
  "my_index": {
    "aliases": {},
    "mappings": {
      "properties": {
        "created": {
          "type": "date"
        },
        "point": {
          "type": "float"
        },
        "public": {
          "type": "boolean"
        },
        "title": {
          "type": "text",
          "fields": {
            "keyword": {
              "type": "keyword",
              "ignore_above": 256
            }
          }
        },
        "views": {
          "type": "long"
        }
      }
    },
    ...
}

명시적 맵핑

맵핑 설정은 한 번 지정이되면 변경하기가 힘들다.

운영시 명시적 맵핑을 활용해야하며, 신규 필드 추가시에도 명시적 맵핑을 이용하는 것이 좋다.

PUT /my_index
{
  "mappings": {
    "properties": {
      "title": {
        "type": "text"
      },
      "views": {
        "type": "integer"
      },
      "public": {
        "type": "boolean"
      },
      "point": {
        "type": "float"
      },
      "created": {
        "type": "date",
        "format": "strict_date_time" 
        // ISO 8601, 예: 2025-04-20T14:00:54.123Z
      }
    }
  }
}

# 적용확인
GET my_index/_mapping

필드타입

필드타입은 boolean, text, keyword, long, integer, short, byte, double, float, half_float, scaled_float,

date, ip, array, object, nested, geo_point, geo_shape 등이 있으며

작은 비트를 사용하는 자료형은 색인과 검색시 이득이 있다.

다만 저장할 때는 실제 값에 맞춰 최적화되기에 디스크 사용량에는 이득이 없다.

text 타입과 keyword 타입

text :

애널라이저가 적용된 후 색인된다.
즉 들어온 값은 분석하여 여러 토큰으로 쪼개어 역색인을 구성한다.
전문검색에 적합합니다.

keywork :

문자열 값을 여러 토큰으로 쪼개지 않고 역색인한다.
간단한 전처리만을 실행하는 노멀라이저를 적용한다.
정렬과 집계과 작은 작업일 때 적절하다.

타입 참조 :

https://www.elastic.co/docs/reference/elasticsearch/mapping-reference/field-data-types

[ 애널라이저와 토크나이저 ]

애널라이저는 3단계로 이루어져있다.

캐릭터 필터 (Character Filter)

원본 텍스트에서 특수 문자 제거 등의 전처리
0개 이상의 캐릭터필터를 지정할 수 있으며 순서대로 수행된다.

토크나이저 (Tokenizer)

텍스트를 개별 토큰으로 분리
한 개의 토크나이저만 지정할 수 있다.

토큰 필터 (Token Filter)

토큰 변형, 추가 또는 제거
lowercase / pattern_replace / trim / tuncate 등이 있다.

예시

curl -X GET "localhost:9200/_analyze" -H 'Content-Type: application/json' -d '
{
  "char_filter": ["html_strip"],
  "tokenizer": "standard",
  "filter": ["uppercase"],
  "text": "<p>hellow, hi word!</p>"
}'

>>>
{
  "tokens": [
    {
      "token": "HELLOW",
      "start_offset": 0,
      "end_offset": 6,
      "type": "<ALPHANUM>",
      "position": 0
    },
    {
      "token": "HI",
      "start_offset": 8,
      "end_offset": 10,
      "type": "<ALPHANUM>",
      "position": 1
    },
    {
      "token": "WORD",
      "start_offset": 11,
      "end_offset": 15,
      "type": "<ALPHANUM>",
      "position": 2
    }
  ]
}

[ 템플릿 ]

인덱스를 설정할 때마다 이런 설정값을 매번지정하는 번거로움이 있기에

사전에 템플릿을 정의해 두면 반복적인 작업을 줄여준다.

인덱스 템플릿

인덱스 패턴에는 * 와일드카드를 사용할 수 있다.

priority 값을 이용하면 인덱스 템플릿 간 우선 적용순위를 조정한다. (높을수록 우선순위 높음)

예시

PUT /_template/my_template
{
  "index_patterns": ["test-te*", "bar*"],
  "priority": 1,
  "template" {
      "settings": {
        "number_of_shards": 1
      },
      "mappings": {
        "properties": {
          "host_name": {
            "type": "keyword"
          },
          "created_at": {
            "type": "date",
            "format": "EEE MMM dd HH:mm:ss Z yyyy"
          }
        }
      }
   }
}
# 생성된 템플릿 조회
GET /_template/my_template

# 위 템플릿에 맞는 인덱스 생성
PUT test-text-1 
GET test-text-1

컴포넌트 템플릿

인덱스 템플릿을 많이 만들면 중복되는 부분이 생김나.

이를 재사용할 수 있는 작은 템플릿 블록으로 쪼갠 것이 컴포넌트 템플릿이다.

예제

PUT /_component_template/log_mappings
{
  "template": {
    "mappings": {
      "properties": {
        "host_name": {
          "type": "keyword"
        },
        "created_at": {
          "type": "date",
          "format": "EEE MMM dd HH:mm:ss Z yyyy"
        },
        "message": {
          "type": "text"
        },
        "level": {
          "type": "keyword"
        }
      }
    }
  }
}

PUT /_index_template/logs_template
{
  "index_patterns": ["logs-*", "app-logs-*"],
  "composed_of": ["log_mappings"],
  "priority": 100,
  "template": {
    "settings": {
      "number_of_shards": 1,
      "number_of_replicas": 1
    }
  }
}

PUT /_component_template/basic_settings
{
  "template": {
    "settings": {
      "number_of_shards": 2,
      "number_of_replicas": 1
    }
  }
}

PUT /_index_template/complete_logs_template
{
  "index_patterns": ["logs-*"],
  "composed_of": ["basic_settings", "log_mappings"],
  "priority": 200
}

동적 템플릿

동적 템플릿은 인덱스에 새로 들어온 필드의 매핑을 사전에 정의한대로 동적 생성한다.

예제

- description_text와 같이 _text로 끝나는 문자열 필드는 text 타입으로 매핑

- user_id_keyword와 같이 _keyword로 끝나는 문자열 필드는 keyword 타입으로 매핑

PUT my-index
{
  "mappings": {
    "dynamic_templates": [
      {
        "text_fields": {
          "match_mapping_type": "string",
          "match": "*_text",
          "mapping": {
            "type": "text"
          }
        }
      },
      {
        "keyword_fields": {
          "match_mapping_type": "string",
          "match": "*_keyword",
          "mapping": {
            "type": "keyword"
          }
        }
      }
    ]
  }
}

[ 라우팅 ]

엘라스틱서치가 인덱스를 구성하는 샤드 중, 몇 번 샤드를 대상으로 작업을 수행하지 지정하기 위해 사용하는 값

데이터 분산과 검색 성능에 중요한 영향을 미침

예제

- 5개의 샤드를 가진 익덱스를 생성

- routing 값으로 라우팅을 지정

PUT my-index
{
	"settings":{
    	"number_of_shards" 5,
        "number_of_replicas": 1
    }
}

PUT my-index/_doc/1?routing=user1
{
  "title": "This is a document"
}

조회

GET my-index/_search
{
  "took": 5,
  "timed_out": false,
  "_shards": {
    "total": 2,            // 실제 검색이 수행된 샤드 수 (user1, user2에 해당하는 샤드만)
    "successful": 2,
    "skipped": 0,
    "failed": 0
  },
  "hits": {
    "total": {
      "value": 42,
      "relation": "eq"
    },
    "max_score": 1.0,
    "hits": [
      {
        "_index": "my-index",
        "_id": "1",
        "_score": 1.0,
        "_routing": "user1",    // 이 문서는 user1 라우팅 값으로 저장됨
        "_source": {
          "title": "Document for User 1",
          "content": "This is content for user1",
          "timestamp": "2023-07-15T10:30:00Z",
          "user_id": "user1"
        }
      },
      {
        "_index": "my-index",
        "_id": "3",
        "_score": 1.0,
        "_routing": "user2",    // 이 문서는 user2 라우팅 값으로 저장됨
        "_source": {
          "title": "Document for User 2",
          "content": "This is content for user2",
          "timestamp": "2023-07-14T14:20:00Z",
          "user_id": "user2"
        }
      },
	  ...
    ]
  }
}

운영에서는 라우팅을 지정하는 것을 권장

- 라우팅 값을 필수로 설정하는 예제

PUT my-index
{
  "mappings": {
    "_routing": {
      "required": true
    }
  }
}

Python - bisect 예제

wave35 — Wed, 23 Apr 2025 22:40:30 +0900

[ bisect 모듈 ]

bisect 모듈은 이진 탐색을 쉽게 쓸 수 있게 해주는 파이썬 표준 라이브러리

"정렬된 리스트"에 값을 효율적으로 삽입하거나 위치를 찾을 때 유용

[ 사용 함수 ]

함수	의미	반환값
bisect_left(a, x)	좌측 삽입 위치 탐색	x를 a에 넣을 때 왼쪽 인덱스
bisect_right(a, x)	우측 삽입 위치 탐색	x를 a에 넣을 때 오른쪽 인덱스
insort_left(a, x)	bisect_left 위치에 삽입	리스트 a가 정렬된 상태 유지
insort_right(a, x)	bisect_right 위치에 삽입	동일

[ 예제 ]

정렬 리스트에 중복을 허용하며 요소 삽입

import bisect

scores = [15, 22, 22, 30]
bisect.insort(scores, 22)      # insort == insort_right
print(scores)                  # [15, 22, 22, 22, 30]

리스트에 같은 값이 몇개 있는지 확인

a = [1, 2, 2, 2, 3, 4, 5]
lo = bisect.bisect_left(a, 2)   # 1
hi = bisect.bisect_right(a, 2)  # 4
count = hi - lo                 # 3

실시간 랭킹 유지

from bisect import insort_right

leaderboard = []          # (score, user) 튜플의 내림차순 리스트
def add_score(score, user):
    # 점수가 큰 순으로 정렬하기 위해 음수 key 사용, 튜플(-score, user)
    insort_right(leaderboard, (-score, user))

add_score(300, "Alice")
add_score(270, "Bob")
add_score(285, "Carol")

print(leaderboard[:3])    

>>> 출력
[(-300, 'Alice'), (-285, 'Carol'), (-270, 'Bob')]

[ 문제 ]

정수 배열 nums와 정수 n이 주어질 때, 증가 부분 수열(subsequence) 구하기

예제 1

nums = [2, 1, 5, 0, 4, 6]
n    = 3

가능한 증가 부분 수열 예: [2, 5, 6], [1, 4, 6], [0, 4, 6] 등이 있으므로
→ True

예제 2

nums = [5, 4, 3, 2, 1]
n    = 2

모든 값이 내림차순이므로 길이 2인 증가 부분 수열도 만들 수 없음
→ False

이 문제를 O(N log N) 시간에 해결하는 표준 기법(그리디+이진 탐색)을 구현한 예시

import bisect

def increasingSubsequence(nums, n):
    tail = []  # 각 길이별 수열의 최소 마지막 값 저장

    for num in nums:
        idx = bisect.bisect_left(tail, num)  # 현재 num이 들어갈 자리
        if idx == len(tail):
            tail.append(num)  # 새로운 길이의 수열이 생김
        else:
            tail[idx] = num  # 기존 길이 수열의 최소 마지막 값 갱신

        if len(tail) >= n:
            return True  # n중 수열 발견

    return False

엘라스틱서치 바이블 - 2장 기본동작과 구조

wave35 — Tue, 15 Apr 2025 07:10:51 +0900

[ 구조 개괄 ]

기본적인 용어

문서 : 엘라스틱서치가 저장하고 색인을 생성하는 JSON 문서
인덱스 : 문서를 모아 놓은 단위, 인덱스 단위로 검색을 요청
샤드 : 인덱스는 그 내용을 여러 샤드로 분리하여 분산 저장하여 고가용성을 제공
_id : 인덱스 내 문서에 부여되는 고유한 구분자
노드 : 엘라스틱서치 프로세스 하나가 노드 하나를 구성
노드의 역할 : 데이터노드, 마스터노드, 조정노드 등 하나의 역할을 맡아 수행
- 클러스터를 관리하는 역할을 마스터노드에서 진행
- 샤드를 보유하고 샤드에 읽기 쓰기 작업을 수행하는 노드는 데이터노드
- 클라이언트의 요청을 받아서 노드에 요청을 분배하는 노드는 조정노드

엘라스틱 클러스터

[ 내부 구조와 루씬 ]

루씬 flush

문서 색인 요청이 들어오면 루씬은 문서를 분석해서 역색인을 생성한다.

최초 메모리 버퍼에 들어가며 주기적으로 디스크에 flush한다.

루씬 commit

디스크에 파일이 기록하는 것까지 보장하지는 않으므로

fsync 시스템콜을 통해 주기적으로 싱크를 맞추는 작업을 수행한다.

세그먼트

디스크에 기록된 파일들이 모이면 세그먼트라는 단위가 된다.

루씬의 검색 대상이며 불변(immutable)인 데이터로 구성된다.

중간중간 세그먼트 병합을 수행해 검색 성능의 향상시킨다.

루씬 인덱스와 엘라스틱서치 인덱스

여러 세그먼트가 모이면 하나의 루씬 인덱스가 된다.

엘라스틱 샤드는 루씬인덱스의 래핑(wrap)한 단위이며 여러개 보이면 엘라스틱 인덱스가 된다.

AWS - DynamoDB GSI

wave35 — Fri, 11 Apr 2025 12:17:55 +0900

[ GSI 개념 ]

DyanmoDB는 기본키(PK) 기준으로 데이터를 조회하며

다양한 쿼리 패턴을 위해서는 추가적으로 인덱스가 필요합니다.

예를 들어 PK = user_id 로 지정했는데 age로 조회하고 싶을 경우,

작은 테이블에선 조회가 가능할지 모르지만 저장된 데이터가 클 경우 에러 혹은 검색이 되지 않습니다.

이럴 때 GSI나 LSI를 사용하면 데이터 복제 없이도 새로운 쿼리 경로를 생성할 수 있습니다.

아래는 DynamoDB에서 지원하는 인덱스 2가지 입니다.

Global Secondary Index : 기본 키와 관계없이 다른 파키션 키와 정렬 키를 사용하는 인덱스
Local Secondary Index : 기본 파키션 키는 유지하고 다른 정렬 키를 사용하는 인덱스

[ PK와 SK의 역할 ]

DynamoDB 테이블의 기본 키는 아래 두 가지 형태 중 하나로 정의된다:

단일 키: Partition Key만 존재 : 완전히 고유한 값으로만 조회 가능
복합 키: Partition Key + Sort Key 조합 : 파티션 키로 필터링한 후, 정렬 키로 정렬된 범위 쿼리 가능

Table: Users
Partition Key: user_id
Sort Key: position
→ 특정 유저의 포지션 별로 데이터를 쉽게 조회 가능

[ 기본 쿼리의 한계 ]

기본 키가 아닌 속성으로는 직접 조회가 불가능하거나, 스캔(Scan) 연산이 발생합니다.

성능 저하: 전체 테이블을 읽는 스캔은 매우 비효율적
비용 증가: 읽은 모든 항목에 대해 비용 발생
응답 지연: 필터링이 클라이언트 또는 DynamoDB 내부에서 발생하므로 지연

그러므로 인덱스(GSI 또는 LSI)를 설계하여 다양한 쿼리가 가능하게 구현합니다.

[ GIS (Global Secondary Index ) ]

GSI 생성

AWS DynamoDB Console에서 GSI를 생성합니다.

속성 프로젝션

GSI( 또는 LIS)를 만들 때 선택하는 속성 프로젝션(Attribute Projection)은

인덱스에 어떤 데이터를 저장할지 결정합니다.

다시 말해 인덱스만 보고 원하는 데이터를 얻을 수 있는지,

기본 테이블 컬럼 값까지 다시 조회해야 하는지에 영향을 줍니다.

예제 테이블 Employee ( PK = emp_id )

aws dynamodb create-table \
  --table-name Employee \
  --attribute-definitions \
      AttributeName=emp_id,AttributeType=S \
      AttributeName=department,AttributeType=S \
  --key-schema AttributeName=emp_id,KeyType=HASH \
  --billing-mode PAY_PER_REQUEST

ALL 옵션

all 옵션으로 GSI를 생성할 경우 인덱스에 모든 속성이 포함되어 있어서 바로 조회가 가능합니다.

쿼리만으로 모든 속성 조회가 가능하지만, 인덱스가 커짐에 따라 쓰기 비용이 증가합니다.

# 생성
aws dynamodb update-table \
  --table-name Employee \
  --attribute-definitions AttributeName=department,AttributeType=S \
  --global-secondary-index-updates \
    '[{
      "Create": {
        "IndexName": "GSI_All",
        "KeySchema": [{"AttributeName":"department","KeyType":"HASH"}],
        "Projection": {"ProjectionType":"ALL"}
      }
    }]'

# 조회
aws dynamodb query \
  --table-name Employee \
  --index-name GSI_All \
  --key-condition-expression "department = :dept" \
  --expression-attribute-values '{":dept": {"S": "Engineering"}}'

KEYS_ONLY 옵션

GSI로 조회한 속성이 기본키가 아닌 경우에는 한번 더 조회가 필요합니다.

기본키만 저장되므로 저장 효율이 높지만, 추가 조회가 필요할 수 있습니다.

# 생성
aws dynamodb update-table \
  --table-name Employee \
  --global-secondary-index-updates \
    '[{
      "Create": {
        "IndexName": "GSI_KeysOnly",
        "KeySchema": [{"AttributeName":"department","KeyType":"HASH"}],
        "Projection": {"ProjectionType":"KEYS_ONLY"}
      }
    }]'

# 조회
# 1단계: 인덱스에서 기본 키 조회
aws dynamodb query \
  --table-name Employee \
  --index-name GSI_KeysOnly \
  --key-condition-expression "department = :dept" \
  --expression-attribute-values '{":dept": {"S": "Engineering"}}'

# 2단계: 반환된 emp_id로 본 테이블에서 전체 정보 조회
aws dynamodb get-item \
  --table-name Employee \
  --key '{"emp_id": {"S": "e001"}}'

INCLUDE 옵션

name과 position은 바로 조회가 가능하며 다른 속성은 key_only옵션처럼 본테이블에서 조회가 필요합니다.

# 생성
aws dynamodb update-table \
  --table-name Employee \
  --global-secondary-index-updates \
    '[{
      "Create": {
        "IndexName": "GSI_Include",
        "KeySchema": [{"AttributeName":"department","KeyType":"HASH"}],
        "Projection": {
          "ProjectionType":"INCLUDE",
          "NonKeyAttributes":["name", "position"]
        }
      }
    }]'

# 조회
aws dynamodb query \
  --table-name Employee \
  --index-name GSI_Include \
  --key-condition-expression "department = :dept" \
  --expression-attribute-values '{":dept": {"S": "Engineering"}}'

[ LSI (Local Secondary Index) ]

LSI 생성

유저 활동의 로그 테이블

# Table Name: UserActivityLog
# Partition Key: user_id
# Sort Key: activity_time
# LSI: (Sort Key로 action_type 추가)

aws dynamodb create-table \
  --table-name UserActivityLog \
  --attribute-definitions \
      AttributeName=user_id,AttributeType=S \
      AttributeName=activity_time,AttributeType=S \
      AttributeName=action_type,AttributeType=S \
  --key-schema \
      AttributeName=user_id,KeyType=HASH \
      AttributeName=activity_time,KeyType=RANGE \
  --local-secondary-indexes \
      '[{
          "IndexName": "ActionTypeIndex",
          "KeySchema": [
            {"AttributeName": "user_id", "KeyType": "HASH"},
            {"AttributeName": "action_type", "KeyType": "RANGE"}
          ],
          "Projection": {
            "ProjectionType": "ALL"
          }
        }]'

LSI 조회

action_type 기준으로 조회

- PK + SK 의 조합이 아닌 PK + LSI 키로 조회 가능

aws dynamodb query \
  --table-name UserActivityLog \
  --index-name ActionTypeIndex \
  --key-condition-expression "user_id = :uid AND action_type = :atype" \
  --expression-attribute-values '{
    ":uid": {"S": "user123"},
    ":atype": {"S": "login"}
  }'

LSI 주의점

테이블 생성 시에만 정의 가능 : 반드시 처음에 정의해야 합니다.
같은 파티션 내 10GB 제한 : 하나의 파티션 키에 대한 총 크기가 10GB를 넘을 수 없습니다.
파티션 키는 동일 : LSI는 테이블의 PK와 같은 값을 공유합니다.
쓰기비용 : LSI도 데이터 복제가 필요하므로 쓰기 비용이 증가할 수 있습니다.

[ GSI와 LIS 차이 ]

항목	GSI	LSI
Partition Key	기본 테이블과 달라도 됨	기본 테이블의 PK와 같고 SK만 다르게 지정
생성 시점	언제든지	테이블 생성시에만
저장 위치	테이블과 별로도 저장	기본 테이블과 같은 파티션에 저장 (10GB 제한)
처리량	GSI 별도로 설정 또는 On-demand로 처리 가능	기본 테이블의 처리량을 공유함
쿼리 성능	다양한 키 조합 쿼리 가능	같은 PK내에서 다른 SK로 조회
비용	GSI 당 별도 비용	추가 비용 없음

[ 적용 예시 ]

테이블 스키마

PK: user_id
SK: timestamp

예시 1) 특정 유저의 특정 활동 유형만 조회

LSI: activity_type 로 지정

조회시 아래 키 사용
PK = user_id, 
SK = activity_type

예시 2) 특정 직무에서 월급이 높은 순으로 조회

GSI: position, salary 지정

조회 시 아래 키 사용
PK=position, 
SK=salary