Match 쿼리

Match 쿼리

match 쿼리를 사용해 특정 문서 필드에서 전문(full-text) 검색을 수행할 수 있어요. text 필드에서 실행하면 제공된 검색 문자열을 분석하고 문자열의 어떤 용어와라도 일치하는 문서를 반환합니다.

출처: 문서

본문

match 쿼리를 사용해 특정 문서 필드에서 전문 검색을 수행하세요. text 필드에서 match 쿼리를 실행하면 제공된 검색 문자열을 분석하고 문자열의 어떤 용어와라도 일치하는 문서를 반환해요. 정확한 값 필드에서 match 쿼리를 실행하면 정확한 값과 일치하는 문서를 반환해요. 정확한 값 필드를 검색할 때는 filter를 사용하는 것이 선호돼요. 쿼리와 달리 filter는 캐시되기 때문이에요.

다음 예시는 title에서 단어 wind에 대한 기본 match 쿼리를 보여줘요.

GET _search
{
  "query": {
    "match": {
      "title": "wind"
    }
  }
}

추가 파라미터를 전달하려면 확장 구문을 사용할 수 있어요.

GET _search
{
  "query": {
    "match": {
      "title": {
        "query": "wind",
        "analyzer": "stop"
      }
    }
  }
}

예시 (Examples)

다음 예시에서는 다음 문서를 포함하는 인덱스를 사용해요.

PUT testindex/_doc/1
{
  "title": "Let the wind rise"
}

PUT testindex/_doc/2
{
  "title": "Gone with the wind"
  
}

PUT testindex/_doc/3
{
  "title": "Rise is gone"
}

연산자 (Operator)

text 필드에서 match 쿼리를 실행하면 텍스트가 analyzer 파라미터에 지정된 분석기로 분석돼요. 그런 다음 결과 토큰들이 operator 파라미터에 지정된 연산자를 사용해 Boolean 쿼리로 결합돼요. 기본 연산자는 OR이므로 쿼리 wind rise는 wind OR rise로 바뀌어요. 이 예시에서 이 쿼리는 각 문서가 쿼리와 일치하는 용어를 하나씩 가지므로 문서 1–3을 반환해요. and 연산자를 지정하려면 다음 쿼리를 사용하세요.

GET testindex/_search
{
  "query": {
    "match": {
      "title": {
        "query": "wind rise",
        "operator": "and"
      }
    }
  }
}

쿼리는 wind AND rise로 구성되고 문서 1을 일치 문서로 반환해요.

응답

{
  "took": 17,
  "timed_out": false,
  "_shards": {
    "total": 1,
    "successful": 1,
    "skipped": 0,
    "failed": 0
  },
  "hits": {
    "total": {
      "value": 1,
      "relation": "eq"
    },
    "max_score": 1.2667098,
    "hits": [
      {
        "_index": "testindex",
        "_id": "1",
        "_score": 1.2667098,
        "_source": {
          "title": "Let the wind rise"
        }
      }
    ]
  }
}

Minimum should match

minimum_should_match 파라미터를 지정해 문서가 결과에 반환되기 위해 일치해야 하는 최소 용어 수를 제어할 수 있어요.

GET testindex/_search
{
  "query": {
    "match": {
      "title": {
        "query": "wind rise",
        "operator": "or",
        "minimum_should_match": 2
      }
    }
  }
}

이제 문서는 두 용어 모두와 일치해야 하므로 문서 1만 반환돼요(and 연산자와 동일).

응답

{
  "took": 23,
  "timed_out": false,
  "_shards": {
    "total": 1,
    "successful": 1,
    "skipped": 0,
    "failed": 0
  },
  "hits": {
    "total": {
      "value": 1,
      "relation": "eq"
    },
    "max_score": 1.2667098,
    "hits": [
      {
        "_index": "testindex",
        "_id": "1",
        "_score": 1.2667098,
        "_source": {
          "title": "Let the wind rise"
        }
      }
    ]
  }
}

분석기 (Analyzer)

