メタデータフィルター ​

List documents（advanced filters）およびSearch documents（advanced filters）バッチアクションでメタデータフィルターを使用します。

data_filters JSONオブジェクトを使用してメタデータをフィルターし、値のリストとの照合、条件のORグループ、複数条件の同時組み合わせなど、専用フィールドでは表現できないデータを取得します。

詳細フィルターを使用するタイミング ​

標準のSearch documentsアクションおよびList documentsアクションでは、コンテンツタイプ、Created after、Created before、Updated after、Updated before、キー値形式のMetadata filtersリストなどの専用フィールドに静的フィルタリングを使用します。

List documents（advanced filters）およびSearch documents（advanced filters）は、静的フィルタリングでデータを解析できない場合に、動的な詳細フィルタリングを有効にするためにdata_filtersを使用します。

詳細フィルターの使用方法 ​

詳細フィルタリングをワークフローに適用する方法を判断するには、次の例を使用します。

完全一致 ​

次の例では、statusメタデータがactiveと等しいドキュメントのみを返します。 フィールドが単一の値と等しい場合は、この例を使用します。

{ "status": "active" }

複数の値の一致（OR） ​

次の例では、指定したリストと一致する任意の値を返します。 配列内に値が存在するかどうかを確認する必要がある場合は、この例を使用します。

{ "owner": ["abby", "jaime"] }

これにより、abbyまたはjaimeが所有するドキュメントが返されます。

ORグループ ​

次の例では、単一フィールドの値ではなく、指定したリスト内の条件全体のいずれかに一致するドキュメントを返します。 異なるフィールドで条件をORと組み合わせる必要がある場合は、この例を使用します。

{ "or": [ { "category": "finance" }, { "category": "legal" } ] }

これにより、categoryがfinanceまたはlegalと等しいドキュメントが返されます。

各ブランチに複数の条件があるORグループ ​

ブランチに複数の条件がある場合は、次の例を使用します。 or内の各オブジェクトはキーをANDで組み合わせることができるため、2つの異なる複数フィールド条件をORで結合できます。

{
  "or": [
    { "category": "finance", "region": "US" },
    { "category": "legal", "region": "EU" }
  ]
}

(category = finance AND region = US) OR (category = legal AND region = EU)を返します。

最上位のAND条件と組み合わせたORグループ ​

orの隣にある最上位キーがすべての結果に適用され、一致するORブランチにANDで組み合わされる場合は、次の例を使用します。

{
  "status": "active",
  "or": [
    { "owner": "abby" },
    { "owner": "jaime" }
  ]
}

activeステータスで、所有者がabbyまたはjaimeであるドキュメントを返します。

日付範囲 ​

次の例では、指定した範囲内に該当するドキュメントを返します。 日付の前、後、または日付間でcreated_atまたはupdated_atをフィルタリングする必要がある場合は、この例を使用します。

{ "created_at": { "start": "2024-01-01", "end": "2024-12-31" } }

これにより、created_atが2024年1月1日から2024年12月31日までのドキュメントが返されます。 startとendはいずれも任意です。 日付にはISO 8601形式を使用します。YYYY-MM-DDまたは完全なタイムスタンプを指定できます。 この範囲形式はcreated_atとupdated_atにのみ適用されます。 他のフィールドの値を比較するには、フィールド演算子を参照してください。

この日付以降のドキュメントを取得するには、startのみを指定し、endを省略します。 例:

{ "updated_at": { "start": "2024-06-01" } }

指定した日付より前のドキュメントを取得するには、endのみを指定し、startを省略します。 例:

{ "created_at": { "end": "2024-06-30" } }

フィールド演算子 ​

プレーン値の代わりに、次の演算子の1つ以上を含むオブジェクトをフィールドに指定します。

値を除外、値を比較、または値の一部を一致させる必要がある場合は、これらの演算子を使用します。 演算子は、created_atとupdated_atだけでなく、すべてのメタデータフィールドで機能します。

