Share via

@azure/cosmos package

  • Reference

Classes

AbortError

This error is thrown when an asynchronous operation has been aborted. Check for this error by testing the name that the name property of the error matches "AbortError".

Example

const controller = new AbortController();
controller.abort();
try {
  doAsyncWork(controller.signal)
} catch (e) {
  if (e.name === 'AbortError') {
    // handle abort error here.
  }
}
ChangeFeedIterator

Provides iterator for change feed.

Use Items.changeFeed() to get an instance of the iterator.
ChangeFeedIteratorResponse

A single response page from the Azure Cosmos DB Change Feed
ChangeFeedPolicy

Represents the change feed policy configuration for a container in the Azure Cosmos DB service.
ChangeFeedResponse

A single response page from the Azure Cosmos DB Change Feed
ChangeFeedRetentionTimeSpan
ChangeFeedStartFrom

Base class for where to start a ChangeFeedIterator.
ClientSideMetrics
Conflict

Use to read or delete a given Conflict by id.

See Conflicts to query or read all conflicts.
ConflictResponse
Conflicts

Use to query or read all conflicts.

See Conflict to read or delete a given Conflict by id.
Container

Operations for reading, replacing, or deleting a specific, existing container by id.

See Containers for creating new containers, and reading/querying all containers; use .containers.

Note: all these operations make calls against a fixed budget. You should design your system such that these calls scale sublinearly with your application. For instance, do not call container(id).read() before every single item.read() call, to ensure the container exists; do this once on application start up.
ContainerResponse

Response object for Container operations
Containers

Operations for creating new containers, and reading/querying all containers

See Container for reading, replacing, or deleting an existing container; use .container(id).

Note: all these operations make calls against a fixed budget. You should design your system such that these calls scale sublinearly with your application. For instance, do not call containers.readAll() before every single item.read() call, to ensure the container exists; do this once on application start up.
CosmosClient

Provides a client-side logical representation of the Azure Cosmos DB database account. This client is used to configure and execute requests in the Azure Cosmos DB database service.

Example

Instantiate a client and create a new database

const client = new CosmosClient({endpoint: "<URL HERE>", key: "<KEY HERE>"});
await client.databases.create({id: "<database name here>"});

Example

Instantiate a client with custom Connection Policy

const client = new CosmosClient({
   endpoint: "<URL HERE>",
   key: "<KEY HERE>",
   connectionPolicy: {
    requestTimeout: 10000,
   },
});
CosmosDiagnostics
  • This is a Cosmos Diagnostic type that holds collected diagnostic information during a client operations. ie. Item.read(), Container.create(). It has three members -
  1. clientSideRequestStatistics member contains aggregate diagnostic information, including -
  • metadata lookups. Here all the server requests, apart from the final intended resource are considered as metadata calls. i.e. for item.read(id), if the client makes server call to discover endpoints it would be considered as metadata call.
  • retries
  • endpoints contacted.
  • request, response payload stats.
  • gatewayStatistics - Information corresponding to main operation. For example during Item.read(), the client might perform many operations i.e. metadata lookup etc, but gatewayStatistics represents the diagnostics information for actual read operation.
  1. diagnosticNode - Is a tree like structure which captures detailed diagnostic information. By default it is disabled, and is intended to be used only for debugging on non production environments. The kind of details captured in diagnosticNode is controlled by CosmosDbDiagnosticLevel.
  • CosmosDbDiagnosticLevel.info - Is default value. In this level only clientSideRequestStatistics are captured. Is is meant for production environments.
  • CosmosDbDiagnosticLevel.debug - Captures diagnosticNode and clientConfig. No request and response payloads are captured. Is not meant to be used in production environment.
  • CosmosDbDiagnosticLevel.debug-unsafe - In addition to data captured in CosmosDbDiagnosticLevel.debug, also captures request and response payloads. Is not meant to be used in production environment.
  1. clientConfig - Captures information related to how client was configured during initialization.
Database

Operations for reading or deleting an existing database.

See Databases for creating new databases, and reading/querying all databases; use client.databases.

Note: all these operations make calls against a fixed budget. You should design your system such that these calls scale sublinearly with your application. For instance, do not call database.read() before every single item.read() call, to ensure the database exists; do this once on application start up.
DatabaseAccount

Represents a DatabaseAccount in the Azure Cosmos DB database service.
DatabaseResponse

Response object for Database operations
Databases

Operations for creating new databases, and reading/querying all databases

See Database for reading or deleting an existing database; use client.database(id).

Note: all these operations make calls against a fixed budget. You should design your system such that these calls scale sublinearly with your application. For instance, do not call databases.readAll() before every single item.read() call, to ensure the database exists; do this once on application start up.
ErrorResponse
FeedRange

Specifies a feed range for the changefeed.
FeedResponse
Item

Used to perform operations on a specific item.

See Items for operations on all items; see container.items.
ItemResponse
Items

