查詢數據表和實體

在表格服務中查詢資料表和實體時,需要謹慎架構要求 URI。 以下各節描述查詢選項,並示範一些常見案例。

基本查詢語法

若要傳回指定記憶體帳戶中的所有數據表,請在數據表資源上執行 GET 作業,如 查詢數據表 作業中所述。 用來將資料表資源定址的基底 URI 如下:

https://myaccount.table.core.windows.net/Tables  

若要傳回單一具名資料表,請依下列方式指定該資料表:

https://myaccount.table.core.windows.net/Tables('MyTable')  

若要傳回資料表中的所有實體,請在 URI 上指定資料表名稱,但不包含資料表資源:

https://myaccount.table.core.windows.net/MyTable()  

查詢結果會依 PartitionKey 排序,然後依 RowKey 排序。 目前不支援以任何其他方式排列結果。

您可以指定其他選項以限制傳回的資料表或實體集,如下一節 [支援的查詢選項] 所述。

注意

如果查詢超出實體數目上限、超出逾時間隔,或跨越資料分割界限,則會限制針對單一要求傳回的實體數目。 如需詳細資訊,請參閱 查詢逾時和分頁

支援的查詢選項

數據表服務支援下列查詢選項,其符合 OData 通訊協定規格。 您可以使用這些選項以限制查詢傳回的資料表、實體或實體屬性集。

系統查詢選項 Description
$filter 只會傳回符合指定篩選的資料表或實體。

請注意,$filter 字串中最多可允許 15 個離散比較。
$top 只會傳回集合中的前 n 個資料表或實體。
$select 從集合傳回所需的實體屬性。 此查詢選項只支援使用 2011-08-18 版或更新版本的要求。 如需詳細資訊,請參閱 針對數據表服務撰寫 LINQ 查詢

注意

傳回超過預設最大值或指定結果數目上限的要求,會傳回執行分頁的接續令牌。 提出包含接續令牌的後續要求時,請務必在要求上傳遞原始 URI。 例如,如果您已將、 $select$top 查詢選項指定為原始要求的一$filter部分,您會想要在後續要求中包含該選項。 否則,後續的要求可能會傳回非預期的結果。 如需詳細資訊 ,請參閱查詢逾時和分頁

請注意, $top 當結果編頁時,查詢選項會指定每個頁面的結果數目上限,而不是整個回應集中的結果數目上限。

表格服務不支援 OData 定義的其他查詢選項。

支援的比較運算子

$filter 子句中,您可以使用比較運算子指定準則,藉以篩選查詢結果。

針對所有屬性類型,可支援的比較運算子如下:

運算子 URI 運算式
Equal eq
GreaterThan gt
GreaterThanOrEqual ge
LessThan lt
LessThanOrEqual le
NotEqual ne

此外,還可為布林屬性支援下列運算子:

運算子 URI 運算式
And and
Not not
Or or

如需篩選語法的詳細資訊,請參閱 OData 通訊協議規格

查詢字串編碼

如果要在查詢字串中使用下列字元,必須將這些字元編碼:

  • 斜線 (/)
  • 問號 (?)
  • 冒號 (:)
  • 'At' 符號 (@)
  • 連字號 (&)
  • 等號 (=)
  • 加號 (+)
  • 逗號 (,)
  • 貨幣符號 ($)

