Azure Cosmos DB Node.js SDK for SQL API: Release notes and resources

• 08/12/2020
• 14 minutter til læsning
• • a
  • S
  • D
  • d
  • N
  • +9

APPLIES TO: SQL API

Release notes

3.1.0

• Set default ResponseContinuationTokenLimitInKB to 1kb. By default, we are capping this to 1kb to avoid long headers (Node.js has a global header size limit). A user may set this field to allow for longer headers, which can help the backend optimize query execution.
• Remove disableSSLVerification. This option has new alternatives described in #388

3.0.4

• Allow initialHeaders to explicitly set partition key header
• Use package.json#files to prevent extraneous files from being published
• Fix routing map sort error on older version of node+v8
• Fixes bug when user supplies partial retry options

3.0.3

• Prevent webpack from resolving modules called with require

3.0.2

• Fixes a long outstanding bug where RUs were always being reported as 0 for aggregate queries

3.0.0

🎉 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 guidelines

Migration guide for breaking changes

Improved client Constructor options

Constructor options have been simplified:

• masterKey was renamed key 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"
})

Simplified QueryIterator API

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 duplicate 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 instead 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)
}

Fixed containers are now partitioned

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.

Upsert removed for stored procedures

Previously upsert was allowed for non-partitioned collections, but with the API version update, all collections are partitioned so we removed it entirely.

Item reads will not throw on 404

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') }

Default multi-region write

The SDK will now write to multiple regions by default if your Cosmos configuration supports it. This was previously opt-in behavior.

Proper error objects

Failed requests now throw proper Error or subclasses of Error. Previously they threw plain JS objects.

New features

User-cancelable requests

The move to fetch internally allows us to use the browser AbortController API to support user-cancelable 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()

Set throughput as part of db/container create operation

const { database }  = client.databases.create({ id: 'my-database', throughput: 10000 })
database.containers.create({ id: 'my-container', throughput: 10000 })

@azure/cosmos-sign

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.

UUID for generated IDs

v2 had custom code to generate item IDs. We have switched to the well known and maintained community library uuid.

Connection strings

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=c213asdasdefgdfgrtweaYPpgoeCsHbpRTHhxuMsTaw==;")
Add DISTINCT and LIMIT/OFFSET queries (#306)
 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()

Improved browser experience

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)

Bug fixes

• 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)

Engineering systems

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)

2.1.5

• No code changes. Fixes an issue where some extra files were included in 2.1.4 package.

2.1.4

• Fix regional failover within retry policy
• Fix ChangeFeed hasMoreResults property
• Dev dependency updates
• Add PolicheckExclusions.txt

2.1.3

• Switch _ts type from string to number
• Fix default indexing tests
• Backport uniqueKeyPolicy to v2
• Demo and demo debugging fixes

2.1.2

• Backport offer fixes from v3 branch
• Fix bug in executeNext() type signature
• Typo fixes

2.1.1

• Build restructuring. Allows pulling the SDK version at build time.

2.1.0

New Features

