テーブルとエンティティのクエリ

  • [アーティクル]

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 クエリの作成