Operations for creating new items, and reading/querying all items

See Item for reading, replacing, or deleting an existing container; use .item(id).
Offer

Use to read or replace an existing Offer by id.

See Offers to query or read all offers.
OfferResponse
Offers

Use to query or read all Offers.

See Offer to read or replace an existing Offer by id.
PartitionKeyBuilder

Builder class for building PartitionKey.
Permission

Use to read, replace, or delete a given Permission by id.

See Permissions to create, upsert, query, or read all Permissions.
PermissionResponse
Permissions

Use to create, replace, query, and read all Permissions.

See Permission to read, replace, or delete a specific permission by id.
QueryIterator

Represents a QueryIterator Object, an implementation of feed or query response that enables traversal and iterating over the response in the Azure Cosmos DB database service.
QueryMetrics
QueryPreparationTimes
ResourceResponse
RestError

A custom error type for failed pipeline requests.
RuntimeExecutionTimes
SasTokenProperties
Scripts
StoredProcedure

Operations for reading, replacing, deleting, or executing a specific, existing stored procedure by id.

For operations to create, read all, or query Stored Procedures,
StoredProcedureResponse
StoredProcedures

Operations for creating, upserting, or reading/querying all Stored Procedures.

For operations to read, replace, delete, or execute a specific, existing stored procedure by id, see container.storedProcedure().
TimeoutError
Trigger

Operations to read, replace, or delete a Trigger.

Use container.triggers to create, upsert, query, or read all.
TriggerResponse
Triggers

Operations to create, upsert, query, and read all triggers.

Use container.triggers to read, replace, or delete a Trigger.
User

Used to read, replace, and delete Users.

Additionally, you can access the permissions for a given user via user.permission and user.permissions.

See Users to create, upsert, query, or read all.
UserDefinedFunction

Used to read, replace, or delete a specified User Definied Function by id.

See UserDefinedFunction to create, upsert, query, read all User Defined Functions.
UserDefinedFunctionResponse
UserDefinedFunctions

Used to create, upsert, query, or read all User Defined Functions.

See UserDefinedFunction to read, replace, or delete a given User Defined Function by id.
UserResponse
Users

Used to create, upsert, query, and read all users.

See User to read, replace, or delete a specific User by id.

Interfaces

@azure/cosmos.Index
Agent
BulkOptions

Options object used to modify bulk execution. continueOnError (Default value: false) - Continues bulk execution when an operation fails ** NOTE THIS WILL DEFAULT TO TRUE IN the 4.0 RELEASE
ChangeFeedIteratorOptions

Specifies options for the change feed

If none of those options are set, it will start reading changes from now for the entire container.
ChangeFeedOptions

Specifies options for the change feed

Some of these options control where and when to start reading from the change feed. The order of precedence is:

  • continuation
  • startTime
  • startFromBeginning

If none of those options are set, it will start reading changes from the first ChangeFeedIterator.fetchNext() call.
ChangeFeedPullModelIterator

Use Items.getChangeFeedIterator() to return an iterator that can iterate over all the changes for a partition key, feed range or an entire container.
CompositePath

Represents a composite path in the indexing policy.
ComputedProperty
ConflictDefinition
ConflictResolutionPolicy

Represents the conflict resolution policy configuration for specifying how to resolve conflicts in case writes from different regions result in conflicts on documents in the collection in the Azure Cosmos DB service.
ConnectionPolicy

Represents the Connection policy associated with a CosmosClient in the Azure Cosmos DB database service.
ContainerDefinition
ContainerRequest
CosmosClientOptions
CosmosHeaders
CreateOperationInput
DatabaseDefinition
DatabaseRequest
DeleteOperationInput
DiagnosticNode

Represents a tree like structure, for capturing diagnostic information.
ErrorBody
FailedRequestAttemptDiagnostic

This type captures diagnostic information regarding a failed request to server api.
FeedOptions

The feed options and query methods.
FullTextIndex

Represents a full text index in the indexing policy.
FullTextPath

Represents a full text path to be indexed in the Azure Cosmos DB service.
FullTextPolicy

Represents a full text policy for a collection in the Azure Cosmos DB service.
GroupByAliasToAggregateType
IndexedPath
IndexingPolicy
ItemDefinition

Items in Cosmos DB are simply JSON objects. Most of the Item operations allow for your to provide your own type that extends the very simple ItemDefinition.

You cannot use any reserved keys. You can see the reserved key list in <xref:ItemBody>
JSONArray
JSONObject
Location

Used to specify the locations that are available, read is index 1 and write is index 0.
MetadataLookUpDiagnostic

This type contains diagnostic information regarding a single metadata request to server.
OfferDefinition
OperationBase
OperationResponse
PartitionKeyDefinition
PartitionKeyRangePropertiesNames
PatchOperationInput
PermissionBody
PermissionDefinition
ReadOperationInput
ReplaceOperationInput
RequestOptions

