- 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, andv4
for features up to the v4 release. - Added support for MakeList and MakeSet query aggregators
- 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 thevectorSearchBufferSize
option from query FeedOptions.
- The AllVersionsAndDeletes mode is only supported with
ChangeFeedStartFrom.Now
andChangeFeedStartFrom.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);
- Here is a sample showing how to enable
bypassIntegratedCache
in RequestOptions.
const options: RequestOptions = {bypassIntegratedCache: true};
const response = await container.item("1").read(options);
- 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);
- 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 aCosmosClient
.
- 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.
- Fix Bulk operations(Read, Delete, and Patch) failing due to wrong format of partition key in non-partitioned container.
🎉 v4 release! 🎉 Many new features, bug fixes, and a few breaking changes.
- Summary of new added features
- Diagnostics: A diagnostic object has been added to responses of api operations ie. point lookups, bulk & batch operations, query and error responses, which contains information related to metadata lookups, retries, request and reponse latencies and payload siezes.
- Hierarchical Partitioning: Containers with hierarchical partitions are now supported. docs
- Index metrics: can be enabled to show both utilized indexed paths and recommended indexed paths. docs
- New Changefeed iterator: which can consume changes for a specific partition key, a feed range or an entire container. docs
- Priority based throttling is now supported. docs
- Since
diagnostics
is added to all Response objects. You could programatically accessCosmosDiagnostic
as follows.
// For point look up operations
const { container, diagnostics: containerCreateDiagnostic } =
await database.containers.createIfNotExists({
id: containerId,
partitionKey: {
paths: ["/key1"],
},
});
// For Batch operations
const operations: OperationInput[] = [
{
operationType: BulkOperationType.Create,
resourceBody: { id: 'A', key: "A", school: "high" },
},
];
const response = await container.items.batch(operations, "A");
const diagnostics = response.diagnostics
// For Bulk operations
const operations: OperationInput[] = [
{
operationType: BulkOperationType.Create,
resourceBody: { id: 'A', key: "A", school: "high" },
},
];
const response = await container.items.bulk(operations);;
const diagnostics = response.diagnostics
// For query operations
const queryIterator = container.items.query("select * from c");
const { resources, diagnostics } = await queryIterator.fetchAll();
// While error handling
try {
// Some operation that might fail
} catch (err) {
const diagnostics = err.diagnostics
}
-
Here is a sampele for creating container with Hierarchical Partitions
const containerDefinition = { id: "Test Database", partitionKey: { paths: ["/name", "/address/zip"], version: PartitionKeyDefinitionVersion.V2, kind: PartitionKeyKind.MultiHash, }, }; const { container } = await database.containers.createIfNotExists(containerDefinition); console.log(container.id);
-
Definition of PartitionKey has been changed to support Hierarchical partitioning. Here is how to use the new definition.
-
The operations for which PartitionKey can be derived from Request body, providing PartitionKey is optional as always i.e
const item = { id: 1, name: "foo", address: { zip: 100, }, active: true, }; await container.items.create(item);
-
Here is sample for operations which require hierarchical partition to be passed.
await container.item("1", ["foo", 100]).read();
OR
const partitionKey: PartitionKey = new PartitionKeyBuilder() .addValue("foo") .addValue(100) .build(); await container.item("1", partitionKey).read();
-
If you are not using Hierarchical Partitioning feature, Definition of Partition Key is practically backward compatible.
await container.item("1", "1").read();
-
The v4 SDK now supports Change feed pull model.
Note: There are no breaking changes, the old change feed iterator is still supported.
Major Differences:
-
The new iterator allows fetching change feed for a partition key, a feed range, or an entire container, compared to the older iterator, which was limited to fetching change feed for a partition key only.
-
The new implementation is effectively an infinite list of items that encompasses all future writes and updates. The
hasMoreResults
property now always returnstrue
, unlike the older implementation, which returnedfalse
when aNotModified
status code was received from the backend.
Here is an example of creating and using the new change feed iterator:
const changeFeedOptions = {
changeFeedStartFrom: ChangeFeedStartFrom.Beginning("partition key or feed range"),
maxItemCount: 10,
};
const iterator = container.items.getChangeFeedIterator(changeFeedOptions);
while (iterator.hasMoreResults) {
const res = await iterator.readNext();
// process res
}
Index Metrics #20194
Azure Cosmos DB provides indexing metrics for optimizing query performance, especially when you're unsure about adjusting the indexing policy. You can enable indexing metrics for a query by setting the PopulateIndexMetrics property to true(default=false).
const { resources: resultsIndexMetrics, indexMetrics } = await container.items
.query(querySpec, { populateIndexMetrics: true })
.fetchAll();
We only recommend enabling the index metrics for troubleshooting query performance.
Enhanced Retry Utility for Improved SDK Reliability #23475
Improved the retry utility to align with other language SDKs. Now, it automatically retries requests on the next available region when encountering HTTP 503 errors (Service Unavailable) and handles HTTP timeouts more effectively, enhancing the SDK's reliability.
Priority-based execution is a capability which allows users to specify priority for the request sent to Azure Cosmos DB. Based on the priority specified by the user, if there are more requests than the configured RU/s in a second, then Azure Cosmos DB will throttle low priority requests to allow high priority requests to execute. You can enable priority based throttling by setting priorityLevel property.
const response =
(await container.item(document.id).read) < TestItem > { priorityLevel: PriorityLevel.Low };
- Updated response codes for the getDatabase() method. #25932
- Fix Upsert operation failing when partition key of container is
/id
and/id
is missing in the document. #21383
- The definition of PartitionKey is changed, PartitionKeyDefinition is now a independent type. #23416
- Changes in bulk api to honour size restictions (i.e 2Mb) while creating individual batches.#23923
- Enriched Timeout error response. We had defined Timeout error as custom error in our sdk but we were not sending up any message along with it, now we are throwing the specific Error. #23025
- Added functionality to delete entire data for a partition id. #22091
- SDK now defines all possible error types, namely Export RestError, AbortError, TimeoutError, and ErrorResponse. 22789
- Removed excessive log warnings during bulk operations on a container with no partitionkey set.
- Fix issue with GlobalEndpointManager never making endpoints available after they fall-back #22726
- Fix issue that caused parallel queries to break when returning a result of 0 or false. #24493
- Error handling guidelines are added in README.md
- Fix issue with patch api not working with aadCredentials #20689
- Improve the contract of Item.batch operation from type any to OperationResponse #23652
- Add section for the current limitations with the SDK #21650
- Fix issue aad refresh token automatically getting refreshed #22620
- Fix issue with unwanted runtime dependency on
@azure/identity
#22968
- Support DedicatedGatewayRequestOptions and MaxIntegratedCacheStaleness #21240
- Upgrade cosmos with azure core tracing #22284
- Removed old logging and implement Azure core logging coverage #18723
- ParallelQueryExecutionContextBase breaks use of abortSignal #18544
- Fixes id encoding issues when using special characters fo RoutingGateway
- Fixes issues with "id" encoding when using special characters that should be allowed in the "id" property of a document. #22548
- Adds support to run queries with group by over a column with null values. #22345
- Allow users like cosmos-explorer to specify hierarchical partition keys. #21934
- Support Dedicated Gateway RequestOptions and Max Integrated Cache Staleness. #21240
- Fixed the paths mapped by the
browser
entry inpackage.json
to be correct for the package's new output structure. This solves errors with bundling the package for browsers.
- GA Adds
container.item(itemId).patch()
.patch()
is an alternative toreplace()
for item updates. https://github.com/Azure/azure-sdk-for-js/pull/16264/files#diff-7caca690c469e2025576523c0377ac71815f001024fde7c48b20cd24adaa6977R561 - GA support for Bulk operation PATCH.
- GA support for Batch operation PATCH.
- Added the
SasTokenProperties
type and acreateAuthorizationSasToken
function to enable scoped access to Cosmos resources with SAS tokens. For an example that demonstrates creating a SAS token and using it to authenticate aCosmosClient
, see theSasTokenAuth
sample.
- Made several changes to the sample programs to improve code quality and compatibility with Node 12, and upgraded the sample programs' dependencies.
- Fix @azure/core-rest-pipeline version for AAD auth.
- PREVIEW Adds
container.item(itemId).patch()
.patch()
is an alternative toreplace()
for item updates. https://github.com/Azure/azure-sdk-for-js/pull/16264/files#diff-7caca690c469e2025576523c0377ac71815f001024fde7c48b20cd24adaa6977R561 - PREVIEW Adds support for Bulk operation PATCH.
- PREVIEW Adds support for Batch operation PATCH.
- Fixes bug where Batch was passing the wrong header for batch requests with partition keys
- Fixes 401s when using AAD auth. AAD credentials should now work and no longer cause 429s from @azure/identity at high throughput.
- Fixed bugs in session token clearing logic. Session Not found (404, substatus 1002) was not being handled correctly by the session retry policy and would mistakenly retry the request with the same session token.
- Adds TransactionalBatch to items
container.items.batch(operations)
- Fixed bulk requests which had operations without partitionKey specified.
- Fix bulk operations on containers with multiple partitions with nested partition keys
- Adopted target ES2017 to reduce bundle size.
- Returned default retryPolicy option
fixedRetryIntervalInMilliseconds
to its original default 0.
- With the dropping of support for Node.js versions that are no longer in LTS, the dependency on
@types/node
has been updated to version 12. Read our support policy for more details. - Added background refresher for endpoints, and new
ConnectionPolicy
options. Refreshing defaults to true, and the default refresh rate is every 5 minutes.
const client = new CosmosClient({
endpoint,
key: masterKey,
connectionPolicy: {
...defaultConnectionPolicy,
endpointRefreshRateInMs: 700,
enableBackgroundEndpointRefreshing: true,
},
});
- Added
client.dispose()
for closing the endpoint refresher verbosely. Necessary when destroying the CosmosClient inside existing processes like an express web server, or when you want to destroy the client and create a new one in the same process.
const client = new CosmosClient();
client.dispose(); // cancels background endpoint refreshing
- BUGFIX: Adds another failover condition.
- BUGFIX: Correctly failover to new regions when regional DNS has gone offline.
- BUGFIX: Sanitize user endpoint URLs for AAD DataPlane RBAC token generation.
- BUGFIX: Cache https client between requests.
- BUGFIX: Import URL from Browser/Node shim rather than built-in module.
- FEATURE: Internal client update. No user facing changes, but major version bump to be safe.
- BUGFIX: Adds partitionKey parameter to
container.conflicts.delete
- BUGFIX: Pins node-abort-controller version as we depend on a type in v1.2.0.
- FEATURE: Adds Bulk continueOnError option.
- BUGFIX: Removes direct dependency on @azure/identity while retaining compatibility.
- BUGFIX: Fixes @azure/identity dependency in dev deps.
- BUGFIX: Autogenerates IDs for Upsert operations in bulk.
- FEATURE: Adds AAD authentication via @azure/identity.
- BUGFIX: Throws correct Invalid Continuation Token error when making request with malformed token
- BUGFIX: Defaults partitionKeyValue to
'[{}]'
when missing in Read/Delete bulk operations - BUGFIX: Sums group by operations for cross-partition queries correctly with null values.
- BUGFIX: Fixes bulk operations with top level partitionKey values that are undefined or null.
- BUGFIX: Fixes slow
userAgent
lookup on azure functions.
- BUGFIX: Fixes
OperationInput
type to be more accurate based onOperationType
. - FEATURE: Bulk requests with
Create
operations will now autogenerate IDs if they are not present. - FEATURE: The
BulkOperationType
enum now exists and can be used when making bulk requests.
- FEATURE: Adds support for autoscale parameters on container and database create methods
Note that maxThroughput
cannot be passed with throughput
.
// correct
const containerDefinition = {
id: "sample container",
indexingPolicy: { indexingMode: IndexingMode.consistent },
maxThroughput: 500,
autoUpgradePolicy: {
throughputPolicy: {
incrementPercent: 15
}
}
};
database.container.create(containerDefinition)
// incorrect
const containerDefinition = {
id: "sample container",
indexingPolicy: { indexingMode: IndexingMode.consistent },
throughput: 500, // do not specify throughput with maxThroughput
maxThroughput: 500
autoUpgradePolicy: {
throughputPolicy: {
incrementPercent: 15
}
}
};
database.container.create(containerDefinition)
- BUGFIX: Fix checkURL function for Node 8
- BUGFIX: Adds separate URL module for browser/node.
- FEATURE: Throws when initializing ClientContext with an invalid endpoint
- FEATURE: Changes JSONArray type internal from Array to ArrayLike to avoid requiring type coercion for immutable data
- FEATURE: Adds bulk request to container.items. Allows aggregate bulk request for up to 100 operations on items with the types: Create, Upsert, Read, Replace, Delete
// up to 100 operations
const operations: OperationInput[] = [
{
operationType: "Create",
resourceBody: { id: "doc1", name: "sample", key: "A" },
},
{
operationType: "Upsert",
resourceBody: { id: "doc2", name: "other", key: "A" },
},
{
operationType: "Read",
id: "readItemId",
partitionKey: "key",
},
];
await database.container.items.bulk(operations);
- BUGFIX: Properly escape ASCII "DEL" character in partition key header
- BUGFIX: Cannot create item with automatic id generation and a container partitioned on ID (#9734)
- BUGFIX: Internal abort signal incorrectly triggered when user passes a custom abort signal. See #9510 for details.
- BUGFIX: Typo in globalCrypto.js causing errors in IE browser
- BUGFIX: Resource tokens not matching for item delete operations (#9110)
- BUGFIX: Support crypto functions in Internet Explorer browser
- BUGFIX: Incorrect key casing in object returned by
setAuthorizationHeader
- FEATURE: Adds
readOffer
methods to container and database - FEATURE: Allows string value
partitionKey
parameter when creating containers
The following result in the same behavior:
const containerDefinition = {
id: "sample container",
indexingPolicy: { indexingMode: IndexingMode.consistent },
throughput: 400,
partitionKey: { paths: ["/key"] }
};
database.container.create(containerDefinition);
// OR as a string
const containerDefinition = {
id: "sample container",
indexingPolicy: { indexingMode: IndexingMode.consistent },
throughput: 400,
partitionKey: "/key" } // must have leading slash "/"
};
database.container.create(containerDefinition);
- FEATURE: Add
partitionKey
toFeedOptions
for scoping a query to a single partition key value
@azure/cosmos V2 has two different but equivalent ways to specify the partition key for a query:
// V2 These are effectively the same
container.items.query("SELECT * from c", { partitionKey: "foo" }).toArray();
container.items.query('SELECT * from c WHERE c.yourPartitionKey = "foo"').toArray();
In an effort to simplify, the V3 SDK removed partitionKey
from FeedOptions
so there was only one way to specify the partition key:
// V3
container.items.query('SELECT * from c WHERE c.yourPartitionKey = "foo"').fetchAll();
Based on customer feedback, we identified scenarios where it still makes sense to support passing the partition key via FeedOptions
and have decided to restore the behavior.
- BUG FIX: Support signing in web workers where this === self
- BUG FIX: Normalize location names when selecting endpoint. Allows passing of normalized endpoint names
- FEATURE: Add support for spatial indexing, bounding boxes, and geospatial configuration
- BUG FIX: Fix bug when passing forceQueryPlan to QueryIterator for non-item resources (#7333)
- BUG FIX: Return parsed number instead of string for request charge
- BUG FIX: maxDegreeOfParallelism was defaulting to 1 and should default to the number of partitions of the collection
- BUG FIX: maxItemCount was defaulting to 10 and should default to undefined
- Set default TLS version to 1.2 (#6761)
- Use tslib 1.10.0 (#6710)
- Add partition key to code sample (#6612)
- Fix handling of special characters in item ids when signing tokens in the browser (#6379)
- Fix bug when paginating GROUP BY queries or using in conjunction with TOP/OFFSET/LIMIT (#6003)
- Improve error message for mixed type ORDER BY (#6306)
- FEATURE: Endpoint discovery and multi-region failover improvements. See #6283 for more information on this change. (#6283)
- Makes changeFeed and query options optional. Fix #6232 Fix #6277 (#6273)
- Fixes bug where the query may throw a 410 error during a split operation. Instead, throw 503 (#6074)
- Fix region drop failover scenario and add test (#5892)
- FEATURE: GROUP BY query support (#5749)
- Update proxy-agent. Remove types folder (#5854)
- Typo: Fix "an" vs "a" (#5812)
- Update to Mocha 6.2.2 (#5824)
- Remove unused Range type (#5686)
- Remove universal-user-agent (#5869)
- Query bug fix. Empty result last call not reporting proper RUs (#5517)
- Sign headers using internal package (#5523)
- Use internal digest function instead of crypto-hash package (#5493)
- Remove internal binary-search-bounds package (#5417)
- Fix atob bug impacting browser users (#5375)
- Export TokenProvider and RequestInfo types (#5262)
- Remove atob package in favor of local version (#5334)
- Fix incorrect lib version in UserAgent (#5295)
- Allow zero for Item TTL (#5257)
- FEATURE: Add userAgentSuffix to CosmosClient constructor options (#5068)
- Guard process.env to fix webpack issues (#5223)
- Fixes bug where initial QueryIterator promise was not being created (#5215)
- Fix aggregates bug when query was returning no results (#5184)
- sideEffects field set to false (#5022)
- FEATURE: Endpoint resolution now blocks until initialized (#409)
- FEATURE: Add bufferItems support & other cross-partition perf improvements (#397)
- Fix missing AbortSignal type for users not targeting the DOM (#416)
- Add sample for bulk update with continuation token (#402)
- Export default partition key path (#405)
- Fix bug where offset limit iterator was being called for each item under the offset count (#398)
- Add retry on EPIPE error (#400)
- FEATURE: Set default ResponseContinuationTokenLimitInKB to 1kb. Prevents header limit errors (#384)
- Remove unused disableSSLVerification options (#388)
- Allow initialHeaders to explicitly set partition key header (#383)
- Use package.json#files to prevent extraneous files from being pubished (#382)
- Fix for routing map sort error on older version of node+v8 (#378)
- Fixes bug when user supplies partial retry options. Close #377 (#379)
- README updates (#374)
- Fix webpack usage. Prevent resolving modules called with
require
(#373) - Various internal API cleanups and sample fixes
Fixes a long outstanding bug where RUs were always being reported as 0 for aggregate queries (#366)
Fixes broken session tokens in the browser. Cosmos uses file system friendly base64 to represent resources internally but does not work with the builtin browser atob function (#363)
🎉 v3 release! 🎉 Many new features, bug fixes, and a few breaking changes. Primary goals of this release:
- Implement major new features:
- DISTINCT queries
- LIMIT/OFFSET queries
- User cancelable requests
- Update to the latest Cosmos REST API version where all containers have unlimited scale
- Make it easier to use Cosmos from the browser
- Better align with the new Azure JS SDK guidlines
Constructor options have been simplified:
masterKey
was renamedkey
and moved to the top-level- Properties previously under
options.auth
have moved to the top-level
// v2
const client = new CosmosClient({
endpoint: "https://your-database.cosmos.azure.com",
auth: {
masterKey: "your-primary-key",
},
});
// v3
const client = new CosmosClient({
endpoint: "https://your-database.cosmos.azure.com",
key: "your-primary-key",
});
In v2 there were many different ways to iterate or retrieve results from a query. We have attempted to simplify the v3 API and remove similar or duplciate APIs:
- Remove iterator.next() and iterator.current(). Use fetchNext() to get pages of results.
- Remove iterator.forEach(). Use async iterators instead.
- iterator.executeNext() renamed to iterator.fetchNext()
- iterator.toArray() renamed to iterator.fetchAll()
- Pages are now proper
Response
objects intead of plain JS objects
const container = client.database(dbId).container(containerId)
// v2
container.items.query('SELECT * from c').toArray()
container.items.query('SELECT * from c').executeNext()
container.items.query('SELECT * from c').forEach(({ body: item }) => { console.log(item.id) })
// v3
container.items.query('SELECT * from c').fetchAll()
container.items.query('SELECT * from c').fetchNext()
for await(const { result: item } in client.databases.readAll().getAsyncIterator()) {
console.log(item.id)
}
v2 has two different but equivalent ways to specify the partition key for a query:
// v2. These are effectively the same
container.items.query("SELECT * from c", { partitionKey: "foo" }).toArray();
container.items.query('SELECT * from c WHERE c.yourPartitionKey = "foo"').toArray();
v3 removed partitionKey
from FeedOptions
so there is now only one way to specify the partition key:
// v3
container.items.query('SELECT * from c WHERE c.yourPartitionKey = "foo"').fetchAll();
The Cosmos service now supports partition keys on all containers, including those that were previously created as fixed containers. The v3 SDK updates to the latest API version that implements this change, but it is not breaking. If you do not supply a partition key for operations, we will default to a system key that works with all your existing containers and documents.
Previously upsert
was allowed for non-partitioned collections, but with the API version update, all collections are partitioned so we removed it entirely.
const container = client.database(dbId).container(containerId);
// v2
try {
container.items.read(id, undefined);
} catch (e) {
if (e.code === 404) {
console.log("item not found");
}
}
// v3
const { result: item } = container.items.read(id, undefined);
if (item === undefined) {
console.log("item not found");
}
The SDK will now write to multiple regions by default if your database configuration supports it. This was previously opt-in behavior.
Failed requests now throw proper Error
or subclasses of Error
. Previously they threw plain JS objects.
The move to fetch
internally allows us to use the browser AbortController
API to support user cancellable operations. In the case of operations where multiple requests are potentially in progress (like cross partition queries), all requests for the operation will be canceled. Modern browser users will already have AbortController
. Node.js users will need to use a polyfill library
const controller = new AbortController();
const { result: item } = await items.query("SELECT * from c", { abortSignal: controller.signal });
controller.abort();
const { database } = client.databases.create({ id: "my-database", throughput: 10000 });
database.containers.create({ id: "my-container", throughput: 10000 });
Header token generation was split out into a new library, @azure/cosmos-sign. Anyone calling the Cosmos REST API directly can use this to sign headers using the same code we call inside @azure/cosmos.
v2 had custom code to generate item IDs. We have switched to the well known and maintained community library uuid
.
It is now possible to pass a connection string copied from the Azure portal:
const client = new CosmosClient(
"AccountEndpoint=https://test-account.documents.azure.com:443/;AccountKey=<KEY HERE>;",
);
const { results } = await items.query("SELECT DISTINCT VALUE r.name FROM ROOT").fetchAll();
const { results } = await items.query("SELECT * FROM root r OFFSET 1 LIMIT 2").fetchAll();
While it was possible to use the v2 SDK in the browser it was not an ideal experience. You needed to polyfill several node.js built-in libraries and use a bundler like Webpack or Parcel. The v3 SDK makes the out of the box experience much better for browser users.
- Replace request internals with
fetch
(#245) - Remove usage of Buffer (#330)
- Remove node builtin usage in favor of universal packages/APIs (#328)
- Switch to node-abort-controller (#294)
- Fix offer read and bring back offer tests (#224)
- Fix EnableEndpointDiscovery (#207)
- Fix missing RUs on paginated results (#360)
- Expand SQL query parameter type (#346)
- Add ttl to ItemDefinition (#341)
- Fix CP query metrics (#311)
- Add activityId to FeedResponse (#293)
- Switch _ts type from string to number (#252)(#295)
- Fix Request Charge Aggregation (#289)
- Allow blank string partition keys (#277)
- Add string to conflict query type (#237)
- Add uniqueKeyPolicy to container (#234)
Not always the most visible changes, but they help our team ship better code, faster.
- Use rollup for production builds (#104)
- Update to Typescript 3.5 (#327)
- Convert to TS project references. Extract test folder (#270)
- Enable noUnusedLocals and noUnusedParameters (#275)
- Azure Pipelines YAML for CI builds (#298)
- Fix type issue (See #141)
- Multi-region Write support
- Shared resource response properties added to responses
- Changed query to allow for customer types for all Resource types
- Modified items.query to allow for cross partition query
- Misc fixes/doc updates
- New object model
- Updated documentation and samples
- Improved types
- Added
createdIfNotExists
for database and container - Added prettier
- Added public CI (Travis and VSTS)
- Added Promise support
- Added token handler option for auth
- typings now emitted from source (moved source to TypeScript)
- Added CosmosClient (DocumentClient now considered deprecated)
- npm documentation fixed.
- Added support for default retries on connection issues.
- Added support to read collection change feed.
- Fixed session consistency bug that intermittently caused "read session not available".
- Added support for query metrics.
- Modified http Agent's maximum number of connections.
- Updated documentation to use Azure Cosmos DB.
- Added Support for proxyUrl setting in ConnectionPolicy.
- Minor fix for case sensitive file systems.
- Adds support for Session Consistency.
- This SDK version requires the latest version of Azure Cosmos DB Emulator available for download from https://aka.ms/cosmosdb-emulator.
- Splitproofed cross partition queries.
- Adds supports for resource link with leading and trailing slashes (and corresponding tests).
- npm documentation fixed.
- Fixed bug in executeStoredProcedure where documents involved had special unicode characters (LS, PS).
- Fixed bug in handling documents with unicode characters in partition key.
- Fixed support for creating collection with name media (github #114).
- Fixed support for permission authorization token (github #178).
- Added support for Request Unit per Minute (RU/m) feature.
- Added support for a new consistency level called ConsistentPrefix.
- Added support for UriFactory.
- Fixed the unicode support bug (github #171)
- Added the support for aggregation queries (COUNT, MIN, MAX, SUM, and AVG).
- Added the option for controlling degree of parallelism for cross partition queries.
- Added the option for disabling SSL verification when running against Emulator.
- Lowered minimum throughput on partitioned collections from 10,100 RU/s to 2500 RU/s.
- Fixed the continuation token bug for single partition collection (github #107).
- Fixed the executeStoredProcedure bug in handling 0 as single param (github #155).
- Fixed user-agent header to include the SDK version.
- Minor code cleanup.
- Disabling SSL verification when using the SDK to target the emulator(hostname=localhost).
- Added support for enabling script logging during stored procedure execution.
- Added support for cross partition parallel queries.
- Added support for TOP/ORDER BY queries for partitioned collections.
-
Added retry policy support for throttled requests. (Throttled requests receive a request rate too large exception, error code 429.) By default, DocumentClient retries nine times for each request when error code 429 is encountered, honoring the retryAfter time in the response header. A fixed retry interval time can now be set as part of the RetryOptions property on the ConnectionPolicy object if you want to ignore the retryAfter time returned by server between the retries. DocumentClient now waits for a maximum of 30 seconds for each request that is being throttled (irrespective of retry count) and returns the response with error code 429. This time can also be overriden in the RetryOptions property on ConnectionPolicy object.
-
DocumentClient now returns x-ms-throttle-retry-count and x-ms-throttle-retry-wait-time-ms as the response headers in every request to denote the throttle retry count and the cummulative time the request waited between the retries.
-
The RetryOptions class was added, exposing the RetryOptions property on the ConnectionPolicy class that can be used to override some of the default retry options.
- Added the support for geo-replicated database accounts.
- Added the support for TimeToLive(TTL) feature for documents.
- Added support for Partitioned Collections.
- Added support for new offer types.
- Fixed RangePartitionResolver.resolveForRead bug where it was not returning links due to a bad concat of results.
- Move compareFunction from Range class to RangePartitionResolver class.
- Fixed hashParitionResolver resolveForRead(): When no partition key supplied was throwing exception, instead of returning a list of all registered links.
- Dedicated HTTPS Agent: Avoid modifying the global. Use a dedicated agent for all of the lib’s requests.
- Properly handle dashes in the mediaIds.
- Fix memory leak.
- Renamed "Hash" directory to "hash".
- Added client-side sharding support.
- Added hash partition resolver implementation.
- Added range partitoin resolver implementation.
- Implement Upsert. New upsertXXX methods on documentClient.
- Skipped to bring version numbers in alignment with other SDKs.
- Split Q promises wrapper to new repository.
- Update to package file for npm registry.
- Implements ID Based Routing.
- Fixes Issue #49 - current property conflicts with method current().
- Added support for GeoSpatial index.
- Validates id property for all resources. Ids for resources cannot contain ?, /, #, \, characters or end with a space.
- Adds new header "index transformation progress" to ResourceResponse.
- Implements V2 indexing policy.
- Issue #40 - Implemented eslint and grunt configurations in the core and promise SDK.
- Issue #45 - Promises wrapper does not include header with error.
- Implemented ability to query for conflicts by adding readConflicts, readConflictAsync, queryConflicts.
- Updated API documentation.
- Issue #41 - client.createDocumentAsync error.
Microsoft will provide notification at least 12 months in advance of retiring an SDK in order to smooth the transition to a newer/supported version.
New features, functionality, and optimizations are only added to the current SDK. So it's recommended that you always upgrade to the latest SDK version as early as possible.
Any request to Cosmos DB using a retired SDK will be rejected by the service.
Warning
All versions 1.x of the Cosmos JavaScript SDK for SQL API will be retired on August 30, 2020.
Version | Release Date | Retirement Date |
---|---|---|
3.4.2 | November 7, 2019 | --- |
3.4.1 | November 5, 2019 | --- |
3.4.0 | October 28, 2019 | --- |
3.3.6 | October 14, 2019 | --- |
3.3.5 | October 14, 2019 | --- |
3.3.4 | October 14, 2019 | --- |
3.3.3 | October 3, 2019 | --- |
3.3.2 | October 3, 2019 | --- |
3.3.1 | October 1, 2019 | --- |
3.3.0 | September 24, 2019 | --- |
3.2.0 | August 26, 2019 | --- |
3.1.1 | August 7, 2019 | --- |
3.1.0 | July 26, 2019 | --- |
3.0.4 | July 22, 2019 | --- |
3.0.3 | July 17, 2019 | --- |
3.0.2 | July 9, 2019 | --- |
3.0.0 | June 28, 2019 | --- |
2.1.5 | March 20, 2019 | --- |
2.1.4 | March 15, 2019 | --- |
2.1.3 | March 8, 2019 | --- |
2.1.2 | January 28, 2019 | --- |
2.1.1 | December 5, 2018 | --- |
2.1.0 | December 4, 2018 | --- |
2.0.5 | November 7, 2018 | --- |
2.0.4 | October 30, 2018 | --- |
2.0.3 | October 30, 2018 | --- |
2.0.2 | October 10, 2018 | --- |
2.0.1 | September 25, 2018 | --- |
2.0.0 | September 24, 2018 | --- |
2.0.0-3 (RC) | August 2, 2018 | --- |
1.14.4 | May 03, 2018 | August 30, 2020 |
1.14.3 | May 03, 2018 | August 30, 2020 |
1.14.2 | December 21, 2017 | August 30, 2020 |
1.14.1 | November 10, 2017 | August 30, 2020 |
1.14.0 | November 9, 2017 | August 30, 2020 |
1.13.0 | October 11, 2017 | August 30, 2020 |
1.12.2 | August 10, 2017 | August 30, 2020 |
1.12.1 | August 10, 2017 | August 30, 2020 |
1.12.0 | May 10, 2017 | August 30, 2020 |
1.11.0 | March 16, 2017 | August 30, 2020 |
1.10.2 | January 27, 2017 | August 30, 2020 |
1.10.1 | December 22, 2016 | August 30, 2020 |
1.10.0 | October 03, 2016 | August 30, 2020 |
1.9.0 | July 07, 2016 | August 30, 2020 |
1.8.0 | June 14, 2016 | August 30, 2020 |
1.7.0 | April 26, 2016 | August 30, 2020 |
1.6.0 | March 29, 2016 | August 30, 2020 |
1.5.6 | March 08, 2016 | August 30, 2020 |
1.5.5 | February 02, 2016 | August 30, 2020 |
1.5.4 | February 01, 2016 | August 30, 2020 |
1.5.3 | January 26, 2016 | August 30, 2020 |
1.5.2 | January 22, 2016 | August 30, 2020 |
1.5.1 | January 4, 2016 | August 30, 2020 |
1.5.0 | December 31, 2015 | August 30, 2020 |
1.4.0 | October 06, 2015 | August 30, 2020 |
1.3.0 | October 06, 2015 | August 30, 2020 |
1.2.2 | September 10, 2015 | August 30, 2020 |
1.2.1 | August 15, 2015 | August 30, 2020 |
1.2.0 | August 05, 2015 | August 30, 2020 |
1.1.0 | July 09, 2015 | August 30, 2020 |
1.0.3 | June 04, 2015 | August 30, 2020 |
1.0.2 | May 23, 2015 | August 30, 2020 |
1.0.1 | May 15, 2015 | August 30, 2020 |
1.0.0 | April 08, 2015 | August 30, 2020 |