同じフィールドに複数の演算子を指定すると、ANDを使用して演算子が連結されます。 たとえば、gteとltを組み合わせると半開区間が生成されます。

{ "page_count": { "gte": 10, "lt": 100 } }

これにより、page_countが10以上100未満のドキュメントが返されます。 下限は含まれ、上限は除外されます。

値を除外 ​

次の例では、authorメタデータがbot以外のドキュメントを返します。

{ "author": { "ne": "bot" } }

複数の値を一度に除外するには、リストを指定します。 例:

{ "status": { "ne": ["spam", "deleted"] } }

これにより、statusがspamとdeletedのどちらにも等しくないドキュメントが返されます。

数値範囲 ​

次の例では、page_countが10から100の範囲に該当するドキュメントを返します。 数値を保持するフィールドで包括的な範囲が必要な場合は、この例を使用します。

{ "page_count": { "gte": 10, "lte": 100 } }

境界値を除外する必要がある場合は、gtとltを使用します。 例:

{ "page_count": { "gt": 10, "lt": 100 } }

これにより、page_countが10より大きく100未満のドキュメントが返されます。

部分一致 ​

次の例では、値の任意の場所にquarterlyを含むtitleのドキュメントを返します。 値全体ではなく値の一部を一致させる必要がある場合は、この例を使用します。

{ "title": { "like": "*quarterly*" } }

""、null、[]など、空または欠落している演算子値は、エラーを返すのではなく無視されます。 これは他のビルディングブロックでの動作と一致しています。

キー間のAND ​

次の例では、指定したすべてのキーに一致するドキュメントを返します。 複数の条件を同時に適用する必要がある場合は、この例を使用します。 複数のキーを指定すると、キーは自動的にANDで結合されます。

{ "lang": "en", "status": "published" }

これにより、langがenに等しく、statusがpublishedに等しいドキュメントが返されます。

フィルターの組み合わせ ​

前述のビルディングブロックを1つのオブジェクトに組み合わせることができます。 組み合わせたキーはANDで結合されます。

{
  "status": "active",
  "owner": ["abby", "jaime"],
  "created_at": { "start": "2024-01-01", "end": "2024-12-31" }
}

これにより、statusがactiveに等しく、ownerがabbyまたはjaimeで、created_atが2024年に該当するドキュメントが返されます。

配列値メタデータフィールドでのリスト包含 ​

ドキュメントメタデータフィールド配列で完全一致フィルターが必要な場合は、次の例を使用します。

{ "participant_email": "[email protected]" }

これにより、participant_email配列の値の中に[email protected]が含まれるすべてのドキュメントが返されます。

一括操作の絞り込み ​

古い未公開ドキュメントを特定する必要がある場合は、次の例を使用します。

{
  "status": "draft",
  "updated_at": { "end": "2024-01-01" }
}

2024-01-01より前に作成されたdraftステータスのドキュメントのリストを返します。

その他のデータ型 ​

完全一致、OR-list、ne、likeでは、整数型、ブール型、数値型は使用されません。 Enterprise context by Workatoは、すべてのメタデータ値をテキストとして保存および照合します。

• 完全一致とOR-listはいずれも、正確なテキスト一致を確認します。 {"count": 5}のようなフィルターは、保存されているテキストが5と等しいかどうかを確認します。 数値比較は実行されません。
• likeは、保存されている正確な値に対してテキストとしてワイルドカードを一致させます。
• {start, end}範囲形式はcreated_atとupdated_atにのみ適用されます。 他のフィールドの値を比較するには、フィールド演算子を使用します。

priorityが4または5であるドキュメントを一致させるには、OR-listで両方の値を指定できます。

{ "priority": ["4", "5"] }

または、フィールドが数値としてマッピングされている場合はgteを使用します。

{ "priority": { "gte": 4 } }