Bagikan melalui

Kiat kinerja kueri untuk SDK Azure Cosmos DB

  • Berlaku untuk: ✅ NoSQL

Azure Cosmos DB adalah database terdistribusi yang cepat dan fleksibel yang menskalakan dengan mulus dengan tingkat latensi dan throughput terjamin. Anda tidak perlu membuat perubahan arsitektur besar atau menulis kode kompleks untuk menskalakan database dengan Azure Cosmos DB. Peningkatan atau penurunan skala semudah menjalankan satu panggilan API. Untuk mempelajari lebih lanjut, lihat sediakan throughput kontainer atau sediakan throughput database.

Mengurangi panggilan paket kueri

Untuk menjalankan kueri, rencana eksekusi kueri perlu dibuat. Permintaan jaringan ke Gateway Azure Cosmos DB menambah latensi operasi kueri. Ada dua cara untuk menghapus permintaan ini dan mengurangi latensi operasi kueri:

Mengoptimalkan kueri partisi tunggal dengan Eksekusi Langsung Optimis

Azure Cosmos DB NoSQL memiliki pengoptimalan yang disebut Optimis Eksekusi Langsung (ODE), yang dapat meningkatkan efisiensi kueri NoSQL tertentu. Secara khusus, kueri yang tidak memerlukan distribusi mencakup kueri yang dapat dijalankan pada satu partisi fisik atau yang memiliki respons yang tidak memerlukan penomoran halaman. Kueri yang tidak memerlukan distribusi dapat dengan yakin melewati beberapa proses, seperti pembuatan rencana kueri sisi klien dan penulisan ulang kueri, yang mengurangi latensi kueri dan biaya Unit Permintaan (RU). Jika Anda menentukan kunci partisi dalam permintaan atau kueri itu sendiri (atau hanya memiliki satu partisi fisik), dan hasil kueri Anda tidak memerlukan penomoran halaman, maka ODE dapat meningkatkan kueri Anda.

Nota

ODE, yang dirancang untuk menawarkan peningkatan performa untuk kueri yang tidak memerlukan distribusi, seharusnya jangan disamakan dengan mode langsung, yang merupakan jalur untuk menghubungkan aplikasi Anda ke replika backend.

ODE sekarang tersedia di .NET SDK versi 3.38.0 dan yang lebih baru. Saat Anda menjalankan kueri dan menentukan kunci partisi dalam permintaan atau kueri itu sendiri, atau database Anda hanya memiliki satu partisi fisik, eksekusi kueri Anda dapat menggunakan manfaat ODE. Untuk mengaktifkan ODE, atur EnableOptimisticDirectExecution ke true di QueryRequestOptions.

Kueri partisi tunggal yang menampilkan fungsi GROUP BY, ORDER BY, DISTINCT, dan agregasi (seperti jumlah, rata-rata, min, dan maks) dapat secara signifikan mendapat manfaat dari penggunaan ODE. Namun, dalam skenario di mana kueri menargetkan beberapa partisi atau masih memerlukan penomoran halaman, latensi respons kueri dan biaya RU mungkin lebih tinggi daripada tanpa menggunakan ODE. Oleh karena itu, saat menggunakan ODE, Anda harus:

  • Tentukan kunci partisi dalam panggilan atau kueri itu sendiri.
  • Pastikan ukuran data Anda belum tumbuh dan menyebabkan partisi terpecah.
  • Pastikan bahwa hasil kueri Anda tidak memerlukan penomoran halaman untuk mendapatkan manfaat penuh dari ODE.

Berikut adalah beberapa contoh kueri partisi tunggal sederhana yang dapat memperoleh manfaat dari ODE:

- SELECT * FROM r
- SELECT * FROM r WHERE r.pk == "value"
- SELECT * FROM r WHERE r.id > 5
- SELECT r.id FROM r JOIN id IN r.id
- SELECT TOP 5 r.id FROM r ORDER BY r.id
- SELECT * FROM r WHERE r.id > 5 OFFSET 5 LIMIT 3

