Container class

Пакет:
@azure/cosmos

Операции чтения, замены или удаления определенного существующего контейнера по идентификатору.

Ознакомьтесь с контейнерами для создания новых контейнеров и чтения и запроса всех контейнеров; используйте .containers.

Примечание. Все эти операции выполняют вызовы к фиксированному бюджету. Вы должны разработать систему таким образом, чтобы эти вызовы масштабировать подстроки с приложением. Например, не вызывайте container(id).read() перед каждым вызовом item.read(), чтобы убедиться, что контейнер существует; Выполните это один раз при запуске приложения.

Свойства

conflicts

Операции чтения и запроса конфликтов для данного контейнера.

Для чтения или удаления определенного конфликта используйте .conflict(id).
database
id
items

Операции для создания новых элементов и чтения и запроса всех элементов

Для чтения, замены или удаления существующего элемента используйте .item(id).

пример

Создание нового элемента

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

Все операции для хранимых процедур, триггеров и пользовательских функций
url

Возвращает URL-адрес ссылки для ресурса. Используется для связывания в разрешениях.

Методы

conflict(string, PartitionKey)

Используется для чтения, замены или удаления определенного существующего конфликта по идентификатору.

Используйте .conflicts для создания новых конфликтов или запроса и чтения всех конфликтов.

пример 

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)

Удаление контейнера

пример 

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)

Удаление всех документов относится к контейнеру для указанного значения ключа секции.

пример 

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

пример 

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

Возвращает определение ключа секции сначала путем просмотра кэша в противном случае путем чтения коллекции.
getQueryPlan(string | SqlQuerySpec)
initializeEncryption()

Прогревает кэши, связанные с шифрованием, для контейнера.

пример 

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)

Используется для чтения, замены или удаления определенного существующего элемента по идентификатору.

Используйте .items для создания новых элементов или запроса и чтения всех элементов.

пример

Замена элемента

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)

Чтение определения контейнера

пример 

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)

Возвращает предложение в контейнере. Если нет, возвращает предложениеResponse с неопределенным значением.

пример 

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)

Получает диапазоны ключей секций для контейнера.

пример 

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)

Замена определения контейнера

пример 

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)

Переранжуйте список документов с помощью семантического реранжирования, используя сервис Cosmos DB Inference. Этот метод использует семантический реранжировщик для оценки и перепорядка предоставленных документов в зависимости от их релевантности к данному контексту.

Запросы на семантическое переранжирование используют отдельный HTTP-конвейер от основного клиента Cosmos DB и не применяют стандартные политики повторных попыток SDK.

Для использования этой функции нужно сделать следующее:

  1. Настройте аутентификацию AAD с aadCredentials помощью в CosmosClientOptions
  2. Предоставьте конечную точку вывода с помощью enablePreviewFeatures.semanticRerank.inferenceEndpoint в CosmosClientOptions

пример

Семантическое переранжирование результатов запросов

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

Сведения о свойстве

conflicts

Операции чтения и запроса конфликтов для данного контейнера.

Для чтения или удаления определенного конфликта используйте .conflict(id).

Conflicts conflicts

Значение свойства

Conflicts

database 

database: Database

Значение свойства

Database

id 

id: string

Значение свойства

string

items

Операции для создания новых элементов и чтения и запроса всех элементов

Для чтения, замены или удаления существующего элемента используйте .item(id).

пример

Создание нового элемента

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

Значение свойства

Items

scripts

Все операции для хранимых процедур, триггеров и пользовательских функций

Scripts scripts

Значение свойства

Scripts

url

Возвращает URL-адрес ссылки для ресурса. Используется для связывания в разрешениях.

string url

Значение свойства

string

Сведения о методе

conflict(string, PartitionKey)

Используется для чтения, замены или удаления определенного существующего конфликта по идентификатору.

Используйте .conflicts для создания новых конфликтов или запроса и чтения всех конфликтов.

пример 

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

Параметры

id

string

Идентификатор конфликта.

partitionKey
PartitionKey

Возвращаемое значение

Conflict

delete(RequestOptions)

Удаление контейнера

пример 

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>

Параметры

options
RequestOptions

Возвращаемое значение

Promise<ContainerResponse>

deleteAllItemsForPartitionKey(PartitionKey, RequestOptions)

Удаление всех документов относится к контейнеру для указанного значения ключа секции.

