Share via

Containers class

  • Reference
Package:
@azure/cosmos

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.

Properties

database

Methods

create(ContainerRequest, RequestOptions)

Creates a container.

A container is a named logical container for items.

A database may contain zero or more named containers and each container consists of zero or more JSON items.

Being schema-free, the items in a container do not need to share the same structure or fields.

Since containers are application resources, they can be authorized using either the master key or resource keys.

Example

import { CosmosClient } from "@azure/cosmos";

const endpoint = "https://your-account.documents.azure.com";
const key = "<database account masterkey>";
const client = new CosmosClient({ endpoint, key });
const container = client.database("<database id>").containers.create({
  id: "<name here>",
});
createIfNotExists(ContainerRequest, RequestOptions)

Checks if a Container exists, and, if it doesn't, creates it. This will make a read operation based on the id in the body, then if it is not found, a create operation. You should confirm that the output matches the body you passed in for non-default properties (i.e. indexing policy/etc.)

A container is a named logical container for items.

A database may contain zero or more named containers and each container consists of zero or more JSON items.

Being schema-free, the items in a container do not need to share the same structure or fields.

Since containers are application resources, they can be authorized using either the master key or resource keys.

Example

import { CosmosClient } from "@azure/cosmos";

const endpoint = "https://your-account.documents.azure.com";
const key = "<database account masterkey>";
const client = new CosmosClient({ endpoint, key });

const { database } = await client.databases.createIfNotExists({ id: "Test Database" });
const { container } = await database.containers.createIfNotExists({ id: "Test Container" });
query(SqlQuerySpec, FeedOptions)

Queries all containers.

Example

Read all containers to array.

import { CosmosClient, SqlQuerySpec } from "@azure/cosmos";

const endpoint = "https://your-account.documents.azure.com";
const key = "<database account masterkey>";
const client = new CosmosClient({ endpoint, key });

const querySpec: SqlQuerySpec = {
  query: `SELECT * FROM root r WHERE r.id = @container`,
  parameters: [{ name: "@container", value: "Todo" }],
};
const { resources: containerList } = await client
  .database("<db id>")
  .containers.query(querySpec)
  .fetchAll();
query<T>(SqlQuerySpec, FeedOptions)

Queries all containers.

Example

Read all containers to array.

import { CosmosClient, SqlQuerySpec } from "@azure/cosmos";

const endpoint = "https://your-account.documents.azure.com";
const key = "<database account masterkey>";
const client = new CosmosClient({ endpoint, key });

const querySpec: SqlQuerySpec = {
  query: `SELECT * FROM root r WHERE r.id = @container`,
  parameters: [{ name: "@container", value: "Todo" }],
};
const { resources: containerList } = await client
  .database("<db id>")
  .containers.query(querySpec)
  .fetchAll();
readAll(FeedOptions)

Read all containers.

Example

Read all containers to array.

import { CosmosClient } from "@azure/cosmos";

const endpoint = "https://your-account.documents.azure.com";
const key = "<database account masterkey>";
const client = new CosmosClient({ endpoint, key });

const { resources: containerList } = await client
  .database("<db id>")
  .containers.readAll()
  .fetchAll();

Property Details

database 

database: Database

Property Value

Database

Method Details

create(ContainerRequest, RequestOptions)

Creates a container.

A container is a named logical container for items.

A database may contain zero or more named containers and each container consists of zero or more JSON items.

Being schema-free, the items in a container do not need to share the same structure or fields.

Since containers are application resources, they can be authorized using either the master key or resource keys.

Example

import { CosmosClient } from "@azure/cosmos";

const endpoint = "https://your-account.documents.azure.com";
const key = "<database account masterkey>";
const client = new CosmosClient({ endpoint, key });
const container = client.database("<database id>").containers.create({
  id: "<name here>",
});

function create(body: ContainerRequest, options?: RequestOptions): Promise<ContainerResponse>

Parameters

body
ContainerRequest

Represents the body of the container.

options
RequestOptions

