Container class

Pacote:
@azure/cosmos

Operações para ler, substituir ou excluir um contêiner específico existente por id.

Consulte Containers para criar novos contêineres e ler/consultar todos os contêineres; use .containers.

Nota: todas estas operações fazem chamadas contra um orçamento fixo. Você deve projetar seu sistema de modo que essas chamadas sejam dimensionadas sublinearmente com seu aplicativo. Por exemplo, não ligue para container(id).read() antes de cada item.read() chamada, para garantir que o contêiner existe; Faça isso uma vez na inicialização do aplicativo.

Propriedades

conflicts

Operações para ler e consultar conflitos para um determinado contêiner.

Para ler ou excluir um conflito específico, use .conflict(id).
database
id
items

Operações para criar novos itens e ler/consultar todos os itens

Para ler, substituir ou excluir um item existente, use .item(id).

Exemplo

Criar um novo item

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" });

const { resource: createdItem } = await container.items.create({
  id: "<item id>",
  properties: {},
});
scripts

Todas as operações para procedimentos armazenados, gatilhos e funções definidas pelo usuário
url

Retorna uma URL de referência para o recurso. Usado para vincular em Permissões.

Métodos

conflict(string, PartitionKey)

Usado para ler, substituir ou excluir um de conflito de específico e existente por id.

Use .conflicts para criar novos conflitos ou consultar/ler todos os conflitos.

Exemplo

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 = database.container("Test Container");

const { resource: conflict } = await container.conflict("<conflict-id>").read();
delete(RequestOptions)

Excluir o contêiner

Exemplo

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

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

await client.database("<db id>").container("<container id>").delete();
deleteAllItemsForPartitionKey(PartitionKey, RequestOptions)

Excluir todos os documentos pertencentes ao contêiner para o valor da chave de partição fornecida

Exemplo

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",
  partitionKey: {
    paths: ["/state"],
  },
});

const cities = [
  { id: "1", name: "Olympia", state: "WA", isCapitol: true },
  { id: "2", name: "Redmond", state: "WA", isCapitol: false },
  { id: "3", name: "Olympia", state: "IL", isCapitol: false },
];
for (const city of cities) {
  await container.items.create(city);
}

await container.deleteAllItemsForPartitionKey("WA");
getFeedRanges()

Exemplo

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" });

const { resources: ranges } = await container.getFeedRanges();
getPartitionKeyDefinition()

Obtém a definição da chave de partição primeiro examinando o cache, caso contrário, lendo a coleção.
getQueryPlan(string | SqlQuerySpec)
initializeEncryption()

Aquece caches relacionados à criptografia para o contêiner.

Exemplo

import { ClientSecretCredential } from "@azure/identity";
import {
  AzureKeyVaultEncryptionKeyResolver,
  CosmosClient,
  EncryptionType,
  EncryptionAlgorithm,
  ClientEncryptionIncludedPath,
  ClientEncryptionPolicy,
} from "@azure/cosmos";

const endpoint = "https://your-account.documents.azure.com";
const key = "<database account masterkey>";
const credentials = new ClientSecretCredential("<tenant-id>", "<client-id>", "<app-secret>");
const keyResolver = new AzureKeyVaultEncryptionKeyResolver(credentials);
const client = new CosmosClient({
  endpoint,
  key,
  clientEncryptionOptions: {
    keyEncryptionKeyResolver: keyResolver,
  },
});
const { database } = await client.databases.createIfNotExists({ id: "<db id>" });

const paths = ["/path1", "/path2", "/path3"].map(
  (path) =>
    ({
      path: path,
      clientEncryptionKeyId: "< cek - id >",
      encryptionType: EncryptionType.DETERMINISTIC,
      encryptionAlgorithm: EncryptionAlgorithm.AEAD_AES_256_CBC_HMAC_SHA256,
    }) as ClientEncryptionIncludedPath,
);
const clientEncryptionPolicy: ClientEncryptionPolicy = {
  includedPaths: paths,
  policyFormatVersion: 2,
};
const containerDefinition = {
  id: "Test Container",
  partitionKey: {
    paths: ["/id"],
  },
  clientEncryptionPolicy: clientEncryptionPolicy,
};
const { container } = await database.containers.createIfNotExists(containerDefinition);

await container.initializeEncryption();
item(string, PartitionKey)

Usado para ler, substituir ou excluir um de Item de específico e existente por id.

Use .items para criar novos itens ou consultar/ler todos os itens.

Exemplo

Substituir um item

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" });

const { body: replacedItem } = await container
  .item("<item id>", "<partition key value>")
  .replace({ id: "<item id>", title: "Updated post", authorID: 5 });
