Container class

Paquet:
@azure/cosmos

Opérations de lecture, de remplacement ou de suppression d’un conteneur spécifique existant par ID.

Consultez conteneurs pour créer de nouveaux conteneurs et lire/interroger tous les conteneurs ; utilisez .containers.

Remarque : toutes ces opérations effectuent des appels sur un budget fixe. Vous devez concevoir votre système afin que ces appels soient mis à l’échelle sous-linéairement avec votre application. Par exemple, n’appelez pas container(id).read() avant chaque appel de item.read() unique, pour vous assurer que le conteneur existe ; effectuez cette opération une fois sur le démarrage de l’application.

Propriétés

conflicts

Opérations de lecture et d’interrogation de conflits pour le conteneur donné.

Pour lire ou supprimer un conflit spécifique, utilisez .conflict(id).
database
id
items

Opérations de création d’éléments et lecture/interrogation de tous les éléments

Pour lire, remplacer ou supprimer un élément existant, utilisez .item(id).

exemple de

Créer un élément

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

Toutes les opérations pour les procédures stockées, les déclencheurs et les fonctions définies par l’utilisateur
url

Retourne une URL de référence à la ressource. Utilisé pour la liaison dans Autorisations.

Méthodes

conflict(string, PartitionKey)

Utilisé pour lire, remplacer ou supprimer un conflit existant existant par ID.

Utilisez .conflicts pour créer de nouveaux conflits, ou interroger/lire tous les conflits.

exemple de 

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)

Supprimer le conteneur

exemple de 

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)

Supprimer tous les documents appartiennent au conteneur pour la valeur de clé de partition fournie

exemple de 

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()

exemple de 

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()

Obtient d’abord la définition de clé de partition en examinant le cache autrement en lisant la collection.
getQueryPlan(string | SqlQuerySpec)
initializeEncryption()

Réchauffe les caches liés au chiffrement pour le conteneur.

exemple de 

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)

Utilisé pour lire, remplacer ou supprimer un élément existant spécifique par ID.

Utilisez .items pour créer des éléments, ou interroger/lire tous les éléments.

exemple de

Remplacer un élément

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)

Lire la définition du conteneur

exemple de 

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)

Obtient l’offre sur le conteneur. S’il n’en existe aucun, retourne un OfferResponse avec undefined.

exemple de 

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)

Obtient les plages de clés de partition pour le conteneur.

exemple de 

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)

Remplacer la définition du conteneur

exemple de 

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)

Reclassez une liste de documents en utilisant le reclassement sémantique via le service d’inférence Cosmos DB. Cette méthode utilise un reclasseur sémantique pour noter et réorganiser les documents fournis en fonction de leur pertinence dans le contexte donné.

Les requêtes de reclassement sémantiques utilisent un pipeline HTTP séparé du client principal de la base de données Cosmos et n’utilisent pas les politiques de réessayage par défaut du SDK.

Pour utiliser cette fonctionnalité, vous devez :

  1. Configurez l’authentification AAD via aadCredentials in CosmosClientOptions
  2. Fournir le point d’extrémité d’inférence via enablePreviewFeatures.semanticRerank.inferenceEndpoint dans CosmosClientOptions

exemple de

Reclassement sémantique des résultats de requêtes

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

Détails de la propriété

conflicts

Opérations de lecture et d’interrogation de conflits pour le conteneur donné.

Pour lire ou supprimer un conflit spécifique, utilisez .conflict(id).

Conflicts conflicts

Valeur de propriété

Conflicts

database 

database: Database

Valeur de propriété

Database

id 

id: string

Valeur de propriété

string

items

Opérations de création d’éléments et lecture/interrogation de tous les éléments

Pour lire, remplacer ou supprimer un élément existant, utilisez .item(id).

exemple de

Créer un élément

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

Valeur de propriété

Items

scripts

Toutes les opérations pour les procédures stockées, les déclencheurs et les fonctions définies par l’utilisateur

Scripts scripts

Valeur de propriété

Scripts

url

Retourne une URL de référence à la ressource. Utilisé pour la liaison dans Autorisations.

string url

Valeur de propriété

string

Détails de la méthode

conflict(string, PartitionKey)

Utilisé pour lire, remplacer ou supprimer un conflit existant existant par ID.

Utilisez .conflicts pour créer de nouveaux conflits, ou interroger/lire tous les conflits.

exemple de 

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

Paramètres

id

string

ID du conflit.

partitionKey
PartitionKey

Retours

Conflict

delete(RequestOptions)

Supprimer le conteneur

exemple de 

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>

Paramètres

options
RequestOptions

Retours

