Term-level and full-text queries compared

    OpenSearch uses the BM25 ranking algorithm to calculate relevance scores. To learn more, see Okapi BM25.

    To clarify the difference between full-text and term-level queries, consider the following two examples that search for a specific text phrase. The complete works of Shakespeare are indexed in an OpenSearch cluster.

    In this example, you’ll search the complete works of Shakespeare for the phrase “To be, or not to be” in the field.

    The response contains no matches, indicated by zero hits:

    1. {
    2.   "took" : 3,
    3.   "timed_out" : false,
    4.   "_shards" : {
    5.     "total" : 1,
    6.     "successful" : 1,
    7.     "skipped" : 0,
    8.     "failed" : 0
    9.   },
    10.   "hits" : {
    11.     "total" : {
    12.       "value" : 0,
    13.       "relation" : "eq"
    14.     },
    15.     "max_score" : null,
    16.     "hits" : [ ]
    17.   }
    18. }

    This is because the term “To be, or not to be” is searched literally in the inverted index, where only the analyzed values of the text fields are stored. Term-level queries aren’t suited for searching analyzed text fields because they often yield unexpected results. When working with text data, use term-level queries only for fields mapped as keyword.

    Now search for the same phrase using a full-text query:

    1. {
    2.   "took" : 19,
    3.   "timed_out" : false,
    4.   "_shards" : {
    5.     "total" : 1,
    6.     "successful" : 1,
    7.     "skipped" : 0,
    8.     "failed" : 0
    9.   },
    10.   "hits" : {
    11.     "total" : {
    12.       "value" : 10000,
    13.       "relation" : "gte"
    14.     },
    15.     "max_score" : 17.419369,
    16.     "hits" : [
    17.       {
    18.         "_index" : "shakespeare",
    19.         "_id" : "34229",
    20.         "_score" : 17.419369,
    21.         "_source" : {
    22.           "type" : "line",
    23.           "line_id" : 34230,
    24.           "play_name" : "Hamlet",
    25.           "speech_number" : 19,
    26.           "line_number" : "3.1.64",
    27.           "text_entry" : "To be, or not to be: that is the question:"
    28.         }
    29.       },
    30.       {
    31.         "_index" : "shakespeare",
    32.         "_id" : "109930",
    33.         "_score" : 14.883024,
    34.         "_source" : {
    35.           "type" : "line",
    36.           "line_id" : 109931,
    37.           "play_name" : "A Winters Tale",
    38.           "speech_number" : 23,
    39.           "line_number" : "4.4.153",
    40.           "speaker" : "PERDITA",
    41.           "text_entry" : "Not like a corse; or if, not to be buried,"
    42.         }
    43.       },
    44.       {
    45.         "_index" : "shakespeare",
    46.         "_id" : "103117",
    47.         "_score" : 14.782743,
    48.         "_source" : {
    49.           "type" : "line",
    50.           "line_id" : 103118,
    51.           "play_name" : "Twelfth Night",
    52.           "speech_number" : 53,
    53.           "line_number" : "1.3.95",
    54.           "speaker" : "SIR ANDREW",
    55.           "text_entry" : "will not be seen; or if she be, its four to one"
    56.         }
    57.       }
    58.     ]
    59.   }
    60. }
    61. ...

    For a list of all full-text queries, see .

    If you want to search for an exact term like “HAMLET” in the speaker field and don’t need the results to be sorted by relevance score, a term-level query is more efficient:

    The response contains document matches:

    1. {
    2.   "took" : 5,
    3.   "timed_out" : false,
    4.   "_shards" : {
    5.     "total" : 1,
    6.     "successful" : 1,
    7.     "skipped" : 0,
    8.     "failed" : 0
    9.   },
    10.   "hits" : {
    11.     "total" : {
    12.       "value" : 1582,
    13.     },
    14.     "max_score" : 4.2540946,
    15.     "hits" : [
    16.       {
    17.         "_index" : "shakespeare",
    18.         "_id" : "32700",
    19.         "_score" : 4.2540946,
    20.         "_source" : {
    21.           "type" : "line",
    22.           "line_id" : 32701,
    23.           "play_name" : "Hamlet",
    24.           "speech_number" : 9,
    25.           "line_number" : "1.2.66",
    26.           "speaker" : "HAMLET",
    27.           "text_entry" : "[Aside]  A little more than kin, and less than kind."
    28.         }
    29.       },
    30.       {
    31.         "_index" : "shakespeare",
    32.         "_id" : "32702",
    33.         "_score" : 4.2540946,
    34.         "_source" : {
    35.           "type" : "line",
    36.           "line_id" : 32703,
    37.           "play_name" : "Hamlet",
    38.           "speech_number" : 11,
    39.           "line_number" : "1.2.68",
    40.           "speaker" : "HAMLET",
    41.           "text_entry" : "Not so, my lord; I am too much i' the sun."
    42.         }
    43.       },
    44.       {
    45.         "_index" : "shakespeare",
    46.         "_id" : "32709",
    47.         "_score" : 4.2540946,
    48.         "_source" : {
    49.           "type" : "line",
    50.           "line_id" : 32710,
    51.           "play_name" : "Hamlet",
    52.           "speech_number" : 13,
    53.           "line_number" : "1.2.75",
    54.           "speaker" : "HAMLET",
    55.           "text_entry" : "Ay, madam, it is common."
    56.         }
    57.       }
    58.     ]
    59.   }