пример 

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>

Параметры

partitionKey
PartitionKey

Значение ключа секции для удаленных элементов

options
RequestOptions

Возвращаемое значение

Promise<ContainerResponse>

getFeedRanges()

пример 

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

Возвращаемое значение

Promise<readonly FeedRange[]>

все диапазоны веб-каналов, для которых можно получить канал изменений.

getPartitionKeyDefinition()

Предупреждение

Теперь этот API является нерекомендуемым.

This method has been renamed to readPartitionKeyDefinition.

Возвращает определение ключа секции сначала путем просмотра кэша в противном случае путем чтения коллекции.

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

Возвращаемое значение

Promise<ResourceResponse<PartitionKeyDefinition>>

getQueryPlan(string | SqlQuerySpec) 

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

Параметры

query

string | SqlQuerySpec

Возвращаемое значение

Promise<Response<PartitionedQueryExecutionInfo>>

initializeEncryption()

Прогревает кэши, связанные с шифрованием, для контейнера.

пример 

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>

Возвращаемое значение

Promise<void>

item(string, PartitionKey)

Используется для чтения, замены или удаления определенного существующего элемента по идентификатору.

Используйте .items для создания новых элементов или запроса и чтения всех элементов.

пример

Замена элемента

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

Параметры

id

string

Идентификатор элемента.

partitionKeyValue
PartitionKey

Значение ключа секции элемента

Возвращаемое значение

Item

read(RequestOptions)

Чтение определения контейнера

пример 

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>

Параметры

options
RequestOptions

Возвращаемое значение

Promise<ContainerResponse>

readOffer(RequestOptions)

Возвращает предложение в контейнере. Если нет, возвращает предложениеResponse с неопределенным значением.

пример 

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>

Параметры

options
RequestOptions

Возвращаемое значение

Promise<OfferResponse>

readPartitionKeyRanges(FeedOptions)

Получает диапазоны ключей секций для контейнера.

пример 

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>

Параметры

feedOptions
FeedOptions

Варианты запроса.

Возвращаемое значение

QueryIterator<PartitionKeyRange>

Итератор диапазонов ключей секций.

replace(ContainerDefinition, RequestOptions)

Замена определения контейнера

пример 

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>

Параметры

body
ContainerDefinition
options
RequestOptions

Возвращаемое значение

Promise<ContainerResponse>

semanticRerank(string, string[], SemanticRerankOptions)

Примечание

API пребывает в бета-версии и предоставляется в качестве предварительной версии для разработчиков. На основе полученных отзывов мы можем внести изменения. Не используйте этот API в рабочей среде.

Переранжуйте список документов с помощью семантического реранжирования, используя сервис Cosmos DB Inference. Этот метод использует семантический реранжировщик для оценки и перепорядка предоставленных документов в зависимости от их релевантности к данному контексту.

Запросы на семантическое переранжирование используют отдельный HTTP-конвейер от основного клиента Cosmos DB и не применяют стандартные политики повторных попыток SDK.

Для использования этой функции нужно сделать следующее:

  1. Настройте аутентификацию AAD с aadCredentials помощью в CosmosClientOptions
  2. Предоставьте конечную точку вывода с помощью enablePreviewFeatures.semanticRerank.inferenceEndpoint в CosmosClientOptions

пример

Семантическое переранжирование результатов запросов

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>

Параметры

rerankContext

string

Контекст (например, строка запроса) для переоценки документов.

documents

string[]

Список документов (в виде JSON-строк), которые нужно переранжировать.

options
SemanticRerankOptions

Необязательный словарь настроек для запроса на изменение ранга. Известные варианты обслуживания:

  • return_documents (булевый) — включить переоценённые документы в ответ.
  • top_k (число) — максимальное количество лучших документов для возврата.
  • batch_size (число) — размер партии для обработки документов.
  • sort (булевый) — сортировать результаты по показателю релевантности в убывающем порядке.
  • document_type ("string" | "json") — тип документов, переранжируемых.
  • target_paths (строка) — пути JSON, разделённые по запятым (когда document_type — "json").
  • abortSignal (Сигнал отмены) — сигнал отменить запрос. Любые дополнительные ключи пересылаются as-is службу вывода.

Возвращаемое значение

Promise<SemanticRerankResult>

Результаты переоценок включают оценочные документы, задержку и использование токенов.