使用 .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 試用其中一個端對端教學課程。