데이터 관리

데이터 관리 (Data management) API

Apache Druid의 데이터 관리 API 엔드포인트를 다룹니다. 세그먼트를 used/unused로 표시하고 Druid에서 삭제하는 방법을 설명해요.

출처: 문서

본문

이 문서는 Apache Druid의 데이터 관리 API 엔드포인트를 설명합니다. 세그먼트를 used 또는 unused로 표시하고 Druid에서 삭제하는 방법에 대한 정보를 포함합니다.

이 문서에서 http://ROUTER_IP:ROUTER_PORT는 여러분의 Router 서비스 주소와 포트를 위한 자리표시자입니다. 이를 배포 정보로 교체하세요. 예를 들어 quickstart 배포라면 http://localhost:8888을 사용합니다.

참고: 데이터 관리를 위한 Coordinator API는 이제 비권장(deprecated)입니다. 대신 Overlord가 제공하는 새 API를 사용하세요.

같은 데이터소스와 간격에 대해 인덱싱 태스크나 kill 태스크가 진행 중일 때는 이 API들을 사용하지 마세요.

세그먼트 관리 (Segment management)

데이터소스에 POST 요청을 보내 세그먼트를 used로 표시할 수 있지만, Coordinator는 구성된 드롭 규칙을 충족하는 세그먼트를 이후에 unused로 표시할 수 있어요. 이 API 요청들이 세그먼트를 used로 업데이트하더라도, Historical 프로세스에 로드하려면 여전히 로드 규칙을 구성해야 합니다.

이 API들을 인덱싱 태스크나 kill 태스크와 동시에 사용하면 동작이 정의되지 않습니다. Druid는 일부 세그먼트를 종료하고 다른 세그먼트를 used로 표시해요. 또한 모든 세그먼트가 unused가 될 수 있는데도 인덱싱 태스크가 이 세그먼트들에서 데이터를 읽고 성공적으로 완료될 가능성도 있어요.

Segment deletion을 제외한 아래 모든 API는 Overlord가 제공합니다. Overlord는 인덱싱 태스크를 대신해 세그먼트 메타데이터에 작업을 수행하는 서비스이기 때문이에요. 이로써 Overlord가 세그먼트 메타데이터의 단일 진실 소스(single source of truth)가 되어 Druid 클러스터 전반에서 일관된 뷰를 보장하고, Overlord가 성능 개선을 위해 메타데이터를 캐시할 수 있게 합니다.

세그먼트 ID

이 문서에 설명된 많은 엔드포인트를 사용할 때는 세그먼트 ID를 제공해야 합니다. 세그먼트 ID에 대한 자세한 내용은 Segment identification을 참고하세요. 웹 콘솔에서 세그먼트 ID를 찾는 방법은 Segments를 참고하세요.

단일 세그먼트를 unused로 표시

세그먼트 ID를 사용해 세그먼트의 상태를 unused로 표시합니다. 이것은 Historical에서 세그먼트를 "소프트 삭제(soft delete)"하는 것입니다. 이 작업을 되돌리려면 세그먼트를 used로 표시하세요.

이 엔드포인트는 세그먼트 ID나 데이터소스가 존재하지 않아도 HTTP 200 OK 응답 코드를 반환합니다. 실제로 세그먼트가 업데이트되었는지 응답 페이로드를 확인하세요.

URL

DELETE /druid/indexer/v1/datasources/{datasource}/segments/{segmentId}

헤더

이 요청에는 다음 헤더가 필요합니다.

Content-Type: application/json
Accept: application/json, text/plain

응답

• 200 SUCCESS — 세그먼트를 성공적으로 업데이트함

샘플 요청

다음 예시는 wikipedia_hour 데이터소스의 세그먼트 wikipedia_hour_2015-09-12T16:00:00.000Z_2015-09-12T17:00:00.000Z_2023-08-10T04:12:03.860Z를 unused로 업데이트합니다.

cURL

curl --request DELETE "http://ROUTER_IP:ROUTER_PORT/druid/indexer/v1/datasources/wikipedia_hour/segments/wikipedia_hour_2015-09-12T16:00:00.000Z_2015-09-12T17:00:00.000Z_2023-08-10T04:12:03.860Z" \
--header 'Content-Type: application/json' \
--header 'Accept: application/json, text/plain'

