使用 .NET 在 Azure Cosmos DB for NoSQL 中查詢項目

發行項
06/01/2023

適用於：NoSQL

Azure Cosmos DB 中的項目代表儲存在容器內的實體。在 NoSQL API 中，項目是由具有唯一識別碼的 JSON 格式資料所組成。當您使用 NoSQL API 發出查詢時，結果會以 JSON 文件的 JSON 陣列形式傳回。

使用 SQL 查詢項目

Azure Cosmos DB for NoSQL 支援使用結構化查詢語言 (SQL)，對容器中的項目執行查詢。像 SELECT * FROM products 這樣的簡單SQL查詢會從容器傳回所有項目和屬性。查詢可能更複雜，並包含特定的欄位投影、篩選和其他常見 SQL 子句：

SELECT 
    p.name, 
    p.description AS copy
FROM 
    products p 
WHERE 
    p.price > 500

若要深入瞭解 Azure Cosmos DB for NoSQL 的 SQL 語法，請參閱開始使用 SQL 查詢。

查詢項目

注意

本文中的範例假設您已經定義 C# 類型來代表名為 Product 的資料：

// C# record type for items in the container
public record Product(
    string id,
    string category,
    string name,
    int quantity,
    bool sale
);

若要查詢容器中的項目，請呼叫下列其中一種方法：

GetItemQueryIterator<>
GetItemLinqQueryable<>

以非同步方式使用 SQL 查詢來查詢項目

此範例會使用簡單的字串建置 SQL 查詢、擷取摘要反覆運算器，然後使用巢狀迴圈逐一查看結果。外部 while 迴圈會逐一查看結果頁面，而內部 foreach 迴圈則會逐一查看頁面內的結果。

// Query multiple items from container
using FeedIterator<Product> feed = container.GetItemQueryIterator<Product>(
    queryText: "SELECT * FROM products WHERE p.quantity > 10"
);

// Iterate query result pages
while (feed.HasMoreResults)
{
    FeedResponse<Product> response = await feed.ReadNextAsync();

    // Iterate query results
    foreach (Product item in response)
    {
        Console.WriteLine($"Found item:\t{item.name}");
    }
}

Container.GetItemQueryIterator<> 方法會傳回用來逐一查看多頁結果的 FeedIterator<>。屬性 HasMoreResults 會指出是否剩下更多結果頁。方法 ReadNextAsync 會取得下一頁的結果，做為可列舉的結果，然後用於迴圈來逐一查看結果。

或者，使用 QueryDefinition 建置具有參數化輸入的 SQL 查詢：

// Build query definition
var parameterizedQuery = new QueryDefinition(
    query: "SELECT * FROM products p WHERE p.quantity > @quantity"
)
    .WithParameter("@quantity", 10);

// Query multiple items from container
using FeedIterator<Product> filteredFeed = container.GetItemQueryIterator<Product>(
    queryDefinition: parameterizedQuery
);

// Iterate query result pages
while (filteredFeed.HasMoreResults)
{
    FeedResponse<Product> response = await filteredFeed.ReadNextAsync();

    // Iterate query results
    foreach (Product item in response)
    {
        Console.WriteLine($"Found item:\t{item.name}");
    }
}

提示

參數化輸入值有助於防止許多常見的 SQL 查詢插入式攻擊。

以非同步方式使用 LINQ 查詢項目

在此範例中，IQueryable<> 物件是用來建構語言整合式查詢 (LINQ)。然後，系統會使用摘要反覆運算器逐一查看結果。

// Get LINQ IQueryable object
IOrderedQueryable<Product> queryable = container.GetItemLinqQueryable<Product>();

// Construct LINQ query
var matches = queryable
    .Where(p => p.quantity > 10);

// Convert to feed iterator
using FeedIterator<Product> linqFeed = matches.ToFeedIterator();

// Iterate query result pages
while (linqFeed.HasMoreResults)
{
    FeedResponse<Product> response = await linqFeed.ReadNextAsync();

    // Iterate query results
    foreach (Product item in response)
    {
        Console.WriteLine($"Matched item:\t{item.name}");
    }
}

Container.GetItemLinqQueryable<> 方法會建構 IQueryable 來建置 LINQ 查詢。然後使用 ToFeedIterator<> 方法將 LINQ 查詢運算式轉換成 FeedIterator<>。

提示

雖然您可以逐一查看 IQueryable<>，但這項作業是同步的。使用 ToFeedIterator<> 方法以非同步方式收集結果。

下一步

既然您已查詢多個項目，請使用 NoSQL API 試用其中一個端對端教學課程。

建置可查詢資料並將資料新增至 Azure Cosmos DB for NoSQL 的應用程式

共用方式為