Mungkin ada kasus di mana kueri partisi tunggal mungkin masih memerlukan distribusi jika jumlah item data meningkat dari waktu ke waktu dan database Azure Cosmos DB Anda membagi partisi. Contoh kueri di mana hal ini dapat terjadi meliputi:

- SELECT Count(r.id) AS count_a FROM r
- SELECT DISTINCT r.id FROM r
- SELECT Max(r.a) as min_a FROM r
- SELECT Avg(r.a) as min_a FROM r
- SELECT Sum(r.a) as sum_a FROM r WHERE r.a > 0

Beberapa kueri kompleks selalu memerlukan distribusi, bahkan jika menargetkan satu partisi. Contoh kueri tersebut meliputi:

- SELECT Sum(id) as sum_id FROM r JOIN id IN r.id
- SELECT DISTINCT r.id FROM r GROUP BY r.id
- SELECT DISTINCT r.id, Sum(r.id) as sum_a FROM r GROUP BY r.id
- SELECT Count(1) FROM (SELECT DISTINCT r.id FROM root r)
- SELECT Avg(1) AS avg FROM root r

Penting untuk dicatat bahwa ODE mungkin tidak selalu mengambil rencana kueri dan, akibatnya, tidak dapat melarang atau menonaktifkan kueri yang tidak didukung. Misalnya, setelah pemisahan partisi, kueri tersebut tidak lagi memenuhi syarat untuk ODE dan, oleh karena itu, tidak akan berjalan karena evaluasi rencana kueri sisi klien memblokirnya. Untuk memastikan kompatibilitas/kelangsungan layanan, sangat penting untuk memastikan bahwa hanya kueri yang sepenuhnya didukung dalam skenario tanpa ODE (yaitu, mereka mengeksekusi dan menghasilkan hasil yang benar dalam kasus multi-partisi umum) yang digunakan dengan ODE.

Nota

Menggunakan ODE berpotensi menyebabkan jenis token kelanjutan baru dihasilkan. Token seperti itu tidak dikenali oleh SDK yang lebih lama sesuai desainnya, dan ini dapat mengakibatkan Malformed Continuation Token Exception. Jika Anda memiliki skenario di mana token yang dihasilkan dari SDK yang lebih baru digunakan oleh SDK yang lebih lama, kami merekomendasikan pendekatan dua langkah untuk meningkatkan:

  • Tingkatkan ke SDK baru dan nonaktifkan ODE, keduanya bersama-sama sebagai bagian dari satu penyebaran. Tunggu hingga semua simpul ditingkatkan.
  • Untuk menonaktifkan ODE, atur EnableOptimisticDirectExecution ke false di QueryRequestOptions.
  • Aktifkan ODE sebagai bagian dari penyebaran kedua untuk semua simpul.

Menggunakan pembuatan rencana kueri lokal

SQL SDK mencakup ServiceInterop.dll asli untuk mengurai dan mengoptimalkan kueri secara lokal. ServiceInterop.dll hanya didukung pada platform Windows x64 . Jenis aplikasi berikut menggunakan pemrosesan hos 32-bit secara default. Untuk mengubah pemrosesan hos menjadi pemrosesan 64-bit, ikuti langkah-langkah ini, berdasarkan jenis aplikasi Anda:

  • Untuk aplikasi yang dapat dieksekusi, Anda dapat mengubah pemrosesan hos dengan mengatur target platform ke x64 di jendela Properti Proyek, pada tab Bangun.

  • Untuk proyek pengujian berbasis VSTest, Anda dapat mengubah pemrosesan hos dengan memilih Uji>Pengaturan Pengujian>Arsitektur Prosesor Default sebagai X64 pada menu Uji Visual Studio.

  • Untuk aplikasi web ASP.NET yang disebarkan secara lokal, Anda dapat mengubah pemrosesan hos dengan memilih Gunakan versi 64-bit IIS Express untuk situs web dan proyek di bawah Alat>Opsi>Proyek dan Solusi>Proyek Web.

  • Untuk aplikasi ASP.NET web yang disebarkan pada Azure, Anda dapat mengubah pemrosesan hos dengan memilih platform 64-bit dalam Pengaturan aplikasi di portal Azure.

