Create a semantic query in Azure AI Search

In this article, learn how to invoke a semantic ranking over a result set, promoting the most semantically relevant results to the top of the stack. You can also get semantic captions, with highlights over the most relevant terms and phrases, and semantic answers.



Captions and answers are extracted verbatim from text in the search document. The semantic subsystem uses machine reading comprehension to recognize content having the characteristics of a caption or answer, but doesn't compose new sentences or phrases. For this reason, content that includes explanations or definitions work best for semantic ranking. If you want chat-style interaction with generated responses, see Retrieval Augmented Generation (RAG).

Choose a client

Choose a search client that supports semantic ranking. Here are some options:

Avoid features that bypass relevance scoring

Several query capabilities in Azure AI Search bypass relevance scoring or are otherwise incompatible with semantic ranking. If your query logic includes the following features, you can't semantically rank your results:

  • A query with search=* or an empty search string, such as pure filter-only query, won't work because there's nothing to measure semantic relevance against. The query must provide terms or phrases that can be assessed during processing.

  • A query composed in the full Lucene syntax (queryType=full) is incompatible with semantic ranking (queryType=semantic). The semantic model doesn't support the full Lucene syntax.

  • Sorting (orderBy clauses) on specific fields overrides search scores and a semantic score. Given that the semantic score is supposed to provide the ranking, adding an orderby clause results in an HTTP 400 error if you apply semantic ranking over ordered results.

Set up the query

In this step, add parameters to the query request. To be successful, your query should be full text search (using the search parameter to pass in a string), and the index should contain text fields with rich semantic content and a semantic configuration.

Search explorer includes options for semantic ranking.

  1. Sign in to the Azure portal.

  2. Open a search index and select Search explorer.

  3. Select Query options. If you already defined a semantic configuration, it's selected by default. If you don't have one, create a semantic configuration for your index.

    Screenshot showing query options in Search explorer.

  4. Enter a query, such as "historic hotel with good food", and select Search.

  5. Alternatively, select JSON view and paste definitions into the query editor:

    Screenshot showing JSON query syntax in the Azure portal.

    Here's some JSON text that you can paste into the view:

         "queryType": "semantic",
         "search": "historic hotel with good food",
         "semanticConfiguration": "my-semantic-config",
         "answers": "extractive|count-3",
         "captions": "extractive|highlight-true",
         "highlightPreTag": "<strong>",
         "highlightPostTag": "</strong>",
         "select": "HotelId,HotelName,Description,Category",
         "count": true

Evaluate the response

Only the top 50 matches from the initial results can be semantically ranked. As with all queries, a response is composed of all fields marked as retrievable, or just those fields listed in the select parameter. A response includes the original relevance score, and might also include a count, or batched results, depending on how you formulated the request.

In semantic ranking, the response has more elements: a new semantically ranked relevance score, an optional caption in plain text and with highlights, and an optional answer. If your results don't include these extra elements, then your query might be misconfigured. As a first step towards troubleshooting the problem, check the semantic configuration to ensure it's specified in both the index definition and query.

In a client app, you can structure the search page to include a caption as the description of the match, rather than the entire contents of a specific field. This approach is useful when individual fields are too dense for the search results page.

The response for the above example query returns the following match as the top pick. Captions are returned because the "captions" property is set, with plain text and highlighted versions. Answers are omitted from the example because one couldn't be determined for this particular query and corpus.

"@odata.count": 35,
"@search.answers": [],
"value": [
        "@search.score": 1.8810667,
        "@search.rerankerScore": 1.1446577133610845,
        "@search.captions": [
                "text": "Oceanside Resort. Luxury. New Luxury Hotel. Be the first to stay. Bay views from every room, location near the pier, rooftop pool, waterfront dining & more.",
                "highlights": "<strong>Oceanside Resort.</strong> Luxury. New Luxury Hotel. Be the first to stay.<strong> Bay</strong> views from every room, location near the pier, rooftop pool, waterfront dining & more."
        "HotelName": "Oceanside Resort",
        "Description": "New Luxury Hotel. Be the first to stay. Bay views from every room, location near the pier, rooftop pool, waterfront dining & more.",
        "Category": "Luxury"

Next steps

Semantic ranking can be used in hybrid queries that combine keyword search and vector search into a single request and a unified response.