Options that can be specified for a requested issued to the Azure Cosmos DB servers.=
Resource
RetryOptions

Represents the Retry policy assocated with throttled requests in the Azure Cosmos DB database service.
SharedOptions

Options that can be specified for a requested issued to the Azure Cosmos DB servers.=
SpatialIndex
SqlParameter

Represents a parameter in a Parameterized SQL query, specified in SqlQuerySpec
SqlQuerySpec

Represents a SQL query in the Azure Cosmos DB service.

Queries with inputs should be parameterized to protect against SQL injection.

Example

Parameterized SQL Query

const query: SqlQuerySpec = {
  query: "SELECT * FROM Families f where f.lastName = @lastName",
  parameters: [
    {name: "@lastName", value: "Wakefield"}
  ]
};
StoredProcedureDefinition
TriggerDefinition
UniqueKey

Interface for a single unique key passed as part of UniqueKeyPolicy
UniqueKeyPolicy

Interface for setting unique keys on container creation
UpsertOperationInput
UserDefinedFunctionDefinition
UserDefinition
VectorEmbedding

Represents a vector embedding. A vector embedding is used to define a vector field in the documents.
VectorEmbeddingPolicy

Represents the policy configuration for vector embeddings in the Azure Cosmos DB service.
VectorIndex

Represents a vector index in the Azure Cosmos DB service. A vector index is used to index vector fields in the documents.

Type Aliases

AggregateType
BulkOperationResponse
BulkPatchOperation
ClientConfigDiagnostic

This type holds information related to initialization of CosmosClient
ClientSideRequestStatistics

This is a collection type for all client side diagnostic information.
CreateOperation
DeleteOperation
ExistingKeyOperation
GatewayStatistics
GroupByExpressions
JSONValue
MetadataLookUpDiagnostics

This type contains diagnostic information regarding all metadata request to server during an CosmosDB client operation.
NonePartitionKeyType

The returned object represents a partition key value that allows creating and accessing items without a value for partition key
NullPartitionKeyType

The returned object represents a partition key value that allows creating and accessing items with a null value for the partition key.
Operation
OperationInput
OperationWithItem
PartitionKey

PartitionKey of a container.
PatchOperation
PatchRequestBody
PrimitivePartitionKeyValue

A primitive Partition Key value.
ReadOperation
RemoveOperation
ReplaceOperation
RetryDiagnostics

This type captures diagnostic information regarding retries attempt during an CosmosDB client operation.
TokenProvider
UpsertOperation

Enums

ChangeFeedMode
ConflictResolutionMode
ConnectionMode

Determines the connection behavior of the CosmosClient. Note, we currently only support Gateway Mode.
ConsistencyLevel

Represents the consistency levels supported for Azure Cosmos DB client operations.
The requested ConsistencyLevel must match or be weaker than that provisioned for the database account. Consistency levels.

Consistency levels by order of strength are Strong, BoundedStaleness, Session, Consistent Prefix, and Eventual.

See https://aka.ms/cosmos-consistency for more detailed documentation on Consistency Levels.
CosmosDbDiagnosticLevel

Cosmos DB Diagnostic Level
DataType

Defines a target data type of an index path specification in the Azure Cosmos DB service.
GeospatialType
IndexKind

Specifies the supported Index types.
IndexingMode

Specifies the supported indexing modes.
MetadataLookUpType

This is enum for Type of Metadata lookups possible.
PartitionKeyDefinitionVersion

PartitionKey Definition Version
PartitionKeyKind

Type of PartitionKey i.e. Hash, MultiHash
PermissionMode

Enum for permission mode values.
PriorityLevel

Represents Priority Level associated with each Azure Cosmos DB client requests.
The Low priority requests are always throttled before any High priority requests.

By default all requests are considered as High priority requests.

See https://aka.ms/CosmosDB/PriorityBasedExecution for more detailed documentation on Priority based throttling.
SpatialType
TriggerOperation

Enum for trigger operation values. specifies the operations on which a trigger should be executed.
TriggerType

Enum for trigger type values. Specifies the type of the trigger.
UserDefinedFunctionType

Enum for udf type values. Specifies the types of user defined functions.
VectorEmbeddingDataType

Represents the data type of the vector.
VectorEmbeddingDistanceFunction

Represents the distance function to use for distance calculation in between vectors.
VectorIndexType

Represents the index type of the vector.

Functions

createAuthorizationSasToken(string, SasTokenProperties)

Experimental internal only Generates the payload representing the permission configuration for the sas token.

Function Details

createAuthorizationSasToken(string, SasTokenProperties)

Experimental internal only Generates the payload representing the permission configuration for the sas token.

function createAuthorizationSasToken(masterKey: string, sasTokenProperties: SasTokenProperties): Promise<string>

Parameters

masterKey

string

sasTokenProperties
SasTokenProperties

Returns

Promise<string>