read(RequestOptions)

Leia a definição do recipiente

Exemplo

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 { resource: database } = await client.database("<db id>").container("<container id>").read();
readOffer(RequestOptions)

Recebe oferta no contêiner. Se não existir, retorna um OfferResponse com undefined.

Exemplo

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 { resource: offer } = await client
  .database("<db id>")
  .container("<container id>")
  .readOffer();
readPartitionKeyRanges(FeedOptions)

Obtém os intervalos de chaves de partição para o contêiner.

Exemplo

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" });

const { resources: ranges } = await container.readPartitionKeyRanges().fetchAll();
replace(ContainerDefinition, RequestOptions)

Substitua a definição do contêiner

Exemplo

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 containerDefinition = {
  id: "Test Container",
  partitionKey: {
    paths: ["/key1"],
  },
  throughput: 1000,
};
const { container } = await database.containers.createIfNotExists(containerDefinition);

containerDefinition.throughput = 400;
const { container: replacedContainer } = await container.replace(containerDefinition);
semanticRerank(string, string[], SemanticRerankOptions)

Reordene uma lista de documentos usando a reclassificação semântica através do Cosmos DB Inference Service. Este método utiliza um reclassificador semântico para pontuar e reordenar os documentos fornecidos com base na sua relevância para o contexto dado.

Os pedidos de reclassificação semântica utilizam um pipeline HTTP separado do cliente principal da Cosmos DB e não utilizam as políticas de retentativa padrão do SDK.

Para usar esse recurso, você deve:

  1. Configurar autenticação AAD via aadCredentials in CosmosClientOptions
  2. Forneça o ponto final de inferência via enablePreviewFeatures.semanticRerank.inferenceEndpoint in CosmosClientOptions

Exemplo

Reclassificação semântica dos resultados das consultas

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

const endpoint = "https://your-account.documents.azure.com";
const aadCredentials = new DefaultAzureCredential();
const client = new CosmosClient({
  endpoint,
  aadCredentials,
  enablePreviewFeatures: {
    semanticRerank: {
      inferenceEndpoint: "https://your-account.<region>.dbinference.azure.com",
    },
  },
});

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

const queryResults = ["doc1 JSON", "doc2 JSON", "doc3 JSON"];
const result = await container.semanticRerank(
  "most economical with multiple adjustments",
  queryResults,
  { return_documents: true, top_k: 10, sort: true },
);
// Access the top-ranked document
if (result.rerankScores.length > 0) {
  const topResult = result.rerankScores[0];
  const topScore = topResult.score;
  const topDocument = topResult.document;
  if (topDocument) {
    console.log("Top-ranked document:", topDocument);
  }
  console.log("Top score:", topScore);
}

Detalhes de Propriedade

conflicts

Operações para ler e consultar conflitos para um determinado contêiner.

Para ler ou excluir um conflito específico, use .conflict(id).

Conflicts conflicts

Valor de Propriedade

Conflicts

database 

database: Database

Valor de Propriedade

Database

id 

id: string

Valor de Propriedade

string

items

Operações para criar novos itens e ler/consultar todos os itens

Para ler, substituir ou excluir um item existente, use .item(id).

Exemplo

Criar um novo item

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" });

const { resource: createdItem } = await container.items.create({
  id: "<item id>",
  properties: {},
});

Items items

Valor de Propriedade

Items

scripts

Todas as operações para procedimentos armazenados, gatilhos e funções definidas pelo usuário

Scripts scripts

Valor de Propriedade

Scripts

url

Retorna uma URL de referência para o recurso. Usado para vincular em Permissões.

string url

Valor de Propriedade

string

Detalhes de Método

conflict(string, PartitionKey)

Usado para ler, substituir ou excluir um de conflito de específico e existente por id.

Use .conflicts para criar novos conflitos ou consultar/ler todos os conflitos.

Exemplo

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 = database.container("Test Container");

const { resource: conflict } = await container.conflict("<conflict-id>").read();

function conflict(id: string, partitionKey?: PartitionKey): Conflict

Parâmetros

id

string

O id do conflito .

partitionKey
PartitionKey

Devoluções

Conflict

delete(RequestOptions)

Excluir o contêiner

Exemplo

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

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

await client.database("<db id>").container("<container id>").delete();

function delete(options?: RequestOptions): Promise<ContainerResponse>

Parâmetros

options
RequestOptions

Devoluções

Promise<ContainerResponse>

deleteAllItemsForPartitionKey(PartitionKey, RequestOptions)

