共用方式為


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

適用於: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
);

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

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

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

// Query multiple items from container
using FeedIterator<Product> feed = container.GetItemQueryIterator<Product>(
    queryText: "SELECT * FROM products p 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 試用其中一個端對端教學課程。