Skip to content
datastudyguides

AI-200 · 2.1.1 · Develop AI solutions by using Azure data management services

Cosmos SDK queries

Connect to Azure Cosmos DB for NoSQL by using the SDK and run queries

Use when id and are known; use when you need filtering or multiple items.

Read one item or search

Cosmos DB comparison of a low-cost point read using item id and partition key versus a filtered query that can cross partitions.

Use one CosmosClient and reuse it. When you know both the item id and , read_item is a and is cheaper than expressing the same lookup as SQL.

Query safely

order = container.read_item(item="o-1001", partition_key="c-42")
rows = container.query_items(
    query="SELECT c.id FROM c WHERE c.status = @status",
    parameters=[{"name": "@status", "value": "open"}],
    enable_cross_partition_query=True,
)

A query with no equality filter on the partition key can fan out across physical partitions. Pass changing values as parameters rather than concatenating them into query text.

Microsoft Entra authentication still needs a Cosmos DB data-plane role; a control-plane role alone cannot read items.

Key points

  • Data plane role: Built-in Data Contributor; control plane roles cannot read items
  • : `read_item` with id and , the cheapest fetch
  • : no partition key equality, fans out to every physical partition
  • JOIN: iterates arrays inside one item, never joins items or containers

Click an underlined term for a one-line explanation, or see them all in the glossary .

Exam trap

A query that filters on id and is still a query and costs more than a with `read_item`.

Sources · 4 Microsoft Learn pages Show ▾

Checked on October 4, 2026. Report a problem

Go deeper on Microsoft Learn

Checked against Microsoft Learn on October 4, 2026. Report a problem with this card

How well do you know this?