{"id":12933,"date":"2026-10-01T00:00:57","date_gmt":"2026-10-01T07:00:57","guid":{"rendered":"https:\/\/devblogs.microsoft.com\/cosmosdb\/?p=12933"},"modified":"2026-09-30T06:46:47","modified_gmt":"2026-09-30T13:46:47","slug":"migrating-elasticsearch-mappings-to-azure-cosmos-db","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/cosmosdb\/migrating-elasticsearch-mappings-to-azure-cosmos-db\/","title":{"rendered":"Migrating Elasticsearch Mappings to Azure Cosmos DB"},"content":{"rendered":"

This post focuses on one of the most important design tasks when migrating from Elasticsearch to Azure Cosmos DB: translating an Elasticsearch mapping into Azure Cosmos DB container configuration.<\/span>\u00a0<\/span><\/p>\n

In Elasticsearch, a mapping defines how document fields are stored and indexed. Azure Cosmos DB is schema-agnostic, so there is no single mapping document to translate. Instead, distribute the mapping\u2019s intent across the indexing policy, full-text policy, vector policy, and computed properties.<\/span>\u00a0<\/span><\/p>\n

The goal is not a line-by-line conversion. It is to preserve the query, filtering, ranking, and retrieval behavior that the application depends on while adopting Azure Cosmos DB\u2019s container-level model.<\/span>\u00a0<\/span><\/p>\n

Mapping translation at a glance<\/h2>\n\n\n\n\n\n\n\n
Elasticsearch<\/span><\/b>\u00a0<\/span><\/td>\nAzure Cosmos DB equivalent<\/span><\/b>\u00a0<\/span><\/td>\n<\/tr>\n
Mapped fields, index, and field types used for exact-match queries, filters, sorting, and aggregations<\/td>\nIndexing policy: included and excluded paths, range indexes, composite indexes, and spatial indexes<\/span>\u00a0<\/span><\/td>\n<\/tr>\n
Text fields and analyzers<\/td>\nFull-text policy plus a full-text index in the indexing policy<\/span>\u00a0<\/span><\/td>\n<\/tr>\n
dense_vector fields and vector index options<\/td>\nContainer vector policy plus a vector index in the indexing policy<\/span>\u00a0<\/span><\/td>\n<\/tr>\n
Runtime fields or values materialized for search<\/td>\nComputed properties<\/span>\u00a0<\/span><\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n

Start by inventorying how each Elasticsearch field is used, not only how it is typed. A field used for filters and sorting translates differently from one used for relevance ranking, even when both contain strings. One Elasticsearch field can also map to more than one Azure Cosmos DB capability.<\/span>\u00a0<\/span><\/p>\n

Translate by capability<\/h2>\n

1. Exact-match, filter, sort, and range behavior<\/h4>\n\n\n\n\n
Elasticsearch<\/span><\/b>\u00a0<\/span><\/td>\nAzure Cosmos DB<\/span><\/b>\u00a0<\/span><\/td>\n<\/tr>\n
\n
\"properties\": {\r\n\u00a0 \"category\": { \"type\": \"keyword\" },\r\n\u00a0 \"price\": { \"type\": \"double\" },\r\n\u00a0 \"description\": { \"type\": \"text\" }\r\n}\u00a0<\/code><\/pre>\n<\/td>\n
\n
\"indexingPolicy\": {\r\n\u00a0 \"includedPaths\": [\r\n\u00a0\u00a0\u00a0 { \"path\": \"\/category\/?\" },\r\n\u00a0\u00a0\u00a0 { \"path\": \"\/price\/?\" }\r\n\u00a0 ],\r\n\u00a0 \"excludedPaths\": [\r\n\u00a0\u00a0\u00a0 { \"path\": \"\/description\/?\" }\r\n\u00a0 ]\r\n}<\/code><\/pre>\n
\u00a0<\/span><\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n
What changes:<\/span><\/b> Keep the JSON values and index the paths used by queries. Add a composite index only when a recurring query filters by category and sorts by price; configure the partition key separately.<\/span>\u00a0<\/span><\/p>\n
2. Full-text fields and analyzers<\/h4>\n\n\n\n\n
Elasticsearch<\/span><\/b>\u00a0<\/span><\/td>\nAzure Cosmos DB<\/span><\/b>\u00a0<\/span><\/td>\n<\/tr>\n
\n
\"properties\": {\r\n\u00a0 \"description\": {\r\n\u00a0\u00a0\u00a0 \"type\": \"text\",\r\n\u00a0\u00a0\u00a0 \"analyzer\": \"english\"\r\n\u00a0 },\r\n\u00a0 \"sku\": { \"type\": \"keyword\" }\r\n}\u00a0<\/code><\/pre>\n<\/td>\n
\n
\"fullTextPolicy\": {\r\n\u00a0 \"defaultLanguage\": \"en-US\",\r\n\u00a0 \"fullTextPaths\": [\r\n\u00a0\u00a0\u00a0 { \"path\": \"\/description\",\r\n\u00a0\u00a0\u00a0\u00a0\u00a0 \"language\": \"en-US\" }\r\n\u00a0 ]\r\n}\r\n\r\n\"fullTextIndexes\": [\r\n\u00a0 { \"path\": \"\/description\" }\r\n]\u00a0<\/code><\/pre>\n<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n
What changes:<\/span><\/b> Translate the analyzer\u2019s intent\u2014language-aware tokenization, stemming, and stop-word handling\u2014rather than copying a custom analysis chain. Keep <\/span>sku<\/span><\/b> in the regular indexing policy for exact matches.<\/span>\u00a0<\/span><\/p>\n
3. Vector fields<\/h4>\n\n\n\n\n
Elasticsearch<\/span><\/b>\u00a0<\/span><\/td>\nAzure Cosmos DB<\/span><\/b>\u00a0<\/span><\/td>\n<\/tr>\n
\n
\"content_vector\": {\r\n\u00a0 \"type\": \"dense_vector\",\r\n\u00a0 \"dims\": 384,\r\n\u00a0 \"similarity\": \"cosine\",\r\n\u00a0 \"index\": true\r\n}\u00a0<\/code><\/pre>\n<\/td>\n
\n
\"vectorEmbeddingPolicy\": {\r\n\u00a0 \"vectorEmbeddings\": [{\r\n\u00a0\u00a0\u00a0 \"path\": \"\/contentVector\",\r\n\u00a0\u00a0\u00a0 \"dataType\": \"float32\",\r\n\u00a0\u00a0\u00a0 \"distanceFunction\": \"cosine\",\r\n\u00a0\u00a0\u00a0 \"dimensions\": 384\r\n\u00a0 }]\r\n}\r\n\r\n\"vectorIndexes\": [{\r\n\u00a0 \"path\": \"\/contentVector\",\r\n\u00a0 \"type\": \"quantizedFlat\"\r\n}]<\/code>\u00a0<\/span><\/pre>\n<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n
What changes:<\/span><\/b> Preserve the embedding model\u2019s dimensions and similarity function. Select the Azure Cosmos DB vector index type according to data size, filters, latency, and recall.<\/span>\u00a0<\/span><\/p>\n
4. Derived and runtime values<\/span><\/b>\u00a0<\/span><\/h4>\n\n\n\n\n
Elasticsearch<\/span><\/b>\u00a0<\/span><\/td>\nAzure Cosmos DB<\/span><\/b>\u00a0<\/span><\/td>\n<\/tr>\n
\n
\"runtime\": {\r\n\u00a0 \"discountedPrice\": {\r\n\u00a0\u00a0\u00a0 \"type\": \"double\",\r\n\u00a0\u00a0\u00a0 \"script\": {\r\n\u00a0\u00a0\u00a0\u00a0\u00a0 \"source\": \"emit(doc['price'].value * 0.9)\"\r\n\u00a0\u00a0\u00a0 }\r\n\u00a0 }\r\n}\u00a0<\/code><\/pre>\n<\/td>\n
\n
\"computedProperties\": [{\r\n\u00a0 \"name\": \"discountedPrice\",\r\n\u00a0 \"query\": \"SELECT VALUE c.price * 0.9 FROM c\"\r\n}]\u00a0<\/code><\/pre>\n<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n
What changes:<\/span><\/b> Rewrite a stable, deterministic derivation as a computed property. Calculate unsupported or external-state logic during ingestion or in the application.<\/span>\u00a0<\/span><\/p>\n
Recommended migration sequence<\/span><\/b>\u00a0<\/span><\/h2>\n
    \n
  1. Inventory the mapping and workload.<\/span><\/b> Export mappings, templates, analyzers, vector settings, runtime fields, and the queries that use them.<\/span>\u00a0<\/span><\/li>\n<\/ol>\n
      \n
    1. Classify every field by behavior.<\/span><\/b> Mark paths for exact filtering or sorting, full-text search, vector search, geospatial queries, or derived values.<\/span>\u00a0<\/span><\/li>\n<\/ol>\n
        \n
      1. Design the container policies together.<\/span><\/b> Resolve overlaps\u2014for example, a description can be available to normal queries, full-text search, and vector retrieval.<\/span>\u00a0<\/span><\/li>\n<\/ol>\n
          \n
        1. Validate with representative data and queries.<\/span><\/b> Compare result correctness, relevance ordering, latency, RU consumption, and write cost.<\/span>\u00a0<\/span><\/li>\n<\/ol>\n
            \n
          1. Roll out deliberately.<\/span><\/b> Apply policy changes before dependent queries, monitor index transformation where applicable, and keep a rollback path.<\/span>\u00a0<\/span><\/li>\n<\/ol>\n
            Key takeaway<\/span><\/b>\u00a0<\/span><\/h2>\n
            An Elasticsearch mapping is best treated as a statement of search intent, not a schema to reproduce. In Azure Cosmos DB, that intent is expressed through coordinated container policies: the indexing policy handles standard query access paths, the full-text policy handles analyzed text, the vector policy handles embeddings, and computed properties handle reusable derived values. Translating by workload preserves behavior while avoiding unnecessary indexes and migration-era assumptions.<\/span>\u00a0<\/span><\/p>\n
            Series roadmap<\/span><\/b>\u00a0<\/span><\/h2>\n
            This post is the second in a series. In <\/span>Blog 1<\/span><\/b>, we introduced the broader migration path for Elasticsearch users moving to Azure Cosmos DB and outlined the core concepts behind full text search support. In this post, we focused on how Elasticsearch mappings translate to Azure Cosmos DB indexing and search configuration. Next, <\/span>Blog 3<\/span><\/b> will cover query translation, showing how to translate an Elasticsearch Search Request into an Azure Cosmos DB query.<\/span>\u00a0<\/span><\/p>\n","protected":false},"excerpt":{"rendered":"
            This post focuses on one of the most important design tasks when migrating from Elasticsearch to Azure Cosmos DB: translating an Elasticsearch mapping into Azure Cosmos DB container configuration.\u00a0 In Elasticsearch, a mapping defines how document fields are stored and indexed. Azure Cosmos DB is schema-agnostic, so there is no single mapping document to translate. […]<\/p>\n","protected":false},"author":220740,"featured_media":13015,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"footnotes":""},"categories":[14],"tags":[],"class_list":["post-12933","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-core-sql-api"],"acf":[],"blog_post_summary":"
            This post focuses on one of the most important design tasks when migrating from Elasticsearch to Azure Cosmos DB: translating an Elasticsearch mapping into Azure Cosmos DB container configuration.\u00a0 In Elasticsearch, a mapping defines how document fields are stored and indexed. Azure Cosmos DB is schema-agnostic, so there is no single mapping document to translate. […]<\/p>\n","_links":{"self":[{"href":"https:\/\/devblogs.microsoft.com\/cosmosdb\/wp-json\/wp\/v2\/posts\/12933","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/devblogs.microsoft.com\/cosmosdb\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/devblogs.microsoft.com\/cosmosdb\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/cosmosdb\/wp-json\/wp\/v2\/users\/220740"}],"replies":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/cosmosdb\/wp-json\/wp\/v2\/comments?post=12933"}],"version-history":[{"count":1,"href":"https:\/\/devblogs.microsoft.com\/cosmosdb\/wp-json\/wp\/v2\/posts\/12933\/revisions"}],"predecessor-version":[{"id":12947,"href":"https:\/\/devblogs.microsoft.com\/cosmosdb\/wp-json\/wp\/v2\/posts\/12933\/revisions\/12947"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/cosmosdb\/wp-json\/wp\/v2\/media\/13015"}],"wp:attachment":[{"href":"https:\/\/devblogs.microsoft.com\/cosmosdb\/wp-json\/wp\/v2\/media?parent=12933"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/cosmosdb\/wp-json\/wp\/v2\/categories?post=12933"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/cosmosdb\/wp-json\/wp\/v2\/tags?post=12933"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}