• Added ChangeFeed support (#196)
• Added MultiPolygon datatype for indexing (#191)
• Add "key" property to constructor as alias for masterKey (#202)

Fixes

• Fix bug where next() was returning incorrect value on iterator

Engineering Improvements

• Add integration test for typescript consumption (#199)
• Enable installing directly from GitHub (#194)

2.0.5

• Adds interface for node Agent type. Typescript users no longer have to install @types/node as a dependency
• Preferred locations are now properly honored
• Improvements to contributing developer documentation
• Various typo fixes

2.0.4

• Fixes type definition issue introduced in 2.0.3

2.0.3

• Remove big-integer dependency
• Switch to reference directives for AsyncIterable type. Typescript users no longer have to customize their "lib" setting.
• Typo Fixes

2.0.2

• Fix readme links

2.0.1

• Fix retry interface implementation

2.0.0

• GA of Version 2.0.0 of the JavaScript SDK
• Added support for multi-region writes.

2.0.0-3

• RC1 of Version 2.0.0 of the JavaScript SDK for public preview.
• New object model, with top-level CosmosClient and methods split across relevant Database, Container, and Item classes.
• Support for promises.
• SDK converted to TypeScript.

1.14.4

• npm documentation fixed.

1.14.3

• 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.

1.14.2

• Updated documentation to reference Azure Cosmos DB instead of Azure DocumentDB.
• Added Support for proxyUrl setting in ConnectionPolicy.

1.14.1

• Minor fix for case sensitive file systems.

1.14.0

• Adds support for Session Consistency.
• This SDK version requires the latest version of Azure Cosmos DB Emulator.

1.13.0

• Split proofed cross partition queries.
• Adds supports for resource link with leading and trailing slashes (and corresponding tests).

1.12.2

• npm documentation fixed.

1.12.1

• Fixed a bug in executeStoredProcedure where documents involved had special Unicode characters (LS, PS).
• Fixed a bug in handling documents with Unicode characters in the partition key.
• Fixed support for creating collections with the name media. GitHub issue #114.
• Fixed support for permission authorization token. GitHub issue #178.

1.12.0

• Added support for a new consistency level called ConsistentPrefix.
• Added support for UriFactory.
• Fixed a Unicode support bug. GitHub issue #171.

1.11.0

• 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 TLS verification when running against Azure Cosmos DB 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 issue #107.
• Fixed the executeStoredProcedure bug in handling 0 as single param. GitHub issue #155.

1.10.2

• Fixed user-agent header to include the SDK version.
• Minor code cleanup.

1.10.1

• Disabling TLS verification when using the SDK to target the emulator(hostname=localhost).
• Added support for enabling script logging during stored procedure execution.

1.10.0

• Added support for cross partition parallel queries.
• Added support for TOP/ORDER BY queries for partitioned collections.

1.9.0

• Added retry policy support for throttled requests. (Throttled requests receive a request rate too large exception, error code 429.) By default, Azure Cosmos DB 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. Azure Cosmos DB 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 overridden in the RetryOptions property on ConnectionPolicy object.
• Cosmos DB 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 cumulative 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.

1.8.0

• Added the support for multi-region database accounts.

1.7.0

• Added the support for Time To Live(TTL) feature for documents.

1.6.0

• Implemented partitioned collections and user-defined performance levels.

1.5.6

• Fixed RangePartitionResolver.resolveForRead bug where it was not returning links due to a bad concat of results.

1.5.5

• Fixed hashPartitionResolver resolveForRead(): When no partition key supplied was throwing exception, instead of returning a list of all registered links.

1.5.4

• Fixes issue #100 - Dedicated HTTPS Agent: Avoid modifying the global agent for Azure Cosmos DB purposes. Use a dedicated agent for all of the lib's requests.

1.5.3

• Fixes issue #81 - Properly handle dashes in media IDs.

1.5.2

• Fixes issue #95 - EventEmitter listener leak warning.

1.5.1

• Fixes issue #92 - rename folder Hash to hash for case-sensitive systems.

1.5.0

• Implement sharding support by adding hash & range partition resolvers.

1.4.0

• Implement Upsert. New upsertXXX methods on documentClient.

1.3.0

• Skipped to bring version numbers in alignment with other SDKs.

1.2.2

• Split Q promises wrapper to new repository.
• Update to package file for npm registry.

1.2.1

• Implements ID Based Routing.
• Fixes Issue #49 - current property conflicts with method current().

1.2.0

• 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.

1.1.0

• Implements V2 indexing policy.

1.0.3

• Issue #40 - Implemented eslint and grunt configurations in the core and promise SDK.

1.0.2

• Issue #45 - Promises wrapper does not include header with error.

1.0.1

• Implemented ability to query for conflicts by adding readConflicts, readConflictAsync, and queryConflicts.
• Updated API documentation.
• Issue #41 - client.createDocumentAsync error.

1.0.0

• GA SDK.

Release & Retirement Dates

Microsoft provides notification at least 12 months in advance of retiring an SDK in order to smooth the transition to a newer/supported version. New features and functionality and optimizations are only added to the current SDK, as such it is recommended that you always upgrade to the latest SDK version as early as possible.

FAQ

How will I be notified of the retiring SDK?

Microsoft will provide 12 month's advance notice before the end of support of the retiring SDK to facilitate a smooth transition to a supported SDK. We'll notify you through various communication channels: the Azure portal, Azure updates, and direct communication to assigned service administrators.

Can I author applications by using a to-be-retired Azure Cosmos DB SDK during the 12-month period?

Yes, you'll be able to author, deploy, and modify applications by using the to-be-retired Azure Cosmos DB SDK during the 12-month notice period. We recommend that you migrate to a newer supported version of the Azure Cosmos DB SDK during the 12-month notice period, as appropriate.

After the retirement date, what happens to applications that use the unsupported Azure Cosmos DB SDK?

After the retirement date, Azure Cosmos DB will no longer make bug fixes, add new features, or provide support to the retired SDK versions. If you prefer not to upgrade, requests sent from the retired versions of the SDK will continue to be served by the Azure Cosmos DB service.

Which SDK versions will have the latest features and updates?

New features and updates will be added only to the latest minor version of the latest supported major SDK version. We recommend that you always use the latest version to take advantage of new features, performance improvements, and bug fixes. If you're using an old, non-retired version of the SDK, your requests to Azure Cosmos DB will still function, but you won't have access to any new capabilities.

What should I do if I can't update my application before a cutoff date?

We recommend that you upgrade to the latest SDK as early as possible. After an SDK is tagged for retirement, you'll have 12 months to update your application. If you're not able to update by the retirement date, requests sent from the retired versions of the SDK will continue to be served by Azure Cosmos DB, so your running applications will continue to function. But Azure Cosmos DB will no longer make bug fixes, add new features, or provide support to the retired SDK versions.

If you have a support plan and require technical support, contact us by filing a support ticket.

See also

To learn more about Cosmos DB, see Microsoft Azure Cosmos DB service page.