Translating an Elasticsearch Search Request to Azure Cosmos DB 

This tutorial shows how common Elasticsearch search requests can be expressed using Azure Cosmos DB query patterns. Some Elasticsearch capabilities map directly to Cosmos DB full-text search functions, while others require separate queries or application-layer handling. Each step shows the closest Cosmos DB pattern and explains what changes in the process. 

In Elasticsearch, one search request can return hits, highlights, and aggregation buckets together. In Azure Cosmos DB, it is clearer to separate those concerns: one query retrieves ranked results, separate aggregate queries calculate facets, and the application handles presentation features such as highlighting. 

Step 1: Translate the ranked result query 

Start with an Elasticsearch multi_match query for “shoes” across title, description, brand, and category. The request returns the first 20 hits. 

{ 
  "from": 0, 
  "size": 20, 
  "query": { 
    "bool": { 
      "must": [{ 
        "multi_match": { 
          "query": "shoes", 
          "fields": ["title^3", "description", 
                     "brand^2", "category"], 
          "type": "best_fields", 
          "fuzziness": "AUTO" 
        } 
      }] 
    } 
  } 
} 

SELECT * 
FROM c 
WHERE ( 
  FullTextContains(c.title, 'shoes') 
  OR FullTextContains(c.description, 'shoes') 
  OR FullTextContains(c.brand, 'shoes') 
  OR FullTextContains(c.category, 'shoes') 
) 
ORDER BY RANK FullTextScore(c.title, ['shoes']) 
OFFSET 0 LIMIT 20 

This translation focuses on the core search behavior rather than an exact one-to-one mapping of every Elasticsearch construct. In Elasticsearch, title³ and brand² are field boosts that make matches in the title and brand fields more influential in relevance scoring. The Azure Cosmos DB query shown here does not replicate those boost factors because field boosting is not currently supported in Azure Cosmos DB for NoSQL full-text search. Instead, results are ranked using the built-in BM25-based full-text scoring model. As a result, the returned result set and ranking order will differ from Elasticsearch when field boosts contribute to relevance. However, the BM25 scoring model is still designed to surface relevant matches first, so users can expect relevant results even though the ranking behavior is not identical. 

Step 2: Split categorical facets into aggregate queries 

The Elasticsearch query returns categories, subcategories, and brands as aggregation buckets in a single request. 

In Azure Cosmos DB, run one aggregate query for each field. Each query repeats the result query’s text predicate and returns a facet key with a count. 

"categories": { 
  "terms": { "field": "category.keyword", "size": 20 } 
}, 
"subcategories": { 
  "terms": { "field": "subcategory.keyword", "size": 30 } 
}, 
"brands": { 
  "terms": { "field": "brand.keyword", "size": 30 } 
} 

SELECT 
  c.category AS facetKey, 
  COUNT(1) AS facetCount 
FROM c 
WHERE ( 
  FullTextContains(c.title, 'shoes') 
  OR FullTextContains(c.description, 'shoes') 
  OR FullTextContains(c.brand, 'shoes') 
  OR FullTextContains(c.category, 'shoes') 
) 
GROUP BY c.category 

SELECT 
  c.subcategory AS facetKey, 
  COUNT(1) AS facetCount 
FROM c 
WHERE ( 
  FullTextContains(c.title, 'shoes') 
  OR FullTextContains(c.description, 'shoes') 
  OR FullTextContains(c.brand, 'shoes') 
  OR FullTextContains(c.category, 'shoes') 
) 
GROUP BY c.subcategory 

SELECT 
  c.brand AS facetKey, 
  COUNT(1) AS facetCount 
FROM c 
WHERE ( 
  FullTextContains(c.title, 'shoes') 
  OR FullTextContains(c.description, 'shoes') 
  OR FullTextContains(c.brand, 'shoes') 
  OR FullTextContains(c.category, 'shoes') 
) 
GROUP BY c.brand 

What changes: Instead of receiving all buckets in the result response, the application issues focused aggregate queries and combines the counts with the result list. 

Step 3: Translate derived rating buckets 

The Elasticsearch query creates rating facets by converting each rating to its floor value before grouping. 

"ratings": { 
  "terms": { 
    "script": "Math.floor(doc['rating'].value)", 
    "size": 5 
  } 
} 

SELECT 
  FLOOR(c.rating) AS facetKey, 
  COUNT(1) AS facetCount 