HTTP

DELETE /druid/indexer/v1/datasources/wikipedia_hour/segments/wikipedia_hour_2015-09-12T16:00:00.000Z_2015-09-12T17:00:00.000Z_2023-08-10T04:12:03.860Z HTTP/1.1
Host: http://ROUTER_IP:ROUTER_PORT
Content-Type: application/json
Accept: application/json, text/plain

샘플 응답

{
    "segmentStateChanged": true,
    "numChangedSegments": 1
}

단일 세그먼트를 used로 표시

세그먼트 ID를 사용해 세그먼트의 상태를 used로 표시합니다.

URL

POST /druid/indexer/v1/datasources/{datasource}/segments/{segmentId}

헤더

이 요청에는 다음 헤더가 필요합니다.

Content-Type: application/json
Accept: application/json, text/plain

응답

• 200 SUCCESS — 세그먼트를 성공적으로 업데이트함

샘플 요청

다음 예시는 ID가 wikipedia_hour_2015-09-12T18:00:00.000Z_2015-09-12T19:00:00.000Z_2023-08-10T04:12:03.860Z인 세그먼트를 used로 업데이트합니다.

cURL

curl --request POST "http://ROUTER_IP:ROUTER_PORT/druid/indexer/v1/datasources/wikipedia_hour/segments/wikipedia_hour_2015-09-12T18:00:00.000Z_2015-09-12T19:00:00.000Z_2023-08-10T04:12:03.860Z" \
--header 'Content-Type: application/json' \
--header 'Accept: application/json, text/plain'

HTTP

POST /druid/indexer/v1/datasources/wikipedia_hour/segments/wikipedia_hour_2015-09-12T18:00:00.000Z_2015-09-12T19:00:00.000Z_2023-08-10T04:12:03.860Z HTTP/1.1
Host: http://ROUTER_IP:ROUTER_PORT
Content-Type: application/json
Accept: application/json, text/plain

샘플 응답

{
    "segmentStateChanged": true,
    "numChangedSegments": 1
}

세그먼트 그룹을 unused로 표시

세그먼트 ID 배열이나 간격을 사용해 세그먼트 그룹의 상태를 unused로 표시합니다. 세그먼트 ID 배열이나 간격을 요청 본문의 JSON 객체로 전달하세요.

간격의 경우 시작·종료 시간을 ISO 8601 문자열로 지정해 시작 시간을 포함하고 종료 시간을 제외한 세그먼트를 식별합니다. 선택적으로 간격과 함께 세그먼트 버전 배열을 지정할 수 있어요. Druid는 지정된 간격에 완전히 포함되고 선택적 버전 목록과 일치하는 세그먼트만 업데이트합니다. 부분적으로 겹치는 세그먼트는 영향받지 않아요.

URL

POST /druid/indexer/v1/datasources/{datasource}/markUnused

요청 본문

세그먼트 그룹은 다음 속성을 받는 JSON 요청 페이로드로 전송됩니다.

속성	설명	필수	예시
interval	ISO 8601 세그먼트 간격	segmentIds가 지정되지 않으면 필수	"2015-09-12T03:00:00.000Z/2015-09-12T05:00:00.000Z"
segmentIds	세그먼트 ID 목록	interval이 지정되지 않으면 필수	["segmentId1", "segmentId2"]
versions	세그먼트 버전 목록. interval과 함께 제공해야 함	아니요	["2024-03-14T16:00:04.086Z", "2024-03-12T16:00:04.086Z"]

응답

• 200 SUCCESS — 세그먼트를 성공적으로 업데이트함
• 204 NO CONTENT — 잘못된 데이터소스 이름
• 400 BAD REQUEST — 잘못된 요청 페이로드

샘플 요청

다음 예시는 세그먼트 ID를 기준으로 wikipedia_hour 데이터소스의 두 세그먼트를 unused로 표시합니다.

cURL

