フィルター構文

一部のAPIエンドポイントではwhereパラメータを受け付けており、結果セットにフィルターを適用できます。

以下のセクションでは、フィルターの使用例と完全な構文リファレンスを紹介します。

例

info

より実践的な例として、ahrefs.comのレポートでビジュアルインターフェースを使っていくつかフィルターを適用し、その後API {}ボタンを押して、生成されたAPI v3クエリのwhereパラメータを確認してみてください。

フィールド「foo」が3に等しい場合：

{ "field": "foo", "is": ["eq", 3] }

オブジェクト型のフィールドでは、ドット表記でネストされたフィールドを参照します。フィールド「foo」の下にネストされたフィールド「bar」が3に等しい場合：

{ "field": "foo.bar", "is": ["eq", 3] }

整数フィールド「foo」が3に等しく、整数フィールド「bar」が10未満の場合：

{
    "and": [
        { "field": "foo", "is": ["eq", 3] },
        { "field": "bar", "is": ["lt", 10] }
    ]
}

文字列フィールド「foo」の値を大文字化したものが「AHREFS」に等しい、または配列フィールド「bar」のすべての文字列要素が接頭辞「Ahrefs」と接尾辞「seo」を持つ場合。

{
  "or": [
    {
      "field": "foo",
      "modifier": "uppercase",
      "is": ["eq", "AHREFS"]
    },
    {
      "field": "bar",
      "list_is": {
        "and": [
          ["prefix", "Ahrefs"],
          ["suffix", "seo"],
        ]
      }
    }
  ]
}

言語リファレンス

フィルター構文は、以下の文法で定義されます。表記はBNFスタイルの記法を使用しています。

山括弧\\<と>で囲まれた項は、記号を表します。記号の後に+が付く場合、その記号を含む空でない配列を表します。オブジェクトのフィールドの前に?が付いている場合、そのフィールドは任意です。

2つの終端記号は以下のように定義されます：

\\<field_alias> フィルターフィールドのエイリアス。有効なエイリアスの一覧は、該当するエンドポイントのドキュメントを参照してください。 selectとwhereパラメータで受け付けるエイリアスが異なる場合がある点に注意してください。
\\<value> JSON値。これは、フィールドの型（修飾子がある場合はその修飾子の型）と一致する必要があります。

正規表現フィルター式で許可されるパターンは、ツールによって異なります。

キーワードエクスプローラー: ワイルドカード演算子として使用できるのは * のみです。
サイトエクスプローラー: RE2 構文。

\<bool_filter> ::= { "and" : \<bool_filter>+ }
              |   { "or" : \<bool_filter>+ }
              |   { "not" : \<bool_filter> }
              |   \<expr>

\<expr> ::= {
             "field" : \<field_alias>,
             ? "is": \<condition>,
             ? "list_is": \<list_condition>
           }

\<condition> ::= [ "eq", \<value> ]
            |   [ "neq", \<value> ]
            |   [ "gt", \<value> ]
            |   [ "gte", \<value> ]
            |   [ "lt", \<value> ]
            |   [ "lte", \<value> ]
            |   [ "substring", \<value> ]
            |   [ "isubstring", \<value> ]
            |   [ "phrase_match", \<value> ]
            |   [ "iphrase_match", \<value> ]
            |   [ "prefix", \<value> ]
            |   [ "suffix", \<value> ]
            |   [ "regex", \<value> ]
            |   "empty"
            |   "is_null"

\<condition_bool_filter> ::= { "and" : \<condition_bool_filter>+ }
                        |   { "or" : \<condition_bool_filter>+ }
                        |   { "not" : \<condition_bool_filter> }
                        |   \<condition>

\<list_condition> ::= { "any" : \<condition_bool_filter> }
                 |   { "all" : \<condition_bool_filter> }