クエリ構文

クエリ構文

メタデータクエリ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値はメタデータテンプレートのscopetemplateKeyを表し、ancestor_folder_idはサブフォルダを含む検索範囲となるフォルダIDを表します。

fieldsパラメータ

デフォルトでは、このAPIで返されるのは、idtype、およびetagの値を含む、ファイルまたはフォルダの基本レプリゼンテーションのみです。その他のデータをリクエストするには、fieldsパラメータを使用すると、追加のフィールドや、その項目に関連付けられたメタデータに対してクエリを実行できます。

例:

  • created_byでは、項目を作成したユーザーの詳細がレスポンスに追加されます。
  • metadata.<scope>.<templateKey>では、scopetemplateKeyによって識別されたメタデータインスタンスの基本レプリゼンテーションが返されます。
  • metadata.<scope>.<templateKey>.<field>では、scopetemplateKeyによって識別されたメタデータインスタンスの基本レプリゼンテーションのすべてのフィールドに加え、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"
  },
  ...
}

論理演算子

クエリでは、以下の論理演算子がサポートされます。

演算子
ANDANDで区切られたすべての条件がTRUEの場合に一致となります。
ORORで区切られた条件のいずれかがTRUEの場合に一致となります。
NOT先行する条件がTRUEでない場合に一致となります。
LIKEテンプレートフィールドの値がパターンと一致する場合に一致となります。文字列値のみに対応します。詳細については、パターン一致を参照してください。その他の制限については以下を参照してください。
NOT LIKEテンプレートフィールドの値がパターンと一致しない場合に一致となります。文字列値のみに対応します。詳細については、パターン一致を参照してください。その他の制限については以下を参照してください。
ILIKELIKEと同じですが、大文字と小文字が区別されません。その他の制限については以下を参照してください。
NOT ILIKENOT LIKEと同じですが、大文字と小文字が区別されません。その他の制限については以下を参照してください。
INテンプレートフィールドの値は、指定された引数のリストのいずれかと等しい場合に一致となります。この形式では、amount NOT IN (:arg1, :arg2, :arg3)のように、リスト内の各項目はquery_params引数として明示的に定義する必要があります。
NOT ININに似ていますが、テンプレートフィールドの値は、リストに指定されたどの引数にも一致しません。
IS NULLテンプレートフィールドの値がnullの場合に一致となります。
IS NOTテンプレートフィールドの値がnullでない場合に一致となります。

ILIKE演算子を使用した場合を除き、stringまたはenumフィールドでの一致は、どれも大文字小文字が区別されます。

比較演算子

クエリでは、以下の比較演算子がサポートされます。

演算子
=テンプレートフィールドの値が、指定した値と等しいことを表します。
>テンプレートフィールドの値が、指定した値よりも大きいことを表します。
<テンプレートフィールドの値が、指定した値よりも小さいことを表します。
>=テンプレートフィールドの値が、指定した値以上であることを表します。
<=テンプレートフィールドの値が、指定した値以下であることを表します。
<>テンプレートフィールドの値が、指定した値と等しくないことを表します。

ビット単位演算子および算術演算子は、メタデータクエリAPIではサポートされていません。

パターン一致

LIKENOT LIKEILIKEおよびNOT ILIKE演算子は、パターンに対して文字列が一致するかどうかを照合します。このパターンでは、以下の予約文字をサポートします。

  • % パーセント記号は0個、1個または複数個の文字を表します。たとえば、%Contractの場合、ContractSales Contractは一致しますが、Contract (Sales)は一致しません。
  • _ アンダースコアは1文字を表します。たとえば、Bo_の場合、BoxBotは一致しますが、Botsは一致しません。

上記の文字はどちらも、他の文字の前後または文字の間に使用できます。パターンには、複数の予約文字を含めることができます。たとえば、Box% (____)の場合はBox Contract (2020)が一致します。

クエリの例は次のようになります。%でラップされた文字列はquery属性ではなくquery_paramsのリストに含まれていることに注意してください。

{
  ...,
  "query": "country ILIKE :country",
  "query_params": {
    "country": "%United%"
  },
  ...
}

%または_文字を、その文字として照合する必要がある場合は、エスケープするためにバックスラッシュ文字\を使用できます。たとえば、20\%の場合は、リテラル値20%が一致します。