curl "http://ROUTER_IP:ROUTER_PORT/druid/indexer/v1/datasources/wikipedia_hour/markUnused" \
--header 'Content-Type: application/json' \
--data '{
    "segmentIds": [
        "wikipedia_hour_2015-09-12T14:00:00.000Z_2015-09-12T15:00:00.000Z_2023-08-10T04:12:03.860Z",
        "wikipedia_hour_2015-09-12T04:00:00.000Z_2015-09-12T05:00:00.000Z_2023-08-10T04:12:03.860Z"
    ]
}'

HTTP

POST /druid/indexer/v1/datasources/wikipedia_hour/markUnused HTTP/1.1
Host: http://ROUTER_IP:ROUTER_PORT
Content-Type: application/json
Content-Length: 230

{
    "segmentIds": [
        "wikipedia_hour_2015-09-12T14:00:00.000Z_2015-09-12T15:00:00.000Z_2023-08-10T04:12:03.860Z",
        "wikipedia_hour_2015-09-12T04:00:00.000Z_2015-09-12T05:00:00.000Z_2023-08-10T04:12:03.860Z"
    ]
}

샘플 응답

{
    "numChangedSegments": 2
}

세그먼트 그룹을 used로 표시

세그먼트 ID 배열이나 간격을 사용해 세그먼트 그룹의 상태를 used로 표시합니다. 세그먼트 ID 배열이나 간격을 요청 본문의 JSON 객체로 전달하세요.

간격의 경우 시작·종료 시간을 ISO 8601 문자열로 지정해 시작 시간을 포함하고 종료 시간을 제외한 세그먼트를 식별합니다. 선택적으로 간격과 함께 세그먼트 버전 배열을 지정할 수 있어요. Druid는 지정된 간격에 완전히 포함되고 선택적 버전 목록과 일치하는 세그먼트만 업데이트합니다. 부분적으로 겹치는 세그먼트는 영향받지 않아요.

URL

POST /druid/indexer/v1/datasources/{datasource}/markUsed

요청 본문

세그먼트 그룹은 다음 속성을 받는 JSON 요청 페이로드로 전송됩니다.

속성	설명	필수	예시
interval	ISO 8601 세그먼트 간격	segmentIds가 지정되지 않으면 필수	"2015-09-12T03:00:00.000Z/2015-09-12T05:00:00.000Z"
segmentIds	세그먼트 ID 목록	interval이 지정되지 않으면 필수	["segmentId1", "segmentId2"]
versions	세그먼트 버전 목록. interval과 함께 제공해야 함	아니요	["2024-03-14T16:00:04.086Z", "2024-03-12T16:00:04.086Z"]

응답

• 200 SUCCESS — 세그먼트를 성공적으로 업데이트함
• 204 NO CONTENT — 잘못된 데이터소스 이름
• 400 BAD REQUEST — 잘못된 요청 페이로드

샘플 요청

다음 예시는 세그먼트 ID를 기준으로 wikipedia_hour 데이터소스의 두 세그먼트를 used로 표시합니다.

cURL

curl "http://ROUTER_IP:ROUTER_PORT/druid/indexer/v1/datasources/wikipedia_hour/markUsed" \
--header 'Content-Type: application/json' \
--data '{
    "segmentIds": [
        "wikipedia_hour_2015-09-12T14:00:00.000Z_2015-09-12T15:00:00.000Z_2023-08-10T04:12:03.860Z",
        "wikipedia_hour_2015-09-12T04:00:00.000Z_2015-09-12T05:00:00.000Z_2023-08-10T04:12:03.860Z"
    ]
}'

HTTP

POST /druid/indexer/v1/datasources/wikipedia_hour/markUsed HTTP/1.1
Host: http://ROUTER_IP:ROUTER_PORT
Content-Type: application/json
Content-Length: 230

{
    "segmentIds": [
        "wikipedia_hour_2015-09-12T14:00:00.000Z_2015-09-12T15:00:00.000Z_2023-08-10T04:12:03.860Z",
        "wikipedia_hour_2015-09-12T04:00:00.000Z_2015-09-12T05:00:00.000Z_2023-08-10T04:12:03.860Z"
    ]
}

샘플 응답

{
    "numChangedSegments": 2
}

모든 세그먼트를 unused로 표시