Nota

Secara default, proyek Visual Studio baru diatur ke CPU mana pun. Kami menyarankan agar Anda mengatur proyek ke x64 sehingga tidak beralih ke x86. Proyek yang diatur ke CPU mana pun dapat dengan mudah beralih ke x86 jika dependensi hanya x86 ditambahkan.

ServiceInterop.dll harus berada di folder tempat DLL SDK dijalankan. Ini sebaiknya menjadi perhatian hanya jika Anda menyalin DLL secara manual atau memiliki sistem bangun/penyebaran kustom.

Menggunakan kueri partisi tunggal

Untuk kueri yang menargetkan kunci partisi dengan mengatur properti PartitionKey di QueryRequestOptions dan yang tidak mengandung agregasi (termasuk Distinct, DCount, atau Group By). Dalam contoh ini, bidang /state kunci partisi difilter pada nilai Washington.

using (FeedIterator<MyItem> feedIterator = container.GetItemQueryIterator<MyItem>(
    "SELECT * FROM c WHERE c.city = 'Seattle' AND c.state = 'Washington'"
{
    // ...
}

Secara opsional, Anda dapat memberikan kunci partisi sebagai bagian dari objek opsi permintaan.

using (FeedIterator<MyItem> feedIterator = container.GetItemQueryIterator<MyItem>(
    "SELECT * FROM c WHERE c.city = 'Seattle'",
    requestOptions: new QueryRequestOptions() { PartitionKey = new PartitionKey("Washington")}))
{
    // ...
}

Penting

Pada klien yang menjalankan OS non-Windows, seperti Linux dan macOS, kunci partisi harus selalu ditentukan dalam objek opsi permintaan.

Nota

Kueri lintas partisi memerlukan SDK untuk mengunjungi semua partisi yang ada untuk memeriksa hasilnya. Semakin banyak partisi fisik yang dimiliki kontainer, kontainer berpotensi menjadi semakin lambat.

Hindari membuat ulang iterator yang tidak perlu

Saat semua hasil kueri digunakan oleh komponen saat ini, Anda tidak perlu membuat ulang iterator dengan kelanjutan untuk setiap halaman. Sebaiknya hapus kueri sepenuhnya kecuali penomoran halaman dikendalikan oleh komponen panggilan lain:

using (FeedIterator<MyItem> feedIterator = container.GetItemQueryIterator<MyItem>(
    "SELECT * FROM c WHERE c.city = 'Seattle'",
    requestOptions: new QueryRequestOptions() { PartitionKey = new PartitionKey("Washington")}))
{
    while (feedIterator.HasMoreResults) 
    {
        foreach(MyItem document in await feedIterator.ReadNextAsync())
        {
            // Iterate through documents
        }
    }
}

Mengatur derajat paralelisme

Untuk kueri, sesuaikan properti MaxConcurrency di QueryRequestOptions untuk mengidentifikasi konfigurasi terbaik untuk aplikasi Anda, terutama jika Anda melakukan kueri lintas partisi (tanpa filter pada nilai kunci partisi). MaxConcurrency mengontrol jumlah maksimum tugas paralel, yaitu, maksimum partisi yang akan dikunjungi secara paralel. Mengatur nilai ke -1 memungkinkan SDK memutuskan konkurensi optimal.

using (FeedIterator<MyItem> feedIterator = container.GetItemQueryIterator<MyItem>(
    "SELECT * FROM c WHERE c.city = 'Seattle'",
    requestOptions: new QueryRequestOptions() { 
        PartitionKey = new PartitionKey("Washington"),
        MaxConcurrency = -1 }))
{
    // ...
}

Mari kita asumsikan bahwa:

  • D = Jumlah maksimum default tugas paralel (= jumlah total prosesor di komputer klien)
  • P = Jumlah maksimum tugas paralel yang ditentukan pengguna
  • N = Jumlah partisi yang perlu dikunjungi untuk menjawab kueri

Berikut ini adalah implikasi tentang bagaimana kueri paralel bereaksi untuk nilai P yang berbeda.

  • (P == 0) => Mode serial
  • (P == 1) => Maksimum satu tugas
  • (P > 1) => Min (P, N) tugas paralel
  • (P < 1) => Min (N, D) tugas paralel

Menyetel ukuran halaman

Saat Anda mengeluarkan kueri SQL, hasilnya ditampilkan secara tersegmentasi jika tataan hasil terlalu besar.

Nota

Properti MaxItemCount sebaiknya tidak digunakan untuk paginasi saja. Penggunaan utamanya adalah untuk meningkatkan kinerja kueri dengan mengurangi jumlah maksimum item yang dikembalikan dalam satu halaman.

Anda juga dapat mengatur ukuran halaman dengan menggunakan SDK Azure Cosmos DB yang tersedia. Properti MaxItemCount dalam QueryRequestOptions memungkinkan Anda mengatur jumlah maksimum item yang akan dikembalikan dalam operasi pencacahan. Ketika MaxItemCount diatur ke -1, SDK secara otomatis menemukan nilai optimal, tergantung pada ukuran dokumen. Contohnya:

using (FeedIterator<MyItem> feedIterator = container.GetItemQueryIterator<MyItem>(
    "SELECT * FROM c WHERE c.city = 'Seattle'",
    requestOptions: new QueryRequestOptions() { 
        PartitionKey = new PartitionKey("Washington"),
        MaxItemCount = 1000}))
{
    // ...
}

Saat kueri dijalankan, data yang dihasilkan dikirim dalam paket TCP. Jika Anda menentukan nilai yang terlalu rendah untuk MaxItemCount, jumlah perjalanan yang diperlukan untuk mengirim data dalam paket TCP menjadi tinggi, yang memengaruhi kinerja. Jadi, jika Anda tidak yakin nilai apa yang akan diatur untuk MaxItemCount properti , yang terbaik adalah mengaturnya ke -1 dan membiarkan SDK memilih nilai default.

Menyetel ukuran buffer

Kueri paralel dirancang untuk melakukan prefetch hasil saat batch hasil saat ini sedang diproses oleh klien. Prefetching ini membantu meningkatkan latensi keseluruhan kueri. Properti MaxBufferedItemCount membatasi QueryRequestOptions jumlah hasil yang sudah diprefetch. Atur MaxBufferedItemCount ke jumlah hasil yang diharapkan yang dikembalikan (atau angka yang lebih tinggi) untuk memungkinkan kueri menerima manfaat maksimum dari prefetching. Jika Anda mengatur nilai ini ke -1, sistem secara otomatis menentukan jumlah item yang akan di-buffer.

using (FeedIterator<MyItem> feedIterator = container.GetItemQueryIterator<MyItem>(
    "SELECT * FROM c WHERE c.city = 'Seattle'",
    requestOptions: new QueryRequestOptions() { 
        PartitionKey = new PartitionKey("Washington"),
        MaxBufferedItemCount = -1}))
{
    // ...
}

Prefetching bekerja dengan cara yang sama terlepas dari tingkat paralelisme, dan ada satu buffer untuk data dari semua partisi.

Langkah selanjutnya

Untuk mempelajari selengkapnya tentang performa menggunakan SDK .NET:

Mengurangi panggilan paket kueri

Untuk menjalankan kueri, rencana eksekusi kueri perlu dibuat. Permintaan jaringan ke Gateway Azure Cosmos DB menambah latensi operasi kueri.

Menggunakan penyimpanan sementara rencana kueri

Rencana kueri, untuk kueri yang dibatasi pada satu partisi, di-cache di klien. Hal ini menghilangkan perlunya melakukan panggilan ke gateway untuk mengambil rencana pencarian setelah panggilan pertama. Kunci untuk rencana kueri yang disimpan adalah string kueri SQL. Anda perlu memastikan kueri diparmetriskan. Jika tidak, pencarian cache paket kueri sering kali merupakan kesalahan cache karena string kueri tidak mungkin identik di seluruh panggilan. Penembolokan rencana kueri diaktifkan secara default untuk Java SDK versi 4.20.0 ke atas dan untuk Spring Data Azure Cosmos DB SDK versi 3.13.0 ke atas.

Menggunakan kueri partisi tunggal berparameter

Untuk kueri parametrik yang didasarkan pada kunci partisi dengan setPartitionKey dalam CosmosQueryRequestOptions dan tidak mengandung agregasi (termasuk Distinct, DCount, atau Group By), rencana kueri dapat dihindari:

CosmosQueryRequestOptions options = new CosmosQueryRequestOptions();
options.setPartitionKey(new PartitionKey("Washington"));

ArrayList<SqlParameter> paramList = new ArrayList<SqlParameter>();
paramList.add(new SqlParameter("@city", "Seattle"));
SqlQuerySpec querySpec = new SqlQuerySpec(
        "SELECT * FROM c WHERE c.city = @city",
        paramList);

//  Sync API
CosmosPagedIterable<MyItem> filteredItems = 
    container.queryItems(querySpec, options, MyItem.class);

//  Async API
CosmosPagedFlux<MyItem> filteredItems = 
    asyncContainer.queryItems(querySpec, options, MyItem.class);

Nota

Kueri lintas partisi memerlukan SDK untuk mengunjungi semua partisi yang ada untuk memeriksa hasilnya. Semakin banyak partisi fisik yang dimiliki kontainer, kontainer dapat menjadi semakin lambat.

Mengatur derajat paralelisme

Kueri paralel bekerja dengan mengkueri beberapa partisi secara paralel. Tetapi, data dari masing-masing kontainer yang dipartisi diambil secara serial sehubungan dengan kueri. Jadi, gunakan setMaxDegreeOfParallelism pada CosmosQueryRequestOptions untuk mengatur nilai ke jumlah partisi yang Anda miliki. Jika Anda tidak mengetahui jumlah partisi, Anda dapat menggunakan setMaxDegreeOfParallelism untuk menetapkan angka tinggi, dan sistem memilih minimum (jumlah partisi, input yang diberikan pengguna) sebagai derajat paralelisme maksimum. Mengatur nilai ke -1 memungkinkan SDK memutuskan konkurensi optimal.

Penting untuk dicatat bahwa kueri paralel menghasilkan manfaat terbaik jika data didistribusikan secara merata di semua partisi sehubungan dengan kueri. Jika kontainer yang dipartisi dipartisi dengan cara sehingga semua atau sebagian besar hasil kueri terpusat pada beberapa partisi (satu partisi dalam kasus terburuk), maka performa kueri akan menurun.

CosmosQueryRequestOptions options = new CosmosQueryRequestOptions();
options.setPartitionKey(new PartitionKey("Washington"));
options.setMaxDegreeOfParallelism(-1);

// Define the query

//  Sync API
CosmosPagedIterable<MyItem> filteredItems = 
    container.queryItems(querySpec, options, MyItem.class);

//  Async API
CosmosPagedFlux<MyItem> filteredItems = 
    asyncContainer.queryItems(querySpec, options, MyItem.class);

Mari kita asumsikan bahwa:

  • D = Jumlah maksimum default tugas paralel (= jumlah total prosesor di komputer klien)
  • P = Jumlah maksimum tugas paralel yang ditentukan pengguna
  • N = Jumlah partisi yang perlu dikunjungi untuk menjawab kueri

Berikut ini adalah implikasi tentang bagaimana kueri paralel bereaksi untuk nilai P yang berbeda:

  • (P == 0) => Mode serial
  • (P == 1) => Maksimum satu tugas
  • (P > 1) => Min (P, N) tugas paralel
  • (P == -1) => Min (N, D) tugas yang dieksekusi secara paralel

Menyetel ukuran halaman

Saat Anda mengeluarkan kueri SQL, hasilnya ditampilkan secara tersegmentasi jika tataan hasil terlalu besar. Secara default, hasil dikembalikan dalam gugus 100 item atau 4 MB, batas mana saja yang tercapai lebih dulu. Meningkatkan ukuran halaman mengurangi jumlah perjalanan pulang pergi yang diperlukan dan meningkatkan performa untuk kueri yang mengembalikan lebih dari 100 item. Jika Anda tidak yakin nilai apa yang akan ditetapkan, 1000 biasanya merupakan pilihan yang baik. Konsumsi memori meningkat saat ukuran halaman meningkat, jadi jika beban kerja Anda sensitif memori, pertimbangkan nilai yang lebih rendah.

Anda dapat menggunakan parameter pageSize di iterableByPage() untuk API sinkronisasi dan byPage() untuk API asinkron, guna menentukan ukuran halaman:

//  Sync API
Iterable<FeedResponse<MyItem>> filteredItemsAsPages =
    container.queryItems(querySpec, options, MyItem.class).iterableByPage(continuationToken,pageSize);

for (FeedResponse<MyItem> page : filteredItemsAsPages) {
    for (MyItem item : page.getResults()) {
        //...
    }
}

//  Async API
Flux<FeedResponse<MyItem>> filteredItemsAsPages =
    asyncContainer.queryItems(querySpec, options, MyItem.class).byPage(continuationToken,pageSize);

filteredItemsAsPages.map(page -> {
    for (MyItem item : page.getResults()) {
        //...
    }
}).subscribe();

Menyetel ukuran buffer

Kueri paralel dirancang untuk melakukan prefetch hasil saat batch hasil saat ini sedang diproses oleh klien. Prefetching membantu dalam pengurangan latensi kueri secara keseluruhan. setMaxBufferedItemCount dalam CosmosQueryRequestOptions membatasi jumlah hasil yang di-prefetch. Untuk memaksimalkan prefetching, atur maxBufferedItemCount ke angka yang lebih tinggi dari pageSize (CATATAN: Ini juga dapat mengakibatkan konsumsi memori yang tinggi). Untuk meminimalkan prefetching, atur maxBufferedItemCount sama dengan pageSize. Jika Anda mengatur nilai ini ke 0, sistem secara otomatis menentukan jumlah item yang akan di-buffer.

CosmosQueryRequestOptions options = new CosmosQueryRequestOptions();
options.setPartitionKey(new PartitionKey("Washington"));
options.setMaxBufferedItemCount(-1);

// Define the query

//  Sync API
CosmosPagedIterable<MyItem> filteredItems = 
    container.queryItems(querySpec, options, MyItem.class);

//  Async API
CosmosPagedFlux<MyItem> filteredItems = 
    asyncContainer.queryItems(querySpec, options, MyItem.class);

Prefetching bekerja dengan cara yang sama terlepas dari tingkat paralelisme, dan ada satu buffer untuk data dari semua partisi.

Langkah selanjutnya

Untuk mempelajari selengkapnya tentang performa menggunakan SDK Java:

Mengurangi panggilan paket kueri

Untuk menjalankan kueri, rencana eksekusi kueri perlu dibuat. Permintaan jaringan ke Gateway Azure Cosmos DB menambah latensi operasi kueri. Ada cara untuk menghapus permintaan ini dan mengurangi latensi operasi kueri partisi tunggal. Untuk kueri partisi tunggal, tentukan nilai kunci partisi untuk item dan teruskan sebagai argumen partition_key :

items = container.query_items(
        query="SELECT * FROM r where r.city = 'Seattle'",
        partition_key="Washington"
    )

Menyetel ukuran halaman

Saat Anda mengeluarkan kueri SQL, hasilnya ditampilkan secara tersegmentasi jika tataan hasil terlalu besar. max_item_count memungkinkan Anda mengatur jumlah maksimum item yang akan dikembalikan dalam operasi enumerasi.

items = container.query_items(
        query="SELECT * FROM r where r.city = 'Seattle'",
        partition_key="Washington",
        max_item_count=1000
    )

Langkah selanjutnya

Untuk mempelajari selengkapnya tentang menggunakan Python SDK untuk API untuk NoSQL:

Mengurangi panggilan paket kueri

Untuk menjalankan kueri, rencana eksekusi kueri perlu dibuat. Permintaan jaringan ke Gateway Azure Cosmos DB menambah latensi operasi kueri. Ada cara untuk menghapus permintaan ini dan mengurangi latensi operasi kueri partisi tunggal. Untuk kueri partisi tunggal, cakupan kueri ke satu partisi dapat dicapai dengan dua cara.

Menggunakan ekspresi kueri berparameter dan menentukan kunci partisi dalam pernyataan kueri. Kueri secara terprogram terdiri dari SELECT * FROM todo t WHERE t.partitionKey = 'Bikes, Touring Bikes':

// find all items with same categoryId (partitionKey)
const querySpec = {
    query: "select * from products p where p.categoryId=@categoryId",
    parameters: [
        {
            name: "@categoryId",
            value: "Bikes, Touring Bikes"
        }
    ]
};

// Get items 
const { resources } = await container.items.query(querySpec).fetchAll();

for (const item of resources) {
    console.log(`${item.id}: ${item.name}, ${item.sku}`);
}

Atau tentukan partitionKey masuk FeedOptions dan berikan sebagai argumen:

const querySpec = {
    query: "select * from products p"
};

const { resources } = await container.items.query(querySpec, { partitionKey: "Bikes, Touring Bikes" }).fetchAll();

for (const item of resources) {
    console.log(`${item.id}: ${item.name}, ${item.sku}`);
}

Menyetel ukuran halaman

Saat Anda mengeluarkan kueri SQL, hasilnya ditampilkan secara tersegmentasi jika tataan hasil terlalu besar. maxItemCount memungkinkan Anda mengatur jumlah maksimum item yang akan dikembalikan dalam operasi enumerasi.

const querySpec = {
    query: "select * from products p where p.categoryId=@categoryId",
    parameters: [
        {
            name: "@categoryId",
            value: items[2].categoryId
        }
    ]
};

const { resources } = await container.items.query(querySpec, { maxItemCount: 1000 }).fetchAll();

for (const item of resources) {
    console.log(`${item.id}: ${item.name}, ${item.sku}`);
}

Kontrol kueri yang disempurnakan

Untuk Cosmos DB JS SDK versi 4.3.0 dan yang lebih baru, enableQueryControl flag diperkenalkan, yang memberikan kontrol lebih besar atas eksekusi kueri, menawarkan lebih banyak fleksibilitas dalam mengelola konsumsi Unit Permintaan (RU).

Secara bawaan, enableQueryControl diatur ke false dan SDK menjamin bahwa setiap fetchNext pemanggilan akan mengembalikan maxItemCount jumlah hasil, asalkan banyak hasil tersebut ada di back end. Tetapi untuk memenuhi jumlah hasil yang dijamin, SDK mungkin mengkueri partisi back end beberapa kali dalam satu fetchNext iterasi. Hal ini terkadang dapat menyebabkan latensi dan pengurasan RU yang tidak dapat diprediksi tanpa kontrol pengguna, terutama ketika hasil tersebar di seluruh partisi.

Ketika enableQueryControl diatur ke true, setiap panggilan fetchNext sekarang melakukan kueri hingga maxDegreeOfParallelism partisi fisik. Jika tidak ada hasil yang ditemukan atau hasil belum siap untuk dilayani, SDK mengembalikan halaman kosong alih-alih terus mencari semua partisi di latar belakang. Dengan cara ini, pengguna mendapatkan kontrol yang lebih baik atas eksekusi kueri mereka dengan latensi yang dapat diprediksi dan data konsumsi RU terperinci.

const options = {
  enableQueryControl: true, // Flag to enable new query pipeline.
  maxItemCount: 100,
  maxDegreeOfParallelism: 6
};

const querySpec = {
    query: "select * from products p where p.categoryId=@categoryId",
    parameters: [
        {
            name: "@categoryId",
            value: items[2].categoryId
        }
    ]
};
const queryIterator = container.items.query(querySpec, options);
// use this iterator to fetch results.

Langkah selanjutnya

Untuk mempelajari selengkapnya tentang menggunakan SDK Node.js untuk API untuk NoSQL:

  • Last updated on