Use to set options like response page size, continuation tokens, etc.

Returns

Promise<ContainerResponse>

createIfNotExists(ContainerRequest, RequestOptions)

Checks if a Container exists, and, if it doesn't, creates it. This will make a read operation based on the id in the body, then if it is not found, a create operation. You should confirm that the output matches the body you passed in for non-default properties (i.e. indexing policy/etc.)

A container is a named logical container for items.

A database may contain zero or more named containers and each container consists of zero or more JSON items.

Being schema-free, the items in a container do not need to share the same structure or fields.

Since containers are application resources, they can be authorized using either the master key or resource keys.

Example

import { CosmosClient } from "@azure/cosmos";

const endpoint = "https://your-account.documents.azure.com";
const key = "<database account masterkey>";
const client = new CosmosClient({ endpoint, key });

const { database } = await client.databases.createIfNotExists({ id: "Test Database" });
const { container } = await database.containers.createIfNotExists({ id: "Test Container" });

function createIfNotExists(body: ContainerRequest, options?: RequestOptions): Promise<ContainerResponse>

Parameters

body
ContainerRequest

Represents the body of the container.

options
RequestOptions

Use to set options like response page size, continuation tokens, etc.

Returns

Promise<ContainerResponse>

query(SqlQuerySpec, FeedOptions)

Queries all containers.

Example

Read all containers to array.

import { CosmosClient, SqlQuerySpec } from "@azure/cosmos";

const endpoint = "https://your-account.documents.azure.com";
const key = "<database account masterkey>";
const client = new CosmosClient({ endpoint, key });

const querySpec: SqlQuerySpec = {
  query: `SELECT * FROM root r WHERE r.id = @container`,
  parameters: [{ name: "@container", value: "Todo" }],
};
const { resources: containerList } = await client
  .database("<db id>")
  .containers.query(querySpec)
  .fetchAll();

function query(query: SqlQuerySpec, options?: FeedOptions): QueryIterator<any>

Parameters

query
SqlQuerySpec

Query configuration for the operation. See SqlQuerySpec for more info on how to configure a query.

options
FeedOptions

Use to set options like response page size, continuation tokens, etc.

Returns

QueryIterator<any>

QueryIterator Allows you to return specific containers in an array or iterate over them one at a time.

query<T>(SqlQuerySpec, FeedOptions)

Queries all containers.

Example

Read all containers to array.

import { CosmosClient, SqlQuerySpec } from "@azure/cosmos";

const endpoint = "https://your-account.documents.azure.com";
const key = "<database account masterkey>";
const client = new CosmosClient({ endpoint, key });

const querySpec: SqlQuerySpec = {
  query: `SELECT * FROM root r WHERE r.id = @container`,
  parameters: [{ name: "@container", value: "Todo" }],
};
const { resources: containerList } = await client
  .database("<db id>")
  .containers.query(querySpec)
  .fetchAll();

function query<T>(query: SqlQuerySpec, options?: FeedOptions): QueryIterator<T>

Parameters

query
SqlQuerySpec

Query configuration for the operation. See SqlQuerySpec for more info on how to configure a query.

options
FeedOptions

Use to set options like response page size, continuation tokens, etc.

Returns

QueryIterator<T>

QueryIterator Allows you to return specific containers in an array or iterate over them one at a time.

readAll(FeedOptions)

Read all containers.

Example

Read all containers to array.

import { CosmosClient } from "@azure/cosmos";

const endpoint = "https://your-account.documents.azure.com";
const key = "<database account masterkey>";
const client = new CosmosClient({ endpoint, key });

const { resources: containerList } = await client
  .database("<db id>")
  .containers.readAll()
  .fetchAll();

function readAll(options?: FeedOptions): QueryIterator<ContainerDefinition & Resource>

Parameters

options
FeedOptions

Use to set options like response page size, continuation tokens, etc.

Returns

QueryIterator<ContainerDefinition & Resource>

QueryIterator Allows you to return all containers in an array or iterate over them one at a time.