Full-text queries

match and required words

match analyzes input and builds term clauses. operator=or generally permits individual words; and requires all. minimum_should_match provides intermediate strictness. Absolute AND can lose useful products for long queries, so use quality evidence. Inputs reduced to no tokens by stop filters need a deliberate zero_terms_query policy.

Order and proximity

match_phrase uses positions. slop permits positional displacement and is not simply a count of extra words in every case: transposition has a cost too. A phrase query does not compare the entire original string because analysis has already happened. Whole-name equality needs a separate keyword representation when required.

Multiple fields

multi_match best_fields emphasizes the best field, most_fields combines evidence from representations, and cross_fields distributes terms across compatible fields. combined_fields treats compatible text fields as a combined representation, subject to analyzer constraints. Name and description do not always belong together: their roles and lengths can require explicit boosts.

{
  "query": {
    "multi_match": {
      "query": "wireless headphones",
      "fields": [
        "name^3",
        "description"
      ],
      "type": "best_fields"
    }
  }
}

Catalog reasoning example

Product A has name="wireless headphones". Product B has name="headphones" and description="wireless charging case". Multi-field search may retrieve both with different evidence. Requiring all words in one field differs from allowing them anywhere across fields. State the requirement before choosing multi_match or combined_fields. A product with words split across fields is an essential counterexample.

Search analyzed text

match is the starting point for searching a text field. The input TRAVEL is analyzed and can match Travel in name. The result is based on analyzed terms, not a case-sensitive comparison of the original JSON string. Score reflects the match in the current corpus, not a boolean confidence percentage.

For multiple input words the default operator is or: one analyzed word may be enough. That behavior is useful for broad recall but must not be confused with matching all words or a phrase. The following sections make those requirements explicit.

{
  "query": {
    "match": {
      "name": "TRAVEL"
    }
  },
  "size": 2,
  "_source": [
    "name",
    "price"
  ]
}

{
  "hits": {
    "total": {
      "value": 60,
      "relation": "eq"
    },
    "hits": [
      {
        "_id": "3",
        "_score": 1.6332386,
        "_source": {
          "name": "Sony Travel Speaker 3",
          "price": 100
        }
      },
      {
        "_id": "13",
        "_score": 1.6332386,
        "_source": {
          "name": "Apple Travel Speaker 13",
          "price": 100
        }
      }
    ]
  }
}

Match a phrase

match_phrase considers token positions as well as terms. With the default slop of zero, the analyzed words must be adjacent and in the same order. The example searches for gaming keyboard; a title with keyboard before gaming is a different phrase even if it has both words.

Phrase matching still analyzes text. It does not require the entire field to equal the phrase: a longer title may contain the phrase as part of its token sequence. Exact full-field equality belongs to an appropriate keyword field, not to match_phrase.

{
  "query": {
    "match_phrase": {
      "name": "gaming keyboard"
    }
  },
  "size": 2,
  "_source": [
    "name",
    "price"
  ]
}

{
  "hits": {
    "total": {
      "value": 30,
      "relation": "eq"
    },
    "hits": [
      {
        "_id": "4",
        "_score": 4.6608744,
        "_source": {
          "name": "Logitech Gaming Keyboard 4",
          "price": 199
        }
      },
      {
        "_id": "14",
        "_score": 4.6608744,
        "_source": {
          "name": "Samsung Gaming Keyboard 14",
          "price": 199
        }
      }
    ]
  }
}

Search multiple fields

multi_match applies a text query to explicitly listed fields. Searching name and description can retrieve a product whose useful wording appears only in the description. The default best_fields strategy derives relevance from the best matching field rather than simply adding one point for each matching field.

Field names belong in a fields array. Values remain case-analyzed according to each field mapping. This trainer requires an explicit allowed list, so do not use a wildcard field selector. The returned source fields are independent from the fields searched.

{
  "query": {
    "multi_match": {
      "query": "gaming",
      "fields": [
        "name",
        "description"
      ]
    }
  },
  "size": 2,
  "_source": [
    "name",
    "description"
  ]
}

{
  "hits": {
    "total": {
      "value": 30,
      "relation": "eq"
    },
    "hits": [
      {
        "_id": "4",
        "_score": 2.3304372,
        "_source": {
          "name": "Logitech Gaming Keyboard 4",
          "description": "Reliable everyday accessory"
        }
      },
      {
        "_id": "14",
        "_score": 2.3304372,
        "_source": {
          "name": "Samsung Gaming Keyboard 14",
          "description": "Travel companion with long battery life"
        }
      }
    ]
  }
}

Require all words

A match object can contain query and operator. Setting operator to and requires every analyzed term in that one field. In the example both travel and speaker must occur in name. The words need not be adjacent, and this is not the same as requiring the string to equal the entire product name.

Do not confuse this term-level AND with bool.must across different query clauses. Both enforce conjunction, but at different levels. When a task specifies all words in one field, a match with operator and communicates that intent directly.

{
  "query": {
    "match": {
      "name": {
        "query": "travel speaker",
        "operator": "and"
      }
    }
  },
  "size": 2,
  "_source": [
    "name",
    "price"
  ]
}

{
  "hits": {
    "total": {
      "value": 30,
      "relation": "eq"
    },
    "hits": [
      {
        "_id": "3",
        "_score": 3.9636757,
        "_source": {
          "name": "Sony Travel Speaker 3",
          "price": 100
        }
      },
      {
        "_id": "13",
        "_score": 3.9636757,
        "_source": {
          "name": "Apple Travel Speaker 13",
          "price": 100
        }
      }
    ]
  }
}