쿼리 검증 API

쿼리 검증 API (Validate Query API)

Validate Query API를 사용하면 쿼리를 실행하지 않고 검증할 수 있어요. 쿼리는 경로 파라미터로 보내거나 요청 본문에 포함할 수 있어요.

도입 버전 1.0

엔드포인트

Validate Query API는 다음 경로를 포함해요:

GET {index}/_validate/query

경로 파라미터

모든 경로 파라미터는 선택 사항이에요.

파라미터	데이터 타입	설명
index	String	쿼리를 검증할 인덱스예요. URL에 인덱스나 여러 인덱스를 지정하지 않았거나(개별 검색에 대해 URL 값을 덮어쓰고 싶은 경우) 여기에 포함할 수 있어요. `"logs-*"`나 `["my-store", "sample_data_ecommerce"]` 같은 예가 있어요.
query	Query 객체	Query DSL 을 사용한 쿼리예요.

쿼리 파라미터

다음 표는 사용 가능한 쿼리 파라미터를 보여줘요. 모든 쿼리 파라미터는 선택 사항이에요.

파라미터	데이터 타입	설명
all_shards	Boolean	true 면 인덱스당 하나의 샤드 대신 모든 샤드에 대해 검증을 실행해요. 기본값은 false 예요.
allow_no_indices	Boolean	어떤 인덱스와도 일치하지 않는 와일드카드를 무시할지 여부예요. 기본값은 true 예요.
allow_partial_search_results	Boolean	요청에서 오류가 발생하거나 타임아웃되면 부분 결과를 반환할지 여부예요. 기본값은 true 예요.
analyzer	String	쿼리 문자열에서 사용할 분석기(analyzer)예요. q 옵션에서만 사용해야 해요.
analyze_wildcard	Boolean	와일드카드 및 접두어 쿼리를 분석할지 여부를 지정해요. 기본값은 false 예요.
default_operator	String	문자열 쿼리의 기본 연산자가 AND 인지 OR 인지 나타내요. 기본값은 OR 예요.
df	String	쿼리 문자열에 필드 접두어가 제공되지 않을 때의 기본 필드예요.
expand_wildcards	String	와일드카드 표현식이 일치할 수 있는 인덱스 유형을 지정해요. 쉼표로 구분된 값을 지원해요. 유효한 값은 all (모든 인덱스 일치), open (열려 있고 숨겨지지 않은 인덱스 일치), closed (닫혀 있고 숨겨지지 않은 인덱스 일치), hidden (숨겨진 인덱스 일치), none (와일드카드 표현식 거부)이에요. 기본값은 open 이에요.
explain	Boolean	OpenSearch가 문서의 score 를 어떻게 계산했는지에 대한 정보를 반환할지 여부예요. 기본값은 false 예요.
ignore_unavailable	Boolean	없는 인덱스나 닫힌 인덱스를 응답에 포함할지 지정하고, 검색 요청 중 사용할 수 없는 샤드를 무시할지 여부예요. 기본값은 false 예요.
lenient	Boolean	OpenSearch가 형식 기반 쿼리 실패(예: 텍스트 필드를 정수로 쿼리한 경우)를 무시할지 지정해요. 기본값은 false 예요.
rewrite	다중 항목 쿼리를 OpenSearch가 다시 작성하고 점수를 매기는 방식을 결정해요. 유효한 값은 constant_score , scoring_boolean , constant_score_boolean , top_terms_N , top_terms_boost_N , top_terms_blended_freqs_N 이에요. 기본값은 constant_score 예요.
q	String	Lucene 문자열 구문의 쿼리예요.

예제 요청

다음 예제 요청은 bulk 요청으로 생성한 Hamlet이라는 이름의 인덱스를 사용해요:

PUT /hamlet/_bulk?refresh
{"index":{"_id":1}}
{"user" : { "id": "hamlet" }, "@timestamp" : "2099-11-15T14:12:12", "message" : "To Search or Not To Search"}
{"index":{"_id":2}}
{"user" : { "id": "hamlet" }, "@timestamp" : "2099-11-15T14:12:13", "message" : "My dad says that I'm such a ham."}

그런 다음 Validate Query API를 사용해 인덱스 쿼리를 검증할 수 있어요. 다음 예제를 보세요:

GET /hamlet/_validate/query?q=user.id:hamlet

쿼리는 다음 예제처럼 요청 본문으로도 보낼 수 있어요:

GET /hamlet/_validate/query
{
  "query": {
    "bool": {
      "must": {
        "query_string": {
          "query": "*:*"
        }
      },
      "filter": {
        "term": {
          "user.id": "hamlet"
        }
      }
    }
  }
}

예제 응답

쿼리가 검증을 통과하면 응답은 쿼리가 true임을 나타내요. 다음 예제 응답처럼 valid 파라미터가 true예요:

{
  "_shards": {
    "total": 1,
    "successful": 1,
    "failed": 0
  },
  "valid": true
}

쿼리가 검증을 통과하지 못하면 OpenSearch는 쿼리가 false라고 응답해요. 다음 예제 요청 쿼리에는 hamlet 인덱스에 구성되지 않은 동적 매핑이 포함되어 있어요:

GET /hamlet/_validate/query
{
  "query": {
    "query_string": {
      "query": "@timestamp:foo",
      "lenient": false
    }
  }
}

OpenSearch는 다음과 같이 응답하며 valid 파라미터는 false예요:

{
  "_shards": {
    "total": 1,
    "successful": 1,
    "failed": 0
  },
  "valid": false
}

특정 쿼리 파라미터는 응답에 포함되는 내용에도 영향을 줄 수 있어요. 다음 예제들은 Explain, Rewrite, all_shards 쿼리 옵션이 응답에 어떻게 영향을 주는지 보여줘요.

Explain

explain 옵션은 다음 예제 응답처럼 쿼리 실패에 대한 정보를 explanations 필드에 반환해요:

{
  "valid" : false,
  "_shards" : {
    "total" : 1,
    "successful" : 1,
    "failed" : 0
  },
  "explanations" : [ {
    "index" : "_shakespeare",
    "valid" : false,
    "error" : "shakespeare/IAEc2nIXSSunQA_suI0MLw] QueryShardException[failed to create query:...failed to parse date field [foo]"
  } ]
}

Rewrite

요청에서 rewrite 옵션을 true로 설정하면 explanations 옵션은 다음 응답처럼 실행되는 Lucene 쿼리를 문자열로 보여줘요:

{
   "valid": true,
   "_shards": {
      "total": 1,
      "successful": 1,
      "failed": 0
   },
   "explanations": [
      {
         "index": "",
         "valid": true,
         "explanation": "((user:hamlet^4.256753 play:hamlet^6.863601 play:romeo^2.8415773 plot:puck^3.4193945 plot:othello^3.8244398 ... )~4) -ConstantScore(_id:2) #(ConstantScore(_type:_doc))^0.0"
      }
   ]
}

Rewrite와 all_shards

rewrite와 all_shards 옵션을 모두 true로 설정하면 Validate Query API는 기본값인 샤드 하나 대신 사용 가능한 모든 샤드의 자세한 정보로 응답해요. 다음 응답을 보세요:

{
  "valid": true,
  "_shards": {
    "total": 1,
    "successful": 1,
    "failed": 0
  },
  "explanations": [
    {
      "index": "my-index-000001",
      "shard": 0,
      "valid": true,
      "explanation": "(user.id:hamlet)^0.6333333"
    }
  ]
}

필요한 권한

Security 플러그인을 사용한다면 적절한 권한이 있는지 확인하세요: indices:admin/validate/query.

출처: 문서