Count API

Count API

1.0에서 도입

Count API는 쿼리와 일치하는 문서의 수를 반환해요. 인덱스, 데이터 스트림, 클러스터의 문서 수를 조회하는 데 쓸 수 있어요. 흔한 사용 사례는 다음과 같아요.

  • 실제 문서를 조회하지 않고 인덱스나 데이터 스트림의 총 문서 수를 가져오기
  • 특정 기준과 일치하는 문서를 세어 데이터가 올바르게 색인되었는지 확인하기
  • 서로 다른 시점의 문서 수를 추적해서 시간에 따른 데이터 증가를 모니터링하기
  • 비용이 큰 검색 작업을 실행하기 전에 먼저 일치 문서 수를 가져와 쿼리 결과를 검증하기

Count API는 size: 0인 Search API를 쓸 때보다 문서 수만 필요할 때 더 효율적이에요. 카운트 작업에 특화되어 최적화되어 있기 때문이에요. 성능을 높이기 위해 OpenSearch는 카운트 쿼리를 모든 샤드에 병렬로 분산해요. 각 샤드는 사용 가능한 복제본 중 하나로 요청을 처리하므로, 복제본 수가 늘어나면 수평 확장이 가능해요.

또는 CAT Indices API나 CAT Count API를 사용해서 각 인덱스나 데이터 스트림의 문서 수를 조회할 수도 있어요.

출처: 문서

본문

엔드포인트 (Endpoints)

GET  /_count
POST /_count
GET  /{index}/_count
POST /{index}/_count

경로 매개변수 (Path parameters)

다음 표는 사용 가능한 경로 매개변수예요. 모든 경로 매개변수는 선택 사항이에요.

매개변수 데이터 타입 설명
index List 또는 String 검색할 데이터 스트림, 인덱스, 별칭의 쉼표로 구분된 목록이에요. 와일드카드(*)를 지원해요. 모든 데이터 스트림과 인덱스를 검색하려면 이 매개변수를 생략하거나 * 또는 _all을 사용해요.

쿼리 매개변수 (Query parameters)

다음 표는 사용 가능한 쿼리 매개변수예요. 모든 쿼리 매개변수는 선택 사항이에요.

매개변수 데이터 타입 설명 기본값
allow_no_indices Boolean false면 와일드카드 표현식, 인덱스 별칭, _all 값이 존재하지 않거나 닫힌 인덱스만 대상으로 하면 오류를 반환해요. 요청이 다른 열린 인덱스도 대상으로 하더라도 마찬가지예요. N/A
analyze_wildcard Boolean true면 와일드카드·prefix 쿼리가 분석돼요. 이 매개변수는 q 쿼리 문자열 매개변수가 지정된 경우에만 사용할 수 있어요. false
analyzer String 쿼리 문자열에 사용할 애널라이저예요. 이 매개변수는 q 쿼리 문자열 매개변수가 지정된 경우에만 사용할 수 있어요. N/A
default_operator String 쿼리 문자열 쿼리의 기본 연산자: AND 또는 OR. 이 매개변수는 q 쿼리 문자열 매개변수가 지정된 경우에만 사용할 수 있어요. N/A
유효한 값은 and, AND, or, OR이에요.
df String 쿼리 문자열에서 필드 접두사가 주어지지 않을 때 기본으로 사용할 필드예요. 이 매개변수는 q 쿼리 문자열 매개변수가 지정된 경우에만 사용할 수 있어요. N/A
expand_wildcards List 또는 String 와일드카드 표현식이 일치할 수 있는 인덱스 유형을 지정해요. 쉼표로 구분된 값을 지원해요. N/A
유효한 값은 다음과 같아요:
- all: 숨은 인덱스를 포함해 모든 인덱스와 일치해요.
- closed: 닫힌, 숨지 않은 인덱스와 일치해요.
- hidden: 숨은 인덱스와 일치해요. open, closed 또는 둘 다와 함께 사용해야 해요.
- none: 와일드카드 표현식을 허용하지 않아요.
- open: 열린, 숨지 않은 인덱스와 일치해요.
ignore_throttled Boolean true면 고정(frozen)된 상태에서 구체적·확장·별칭 인덱스가 무시돼요. N/A
ignore_unavailable Boolean false면 존재하지 않거나 닫힌 인덱스를 대상으로 하면 오류를 반환해요. N/A
lenient Boolean true면 쿼리 문자열의 형식 기반 쿼리 실패(숫자 필드에 텍스트를 주는 등)가 무시돼요. N/A
min_score Float 문서가 결과에 포함되기 위해 가져야 하는 최소 _score 값을 설정해요. N/A
preference String 작업을 수행할 노드 또는 샤드를 지정해요. 기본은 무작위예요. random
q String Lucene 쿼리 문자열 구문의 쿼리예요. N/A
routing List 또는 String 작업을 특정 샤드로 라우팅하는 데 사용하는 사용자 지정 값이에요. N/A
terminate_after Integer 각 샤드에서 수집할 최대 문서 수예요. 쿼리가 이 제한에 도달하면 OpenSearch가 쿼리를 일찍 종료해요. OpenSearch는 정렬 전에 문서를 수집해요. N/A