이 예시에서 분석기를 명시적으로 지정하지 않았으므로 기본 표준 분석기가 사용돼요. 기본 분석기는 형태소 분석을 수행하지 않으므로 the wind rises 쿼리를 실행하면 토큰 rises가 토큰 rise와 일치하지 않아 결과가 없어요. 검색 분석기를 바꾸려면 analyzer 필드에 지정하세요. 예를 들어 다음 쿼리는 english 분석기를 사용해요.

GET testindex/_search
{
  "query": {
    "match": {
      "title": {
        "query": "the wind rises",
        "operator": "and",
        "analyzer": "english"
      }
    }
  }
}

english 분석기는 불용어 the를 제거하고 형태소 분석을 수행해 토큰 wind와 rise를 만들어요. 후자 토큰이 문서 1과 일치하므로 결과에 반환돼요.

응답

{
  "took": 19,
  "timed_out": false,
  "_shards": {
    "total": 1,
    "successful": 1,
    "skipped": 0,
    "failed": 0
  },
  "hits": {
    "total": {
      "value": 1,
      "relation": "eq"
    },
    "max_score": 1.2667098,
    "hits": [
      {
        "_index": "testindex",
        "_id": "1",
        "_score": 1.2667098,
        "_source": {
          "title": "Let the wind rise"
        }
      }
    ]
  }
}

빈 쿼리 (Empty query)

어떤 경우에는 분석기가 쿼리에서 모든 토큰을 제거할 수 있어요. 예를 들어 english 분석기는 불용어를 제거하므로 and OR or 쿼리에서는 모든 토큰이 제거돼요. 분석기 동작을 확인하려면 Analyze API를 사용할 수 있어요.

GET testindex/_analyze
{
  "analyzer" : "english",
  "text" : "and OR or"
}

예상대로 쿼리는 토큰을 생성하지 않아요.

{
  "tokens": []
}

빈 쿼리의 동작은 zero_terms_query 파라미터로 지정할 수 있어요. zero_terms_query를 all로 설정하면 인덱스의 모든 문서를 반환하고, none으로 설정하면 어떤 문서도 반환하지 않아요.

GET testindex/_search
{
  "query": {
    "match": {
      "title": {
        "query": "and OR or",
        "analyzer" : "english",
        "zero_terms_query": "all"
      }
    }
  }
}

퍼지 매칭 (Fuzziness)

오타를 처리하기 위해 쿼리에 fuzziness를 다음 중 하나로 지정할 수 있어요.

  • 이 편집에 대해 허용되는 최대 Damerau–Levenshtein 거리를 지정하는 정수.
  • AUTO: 0–2자의 문자열은 정확히 일치해야 함. 3–5자의 문자열은 1개 편집을 허용함. 5자보다 긴 문자열은 2개 편집을 허용함.

대부분의 경우 fuzziness를 AUTO 값으로 설정하는 것이 가장 잘 작동해요.

GET testindex/_search
{
  "query": {
    "match": {
      "title": {
        "query": "wnid",
        "fuzziness": "AUTO"
      }
    }
  }
}

토큰 wnid가 wind와 일치하고 쿼리가 문서 1과 2를 반환해요.

응답

{
  "took": 31,
  "timed_out": false,
  "_shards": {
    "total": 1,
    "successful": 1,
    "skipped": 0,
    "failed": 0
  },
  "hits": {
    "total": {
      "value": 2,
      "relation": "eq"
    },
    "max_score": 0.47501624,
    "hits": [
      {
        "_index": "testindex",
        "_id": "1",
        "_score": 0.47501624,
        "_source": {
          "title": "Let the wind rise"
        }
      },
      {
        "_index": "testindex",
        "_id": "2",
        "_score": 0.47501624,
        "_source": {
          "title": "Gone with the wind"
        }
      }
    ]
  }
}

접두사 길이 (Prefix length)

단어의 시작 부분에서는 오타가 드물게 발생해요. 따라서 문서가 결과에 반환되기 위해 일치된 접두사가 가져야 하는 최소 길이를 지정할 수 있어요. 예를 들어 앞의 쿼리에 prefix_length를 포함시킬 수 있어요.

