@azure/cosmos has moved to a new repo https://github.com/Azure/azure-sdk-for-js
Prevent webpack from resolving modules called with require (#373)
Fixes a long outstanding bug where RUs were always being reported as 0 for aggregate queries (#366)
🎉 v3 release! 🎉 Many new features, bug fixes, and a few breaking changes. Primary goals of this release:
Constructor options have been simplified:
masterKey was renamed key and moved to the top-leveloptions.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:
Response objects intead of plain JS objectsconst 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)
}
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.
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=c213asdasdefgdfgrtweaYPpgoeCsHbpRTHhxuMsTaw==;")
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.
fetch (#245)Not always the most visible changes, but they help our team ship better code, faster.
No code changes. Fixes an issue where some extra files were included in 2.1.4 package.