데이터소스의 모든 세그먼트 상태를 unused로 표시합니다. 이 작업은 Historical에서 세그먼트를 "소프트 삭제"합니다.

이 엔드포인트는 데이터소스가 존재하지 않아도 HTTP 200 OK 응답 코드를 반환합니다. 실제로 세그먼트가 업데이트되었는지 응답 페이로드를 확인하세요.

URL

DELETE /druid/indexer/v1/datasources/{datasource}

응답

• 200 SUCCESS — 세그먼트를 성공적으로 업데이트함

샘플 요청

cURL

curl --request DELETE "http://ROUTER_IP:ROUTER_PORT/druid/indexer/v1/datasources/wikipedia_hour"

HTTP

DELETE /druid/indexer/v1/datasources/wikipedia_hour HTTP/1.1
Host: http://ROUTER_IP:ROUTER_PORT

샘플 응답

{
    "numChangedSegments": 24
}

모든 non-overshadowed 세그먼트를 used로 표시

다른 세그먼트에 의해 이미 overshadowed 되지 않은 데이터소스의 모든 unused 세그먼트 상태를 used로 표시합니다. 이 엔드포인트는 변경된 세그먼트 수를 반환합니다.

이 엔드포인트는 데이터소스가 존재하지 않아도 HTTP 200 OK 응답 코드를 반환합니다. 실제로 업데이트된 세그먼트 수를 얻으려면 응답 페이로드를 확인하세요.

URL

POST /druid/indexer/v1/datasources/{datasource}

헤더

이 요청에는 다음 헤더가 필요합니다.

Content-Type: application/json
Accept: application/json, text/plain

응답

• 200 SUCCESS — 세그먼트를 성공적으로 업데이트함

샘플 요청

다음 예시는 wikipedia_hour의 모든 unused 세그먼트를 used로 업데이트합니다. wikipedia_hour에는 used로 표시할 자격이 있는 unused 세그먼트가 하나 있습니다.

cURL

curl --request POST "http://ROUTER_IP:ROUTER_PORT/druid/indexer/v1/datasources/wikipedia_hour" \
--header 'Content-Type: application/json' \
--header 'Accept: application/json, text/plain'

HTTP

POST /druid/indexer/v1/datasources/wikipedia_hour HTTP/1.1
Host: http://ROUTER_IP:ROUTER_PORT
Content-Type: application/json
Accept: application/json, text/plain

샘플 응답

{
    "numChangedSegments": 1
}

세그먼트 삭제 (Segment deletion)

세그먼트 영구 삭제

DELETE 엔드포인트는 주어진 간격과 데이터소스에 대해 kill 태스크를 보냅니다. 간격 값은 _로 구분된 ISO 8601 문자열입니다. 이 요청은 unused 세그먼트의 모든 메타데이터를 영구 삭제하고 딥 스토리지에서 제거합니다.

이 엔드포인트는 데이터소스가 존재하지 않아도 HTTP 200 OK 응답 코드를 반환합니다.

이 엔드포인트는 비권장 엔드포인트 DELETE /druid/coordinator/v1/datasources/{datasource}?kill=true&interval={interval}을 대체합니다.

URL

DELETE /druid/coordinator/v1/datasources/{datasource}/intervals/{interval}

응답

• 200 SUCCESS — kill 태스크를 성공적으로 보냄

샘플 요청

다음 예시는 2015-09-12부터 2015-09-13까지의 간격에서 wikipedia_hour 데이터소스의 세그먼트를 영구 삭제하는 kill 태스크를 보냅니다.

cURL

curl --request DELETE "http://ROUTER_IP:ROUTER_PORT/druid/coordinator/v1/datasources/wikipedia_hour/intervals/2015-09-12_2015-09-13"

HTTP

DELETE /druid/coordinator/v1/datasources/wikipedia_hour/intervals/2015-09-12_2015-09-13 HTTP/1.1
Host: http://ROUTER_IP:ROUTER_PORT

샘플 응답

성공한 요청은 HTTP 200 OK와 빈 응답 본문을 반환합니다.

더 알아보기 (Learn more)

• 세그먼트 식별 방법은 segment identification 문서를 참고하세요.
• 데이터 관리 개념은 data management 문서에서 확인해 보세요.