テーブルとエンティティのクエリ
Table Service でテーブルおよびエンティティをクエリするには、要求 URI を慎重に作成する必要があります。 以下のセクションでは、クエリのオプションについて説明し、一般的な例を示します。
基本的なクエリ構文
特定のストレージ アカウント内のすべてのテーブルを返すには、「クエリ テーブル」の説明に従って Tables リソースに対して操作を実行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 順に並べ替えられます。 結果のその他の並べ替え方法は現在サポートされていません。
次のセクション、「サポートされるクエリ オプション」の説明に従い、その他のオプションを指定して、取得するテーブルまたはエンティティを制限できます。
注意
クエリがエンティティの最大数を超えた場合、タイムアウト間隔を超えた場合、またはパーティションの境界を超えた場合には、1 つの要求で返されるエンティティ数が制限されることがあります。 詳細については、「 クエリのタイムアウトと改ページ設定」を参照してください。
サポートされるクエリ オプション
Table service では、 OData プロトコル仕様に準拠する次のクエリ オプションがサポートされています。 これらのオプションを使用して、クエリで取得するテーブル、エンティティ、またはエンティティ プロパティを制限できます。
| システム クエリ オプション | 説明 |
|---|---|
$filter |
指定したフィルターを満たしたテーブルまたはエンティティのみを返します。$filter 文字列で許可される比較は 15 件までです。 |
$top |
結果セットから最初の n 個のテーブルまたはエンティティのみを返します。 |
$select |
結果セットからエンティティの目的のプロパティを返します。 このクエリ オプションは、バージョン 2011-08-18 以上を使用する要求に対してのみサポートされます。 詳細については、「 Table Service に対する 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 プロトコル仕様」を参照してください。
クエリ文字列のエンコード
次の文字は、クエリ文字列に使用する場合にはエンコードする必要があります。
- スラッシュ (/)
- 疑問符 (?)
- コロン (:)
- アットマーク (@)
- アンパサンド (&)
- 等号 (=)
- プラス記号 (+)
- コンマ (,)
- ドル記号 ($)
単一引用符 (')
クエリ文字列の単一引用符は、2 つの連続する単一引用符 ('') として表す必要があります。 たとえば、"o'clock" は次のようになります。
o''clock
クエリ式の例
次の例は、REST 構文を使用して一般的なエンティティ クエリの要求 URI を作成する方法を示しています。 同じクエリを LINQ 構文で作成することもできます。 詳細については、「 Table Service に対する LINQ クエリの記述」を参照してください。
$top オプションおよび $filter オプションは、String 型のプロパティでフィルター処理する構文例を使用して、テーブル名のフィルター処理にも利用できます。
最初の n 件のエンティティの取得
クエリの最初の n 件のエンティティを取得するには、$top クエリ オプションを指定します。 次の例は、Customers という名前のテーブルから最初の 10 件のエンティティを返します。
https://myaccount.table.core.windows.net/Customers()?$top=10
PartitionKey プロパティおよび RowKey プロパティでのフィルター処理
PartitionKey プロパティおよび RowKey プロパティはエンティティのプライマリ キーを構成するため、次のような特殊な構文でエンティティを識別できます。
https://myaccount.table.core.windows.net/Customers(PartitionKey='MyPartition',RowKey='MyRowKey1')
または、次のセクションで説明するように、これらのプロパティを $filter オプションに含めて指定することもできます。
キーのプロパティ名と定数値では大文字と小文字が区別されます。
PartitionKey プロパティと RowKey プロパティは String 型です。
フィルター文字列の作成
フィルター文字列を指定するときは、次のルールに注意してください。
OData プロトコル仕様で定義されている論理演算子を使用して、プロパティを値と比較します。 プロパティを動的な値と比較することはできません。式の 1 つの辺は定数である必要があります。
プロパティ名、演算子、および定数値は、URL でエンコードされた空白で区切る必要があります。 空白は URL エンコードでは
%20となります。フィルター文字列のすべての要素は大文字と小文字が区別されます。
フィルターで有効な結果を得るためには、定数値をプロパティと同じデータ型にする必要があります。 サポートされているプロパティ型の詳細については、 Table サービス データ モデルに関するページを参照してください。
注意
プロパティの型を文字列以外として扱う前に、プロパティが明示的に型指定されていることを確認してください。 プロパティを明示的に型指定すると、エンティティを返すときの応答内にその型が示されます。 明示的に型指定しない場合、プロパティは String 型になり、エンティティを返すときの応答内に型が示されません。
文字列プロパティのフィルター処理
文字列プロパティをフィルター処理する場合は、文字列定数を単一引用符で囲みます。
次の例では、PartitionKey プロパティおよび RowKey プロパティをフィルター処理しています。キー以外のプロパティをクエリ文字列に追加することもできます。
https://myaccount.table.core.windows.net/Customers()?$filter=PartitionKey%20eq%20'MyPartitionKey'%20and%20RowKey%20eq%20'MyRowKey1'
次の例では、FirstName プロパティおよび LastName プロパティをフィルター処理しています。
https://myaccount.table.core.windows.net/Customers()?$filter=LastName%20eq%20'Smith'%20and%20FirstName%20eq%20'John'
Table Service ではワイルドカードによるクエリはサポートされていません。 ただし、目的のプレフィックスに対して比較演算子を使用することで、プレフィックス一致を実行できます。 次の例は、文字 'A' で始まる LastName プロパティを持つエンティティを返します。
https://myaccount.table.core.windows.net/Customers()?$filter=LastName%20ge%20'A'%20and%20LastName%20lt%20'B'
数値プロパティのフィルター処理
整数または浮動小数点数をフィルター処理するには、引用符なしで URI の定数値を指定します。
次の例は、値が 30 より大きい Age プロパティを持つすべてのエンティティを返します。
https://myaccount.table.core.windows.net/Customers()?$filter=Age%20gt%2030
次の例は、値が 100.25 以下の AmountDue プロパティを持つすべてのエンティティを返します。
https://myaccount.table.core.windows.net/Customers()?$filter=AmountDue%20le%20100.25%20
ブール型プロパティのフィルター処理
ブール値をフィルター処理するには、引用符なしで true または false を指定します。
次の例は、IsActive プロパティが true に設定されているすべてのエンティティを返します。
https://myaccount.table.core.windows.net/Customers()?$filter=IsActive%20eq%20true
DateTime プロパティのフィルター処理
DateTime 値をフィルター処理するには、URI に datetime キーワードを指定し、その後に単一引用符で囲んだ日付/時刻の定数を指定します。 日付/時刻定数は、「 DateTime 値の書式設定」で説明されているように、UTC 形式を組み合わせて指定する必要があります。
次の例は、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'
参照
テーブル サービスの概念
Table Service データ モデルについて
Table Service リソースのアドレス指定
クエリのタイムアウトと改ページ
テーブル サービスに対する LINQ クエリの作成