Excluir todos os documentos pertencentes ao contêiner para o valor da chave de partição fornecida

Exemplo

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",
  partitionKey: {
    paths: ["/state"],
  },
});

const cities = [
  { id: "1", name: "Olympia", state: "WA", isCapitol: true },
  { id: "2", name: "Redmond", state: "WA", isCapitol: false },
  { id: "3", name: "Olympia", state: "IL", isCapitol: false },
];
for (const city of cities) {
  await container.items.create(city);
}

await container.deleteAllItemsForPartitionKey("WA");

function deleteAllItemsForPartitionKey(partitionKey: PartitionKey, options?: RequestOptions): Promise<ContainerResponse>

Parâmetros

partitionKey
PartitionKey

O valor da chave de partição dos itens a serem excluídos

options
RequestOptions

Devoluções

Promise<ContainerResponse>

getFeedRanges()

Exemplo

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" });

const { resources: ranges } = await container.getFeedRanges();

function getFeedRanges(): Promise<readonly FeedRange[]>

Devoluções

Promise<readonly FeedRange[]>

todas as gamas de alimentação para as quais o changefeed pode ser obtido.

getPartitionKeyDefinition()

Aviso

Esta API foi preterida.

This method has been renamed to readPartitionKeyDefinition.

Obtém a definição da chave de partição primeiro examinando o cache, caso contrário, lendo a coleção.

function getPartitionKeyDefinition(): Promise<ResourceResponse<PartitionKeyDefinition>>

Devoluções

Promise<ResourceResponse<PartitionKeyDefinition>>

getQueryPlan(string | SqlQuerySpec) 

function getQueryPlan(query: string | SqlQuerySpec): Promise<Response<PartitionedQueryExecutionInfo>>

Parâmetros

query

string | SqlQuerySpec

Devoluções

Promise<Response<PartitionedQueryExecutionInfo>>

initializeEncryption()

Aquece caches relacionados à criptografia para o contêiner.

Exemplo

import { ClientSecretCredential } from "@azure/identity";
import {
  AzureKeyVaultEncryptionKeyResolver,
  CosmosClient,
  EncryptionType,
  EncryptionAlgorithm,
  ClientEncryptionIncludedPath,
  ClientEncryptionPolicy,
} from "@azure/cosmos";

const endpoint = "https://your-account.documents.azure.com";
const key = "<database account masterkey>";
const credentials = new ClientSecretCredential("<tenant-id>", "<client-id>", "<app-secret>");
const keyResolver = new AzureKeyVaultEncryptionKeyResolver(credentials);
const client = new CosmosClient({
  endpoint,
  key,
  clientEncryptionOptions: {
    keyEncryptionKeyResolver: keyResolver,
  },
});
const { database } = await client.databases.createIfNotExists({ id: "<db id>" });

const paths = ["/path1", "/path2", "/path3"].map(
  (path) =>
    ({
      path: path,
      clientEncryptionKeyId: "< cek - id >",
      encryptionType: EncryptionType.DETERMINISTIC,
      encryptionAlgorithm: EncryptionAlgorithm.AEAD_AES_256_CBC_HMAC_SHA256,
    }) as ClientEncryptionIncludedPath,
);
const clientEncryptionPolicy: ClientEncryptionPolicy = {
  includedPaths: paths,
  policyFormatVersion: 2,
};
const containerDefinition = {
  id: "Test Container",
  partitionKey: {
    paths: ["/id"],
  },
  clientEncryptionPolicy: clientEncryptionPolicy,
};
const { container } = await database.containers.createIfNotExists(containerDefinition);

await container.initializeEncryption();

function initializeEncryption(): Promise<void>

Devoluções

Promise<void>

item(string, PartitionKey)

Usado para ler, substituir ou excluir um de Item de específico e existente por id.

Use .items para criar novos itens ou consultar/ler todos os itens.

Exemplo

Substituir um item

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" });

const { body: replacedItem } = await container
  .item("<item id>", "<partition key value>")
  .replace({ id: "<item id>", title: "Updated post", authorID: 5 });

function item(id: string, partitionKeyValue?: PartitionKey): Item

Parâmetros

id

string

O id do Item.

partitionKeyValue
PartitionKey

O valor da chave de partição Item

Devoluções

Item

read(RequestOptions)

Leia a definição do recipiente

Exemplo

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 { resource: database } = await client.database("<db id>").container("<container id>").read();

function read(options?: RequestOptions): Promise<ContainerResponse>

Parâmetros

options
RequestOptions

Devoluções

Promise<ContainerResponse>

readOffer(RequestOptions)