單引號 (')

查詢字串中的單引號必須以兩個連續單引號表示, ('') 。 例如,“o'clock” 會是:

o''clock

查詢運算式範例

下列範例示範如何使用 REST 語法,為部分的一般實體查詢建構要求 URI。 可以使用 LINQ 語法撰寫相同的查詢。 如需詳細資訊,請參閱 針對數據表服務撰寫 LINQ 查詢

請注意,使用示範語法篩選 String 類型的屬性時,$top$filter 選項也都可以用來篩選資料表名稱。

傳回前 n 個實體

若要傳回任何查詢的前 n 個實體,請指定 $top 查詢選項。 下列範例會從名為 Customers 的資料表傳回前 10 個實體:

https://myaccount.table.core.windows.net/Customers()?$top=10  

篩選 PartitionKey 和 RowKey 屬性

由於 PartitionKeyRowKey 屬性會構成實體的主索引鍵,因此您可以使用特殊語法識別實體,如下所示:

https://myaccount.table.core.windows.net/Customers(PartitionKey='MyPartition',RowKey='MyRowKey1')  

或者,您也可以在指定 $filter 選項時一併指定這些屬性,如下一節中所示。

請注意,索引鍵屬性名稱和常數值有區分大小寫。 PartitionKeyRowKey 屬性都是 String 類型。

建構篩選字串

建構篩選字串時,請牢記下列規則:

  • 使用 OData 通訊協定規格 所定義的邏輯運算元,將屬性與值進行比較。 請注意,無法比較屬性與動態值。運算式的一端必須是常數。

  • 屬性名稱、運算子及常數值必須以 URL 編碼的空格分隔。 空格經 URL 編碼後會變成 %20

  • 篩選字串的所有部分都區分大小寫。

  • 常數和屬性必須是相同的資料類型,篩選才能傳回有效的結果。 如需支援的屬性類型的詳細資訊,請參閱 了解表格服務資料模型

注意

在假設屬性為非字串類型之前,務必檢查是否已明確輸入屬性。 如果已明確輸入屬性,在傳回實體時,回應中會指出類型。 如果尚未明確輸入屬性,其類型將會是 String,而且在傳回實體時,回應中不會指出類型。

篩選字串屬性

篩選字串屬性時,請以單引號括住字串常數。

下列範例會篩選 PartitionKeyRowKey 屬性,其他非索引鍵屬性也可以加入至查詢字串。

https://myaccount.table.core.windows.net/Customers()?$filter=PartitionKey%20eq%20'MyPartitionKey'%20and%20RowKey%20eq%20'MyRowKey1'  

下列範例會篩選 FirstNameLastName 屬性:

https://myaccount.table.core.windows.net/Customers()?$filter=LastName%20eq%20'Smith'%20and%20FirstName%20eq%20'John'  

請注意,表格服務不支援萬用字元查詢。 不過,您可以在所需的前置詞上使用比較運算子,以執行前置詞比對。 下列範例會傳回 LastName 屬性且開頭為字母 'A' 的實體:

https://myaccount.table.core.windows.net/Customers()?$filter=LastName%20ge%20'A'%20and%20LastName%20lt%20'B'  

篩選數值屬性

若要篩選整數或浮點數,請在 URI 中指定常數值,不加引號。

下列範例會傳回 Age 屬性值大於 30 的所有實體:

https://myaccount.table.core.windows.net/Customers()?$filter=Age%20gt%2030  

下列範例會傳回 AmountDue 屬性值小於或等於 100.25 的所有實體:

https://myaccount.table.core.windows.net/Customers()?$filter=AmountDue%20le%20100.25%20  

篩選布林值屬性

若要篩選布林值,請指定 truefalse,不加引號。

下列範例會傳回 IsActive 屬性設為 true 的所有實體:

https://myaccount.table.core.windows.net/Customers()?$filter=IsActive%20eq%20true  

篩選 DateTime 屬性

若要篩選 DateTime 值,請在 URI 中指定 datetime 關鍵字,在其後方以單引號包住日期/時間常數。 日期/時間常數必須結合 UTC 格式,如 格式化 DateTime 值中所述。

下列範例會傳回 CustomerSince 屬性等於 2008 年 7 月 10 日的實體:

https://myaccount.table.core.windows.net/Customers()?$filter=CustomerSince%20eq%20datetime'2008-07-10T00:00:00Z'  

篩選 GUID 屬性

若要篩選 GUID 值,請在 URI 中指定 guid 關鍵字,在其後方以單引號包住 GUID 常數。

下列範例傳回之實體內的 GuidValue 屬性等於:

https://myaccount.table.core.windows.net/Customers()?$filter=GuidValue%20eq%20guid'a455c695-df98-5678-aaaa-81d3367e5a34'  

另請參閱

資料表服務概念
了解數據表服務數據模型
尋址數據表服務資源
查詢逾時和分頁
撰寫針對表格服務的 LINQ 查詢