Promise<ContainerResponse>

deleteAllItemsForPartitionKey(PartitionKey, RequestOptions)

Supprimer tous les documents appartiennent au conteneur pour la valeur de clé de partition fournie

exemple de 

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>

Paramètres

partitionKey
PartitionKey

Valeur de clé de partition des éléments à supprimer

options
RequestOptions

Retours

Promise<ContainerResponse>

getFeedRanges()

exemple de 

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[]>

Retours

Promise<readonly FeedRange[]>

toutes les plages de flux pour lesquelles le flux de modification peut être récupéré.

getPartitionKeyDefinition()

Avertissement

Cette API est à présent déconseillée.

This method has been renamed to readPartitionKeyDefinition.

Obtient d’abord la définition de clé de partition en examinant le cache autrement en lisant la collection.

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

Retours

Promise<ResourceResponse<PartitionKeyDefinition>>

getQueryPlan(string | SqlQuerySpec) 

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

Paramètres

query

string | SqlQuerySpec

Retours

Promise<Response<PartitionedQueryExecutionInfo>>

initializeEncryption()

Réchauffe les caches liés au chiffrement pour le conteneur.

exemple de 

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>

Retours

Promise<void>

item(string, PartitionKey)

Utilisé pour lire, remplacer ou supprimer un élément existant spécifique par ID.

Utilisez .items pour créer des éléments, ou interroger/lire tous les éléments.

exemple de

Remplacer un élément

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

Paramètres

id

string

ID de l’élément .

partitionKeyValue
PartitionKey

Valeur de la clé de partition Élément

Retours

Item

read(RequestOptions)

Lire la définition du conteneur

exemple de 

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>

Paramètres

options
RequestOptions

Retours

Promise<ContainerResponse>

readOffer(RequestOptions)

Obtient l’offre sur le conteneur. S’il n’en existe aucun, retourne un OfferResponse avec undefined.

exemple de 

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>

Paramètres

options
RequestOptions

Retours

Promise<OfferResponse>

readPartitionKeyRanges(FeedOptions)

Obtient les plages de clés de partition pour le conteneur.

exemple de 

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>

Paramètres

feedOptions
FeedOptions

Options de la demande.

Retours

QueryIterator<PartitionKeyRange>

Itérateur de plages de clés de partition.

replace(ContainerDefinition, RequestOptions)

Remplacer la définition du conteneur

exemple de 

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>

Paramètres

body
ContainerDefinition
options
RequestOptions

Retours

Promise<ContainerResponse>

semanticRerank(string, string[], SemanticRerankOptions)

Notes

Ce API est en version bêta et est fourni en tant qu’aperçu pour les développeurs et il peut être modifié en fonction des commentaires que nous avons reçus. N’utilisez pas cet API dans un environnement de production.

Reclassez une liste de documents en utilisant le reclassement sémantique via le service d’inférence Cosmos DB. Cette méthode utilise un reclasseur sémantique pour noter et réorganiser les documents fournis en fonction de leur pertinence dans le contexte donné.

Les requêtes de reclassement sémantiques utilisent un pipeline HTTP séparé du client principal de la base de données Cosmos et n’utilisent pas les politiques de réessayage par défaut du SDK.

Pour utiliser cette fonctionnalité, vous devez :

  1. Configurez l’authentification AAD via aadCredentials in CosmosClientOptions
  2. Fournir le point d’extrémité d’inférence via enablePreviewFeatures.semanticRerank.inferenceEndpoint dans CosmosClientOptions

exemple de

Reclassement sémantique des résultats de requêtes

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>

Paramètres

rerankContext

string

Le contexte (par exemple chaîne de requêtes) à utiliser pour reclasser les documents.

documents

string[]

Une liste de documents (sous forme de chaînes JSON) à reclasser.

options
SemanticRerankOptions

Dictionnaire optionnel des réglages pour la demande de reclassement. Options de service connues :

  • return_documents (booléen) — incluez des documents reclassés dans la réponse.
  • top_k (nombre) — nombre maximal de documents les mieux classés à retourner.
  • batch_size (nombre) — taille du lot pour le traitement des documents.
  • sort (booléen) — trier les résultats par score de pertinence par ordre décroissant.
  • document_type ("string" | "json") — type de documents reclassés.
  • target_paths (chaîne) — chemins JSON séparés par virgules (lorsque document_type est "json").
  • abortSignal (SignalAbort) — signal pour annuler la demande. Toute clé supplémentaire est transmise as-is au service d’inférence.

Retours

Promise<SemanticRerankResult>

Les résultats de reclassement incluent les documents notés, la latence et l’utilisation des jetons.