Loading

Get started with semantic search

If you want to get a sense of how semantic search works in Elasticsearch, this quickstart is for you. You use the semantic_text workflow, the simplest managed path for semantic search. First, you create an index and store your data in two forms: plain text for keyword matching and semantic representations in semantic_text (embeddings are generated automatically using vector search under the hood). Then you run a hybrid query that searches both representations and combines the results.

Note

This quickstart demonstrates semantic search with the semantic_text field type and hybrid search: it combines keyword-based full-text search with semantic search so you can match both exact terms and meaning.

For example, if a document contains the phrase "annual leave policy", a keyword search for "annual leave" will return it because the terms match. However, a search for "vacation rules" may not return the same document, because those exact words are not present.

With semantic search, a query like "vacation rules" can still return the "annual leave policy" document, because it matches based on meaning rather than exact terms.

With hybrid search, the same query can return both keyword and semantic matches, combining exact words with search by meaning so results stay useful.

A running Elasticsearch cluster. For the fastest way to follow this quickstart, create a serverless project which includes a free Serverless trial.

  1. Create an index mapping

    Define the index mapping. The mapping specifies the fields in your index and their data types, including a plain text field for full-text search and a semantic_text field for semantic search.

    				PUT semantic-embeddings
					{
  "mappings": {
    "properties": {
      "semantic_text": {
        "type": "semantic_text"
      },
      "content": {
        "type": "text",
        "copy_to": "semantic_text"
      }
    }
  }
}
    1. The semantic_text field with the semantic_text field type for semantic search. Embeddings are generated and stored automatically using the default inference endpoint.
    2. The content field with the text field type to store plain text. This field is used for keyword search.
    3. Values indexed into content are copied to semantic_text and processed by the default inference endpoint.
    Example response 
    {
  "acknowledged": true,
  "shards_acknowledged": true,
  "index": "semantic-embeddings"
}

  2. Index documents

    Index documents with the bulk API. You only need to provide the content to the content field. The copy_to mapping copies the text into semantic_text and generates embeddings automatically, so you can run keyword search on content and semantic search on semantic_text for the same document.

    				POST _bulk
					{ "index": { "_index": "semantic-embeddings" } }
{ "content": "After running, cool down with light cardio for a few minutes to lower your heart rate and reduce muscle soreness." }
{ "index": { "_index": "semantic-embeddings" } }
{ "content": "Marathon plans stress weekly mileage; carb loading before a race does not replace recovery between hard sessions." }
{ "index": { "_index": "semantic-embeddings" } }
{ "content": "Tune cluster performance by monitoring thread pools and refresh interval." }
    Example response 
    {
  "errors": false,
  "took": 600,
  "items": [
    {
      "index": {
        "_index": "semantic-embeddings",
        "_id": "akiYKZ0BGwHk8ONXXqmi",
        "_version": 1,
        "result": "created",
        "_shards": {
          "total": 1,
          "successful": 1,
          "failed": 0
        },
        "_seq_no": 0,
        "_primary_term": 1,
        "status": 201
      }
    },
    {
      "index": {
        "_index": "semantic-embeddings",
        "_id": "a0iYKZ0BGwHk8ONXXqmi",
        "_version": 1,
        "result": "created",
        "_shards": {
          "total": 1,
          "successful": 1,
          "failed": 0
        },
        "_seq_no": 0,
        "_primary_term": 1,
        "status": 201
      }
    },
    {
      "index": {
        "_index": "semantic-embeddings",
        "_id": "bEiYKZ0BGwHk8ONXXqmi",
        "_version": 1,
        "result": "created",
        "_shards": {
          "total": 1,
          "successful": 1,
          "failed": 0
        },
        "_seq_no": 1,
        "_primary_term": 1,
        "status": 201
      }
    }
  ]
}

Run a search using the Search API.

The JSON body is a hybrid query: a reciprocal rank fusion (RRF) retriever runs two match queries, one on content and one on semantic_text, and merges the results.

Note

An RRF retriever returns top documents based on the RRF formula. This enables hybrid search by combining results from both keyword-based and semantic queries into a single ranked list.

				GET semantic-embeddings/_search
					{
  "retriever": {
    "rrf": {
      "retrievers": [
        {
          "standard": { 
            "query": {
              "match": {
                "content": "muscle soreness after jogging"
              }
            }
          }
        },
        {
          "standard": { 
            "query": {
              "match": {
                "semantic_text": "muscle soreness after jogging"
              }
            }
          }
        }
      ]
    }
  }
}
  1. The match query is run against the content field, which stores plain text for keyword matching.
  2. The match query is run against the semantic_text field for semantic search (embeddings are stored and compared automatically).

If a document ranks well in either query, it can appear in the combined list.

Example response

In the example response below, the two hits show why combining keyword search and semantic search in a hybrid query matters.

The top document contains the phrase muscle soreness and running, so it fits both keyword search and semantic search. The second document does not use those words at all; it talks about marathon training and recovery between sessions. A keyword-only search on content would likely miss or rank that document much lower, because the query terms are not in the text.

Semantic search still matches it because marathon training and recovery relate to the same idea as soreness after a run. Hybrid search keeps the document that matches the words and also brings in documents that match the topic without the same vocabulary.

Each _score is a relevance score for this search only. A higher score means that document ranked higher than the ones below it in the same response.

{
  "took": 202,
  "timed_out": false,
  "_shards": {
    "total": 6,
    "successful": 6,
    "skipped": 0,
    "failed": 0
  },
  "hits": {
    "total": {
      "value": 2,
      "relation": "eq"
    },
    "max_score": 0.032786883,
    "hits": [
      {
        "_index": "semantic-embeddings",
        "_id": "akiYKZ0BGwHk8ONXXqmi",
        "_score": 0.032786883,
        "_source": {
          "content": "After running, cool down with light cardio for a few minutes to lower your heart rate and reduce muscle soreness."
        }
      },
      {
        "_index": "semantic-embeddings",
        "_id": "a0iYKZ0BGwHk8ONXXqmi",
        "_score": 0.016129032,
        "_source": {
          "content": "Marathon plans stress weekly mileage; carb loading before a race does not replace recovery between hard sessions."
        }
      }
    ]
  }
}
  1. How many documents matched the query (here, 2). The unrelated cluster-tuning document is not returned.
  2. The highest relevance score among the returned hits (the same as the top-ranked document’s score).
  3. Relevance score for the top-ranked document. Its text matches query terms like muscle soreness and post-run recovery (running is close to jogging), so both keyword search and semantic search can rank it highly.
  4. Relevance score for the second-ranked document. It does not contain muscle soreness or jogging; it shows up mainly because semantic search matches marathon training and recovery to the query. Keyword-only search on content would often miss this kind of match.
  • Semantic search - Compare the three workflows (semantic_text, inference API, or models deployed in-cluster) and see how they differ in complexity.
  • Vector search - Work directly with dense_vector and sparse_vector fields, related queries, and manual vector implementations when you need control beyond managed semantic workflows.
  • Ranking and reranking - Structure multi-stage pipelines: initial BM25, vector, or hybrid retrieval, then reranking with stronger models on smaller candidate sets.
  • Build your search queries - Choose Query DSL, ES|QL, or retrievers on the Search API depending on whether you need classic queries, analytics-style pipes, or composable retrieval pipelines.

To learn about more options, such as full-text, vector, and hybrid search, go to Search approaches. For a summary of vector search use cases, go to Vector search use cases.