GET testindex/_search
{
  "query": {
    "match": {
      "title": {
        "query": "wnid",
        "fuzziness": "AUTO",
        "prefix_length": 2
      }
    }
  }
}

앞의 쿼리는 결과를 반환하지 않아요. prefix_length를 1로 바꾸면 토큰 wnid의 첫 글자가 잘못되지 않았으므로 문서 1과 2가 반환돼요.

전치 (Transpositions)

앞의 예시에서 단어 wnid는 전치를 포함했어요(in이 ni로 바뀜). 기본적으로 퍼지 매칭에서 전치는 허용되지만 fuzzy_transpositions를 false로 설정해 허용하지 않을 수 있어요.

GET testindex/_search
{
  "query": {
    "match": {
      "title": {
        "query": "wnid",
        "fuzziness": "AUTO",
        "fuzzy_transpositions": false
      }
    }
  }
}

이제 쿼리는 결과를 반환하지 않아요.

동의어 (Synonyms)

synonym_graph 필터를 사용하고 auto_generate_synonyms_phrase_query가 true(기본값)로 설정되어 있으면 OpenSearch는 쿼리를 용어로 파싱한 뒤 용어들을 결합해 다중 용어 동의어에 대한 구문 쿼리를 생성해요. 예를 들어 ba,batting average를 동의어로 지정하고 ba를 검색하면 OpenSearch는 ba OR "batting average"를 검색해요.

auto_generate_synonyms_phrase_query를 false로 설정하면 다중 용어 동의어를 결합(conjunction)으로 매칭해요.

GET /testindex/_search
{
  "query": {
    "match": {
      "text": {
        "query": "good ba",
        "auto_generate_synonyms_phrase_query": false
      }
    }
  }
}

생성된 쿼리는 ba OR (batting AND average)예요.

파라미터 (Parameters)

이 쿼리는 필드 이름(<field>)을 최상위 파라미터로 받아들여요.

GET _search
{
  "query": {
    "match": {
      "": {
        "query": "text to search for",
        ... 
      }
    }
  }
}

<field>는 다음 파라미터를 받아들여요. query를 제외한 모든 파라미터는 선택 사항이에요.