Recebe oferta no contêiner. Se não existir, retorna um OfferResponse com undefined.

Exemplo

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 { resource: offer } = await client
  .database("<db id>")
  .container("<container id>")
  .readOffer();

function readOffer(options?: RequestOptions): Promise<OfferResponse>

Parâmetros

options
RequestOptions

Devoluções

Promise<OfferResponse>

readPartitionKeyRanges(FeedOptions)

Obtém os intervalos de chaves de partição para o contêiner.

Exemplo

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" });

const { resources: ranges } = await container.readPartitionKeyRanges().fetchAll();

function readPartitionKeyRanges(feedOptions?: FeedOptions): QueryIterator<PartitionKeyRange>

Parâmetros

feedOptions
FeedOptions

Opções para o pedido.

Devoluções

QueryIterator<PartitionKeyRange>

Um iterador de intervalos de chaves de partição.

replace(ContainerDefinition, RequestOptions)

Substitua a definição do contêiner

Exemplo

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 containerDefinition = {
  id: "Test Container",
  partitionKey: {
    paths: ["/key1"],
  },
  throughput: 1000,
};
const { container } = await database.containers.createIfNotExists(containerDefinition);

containerDefinition.throughput = 400;
const { container: replacedContainer } = await container.replace(containerDefinition);

function replace(body: ContainerDefinition, options?: RequestOptions): Promise<ContainerResponse>

Parâmetros

body
ContainerDefinition
options
RequestOptions

Devoluções

Promise<ContainerResponse>

semanticRerank(string, string[], SemanticRerankOptions)

Nota

Este API está em Beta e é fornecido como pré-visualização para os programadores, podendo ser alterado com base nos comentários que recebermos. Não utilize esta API num ambiente de produção.

Reordene uma lista de documentos usando a reclassificação semântica através do Cosmos DB Inference Service. Este método utiliza um reclassificador semântico para pontuar e reordenar os documentos fornecidos com base na sua relevância para o contexto dado.

Os pedidos de reclassificação semântica utilizam um pipeline HTTP separado do cliente principal da Cosmos DB e não utilizam as políticas de retentativa padrão do SDK.

Para usar esse recurso, você deve:

  1. Configurar autenticação AAD via aadCredentials in CosmosClientOptions
  2. Forneça o ponto final de inferência via enablePreviewFeatures.semanticRerank.inferenceEndpoint in CosmosClientOptions

Exemplo

Reclassificação semântica dos resultados das consultas

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

const endpoint = "https://your-account.documents.azure.com";
const aadCredentials = new DefaultAzureCredential();
const client = new CosmosClient({
  endpoint,
  aadCredentials,
  enablePreviewFeatures: {
    semanticRerank: {
      inferenceEndpoint: "https://your-account.<region>.dbinference.azure.com",
    },
  },
});

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

const queryResults = ["doc1 JSON", "doc2 JSON", "doc3 JSON"];
const result = await container.semanticRerank(
  "most economical with multiple adjustments",
  queryResults,
  { return_documents: true, top_k: 10, sort: true },
);
// Access the top-ranked document
if (result.rerankScores.length > 0) {
  const topResult = result.rerankScores[0];
  const topScore = topResult.score;
  const topDocument = topResult.document;
  if (topDocument) {
    console.log("Top-ranked document:", topDocument);
  }
  console.log("Top score:", topScore);
}

function semanticRerank(rerankContext: string, documents: string[], options?: SemanticRerankOptions): Promise<SemanticRerankResult>

Parâmetros

rerankContext

string

O contexto (por exemplo, uma cadeia de consulta) a usar para reclassificar os documentos.

documents

string[]

Uma lista de documentos (como cadeias JSON) a serem reclassificados.

options
SemanticRerankOptions

Dicionário opcional de definições para o pedido de reclassificação. Opções de serviço conhecidas:

  • return_documents (booleano) — incluir documentos reclassificados na resposta.
  • top_k (número) — número máximo de documentos de primeira classificação para devolver.
  • batch_size (número) — tamanho do lote para processamento de documentos.
  • sort (booleano) — ordenar os resultados por pontuação de relevância por ordem decrescente.
  • document_type ("string" | "json") — tipo de documentos a serem reclassificados.
  • target_paths (string) — caminhos JSON separados por vírgulas (quando document_type é "json").
  • abortSignal (AbortSignal) — sinal para cancelar o pedido. Quaisquer chaves adicionais são encaminhadas as-is para o serviço de inferência.

Devoluções

Promise<SemanticRerankResult>

Os resultados da reclassificação incluíram documentos pontuados, latência e utilização de tokens.