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

[ 문서 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
            },
            ...
          ]
     }
   }
}