파라미터 데이터 타입 설명
query String 검색에 사용할 쿼리 문자열. 필수.
auto_generate_synonyms_phrase_query Boolean 다중 용어 동의어에 대해 match phrase 쿼리를 자동으로 생성할지 여부를 지정함. 예를 들어 ba,batting average를 동의어로 지정하고 ba를 검색하면 OpenSearch는 (이 옵션이 true이면) ba OR "batting average"를 검색하거나 (이 옵션이 false이면) ba OR (batting AND average)를 검색함. 기본값은 true.
analyzer String 쿼리 문자열 텍스트를 토큰화하는 데 사용되는 분석기. 기본값은 default_field에 대해 지정된 인덱스 시점 분석기. default_field에 분석기가 지정되지 않으면 분석기는 인덱스의 기본 분석기. index.query.default_field에 대한 자세한 내용은 Dynamic index-level index settings를 참조하세요.
boost Floating-point 주어진 배수로 절을 부스트함. 복합 쿼리에서 절에 가중치를 두는 데 유용함. [0, 1) 범위의 값은 관련성을 낮추고 1보다 큰 값은 관련성을 높임. 기본값은 1.
enable_position_increments Boolean true이면 결과 쿼리가 위치 증가를 인식함. 이 설정은 불용어 제거가 용어 사이에 원치 않는 "간격"을 남길 때 유용함. 기본값은 true.
fuzziness String 용어가 값과 일치하는지 결정할 때 한 단어를 다른 단어로 바꾸는 데 필요한 문자 편집 수(삽입, 삭제, 대체 또는 전치). 예를 들어 wined와 wind 사이의 거리는 1. 유효한 값은 음이 아닌 정수 또는 AUTO. 기본값 AUTO는 검색 용어의 길이에 따라 편집 거리를 동적으로 선택함. AUTO:[low],[high] 구문을 사용해 임계값을 사용자 지정할 수 있는데, 여기서 low와 high는 문자 길이 경계를 정의함. 생략하면 OpenSearch는 기본값으로 AUTO:3,6을 사용하며, 이는 다음 규칙을 적용함. - 0–2자의 용어: 정확히 일치 필요(편집 0). - 3–5자의 용어: 최대 1개 편집 허용. - 6자 이상의 용어: 최대 2개 편집 허용. 예를 들어 AUTO:4,7은 0–3자의 용어에서 정확히 일치를 요구하고, 4–6자의 용어에서 최대 1개 편집을 허용하며, 7자 이상의 용어에서 최대 2개 편집을 허용함. 대부분의 시나리오에서는 AUTO 사용을 권장함.
fuzzy_rewrite String OpenSearch가 쿼리를 어떻게 재작성할지 결정함. 유효한 값은 constant_score, scoring_boolean, constant_score_boolean, top_terms_N, top_terms_boost_N, top_terms_blended_freqs_N. fuzziness 파라미터가 0이 아니면 쿼리는 기본적으로 top_terms_blended_freqs_${max_expansions}의 fuzzy_rewrite 방식을 사용함. 기본값은 constant_score.
fuzzy_transpositions Boolean fuzzy_transpositions를 true(기본값)로 설정하면 fuzziness 옵션의 삽입, 삭제, 대체 연산에 인접 문자 교체가 추가됨. 예를 들어 fuzzy_transpositions가 true이면 wind와 wnid 사이의 거리는 1("n"과 "i"를 교체)이고, false이면 2("n"을 삭제, "n"을 삽입). fuzzy_transpositions가 false이면 rewind와 wnid는 wind로부터 같은 거리(2)를 가지며, 더 인간 중심적인 의견상 wnid가 명백한 오타임에도 그렇음. 대부분의 사용 사례에서 기본값이 좋은 선택임.
lenient Boolean lenient를 true로 설정하면 쿼리와 문서 필드 사이의 데이터 타입 불일치를 무시함. 예를 들어 "8.2" 쿼리 문자열은 float 타입 필드와 일치할 수 있음. 기본값은 false.
max_expansions 양의 정수 쿼리가 확장할 수 있는 최대 용어 수. 퍼지 쿼리는 fuzziness에 지정된 거리 안에 있는 일치 용어 수로 "확장"됨. 그런 다음 OpenSearch는 그 용어들을 매칭하려 함. 기본값은 50.
minimum_should_match 양 또는 음의 정수, 양 또는 음의 백분율, 조합 쿼리 문자열에 여러 검색 용어가 있고 or 연산자를 사용하는 경우, 문서가 일치로 간주되기 위해 일치해야 하는 용어 수. 예를 들어 minimum_should_match가 2이면 wind often rising은 The Wind Rises와 일치하지 않음. minimum_should_match가 1이면 일치함. 자세한 내용은 Minimum should match를 참조하세요.
operator String 쿼리 문자열에 여러 검색 용어가 있을 때 문서가 일치로 간주되기 위해 모든 용어가 일치해야 하는지(AND) 아니면 하나의 용어만 일치해도 되는지(OR). 유효한 값은 다음과 같음. - OR: 문자열 to be는 to OR be로 해석됨. - AND: 문자열 to be는 to AND be로 해석됨. 기본값은 OR.
prefix_length 음이 아닌 정수 fuzziness에서 고려되지 않는 선행 문자 수. 기본값은 0.
zero_terms_query String 어떤 경우에는 분석기가 쿼리 문자열에서 모든 용어를 제거함. 예를 들어 stop 분석기는 an but this 문자열에서 모든 용어를 제거함. 이런 경우 zero_terms_query는 문서를 하나도 매칭하지 않을지(none) 모든 문서를 매칭할지(all)를 지정함. 유효한 값은 none과 all. 기본값은 none.

더 알아보기 (Learn more)