Azure/azure-sdk-for-js @azure/cosmos_4.1.0

on GitHub

4.1.0 (2024-08-07)

Features Added

• Vector Search: This feature introduces vector indexes, vector embedding policy and vector queries to enable vector similarity search in JS SDK. docs
• All versions and deletes mode in change feed: The All versions and deletes mode is added in change feed mode which captures every version and every change (create, update, and delete) made to items. docs
• Bypassing integrated cache: The option to bypass integrated cache is now available in RequestOptions. docs
• Computed Properties: Support for adding Computed Properties in items is added. docs
• Composite Indexing: The JS SDK now supports including composite indexes in the indexing policy, improving query performance on multiple fields. docs
• Correlated Activity Id: Correlated Activity Id is added in header of every query request on Items. This helps in troubleshooting by linking all requests for a query that involves multiple server interactions and partitions. Correlated Activity Id can be accessed through query response headers or response.correlatedActivityId.
• Split proof Bulk API: Earlier, whenever Bulk API encountered a partition split during processing, it would return an error message. Now, JS SDK ensures that the Bulk API is resistant to partition split. #18682
• Improved samples: The samples have been updated in this release, now organized into two folders: v3 for features up to the v3 release, and v4 for features up to the v4 release.
• Added support for MakeList and MakeSet query aggregators

Vector Search

• The following sample shows how to create a container with vector embedding and indexing policies.

// define vector indexing policy
const vectorEmbeddingPolicy = {
  vectorEmbeddings: [
    {
      path: "/vector1",
      dataType: VectorEmbeddingDataType.UInt8,
      dimensions: 1000,
      distanceFunction: VectorEmbeddingDistanceFunction.Euclidean,
    },
    {
      path: "/vector2",
      dataType: VectorEmbeddingDataType.Int8,
      dimensions: 200,
      distanceFunction: VectorEmbeddingDistanceFunction.DotProduct,
    },
    {
      path: "/vector3",
      dataType: VectorEmbeddingDataType.UInt8,
      dimensions: 400,
      distanceFunction: VectorEmbeddingDistanceFunction.Cosine,
    },
  ],
};

// add vector indexes in Indexing Policy
const indexingPolicy = {
  automatic: true,
  indexingMode: "consistent",
  vectorIndexes: [
    { path: "/vector1", type: VectorIndexType.Flat },
    { path: "/vector2", type: VectorIndexType.QuantizedFlat },
    { path: "/vector3", type: VectorIndexType.DiskANN },
  ],
};

// define and create container with vector Embedding Policy
const containerDefinition = {
  id: containerId,
  partitionKey: { paths: ["/id"] },
  indexingPolicy: indexingPolicy,
  vectorEmbeddingPolicy: vectorEmbeddingPolicy,
};
await database.containers.createIfNotExists(containerDefinition);

• Vector Search queries without TOP or LIMIT+OFFSET are blocked by default, with an option to disable this check using allowUnboundedNonStreamingQueries in query FeedOptions. Also added an internal buffer size check to prevent excessive memory consumption, throwing errors if the buffer size exceeds the default. The max buffer size can be increased using the vectorSearchBufferSize option from query FeedOptions.

Change Feed - All versions and deletes mode

• The AllVersionsAndDeletes mode is only supported with ChangeFeedStartFrom.Now and ChangeFeedStartFrom.Continuation.
• To read from the change feed in all versions and deletes mode, include changeFeedMode in changeFeedIteratorOptions:

    const changeFeedIteratorOptions: ChangeFeedIteratorOptions = {
      maxItemCount: 5,
      changeFeedStartFrom: ChangeFeedStartFrom.Now(),
      changeFeedMode: ChangeFeedMode.AllVersionsAndDeletes,
    };
    const iterator = container.items.getChangeFeedIterator(changeFeedIteratorOptions);

Bypassing Integrated Cache

• Here is a sample showing how to enable bypassIntegratedCache in RequestOptions.

  const options: RequestOptions = {bypassIntegratedCache: true};
  const response = await container.item("1").read(options);

Computed Properties

• The following snippet configures computed properties for a container:

    const computedProperties: ComputedProperty[] = [{
      name: "lowerLastName",
      query:
        "SELECT VALUE LOWER(IS_DEFINED(c.lastName) ? c.lastName : c.parents[0].familyName) FROM c",
    },];
    const { resource: containerdef } = await database.containers.createIfNotExists({
      id: containerName,
      computedProperties: computedProperties,
      indexingPolicy: indexingPolicy,
    });
    const container: Container = database.container(containerdef.id);

Composite Indexing

• Here's a sample of adding composite indexes for a container:

    const containerDefinition: ContainerDefinition = {
      id: "containerWithCompositeIndexingPolicy",
      indexingPolicy: {
        automatic: true,
        indexingMode: IndexingMode.consistent,
        includedPaths: [
          {
            path: "/*",
          },
        ],
        excludedPaths: [],
        compositeIndexes: [
          [
            { path: "/key", order: "ascending" },
            { path: "/field", order: "ascending" },
          ],
        ],
      },
    };
    await database.containers.create(containerDefinition);

• Added support for passing a custom HttpClient when constructing a CosmosClient.

Breaking Changes

Dropped Support for TypeScript 4.1

• We have opted to discontinue support for TypeScript version 4.1. Consequently, the minimum supported TypeScript version has been elevated to 4.2. Kindly ensure that your environment is promptly updated to align with these changes.

Bugs Fixed

• Fix Bulk operations(Read, Delete, and Patch) failing due to wrong format of partition key in non-partitioned container.