요청 본문 필드 (Request body fields)

요청 본문은 선택 사항이에요. Query DSL로 정의한 쿼리로 결과를 제한하는 데 쓸 수 있어요.

필드 데이터 타입 설명
query Object 문서를 필터링하는 데 사용하는 쿼리예요. 지정하지 않으면 match_all 쿼리로 대상의 모든 문서를 세어요. OpenSearch 쿼리에 대한 자세한 내용은 Query DSL을 참고해요.

예시: 클러스터의 모든 문서 세기 (Counting all documents in a cluster)

다음 예시 요청은 전체 클러스터의 모든 문서 총 개수를 반환해요:

GET /_count

Python 클라이언트로는 이렇게 호출해요:

response = client.count(
body = { "Insert body here" }
)

예시: 여러 인덱스의 모든 문서 세기 (Counting all documents in several indexes)

다음 예시 요청은 movies와 tv_shows 인덱스의 모든 문서 총 개수를 반환해요:

GET /movies,tv_shows/_count

Python 클라이언트로는 이렇게 호출해요:

response = client.count(
index = "movies,tv_shows",
body = { "Insert body here" }
)

예시: 쿼리와 일치하는 문서 세기 (Counting documents that match a query)

다음 예시 요청은 movies 인덱스에서 genre 필드가 drama인 문서를 세어요:

POST /movies/_count
{
"query": {
"term": {
"genre": "drama"
}
}
}

Python 클라이언트로는 이렇게 호출해요:

response = client.count(
index = "movies",
body =   {
"query": {
"term": {
"genre": "drama"
}
}
}
)

예시: 쿼리 문자열로 문서 세기 (Counting documents using a query string)

다음 예시 요청은 q 쿼리 매개변수를 사용해서 genre 필드가 drama인 문서를 세어요:

GET /movies/_count?q=genre:drama

Python 클라이언트로는 이렇게 호출해요:

response = client.count(
index = "movies",
params = { "q": "genre:drama" },
body = { "Insert body here" }
)

예시: 조기 종료로 문서 세기 (Counting documents with early termination)

다음 예시 요청은 terminate_after 매개변수를 사용해서 일치 문서 3개를 찾은 뒤 카운트를 중단해요:

POST /movies/_count?terminate_after=3
{
"query": {
"match_all": {}
}
}

Python 클라이언트로는 이렇게 호출해요:

response = client.count(
index = "movies",
params = { "terminate_after": "3" },
body =   {
"query": {
"match_all": {}
}
}
)

예시 응답 (Example response)

다음 예시 응답은 문서 개수와 샤드 정보를 보여줘요:

{
"count" : 7,
"_shards" : {
"total" : 1,
"successful" : 1,
"skipped" : 0,
"failed" : 0
}
}

terminate_after 매개변수를 사용하면 응답에 terminated_early 필드가 포함돼요:

{
"terminated_early" : true,
"count" : 7,
"_shards" : {
"total" : 1,
"successful" : 1,
"skipped" : 0,
"failed" : 0
}
}

응답 본문 필드 (Response body fields)

Count API 응답에는 다음 필드가 들어 있어요.

필드 데이터 타입 설명
count Integer 쿼리와 일치하는 총 문서 수예요. 쿼리가 제공되지 않으면 지정된 대상의 모든 문서 수를 나타내요.
_shards Object 카운트 작업에 관련된 샤드에 대한 정보를 담고 있어요.
_shards.total Integer 카운트 작업에 조회된 총 샤드 수예요.
_shards.successful Integer 카운트 작업을 성공적으로 실행한 샤드 수예요.
_shards.skipped Integer 카운트 작업 중 건너뛴 샤드 수예요. 쿼리와 일치하는 문서가 없으면 샤드를 건너뛸 수 있어요.
_shards.failed Integer 카운트 작업 실행에 실패한 샤드 수예요. 이 값이 0보다 크면 클러스터 건강과 샤드 할당을 확인해요.
terminated_early Boolean terminate_after 쿼리 매개변수를 사용할 때만 나타나요. true면 모든 일치 문서를 세기 전에 카운트 작업이 종료됐다는 뜻이에요.

필요한 권한 (Required permissions)

Security 플러그인을 사용한다면 적절한 권한이 있는지 확인해야 해요: indices:data/read/search.

더 알아보기