Mengkueri tabel dan entitas
Mengkueri tabel dan entitas dalam layanan Tabel memerlukan konstruksi URI permintaan yang cermat. Bagian berikut ini menjelaskan opsi kueri dan menunjukkan beberapa skenario umum.
Sintaks Kueri Dasar
Untuk mengembalikan semua tabel di akun penyimpanan tertentu, lakukan GET
operasi pada sumber daya Tabel, seperti yang dijelaskan dalam operasi Tabel Kueri . URI dasar untuk mengatasi sumber daya Tabel adalah sebagai berikut:
https://myaccount.table.core.windows.net/Tables
Untuk mengembalikan satu tabel bernama, tentukan tabel tersebut sebagai berikut:
https://myaccount.table.core.windows.net/Tables('MyTable')
Untuk mengembalikan semua entitas dalam tabel, tentukan nama tabel pada URI, tanpa sumber daya Tabel:
https://myaccount.table.core.windows.net/MyTable()
Hasil kueri diurutkan menurut PartitionKey
, lalu menurut RowKey
. Pengurutan menghasilkan dengan cara lain saat ini tidak didukung.
Anda bisa menentukan opsi tambahan untuk membatasi kumpulan tabel atau entitas yang dikembalikan, seperti yang dijelaskan di bagian Opsi Kueri yang Didukung berikut ini.
Catatan
Jumlah entitas yang dikembalikan untuk satu permintaan mungkin dibatasi, jika kueri melebihi jumlah maksimum entitas, melebihi interval batas waktu, atau melewati batas partisi. Untuk informasi selengkapnya, lihat Batas Waktu Kueri dan Penomoran Halaman.
Opsi Kueri yang Didukung
Layanan Tabel mendukung opsi kueri berikut, yang sesuai dengan Spesifikasi Protokol OData. Anda dapat menggunakan opsi ini untuk membatasi kumpulan tabel, entitas, atau properti entitas yang dikembalikan oleh kueri.
Opsi kueri sistem | Deskripsi |
---|---|
$filter |
Mengembalikan hanya tabel atau entitas yang memenuhi filter yang ditentukan. Perhatikan bahwa tidak lebih dari 15 perbandingan diskrit diizinkan dalam $filter string. |
$top |
Hanya mengembalikan tabel atau entitas teratas n dari set. |
$select |
Mengembalikan properti entitas yang diinginkan dari set. Opsi kueri ini hanya didukung untuk permintaan yang menggunakan versi 2011-08-18 atau yang lebih baru. Untuk informasi selengkapnya, lihat Menulis Kueri LINQ Terhadap Layanan Tabel. |
Catatan
Permintaan yang mengembalikan lebih dari maksimum default atau jumlah hasil maksimum yang ditentukan mengembalikan token kelanjutan untuk melakukan pagination. Saat membuat permintaan berikutnya yang menyertakan token kelanjutan, pastikan untuk meneruskan URI asli atas permintaan. Misalnya, jika Anda telah menentukan $filter
opsi kueri , , $select
atau $top
sebagai bagian dari permintaan asli, Anda akan ingin menyertakan opsi tersebut pada permintaan berikutnya. Jika tidak, permintaan Anda berikutnya dapat mengembalikan hasil yang tidak terduga. Lihat Batas Waktu Kueri dan Penomoran Halaman untuk informasi tambahan.
Perhatikan bahwa $top
opsi kueri dalam kasus di mana hasil dipaginasi menentukan jumlah hasil maksimum per halaman, bukan jumlah maksimum hasil di seluruh set respons.
Opsi kueri tambahan yang ditentukan oleh OData tidak didukung oleh layanan Tabel.
Operator Perbandingan yang Didukung
$filter
Dalam klausa, Anda dapat menggunakan operator perbandingan untuk menentukan kriteria untuk memfilter hasil kueri.
Untuk semua jenis properti, operator perbandingan berikut didukung:
Operator | Ekspresi URI |
---|---|
Equal |
eq |
GreaterThan |
gt |
GreaterThanOrEqual |
ge |
LessThan |
lt |
LessThanOrEqual |
le |
NotEqual |
ne |
Selain itu, operator berikut didukung untuk properti Boolean:
Operator | Ekspresi URI |
---|---|
And |
and |
Not |
not |
Or |
or |
Untuk informasi selengkapnya tentang sintaks filter, lihat Spesifikasi Protokol OData.
Pengodean String Kueri
Karakter berikut harus dikodekan jika akan digunakan dalam string kueri:
- Garis miring (/)
- Tanda tanya (?)
- Titik dua (:)
- Simbol 'At' (@)
- Ampersand (&)
- Tanda sama dengan (=)
- Tanda plus (+)
- Koma (,)
- Tanda dolar ($)
Kutipan tunggal (')
Tanda kutip tunggal dalam string kueri harus direpresentasikan sebagai dua tanda kutip tunggal berturut-turut (''
). Misalnya, "jam" adalah:
o''clock
Contoh Ekspresi Kueri
Sampel berikut menunjukkan cara membuat URI permintaan untuk beberapa kueri entitas umum menggunakan sintaks REST. Kueri yang sama dapat ditulis menggunakan sintaks LINQ. Untuk informasi selengkapnya, lihat Menulis Kueri LINQ Terhadap Layanan Tabel.
Perhatikan bahwa opsi $top
dan $filter
juga dapat digunakan untuk memfilter nama tabel, menggunakan sintaks yang ditunjukkan untuk pemfilteran pada properti jenis String
.
Mengembalikan Entitas n Teratas
Untuk mengembalikan entitas teratas n
untuk kueri apa pun, tentukan $top
opsi kueri. Contoh berikut mengembalikan 10 entitas teratas dari tabel bernama Pelanggan:
https://myaccount.table.core.windows.net/Customers()?$top=10
Pemfilteran pada Properti PartitionKey dan RowKey
PartitionKey
Karena properti dan RowKey
membentuk kunci utama entitas, Anda dapat menggunakan sintaks khusus untuk mengidentifikasi entitas, sebagai berikut:
https://myaccount.table.core.windows.net/Customers(PartitionKey='MyPartition',RowKey='MyRowKey1')
Atau, Anda dapat menentukan properti ini sebagai bagian dari opsi $filter
, seperti yang diperlihatkan di bagian berikut.
Perhatikan bahwa nama properti kunci dan nilai konstanta peka huruf besar/kecil.
PartitionKey
Baik properti dan RowKey
berjenis String
.
Membuat String Filter
Saat membuat string filter, ingatlah aturan ini:
Gunakan operator logis yang ditentukan oleh Spesifikasi Protokol OData untuk membandingkan properti dengan nilai. Perhatikan bahwa Anda tidak dapat membandingkan properti dengan nilai dinamis; satu sisi ekspresi harus berupa konstanta.
Nama properti, operator, dan nilai konstanta harus dipisahkan dengan spasi yang dikodekan URL. Spasi dikodekan URL sebagai
%20
.Semua bagian string filter peka huruf besar/kecil.
Nilai konstanta harus memiliki jenis data yang sama dengan properti agar filter mengembalikan hasil yang valid. Untuk informasi selengkapnya tentang jenis properti yang didukung, lihat lihat Memahami Model Data Layanan Tabel.
Catatan
Pastikan untuk memeriksa apakah properti telah ditik secara eksplisit sebelum mengasumsikan properti tersebut adalah jenis selain string. Jika properti telah ditik secara eksplisit, jenis ditunjukkan dalam respons saat entitas dikembalikan. Jika properti belum ditik secara eksplisit, properti akan berjenis String
, dan jenisnya tidak akan ditunjukkan dalam respons ketika entitas dikembalikan.
Pemfilteran pada Properti String
Saat memfilter properti string, sertakan konstanta string dalam tanda kutip tunggal.
Contoh filter berikut pada PartitionKey
properti dan RowKey
; properti non-kunci tambahan juga dapat ditambahkan ke string kueri.
https://myaccount.table.core.windows.net/Customers()?$filter=PartitionKey%20eq%20'MyPartitionKey'%20and%20RowKey%20eq%20'MyRowKey1'
Contoh berikut memfilter properti FirstName
dan LastName
:
https://myaccount.table.core.windows.net/Customers()?$filter=LastName%20eq%20'Smith'%20and%20FirstName%20eq%20'John'
Perhatikan bahwa layanan Tabel tidak mendukung kueri kartubebas. Namun, Anda dapat melakukan pencocokan awalan dengan menggunakan operator perbandingan pada awalan yang diinginkan. Contoh berikut mengembalikan entitas dengan properti yang LastName
dimulai dengan huruf 'A':
https://myaccount.table.core.windows.net/Customers()?$filter=LastName%20ge%20'A'%20and%20LastName%20lt%20'B'
Pemfilteran pada Properti Numerik
Untuk memfilter bilangan bulat atau angka floating-point, tentukan nilai konstanta pada URI tanpa tanda kutip.
Contoh ini mengembalikan semua entitas dengan properti yang Age
nilainya lebih besar dari 30:
https://myaccount.table.core.windows.net/Customers()?$filter=Age%20gt%2030
Contoh ini mengembalikan semua entitas dengan AmountDue
properti yang nilainya kurang dari atau sama dengan 100,25:
https://myaccount.table.core.windows.net/Customers()?$filter=AmountDue%20le%20100.25%20
Pemfilteran pada Properti Boolean
Untuk memfilter nilai Boolean, tentukan true
atau false
tanpa tanda kutip.
Contoh berikut mengembalikan semua entitas di mana IsActive
properti diatur ke true
:
https://myaccount.table.core.windows.net/Customers()?$filter=IsActive%20eq%20true
Pemfilteran pada Properti DateTime
Untuk memfilter DateTime
nilai, tentukan datetime
kata kunci pada URI, diikuti dengan konstanta tanggal/waktu dalam tanda kutip tunggal. Konstanta tanggal/waktu harus dalam format UTC gabungan, seperti yang dijelaskan dalam Memformat nilai DateTime.
Contoh berikut mengembalikan entitas di mana CustomerSince
properti sama dengan 10 Juli 2008:
https://myaccount.table.core.windows.net/Customers()?$filter=CustomerSince%20eq%20datetime'2008-07-10T00:00:00Z'
Pemfilteran pada Properti GUID
Untuk memfilter nilai GUID, tentukan guid
kata kunci pada URI, diikuti dengan konstanta guid dalam tanda kutip tunggal.
Contoh berikut mengembalikan entitas di mana GuidValue
properti sama dengan :
https://myaccount.table.core.windows.net/Customers()?$filter=GuidValue%20eq%20guid'a455c695-df98-5678-aaaa-81d3367e5a34'
Lihat juga
Konsep Layanan Tabel
Memahami Model Data Layanan Tabel
Mengatasi Sumber Daya Layanan Tabel
Batas Waktu Kueri dan Penomoran Halaman
Menulis Kueri LINQ Terhadap Layanan Tabel