クエリ構文

メタデータクエリ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"
  },
  ...
}

論理演算子

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

比較演算子

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

パターン一致

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%"
  },
  ...
}