クエリ構文
クエリ構文
メタデータクエリAPIのクエリ構文はSQLデータベースのクエリ構文と似ています。契約金額が100ドルを超える契約メタデータテンプレートに一致するすべてのファイルとフォルダに対してクエリを実行するには、以下のメタ データクエリを作成します。
{
"from": "enterprise_123456.contractTemplate",
"query": "amount >= :value",
"query_params": {
"value": 100
},
"fields": [
"name",
"metadata.enterprise_123456.contractTemplate.amount"
],
"ancestor_folder_id": "5555"
}
この場合、from値はメタデータテンプレートのscopeとtemplateKeyを表し、ancestor_folder_idはサブフォルダを含む検索範囲となるフォルダIDを表します。
fieldsパラメータ
デフォルトでは、このAPIで返されるのは、id、type、およびetagの値を含む、ファイルまたはフォルダの基本レプリゼンテーションのみです。その他のデータをリクエストするには、fieldsパラメータを使用すると、追加のフィールドや、その項目に関連付けられたメタデータに対してクエリを実行できます。
例:
created_byでは、項目を作成したユーザーの詳細がレスポンスに追加されます。metadata.<scope>.<templateKey>では、scopeとtemplateKeyによって識別されたメタデータインスタンスの基本レプリゼンテーションが返されます。metadata.<scope>.<templateKey>.<field>では、scopeとtemplateKeyによって識別されたメタデータインスタンスの基本レプリゼンテー ションのすべてのフィールドに加え、fieldの名前によって指定されたフィールドが返されます。同じscopeおよびtemplateKeyの複数のフィールドを定義できます。
queryパラメータ
queryパラメータは、選択したメタデータインスタンスに対して実行する、SQLに似たクエリを表します。このパラメータは省略可能で、このパラメータを指定しない場合、APIはこのテンプレートに対してすべてのファイルとフォルダを返します。
左側の各フィールド名 (amountなど) は、関連付けられたメタデータテンプレートのフィールドのkeyに一致する必要があります。つまり、関連付けられたメタデータインスタンスに実際に存在するフィールドだけを検索できます。その他のフィールド名を指定するとエラーが発生し、エラーが返されます。
query_paramsパラメータ
クエリ文字列への動的な値の埋め込みをわかりやすくするために、:valueのように、コロン構文を使用して引数を定義できます。たとえば、次のように指定された各引数では、query_paramsオブジェクトにそのキーを使用した後続の値が必要です。
{
...,
"query": "amount >= :amount AND country = :country",
"query_params": {
"amount": 100,
"country": "United States"
},
...
}
論理演算子
クエリでは、以下の論理演算子がサポートされます。
| 演算子 | |
|---|---|
AND | ANDで区切られたすべての条件がTRUEの場合に一致となります。 |
OR | ORで区切られた条件のいずれかがTRUEの場合に一致となります。 |
NOT | 先行する条件がTRUEでない場合に一致となります。 |
LIKE | テンプレートフィールドの値がパターンと一致する場合に一致となります。文字列値のみに対応します。詳細については、パターン一致を参照してください。その他の制限については以下を参照してください。 |
NOT LIKE | テンプレートフィールドの値がパターンと一致しない場合に一致となります。文字列値のみに対応します。詳細については、パターン一致を参照してください。その他の制限については以下を参照してください。 |
ILIKE | LIKEと同じですが、大文字と小文字が区別されません。その他の制限については以下を参照してください。 |
NOT ILIKE | NOT LIKEと同じですが、大文字と小文字が区別されません。その他の制限については以下を参照してください。 |
IN | テンプレートフィールドの値が指定されたリストの任意の値と等しい場合に一致となります。amount IN (:arg1, :arg2, :arg3)などの各リスト項目には、明示的に定義されたquery_params引数を使用します。仕様では、IN演算子はメタデータクエリの複数選択フィールドでサポートされていないため、400エラーが返されます。 |
NOT IN | INに似ていますが、テンプレートフィールドの値は、リストに指定されたどの引数にも一致しません。 |
IS NULL | テンプレートフィールドの値がnullの場合に一致となります。 |
IS NOT NULL | テンプレートフィールドの値がnullでない場合に一致となります。 |
~ | Performs term-level search on the field against the provided terms. |
HASANY | Matches when the field value is equal to any of the arguments provided. The format requires each item in the list to be an explicitly defined query_params argument, for example, amount HASANY (:arg1, :arg2, :arg3). |
HASALL | Matches when the field value has a match for all the arguments provided. The format requires each item in the list to be an explicitly defined query_params argument, for example, amount HASALL (:arg1, :arg2, :arg3). |
HASANCESTOR | Matches when the field value is a descendant of any argument provided. The format requires each item in the list to be an explicitly defined query_params argument, for example, amount HASANCESTOR (:arg1, :arg2, :arg3). Supported only for the taxonomy MD field. |
比較演算子
クエリでは、以下の比較演算子がサポートされます。
| 演算子 | |
|---|---|
= | テンプレートフィールドの値が、指定した値と等しいことを表します。 |
> | テンプレートフィールドの値が、指定した値よりも大きいことを表します。 |
< | テンプレートフィールドの値が、指定した値よりも小さいことを表します。 |
>= | テンプレートフィールドの値が、指定した値以上であることを表します。 |
<= | テンプレートフィールドの値が、指定した値以下であることを表します。 |
<> | テンプレートフィールドの値が、指定した値と等しくないことを表します。 |
パターン一致
LIKE、NOT LIKE、ILIKEおよびNOT ILIKE演算子は、パターンに対して文字列が一致するかどうかを照合します。このパターンでは、以下の予約文字をサポートします。
%パーセント記号は0個、1個または複数個の文字を表します。たとえば、%Contractの場合、Contract、Sales Contractは一致しますが、Contract (Sales)は一致しません。_アンダースコアは1文字を表します。たとえば、Bo_の場合、Box、Botは一致しますが、Botsは一致しません。
上記の文字はどちらも、他の文字の前後または文字の間に使用できます。パターンには、複数の予約文字を含めることができます。たとえば、Box% (____)の場合はBox Contract (2020)が一致します。
クエリの例は次のようになります。%でラップされた文字列はquery属性ではなくquery_paramsのリストに含まれていることに注意してください。
{
...,
"query": "country ILIKE :country",
"query_params": {
"country": "%United%"
},
...
}