範囲フィルタ

のいくつかのCloud Directory リスト API では、フィルタを範囲形式で指定できます。これらのフィルタを使うと、指定したノードにアタッチされたリンクのサブセットを効率的に選択できます。

通常、範囲はマップ (キー/値のペアの配列) として指定します。キーは属性識別子、値は対応する範囲です。これにより、アイデンティティが 1 つ以上の属性で構成されているリンクをフィルタリングできます。たとえば、ロール関係をモデル化してアクセス権限を決定する TypedLink セットアップは、RoleType 属性と Authorizer 属性の両方を持つ場合があります。この場合、ListOutgoingTypedLinks 呼び出しは、範囲を指定することで、結果を RoleType:”Admin” と Authorizer:”Julia” でフィルタリングできます。1 つのリストリクエストのフィルタリングに使用する範囲のマップには、リンクのアイデンティティ (インデックスの OrderedIndexedAttributeList または TypedLink の IdentityAttributeOrder) を定義する属性のみを含める必要があり、すべての属性の範囲を含める必要はありません。欠落した範囲は、FIRST から LAST までのすべての該当する値にまたがる範囲で自動的に満たされます。

各属性は独立したフラットな値のドメインを定義するものと考えると、範囲構造は、そのドメインの 2 つの論理ポイント (スタートポイントとエンドポイント) を定義し、範囲は 2 つの論理ポイント間のすべての該当するポイントにマッチします。範囲構造の StartValue と EndValue では、これら 2 つのポイントの基礎を定義し、さらに「モード」により適用範囲を絞り込こむとで、各ポイント自体を範囲に含めるか範囲から除外するかを指定します。上の例の RoleType:”Admin” の場合、RoleType 属性の値は両方とも “Admin” で、モードは両方とも “INCLUSIVE” です ([“Admin” to “Admin”] と表記されます)。ListIndex 呼び出しのフィルタ (インデックスを User ファセットの LastName で定義する場合) では、「StartValue=”D”, StartMode=INCLUSIVE, EndValue:”G”, EndMode:EXCLUSIVE」を使用してリストを絞り込み、D、E、または F で始まる名前を抽出できます。

範囲のスタートポイントは、常にエンドポイント以前にする必要があります。EndValue が StartValue に先行している場合は、Cloud Directory からエラーが返されます。また、値はフィルタリングする属性と同じプリミティブ型にする必要があります。つまり、文字列属性には文字列値、整数属性には整数などを使います。たとえば、「StartValue=“D”, StartMode=EXCLUSIVE, EndValue=“D”, EndMode=INCLUSIVE」は無効です。エンドポイントに含まれる値がスタートポイントより先行しているためです。

スタートポイントまたはエンドポイントで使用できる 3 つの特殊なモードがあります。以下のモードでは、位置が明白であるため、対応する値フィールドを指定する必要がありません。

• FIRST - ドメインのすべての該当する値に先行します。これをスタートポイントに使用すると、ドメインの先頭からエンドポイントまでのすべての該当する値にマッチします。これをエンドポイントに使用すると、ドメインのいずれの値も範囲にマッチしません。

• LAST - ドメインのすべての該当する値の後になります。これをエンドポイントに使用すると、スタートポイントに続くすべての該当する値にマッチします (欠落した値も含まれます)。これをスタートポイントに使用すると、ドメインのいずれの値も範囲にマッチしません。

• LAST_BEFORE_MISSING_VALUES - このモードは、オプションの属性で値が欠落している場合にのみ役立ちます (「欠落した値」を参照してください)。これは欠落した値と実際のドメイン値の間のポイントに対応します。これをエンドポイントに使用すると、スタートポイントに続くすべての欠落していないドメイン値にマッチします。これをスタートポイントに使用すると、すべての欠落していないドメイン値が除外されます。属性が必須である場合、欠落した値は存在しないため、このモードは LAST と同じになります。

複数の範囲の制限

複数の属性がある場合は、低レイテンシーで効率的なリクエスト処理を保証するために、Cloud Directory でパターンが制限されます。複数の識別属性を持つ各リンクは、明確に定義された順序で属性を指定します。たとえば、上の例の Role では、RoleType 属性を重要性が最上位、Authorizer 属性を最下位として定義します。リストリクエストで指定できるのは単一の "識別" 範囲であり、その条件として 1) 単一の値でないこと、2) すべての該当する値にまたがる範囲でないことの両方が求められます (この 2 つの条件に該当する範囲は複数存在する場合があります)。識別範囲属性より重要性が高い属性は、範囲として単一の値を指定し、重要性がより低い属性の範囲はすべての該当する値にまたがる必要があります。Role の例の場合、フィルタセット (RoleType:”Admin”, Authorizer:[“J” to “L”]) (単一の値 + 識別範囲)、(RoleType:[”Admin” to “User”]) (識別範囲 + 暗黙のまたがる範囲)、および (RoleType:[FIRST to LAST]) (2 つのまたがる範囲、1 つの暗黙の範囲) のすべてが有効なフィルタセットの例です。(RoleType:[FIRST to LAST], Authorizer:”Julia”) は有効なセットではありません。またがる範囲が単一の値の範囲より重要性が高くなっているためです。

範囲構造を満たす場合に役立つパターンは以下のとおりです。

単一の値のマッチング

StartValue と EndValue の両方の値を指定し、両方のモードを「INCLUSIVE」に設定します。

例: StartValue=“Admin”, StartMode=INCLUSIVE, EndValue=“Admin”, EndMode=INCLUSIVE

プレフィックスのマッチング

プレフィックスを StartValue (INCLUSIVE モード) として指定し、プレフィックスに続く最初の値を EndValue (EXCLUSIVE モード) として指定します。

例: StartValue=“Jo”, StartMode=INCLUSIVE, EndValue=“Jp”, EndMode=EXCLUSIVE (“p” is the next character value after “o”)

値を超える範囲のフィルタリング

StartValue (EXCLUSIVE モード) の値を指定し、LAST を EndMode (または、欠落した値を除外する場合は LAST_BEFORE_MISSING_VALUES) として指定します。

例: StartValue=127, StartMode=EXCLUSIVE, EndValue=null, EndMode=LAST

値以下の範囲のフィルタリング

EndValue (INCLUSIVE モード) の値を指定し、FIRST を StartMode として指定します。

欠落した値

(オプション) スキーマで属性を「Optional」としてマークすると、ファセットをアタッチする際に値を指定する必要がないため、または属性が後で削除されている場合があるため、値が「欠落」していることがあります。値が欠落しているオブジェクトをインデックスにアタッチすると、インデックスリンクは、まだ存在している場合でも、リンクセットの最後に移動されます。ListIndex 呼び出しは、最初にインデックス付き属性がすべて存在するリンクを返してから、1 つ以上の属性が欠落しているリンクを返します。これは、リレーショナルデータベースの NULL 値とほぼ同じです (これらの値の順番は、NULL 以外の値の後になります)。これらの欠落した値を範囲に含めるかどうかは、LAST モードまたは LAST_BEFORE_MISSING_VALUES モードを選択して指定できます。たとえば、ListIndex 呼び出しにフィルタを指定し、範囲 [LAST_BEFORE_MISSING_VALUES to LAST] でフィルタリングすることで、インデックス内の欠落した値のみを返させることができます。