Add vector quantization support (quantizerType) for Cosmos DB vector indexes

sdk/cosmosdb/cosmos/CHANGELOG.md

@@ -4,6 +4,7 @@
 ### Features Added
 
 - Added support for continuation tokens in queries. This capability is available when using the `enableQueryControl` feature in `FeedOptions`.
+- Added support for `quantizerType` property in vector index definition. This is an optional parameter and applies to index types DiskANN and quantizedFlat. Allowed values are "product" and "spherical".
 
 ## 4.8.0 (2025-11-20)
 

sdk/cosmosdb/cosmos/review/cosmos-node.api.md

@@ -2800,10 +2800,17 @@ export interface VectorIndex {
     indexingSearchListSize?: number;
     path: string;
     quantizationByteSize?: number;
+    quantizerType?: VectorIndexQuantizationType;
     type: VectorIndexType;
     vectorIndexShardKey?: string[];
 }
 
+// @public
+export enum VectorIndexQuantizationType {
+    Product = "product",
+    Spherical = "spherical"
+}
+
 // @public
 export enum VectorIndexType {
     DiskANN = "diskANN",

sdk/cosmosdb/cosmos/samples-dev/ContainerManagement.ts

@@ -13,6 +13,7 @@ import {
   VectorEmbeddingDataType,
   VectorEmbeddingDistanceFunction,
   VectorIndexType,
+  VectorIndexQuantizationType,
 } from "@azure/cosmos";
 
 const key = process.env.COSMOS_KEY || "<cosmos key>";
@@ -161,12 +162,14 @@ async function run(): Promise<void> {
       {
         path: "/vector2",
         type: VectorIndexType.QuantizedFlat,
+        quantizerType: VectorIndexQuantizationType.Product,
         quantizationByteSize: 2,
         vectorIndexShardKey: ["/Country"],
       },
       {
         path: "/vector3",
         type: VectorIndexType.DiskANN,
+        quantizerType: VectorIndexQuantizationType.Spherical,
         quantizationByteSize: 2,
         indexingSearchListSize: 50,
         vectorIndexShardKey: ["/ZipCode"],

sdk/cosmosdb/cosmos/samples/v4/javascript/ContainerManagement.js

@@ -12,6 +12,7 @@ const {
   VectorEmbeddingDataType,
   VectorEmbeddingDistanceFunction,
   VectorIndexType,
+  VectorIndexQuantizationType,
 } = require("@azure/cosmos");
 
 const key = process.env.COSMOS_KEY || "<cosmos key>";
@@ -160,12 +161,14 @@ async function run() {
       {
         path: "/vector2",
         type: VectorIndexType.QuantizedFlat,
+        quantizerType: VectorIndexQuantizationType.Product,
         quantizationByteSize: 2,
         vectorIndexShardKey: ["/Country"],
       },
       {
         path: "/vector3",
         type: VectorIndexType.DiskANN,
+        quantizerType: VectorIndexQuantizationType.Spherical,
         quantizationByteSize: 2,
         indexingSearchListSize: 50,
         vectorIndexShardKey: ["/ZipCode"],

sdk/cosmosdb/cosmos/samples/v4/typescript/src/ContainerManagement.ts

@@ -13,6 +13,7 @@ import {
   VectorEmbeddingDataType,
   VectorEmbeddingDistanceFunction,
   VectorIndexType,
+  VectorIndexQuantizationType,
 } from "@azure/cosmos";
 
 const key = process.env.COSMOS_KEY || "<cosmos key>";
@@ -161,12 +162,14 @@ async function run(): Promise<void> {
       {
         path: "/vector2",
         type: VectorIndexType.QuantizedFlat,
+        quantizerType: VectorIndexQuantizationType.Product,
         quantizationByteSize: 2,
         vectorIndexShardKey: ["/Country"],
       },
       {
         path: "/vector3",
         type: VectorIndexType.DiskANN,
+        quantizerType: VectorIndexQuantizationType.Spherical,
         quantizationByteSize: 2,
         indexingSearchListSize: 50,
         vectorIndexShardKey: ["/ZipCode"],

sdk/cosmosdb/cosmos/src/documents/IndexingPolicy.ts

@@ -70,6 +70,12 @@ export interface VectorIndex {
    * Currently, flat, diskANN, and quantizedFlat are supported.
    */
   type: VectorIndexType;
+  /**
+   * The quantizer type for the vector index.
+   * This is an optional parameter and applies to index types DiskANN and quantizedFlat.
+   * Allowed values are "product" and "spherical".
+   */
+  quantizerType?: VectorIndexQuantizationType;
   /**
    * The number of bytes used in product quantization of the vectors.
    * This is an optional parameter and applies to index types DiskANN and quantizedFlat.
@@ -108,6 +114,21 @@ export enum VectorIndexType {
   QuantizedFlat = "quantizedFlat",
 }
 
+/**
+ * Represents the quantization type for a vector index.
+ * This is an optional parameter and applies to index types DiskANN and quantizedFlat.
+ */
+export enum VectorIndexQuantizationType {
+  /**
+   * Represents a product quantizer type.
+   */
+  Product = "product",
+  /**
+   * Represents a spherical quantizer type.
+   */
+  Spherical = "spherical",
+}
+
 /**
  * Represents a composite path in the indexing policy.
  */

sdk/cosmosdb/cosmos/src/index.ts

@@ -70,6 +70,7 @@ export {
   VectorEmbeddingDataType,
   VectorEmbeddingDistanceFunction,
   VectorIndexType,
+  VectorIndexQuantizationType,
   FullTextIndex,
   FullTextPolicy,
   FullTextPath,

sdk/cosmosdb/cosmos/test/public/functional/NonStreamingQueryPolicy.spec.ts

@@ -6,6 +6,7 @@ import {
   VectorEmbeddingDataType,
   VectorEmbeddingDistanceFunction,
   VectorIndexType,
+  VectorIndexQuantizationType,
 } from "../../../src/documents/index.js";
 import { getTestDatabase } from "../common/TestHelpers.js";
 import type { Database } from "../../../src/client/Database/Database.js";
@@ -139,6 +140,92 @@ describe("Vector search feature", async () => {
       assert(containerdef.indexingPolicy.vectorIndexes[1].vectorIndexShardKey[0] === "/Country");
       assert(containerdef.indexingPolicy.vectorIndexes[2].vectorIndexShardKey[0] === "/ZipCode");
     });
+
+    it("validate VectorEmbeddingPolicy with quantizerType", async () => {
+      const indexingPolicy: IndexingPolicy = {
+        vectorIndexes: [
+          { path: "/vector1", type: VectorIndexType.Flat },
+          {
+            path: "/vector2",
+            type: VectorIndexType.QuantizedFlat,
+            quantizerType: VectorIndexQuantizationType.Product,
+            quantizationByteSize: 1,
+            vectorIndexShardKey: ["/Country"],
+          },
+          {
+            path: "/vector3",
+            type: VectorIndexType.DiskANN,
+            quantizerType: VectorIndexQuantizationType.Spherical,
+            quantizationByteSize: 2,
+            indexingSearchListSize: 100,
+            vectorIndexShardKey: ["/ZipCode"],
+          },
+        ],
+      };
+      const vectorEmbeddingPolicy: VectorEmbeddingPolicy = {
+        vectorEmbeddings: [
+          {
+            path: "/vector1",
+            dataType: VectorEmbeddingDataType.Float32,
+            dimensions: 500,
+            distanceFunction: VectorEmbeddingDistanceFunction.Euclidean,
+          },
+          {
+            path: "/vector2",
+            dataType: VectorEmbeddingDataType.Int8,
+            dimensions: 200,
+            distanceFunction: VectorEmbeddingDistanceFunction.DotProduct,
+          },
+          {
+            path: "/vector3",
+            dataType: VectorEmbeddingDataType.UInt8,
+            dimensions: 400,
+            distanceFunction: VectorEmbeddingDistanceFunction.Cosine,
+          },
+        ],
+      };
+      const containerName = "JSApp-vector embedding container with quantizer type";
+      // create container
+      const { resource: containerdef } = await database.containers.createIfNotExists({
+        id: containerName,
+        vectorEmbeddingPolicy: vectorEmbeddingPolicy,
+        indexingPolicy: indexingPolicy,
+      });
+
+      assert(containerdef.indexingPolicy !== undefined);
+      assert(containerdef.vectorEmbeddingPolicy !== undefined);
+      assert(containerdef.indexingPolicy.vectorIndexes.length === 3);
+
+      // Verify Flat index (no quantizerType)
+      assert(containerdef.indexingPolicy.vectorIndexes[0].path === "/vector1");
+      assert(containerdef.indexingPolicy.vectorIndexes[0].type === VectorIndexType.Flat);
+      assert(containerdef.indexingPolicy.vectorIndexes[0].quantizerType === undefined);
+
+      // Verify QuantizedFlat index with Product quantizerType
+      assert(containerdef.indexingPolicy.vectorIndexes[1].path === "/vector2");
+      assert(containerdef.indexingPolicy.vectorIndexes[1].type === VectorIndexType.QuantizedFlat);
+      assert(
+        containerdef.indexingPolicy.vectorIndexes[1].quantizerType ===
+          VectorIndexQuantizationType.Product,
+      );
+      assert(containerdef.indexingPolicy.vectorIndexes[1].quantizationByteSize === 1);
+
+      // Verify DiskANN index with Spherical quantizerType
+      assert(containerdef.indexingPolicy.vectorIndexes[2].path === "/vector3");
+      assert(containerdef.indexingPolicy.vectorIndexes[2].type === VectorIndexType.DiskANN);
+      assert(
+        containerdef.indexingPolicy.vectorIndexes[2].quantizerType ===
+          VectorIndexQuantizationType.Spherical,
+      );
+      assert(containerdef.indexingPolicy.vectorIndexes[2].quantizationByteSize === 2);
+      assert(containerdef.indexingPolicy.vectorIndexes[2].indexingSearchListSize === 100);
+
+      try {
+        await database.container(containerName).delete();
+      } catch {
+        // Ignore if container is not found
+      }
+    });
     it.skip("validate VectorEmbeddingPolicy with Float16 data type", async () => {
       const indexingPolicy: IndexingPolicy = {
         vectorIndexes: [{ path: "/vector1", type: VectorIndexType.QuantizedFlat }],