Koleksi
Azure Cosmos DB adalah database multi-model terdistribusi secara global yang mendukung model data dokumen, grafik, dan nilai kunci. Konten di bagian ini adalah untuk membuat, mengkueri, dan mengelola sumber daya pengumpulan menggunakan SQL API melalui REST.
REST API mendukung operasi CRUD dasar pada sumber daya di bawah akun database. Koleksi adalah kontainer dokumen JSON dan logika aplikasi JavaScript terkait, yaitu prosedur tersimpan, pemicu, dan fungsi yang ditentukan pengguna. Topik ini menguraikan operasi REST yang digunakan untuk mengelola koleksi dokumen.
Catatan
Artikel referensi API ini menunjukkan cara membuat sumber daya menggunakan API sarana data Azure Cosmos DB. Dengan API sarana data, Anda dapat mengonfigurasi opsi dasar seperti kebijakan pengindeksan, kunci partisi seperti yang Anda dapat dengan Cosmos DB SDK. Jika Anda memerlukan dukungan fitur lengkap untuk semua sumber daya Azure Cosmos DB, sebaiknya gunakan Penyedia Sumber Daya Cosmos DB.
Koleksi dipetakan ke kontainer di Azure Cosmos DB. Oleh karena itu, ini adalah entitas yang dapat ditagih, di mana biaya ditentukan oleh throughput yang disediakan yang dinyatakan dalam unit permintaan per detik. Koleksi dapat mencakup satu atau beberapa partisi/server dan ditingkatkan dan diturunkan skalanya dalam hal throughput. Koleksi secara otomatis dipartisi ke dalam satu atau beberapa server fisik oleh Azure Cosmos DB.
Karena koleksi adalah sumber daya sistem, koleksi memiliki skema tetap. Jalur URI koleksi diwakili oleh kolase dalam model sumber daya.
Contoh berikut mengilustrasikan definisi JSON dari koleksi:
{
"id": "testcoll",
"indexingPolicy": {
"indexingMode": "consistent",
"automatic": true,
"includedPaths": [
{
"path": "/*",
"indexes": [
{
"kind": "Range",
"dataType": "String",
"precision": -1
},
{
"kind": "Range",
"dataType": "Number",
"precision": -1
}
]
}
],
"excludedPaths": []
},
"partitionKey": {
"paths": [
"/AccountNumber"
],
"kind": "Hash"
},
"_rid": "PD5DALigDgw=",
"_ts": 1459200611,
"_self": "dbs/PD5DAA==/colls/PD5DALigDgw=/",
"_etag": "\"00005900-0000-0000-0000-56f9a2630000\"",
"_docs": "docs/",
"_sprocs": "sprocs/",
"_triggers": "triggers/",
"_udfs": "udfs/",
"_conflicts": "conflicts/"
}
| Properti | Deskripsi |
|---|---|
| id | Ini adalah nama unik yang mengidentifikasi koleksi baru. |
| indexingPolicy | Ini adalah pengaturan kebijakan pengindeksan untuk pengumpulan. |
| partitionKey | Ini adalah pengaturan konfigurasi partisi untuk pengumpulan. |
| _rid | Ini adalah properti yang dihasilkan sistem. ID sumber daya (_rid) adalah pengidentifikasi unik yang juga hierarkis per tumpukan sumber daya pada model sumber daya. Ini digunakan secara internal untuk penempatan dan navigasi sumber daya izin. |
| _Ts | Ini adalah properti yang dihasilkan sistem. Ini menentukan tanda waktu terakhir yang diperbarui dari sumber daya. Nilainya adalah tanda waktu. |
| _self | Ini adalah properti yang dihasilkan sistem. Ini adalah URI unik yang dapat diatasi untuk sumber daya. |
| _etag | Ini adalah properti yang dihasilkan sistem yang mewakili etag sumber daya yang diperlukan untuk kontrol konkurensi optimis. |
| _Doc | Ini adalah properti yang dihasilkan sistem yang menentukan jalur sumber daya dokumen yang dapat diatasi. |
| _sprocs | Ini adalah properti yang dihasilkan sistem yang menentukan jalur yang dapat diatasi dari sumber daya prosedur tersimpan (sprocs). |
| _Memicu | Ini adalah properti yang dihasilkan sistem yang menentukan jalur sumber daya pemicu yang dapat diatasi. |
| _udfs | Ini adalah properti yang dihasilkan sistem yang menentukan jalur yang dapat diatasi dari sumber daya fungsi yang ditentukan pengguna (udfs). |
| _Konflik | Ini adalah properti yang dihasilkan sistem yang menentukan jalur sumber daya konflik yang dapat diatasi. Selama operasi pada sumber daya dalam koleksi, jika konflik terjadi, pengguna dapat memeriksa sumber daya yang bertentangan dengan melakukan GET pada jalur URI yang bertentangan. |
Properti di bawah Kebijakan Pengindeksan
| Properti | Deskripsi |
|---|---|
| Otomatis | Menunjukkan apakah pengindeksan otomatis aktif atau nonaktif. Nilai defaultnya adalah True, sehingga semua dokumen diindeks. Mengatur nilai ke False akan memungkinkan konfigurasi manual jalur pengindeksan. |
| indexingMode | Secara default, mode pengindeksan Konsisten. Ini berarti bahwa pengindeksan terjadi secara sinkron selama penyisipan, penggantian, atau penghapusan dokumen. Agar pengindeksan terjadi secara asinkron, atur mode pengindeksan menjadi malas. |
| includedPaths | Array yang berisi jalur dokumen yang akan diindeks. Secara default, dua jalur disertakan: jalur / , yang menentukan bahwa semua jalur dokumen diindeks, dan jalur _ts, yang mengindeks untuk perbandingan rentang tanda waktu. |
| excludedPaths | Array yang berisi jalur dokumen yang akan dikecualikan dari pengindeksan. |
Properti di bawah Jalur yang Disertakan
| Properti | Deskripsi |
|---|---|
| jalur | Jalur tempat perilaku pengindeksan berlaku. Jalur indeks dimulai dengan akar (/) dan biasanya diakhir dengan ? operator kartubebas, menunjukkan bahwa ada beberapa nilai yang mungkin untuk awalan. Misalnya, untuk melayani SELECT * FROM Family F WHERE F.familyName = "Andersen", Anda harus menyertakan jalur indeks untuk /familyName/? dalam kebijakan indeks koleksi. Jalur indeks juga dapat menggunakan operator kartubebas * untuk menentukan perilaku jalur secara rekursif di bawah awalan. Misalnya, /payload/* dapat digunakan untuk menyertakan semuanya di bawah properti payload dari pengindeksan. |
| dataType | Ini adalah jenis data tempat perilaku pengindeksan diterapkan. Dapat berupa String, Number, Point, Polygon, atau LineString. Boolean dan null secara otomatis diindeks |
| jenis | Jenis indeks. Indeks hash berguna untuk perbandingan kesetaraan sementara indeks Rentang berguna untuk kesetaraan, perbandingan rentang, dan pengurutan. Indeks spasial berguna untuk kueri spasial. |
| Presisi | Presisi indeks. Dapat diatur ke -1 untuk presisi maksimum atau antara 1-8 untuk Angka, dan 1-100 untuk String. Tidak berlaku untuk jenis data Point, Polygon, dan LineString . |
Properti di bawah Jalur yang Dikecualikan
| Properti | Deskripsi |
|---|---|
| jalur | Jalur yang dikecualikan dari pengindeksan. Jalur indeks dimulai dengan root (/) dan biasanya diakhir dengan operator kartubebas * . Misalnya, /payload/* dapat digunakan untuk mengecualikan semuanya di bawah properti payload dari pengindeksan. |
Properti di bawah Kunci Partisi
| Properti | Deskripsi |
|---|---|
| jalur | Array jalur yang menggunakan data mana dalam koleksi yang dapat dipartisi. Jalur tidak boleh berisi kartubebas atau garis miring berikutnya. Misalnya, properti JSON "AccountNumber" ditentukan sebagai "/AccountNumber". Array hanya boleh berisi satu nilai. |
| jenis | Algoritma yang digunakan untuk pemartisian. Hanya Hash yang didukung. |
Kebijakan pengindeksan
Saat dokumen ditambahkan ke koleksi, Cosmos DB secara default secara default mengindeks dokumen, sehingga memungkinkan dokumen dikueri. Ini adalah pada tingkat pengumpulan yang Anda konfigurasikan kebijakan pengindeksan. Karena kebijakan pengindeksan diatur pada tingkat pengumpulan, setiap koleksi dalam database dapat memiliki kebijakan pengindeksan yang berbeda.
Kebijakan pengindeksan untuk koleksi dapat menentukan opsi berikut:
Otomatis: Anda dapat memilih apakah Anda ingin koleksi mengindeks semua dokumen secara otomatis atau tidak. Secara default, semua dokumen diindeks secara otomatis, tetapi Anda dapat memilih untuk menonaktifkannya. Saat pengindeksan dinonaktifkan, dokumen hanya dapat diakses melalui tautan mandiri atau dengan kueri menggunakan ID.
Mode Pengindeksan: Anda dapat memilih antara pembaruan indeks sinkron (Konsisten), asinkron (Malas), dan tanpa pengindeksan (Tidak Ada). Secara default, indeks diperbarui secara sinkron pada setiap tindakan penyisipan, penggantian, atau penghapusan yang diambil pada dokumen dalam koleksi. Pembaruan ini memungkinkan kueri untuk menghormati tingkat konsistensi yang sama dengan pembacaan dokumen tanpa penundaan agar indeks mengejar ketinggalan.
Jenis dan presisi indeks: Jenis atau skema yang digunakan untuk entri indeks berdampak langsung pada penyimpanan dan performa indeks. Untuk skema yang menggunakan presisi yang lebih tinggi, kueri biasanya lebih cepat. Namun, ada juga overhead penyimpanan yang lebih tinggi untuk indeks. Memilih presisi yang lebih rendah berarti bahwa lebih banyak dokumen mungkin harus diproses selama eksekusi kueri, tetapi overhead penyimpanan akan lebih rendah.
Jalur indeks: Dalam dokumen, Anda dapat memilih jalur mana yang harus disertakan atau dikecualikan dari pengindeksan, yang dapat menawarkan peningkatan performa tulis dan penyimpanan indeks yang lebih rendah untuk skenario ketika pola kueri diketahui sebelumnya.
Tabel berikut ini memperlihatkan beberapa jalur pengindeksan sampel dan bagaimana mereka digunakan dalam kueri.
| Properti | Deskripsi |
|---|---|
| /* | Jalur default untuk koleksi. Rekursif dan berlaku untuk seluruh pohon dokumen. |
| /Prop/? | Jalur indeks diperlukan untuk melayani kueri seperti berikut ini (dengan jenis Hash atau Rentang masing-masing): SELECT * FROM collection c WHERE c.prop = "value" SELECT * FROM collection c WHERE c.prop > 5 SELECT * FROM collection c ORDER BY c.prop |
| /Prop/* | Jalur indeks untuk semua jalur di bawah label yang ditentukan. Bekerja dengan kueri berikut: SELECT * FROM collection c WHERE c.prop = "value" SELECT * FROM collection c WHERE c.prop.subprop > 5 SELECT * FROM collection c WHERE c.prop.subprop.nextprop = "value" SELECT * FROM collection c ORDER BY c.prop |
| /props/[]/? | Jalur indeks yang diperlukan untuk melayani iterasi dan kueri JOIN terhadap array skalar seperti ["a", "b", "c"]: SELECT tag FROM tag IN collection.props WHERE tag = "value" SELECT tag FROM collection c JOIN tag IN c.props WHERE tag > 5 |
| /props/[]/subprop/? | Jalur indeks diperlukan untuk melayani iterasi dan kueri JOIN terhadap array objek seperti [{subprop: "a"}, {subprop: "b"}]: SELECT tag FROM tag IN collection.props WHERE tag.subprop = "value" SELECT tag FROM collection c JOIN tag IN c.props WHERE tag.subprop = "value" |
| /prop/subprop/? | Jalur indeks diperlukan untuk melayani kueri (dengan jenis Hash atau Rentang masing-masing): SELECT * FROM collection c WHERE c.prop.subprop = "value" SELECT * FROM collection c WHERE c.prop.subprop > 5 SELECT * FROM collection c ORDER BY c.prop.subprop |
Untuk informasi selengkapnya tentang kebijakan pengindeksan Cosmos DB, lihat Kebijakan pengindeksan Cosmos DB. Untuk tujuan dokumentasi REST API, semua contoh menggunakan pengindeksan otomatis.
Tingkat Penawaran dan Performa
Saat koleksi dibuat, sumber daya Penawaran juga dibuat yang mereferensikan koleksi yang dibuat. Sumber daya Penawaran berisi informasi konfigurasi tentang throughput pengumpulan di unit permintaan per detik dan unit permintaan per menit.
Tingkat performa koleksi dapat diubah menggunakan Ganti Penawaran.
Tugas
Anda bisa melakukan hal berikut ini dengan koleksi dokumen: