Mengkueri item di Azure Cosmos DB untuk NoSQL menggunakan .NET

  • Artikel

BERLAKU UNTUK: NoSQL

Item di Azure Cosmos DB mewakili entitas yang disimpan dalam kontainer. Dalam API untuk NoSQL, item terdiri dari data berformat JSON dengan pengidentifikasi unik. Saat Anda mengeluarkan kueri menggunakan API untuk NoSQL, hasil dikembalikan sebagai array JSON dokumen JSON.

Mengkueri item menggunakan SQL

Azure Cosmos DB for NoSQL mendukung penggunaan Bahasa Permintaan Terstruktur (SQL) untuk melakukan kueri pada item dalam kontainer. Kueri SQL sederhana seperti SELECT * FROM products akan mengembalikan semua item dan properti dari kontainer. Kueri bisa lebih kompleks dan menyertakan proyeksi bidang tertentu, filter, dan klausa SQL umum lainnya:

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

Untuk mempelajari selengkapnya tentang sintaks SQL untuk Azure Cosmos DB untuk NoSQL, lihat Mulai menggunakan kueri SQL.

Membuat kueri item

Catatan

Contoh dalam artikel ini mengasumsikan bahwa Anda telah menentukan jenis C# untuk mewakili data Anda bernama Produk:

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

Untuk mengkueri item dalam kontainer, panggil salah satu metode berikut:

Mengkueri item menggunakan kueri SQL secara asinkron

Contoh ini membangun kueri SQL menggunakan string sederhana, mengambil iterator umpan, lalu menggunakan perulangan berlapis untuk mengulangi hasil. Perulangan sementara luar akan berulang melalui halaman hasil, sementara perulangan foreach dalam mengulangi hasil dalam satu halaman.

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

Metode Container.GetItemQueryIterator<> mengembalikan FeedIterator<> yang digunakan untuk melakukan iterasi melalui hasil multi-halaman. Properti HasMoreResults menunjukkan apakah ada lebih banyak halaman hasil yang tersisa. Metode ReadNextAsync ini mendapatkan halaman hasil berikutnya sebagai enumerasi yang kemudian digunakan dalam perulangan untuk melakukan iterasi atas hasil.

Atau, gunakan QueryDefinition untuk membuat kueri SQL dengan input berparameter:

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

Tip

Nilai input berparameter dapat membantu mencegah banyak serangan injeksi kueri SQL umum.

Mengkueri item menggunakan LINQ secara asinkron

Dalam contoh ini, IQueryable<> objek digunakan untuk membuat Kueri Terintegrasi Bahasa (LINQ). Hasilnya kemudian diulang menggunakan iterator umpan.

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

Metode Container.GetItemLinqQueryable<> membangun IQueryable untuk membangun kueri LINQ. Kemudian metode ToFeedIterator<> digunakan untuk mengonversi ekspresi kueri LINQ menjadi FeedIterator<>.

Tip

Meskipun Anda dapat melakukan iterasi melalui IQueryable<>, operasi ini sinkron. Gunakan metode ToFeedIterator<> untuk mengumpulkan hasil secara asinkron.

Langkah berikutnya

Sekarang setelah Anda mengkueri beberapa item, coba salah satu tutorial end-to-end kami dengan API untuk NoSQL.

Membuat aplikasi yang mengkueri dan menambahkan data ke Azure Cosmos DB for NoSQL