FROM c 
WHERE ( 
  FullTextContains(c.title, 'shoes') 
  OR FullTextContains(c.description, 'shoes') 
  OR FullTextContains(c.brand, 'shoes') 
  OR FullTextContains(c.category, 'shoes') 
) 
GROUP BY FLOOR(c.rating) 

What changes: In Elasticsearch, the bucket value is produced by a script inside the aggregation. In Azure Cosmos DB, the derived bucket value is expressed directly in SQL using FLOOR(c.rating) and then used in both SELECT and GROUP BY. The result is the same type of facet output: one row per rating bucket, with a count of matching documents in each bucket. 

Step 4: Translate price range facets 

The Elasticsearch query creates fixed price ranges and returns a count for each bucket. In Azure Cosmos DB, the same result can be produced with conditional aggregate expressions: each SUM counts documents that fall into one price range. 

"price_ranges": { 
  "range": { 
    "field": "price", 
    "ranges": [ 
      { "key": "Under $25", "to": 25 }, 
      { "key": "$25 - $50", "from": 25, "to": 50 }, 
      { "key": "$50 - $100", "from": 50, "to": 100 }, 
      { "key": "$100 - $200", "from": 100, "to": 200 }, 
      { "key": "$200 - $500", "from": 200, "to": 500 }, 
      { "key": "$500+", "from": 500 } 
    ] 
  } 
} 

SELECT 
  SUM(c.price < 25 ? 1 : 0) AS under25, 
  SUM(c.price >= 25 AND c.price < 50 ? 1 : 0) AS r25to50, 
  SUM(c.price >= 50 AND c.price < 100 ? 1 : 0) AS r50to100, 
  SUM(c.price >= 100 AND c.price < 200 ? 1 : 0) AS r100to200, 
  SUM(c.price >= 200 AND c.price < 500 ? 1 : 0) AS r200to500, 
  SUM(c.price >= 500 ? 1 : 0) AS over500 
FROM c 
WHERE ( 
  FullTextContains(c.title, 'shoes') 
  OR FullTextContains(c.description, 'shoes') 
  OR FullTextContains(c.brand, 'shoes') 
  OR FullTextContains(c.category, 'shoes') 
)  

What changes: Elasticsearch represents price ranges as a dedicated range aggregation. In Azure Cosmos DB, each range is written as a conditional count in the SELECT clause. The query still uses the same full-text predicate as the result query, so the price buckets count only documents that match the current search. This keeps the facet counts aligned with the result list.

Price boundaries can vary by what a user searches for, so precomputing them is rarely the default solution. You can also group by a derived key such as FLOOR(c.rating). More information about faceting can be found here.

Step 5: Handle highlighting in the application 

The Elasticsearch request configures highlighted fragments and mark tags for title and description. 

"highlight": { 
  "pre_tags": ["<mark>"], 
  "post_tags": ["</mark>"], 
  "fields": { 
    "title": { "number_of_fragments": 1, "fragment_size": 200 }, 
    "description": { "number_of_fragments": 2, "fragment_size": 150 } 
  } 
} 

Native hit highlighting is currently under development. 

Run the translated search 

1. Execute the result query. Use the ranked query to retrieve the current page of matching documents.
2. Execute the required facet queries. Run category, subcategory, brand, rating, and price aggregates for the same search state.
3. Apply active filters everywhere. When a user narrows the search, add that filter to the result query and to every aggregate query before refreshing the UI.
4. Render the experience. Display results, counts, and client-side highlights together so navigation reflects a consistent result set.

Validate behavior, not just syntax 

Start with a representative set of search terms and documents, then repeat the validation with production-like data. Compare ranked results, selected filters, facet counts, page behavior, request units, and end-to-end latency. This turns the tutorial from a syntax exercise into application-level validation. 

Series roadmap 

This post is the third and final post in the series. In Blog 1, we introduced the overall migration path for Elasticsearch users moving to Azure Cosmos DB. In Blog 2, we looked at how Elasticsearch mappings can be translated into Azure Cosmos DB indexing and full text search configuration. In this post, we brought those concepts together by walking through how to translate an Elasticsearch Search Request into an Azure Cosmos DB query. 

With these three posts, you now have a starting framework for evaluating and migrating Elasticsearch-backed search workloads to Azure Cosmos DB: understand the feature model, map your indexing configuration, and translate your query patterns. For more guidance, review the Azure Cosmos DB full text search documentation or reach out to the Azure Cosmos DB team for help with your migration scenario.