Releases: Azure/azure-cosmos-js
3.2.0
Bug fixes
- Fix missing AbortSignal type for users not targeting the DOM (#416)
Improvements
- Endpoint resolution now blocks until initialized (#409)
- Add bufferItems support & other cross-partition perf improvements (#397)
- Export default partition key path (#405)
Documentation
- Add sample for bulk update with continuation token (#402)
- Update Node.js version recommendation in dev.md (#418)
- Add test for aborting a query (#413)
Engineering Systems
3.1.1
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 #384
- Remove disableSSLVerification. This option has new alternatives described in #388
3.0.4
3.0.3
3.0.2
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 guidlines
Migration Guide for Breaking Changes
Improved Client Constructor Options (#246)
Constructor options have been simplified:
masterKeywas renamedkeyand moved to the top-level- Properties previously under
options.authhave 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 (#238 #316)
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
Responseobjects 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)
}Fixed Containers are now Paritioned (#308)
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 (#356)
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 (#343, Community Request)
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 (#335)
The SDK will now write to multiple regions by default if your database configuration supports it. This was previously opt-in behavior.
Proper Error Objects (#334, Community Request)
Failed requests now throw proper Error or subclasses of Error. Previously they threw plain JS objects.
New Features
User Cancellable Requests (#263, Community Request)
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()Set throughput as part of db/container create operation (#220)
const { database } = client.databases.create({ id: 'my-database', throughput: 10000 })
database.containers.create({ id: 'my-container', throughput: 10000 })@azure/cosmos-sign (#213)
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 (#355)
v2 had custom code to generate item IDs. We have switched to the well known and maintained community library uuid.
Connection Strings (#350, Community Request)
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.
2.1.5
No code changes. Fixes an issue where some extra files were included in 2.1.4 package.