> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pubrio.com/llms.txt
> Use this file to discover all available pages before exploring further.

# フィルター概要

> Pubrio の検索フィルターの仕組み — 統一されたフィルターエンジン、AND/OR セマンティクス、そしてどちらをいつ使うか。

Pubrio の検索エンドポイント(`/companies/search`、`/people/search`、`/companies/advertisements/search`)は単一のフィルターエンジンを共有しています。リクエストボディを一度組み立てれば、エンドポイントをまたいで同じルールが適用されます — 複数値フィルターの組み合わせ方、ロケーションのマッチング方法、そして `filter_conditions` でデフォルト演算子を上書きする方法も含めて。

## なぜ統一フィルターエンジンなのか?

<CardGroup cols={2}>
  <Card title="1 つのスキーマ、3 つのエンドポイント" icon="arrows-rotate">
    `technologies`、`verticals`、`founded_dates` といった企業レベルのフィルターは、`/companies/search`、`/people/search`、Monitor の `company_filters` で同一の挙動 — 一度学べば十分です。
  </Card>

  <Card title="フィルターごとの AND/OR" icon="code-merge">
    デフォルトは OR(いずれか一致)。`filter_conditions` に 1 行追加するだけで、個別のフィルターを AND(すべて一致)に切り替えられます — 他の項目には触れません。
  </Card>

  <Card title="Postgres ネイティブ演算子" icon="database">
    配列フィルターはネイティブの Postgres 演算子にコンパイルされます — OR は `&&`(オーバーラップ)、AND は `@>`(包含)。インデックスに優しく、アプリ側の後段フィルタリングは不要です。
  </Card>

  <Card title="Monitor でも同じフィルター" icon="bell">
    [Monitor](/jp/developer-guides/introduction) の `company_filters` ブロックも同じ形を受け付けるため、動作する検索ペイロードはそのまま動作する monitor ペイロードになります。
  </Card>
</CardGroup>

***

## 検索リクエストの構成

すべての検索リクエストは、同じ JSON ボディ内の 3 つのレイヤーから組み立てられます:

| レイヤー       | 配置場所                                                          | 例                                                                          |
| ---------- | ------------------------------------------------------------- | -------------------------------------------------------------------------- |
| 人物フィルター    | トップレベルキー                                                      | `people_titles`、`management_levels`、`departments`、`people_locations`       |
| 企業フィルター    | `company_filters: {...}` 内にネスト(推奨) — トップレベルでも受け付け             | `technologies`、`verticals`、`founded_dates`、`employees`、`company_locations` |
| 演算子オーバーライド | `filter_conditions` 配列(企業キーを上書きするときは `company_filters` の中に置く) | `[{ "key": "technologies", "operator": "and" }]`                           |

3 つのレイヤーすべてを使う最小限の `/people/search` リクエスト:

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.pubrio.com/people/search \
    -H "Content-Type: application/json" \
    -H "pubrio-api-key: YOUR_API_KEY" \
    -d '{
      "people_titles": ["VP of Engineering", "CTO"],
      "company_filters": {
        "technologies": ["Kubernetes", "Docker"],
        "is_enable_similarity_search": true,
        "company_locations": ["US"]
      },
      "per_page": 25,
      "page": 1
    }'
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      "https://api.pubrio.com/people/search",
      headers={
          "Content-Type": "application/json",
          "pubrio-api-key": "YOUR_API_KEY",
      },
      json={
          "people_titles": ["VP of Engineering", "CTO"],
          "company_filters": {
              "technologies": ["Kubernetes", "Docker"],
              "is_enable_similarity_search": True,
              "company_locations": ["US"],
          },
          "per_page": 25,
          "page": 1,
      },
  )
  print(response.json())
  ```

  ```javascript Node.js theme={null}
  const response = await fetch("https://api.pubrio.com/people/search", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "pubrio-api-key": "YOUR_API_KEY",
    },
    body: JSON.stringify({
      people_titles: ["VP of Engineering", "CTO"],
      company_filters: {
        technologies: ["Kubernetes", "Docker"],
        is_enable_similarity_search: true,
        company_locations: ["US"],
      },
      per_page: 25,
      page: 1,
    }),
  });
  console.log(await response.json());
  ```
</CodeGroup>

## `company_filters`:企業レベルのキーをひとまとめに

`company_filters: {...}` ラッパーオブジェクトは、企業レベルのフィルターを送る推奨方法です — どのキーが *人物* を絞り、どのキーが *企業* を絞るかが視覚的に分かれ、また [Monitor](/jp/developer-guides/introduction) が既に使っている構造と一致するため、検索と monitor 設定の間でペイロードをそのまま移動できます。

どちらのスタイルもサポートされます。エンジンは処理前にラップ形式をトップレベルに展開し、**同名キーがある場合はトップレベルが勝ちます**:

<CodeGroup>
  ```json ラップ形式(推奨) theme={null}
  {
    "people_titles": ["VP of Engineering"],
    "company_filters": {
      "technologies": [37, 152],
      "founded_dates": [2015, 2023],
      "company_locations": ["US"]
    }
  }
  ```

  ```json フラット形式(動作も可) theme={null}
  {
    "people_titles": ["VP of Engineering"],
    "technologies": [37, 152],
    "founded_dates": [2015, 2023],
    "company_locations": ["US"]
  }
  ```
</CodeGroup>

企業レベルのキーに対して `filter_conditions` オーバーライドを追加するときは、そのキーと一緒に動くように `company_filters` の **中** に置いてください。

### `/search/similar` バリアントは同じボディ形状

`POST /companies/search/similar` と `POST /people/search/similar` は、非類似版と**同じフィルターボディ**(`company_filters` ラッパーと `filter_conditions` を含む)を受け付けます。各エンドポイントはその上に類似度ステップを重ねます:

|                             | 追加で必要                                                                                       | 追加で得られるもの                                      |
| --------------------------- | ------------------------------------------------------------------------------------------- | ---------------------------------------------- |
| `/companies/search/similar` | 参照企業 — `domain_search_id`、`domain`、`linkedin_url`、または `domains`                             | 各結果に `similarity_score`(0-1 のフロート)、類似度の降順で並びます |
| `/people/search/similar`    | 参照人物/役職 — `people_titles`、`people_search_id`、`linkedin_url`、`linkedin_urls`、`peoples` のいずれか | 同様 — 各結果に `similarity_score`、類似度の降順            |

レスポンスの外形は標準 `search` エンドポイントと同一です。フィルターは類似度ランキングの *前* に候補プールを絞ります — そのため `company_locations: ["US"]` と `/people/search/similar` を組み合わせると、その制約下で参照役職に最も近い米国の人物が返ります。これは「これらの条件下で X に似た人物をさらに見つける」というパターンです。

<Note>
  標準の `/search` エンドポイントと異なり、`/search/similar` は正確な `pagination.total_entries` を**返しません** — 類似検索は関連性でランク付けし、上位マッチのみを返すため、値は上限でキャップされます。類似検索は*最良の*マッチを見つける用途で使い、全件列挙には使わないでください。
</Note>

***

## AND vs OR — フィルターごとに 1 つだけ決めること

複数値フィルター(`technologies`、`verticals`、`keywords`、`categories` …)は配列を受け付けます。演算子が「マッチ」の意味を決めます:

<Tabs>
  <Tab title="OR(デフォルト)">
    **いずれかの値にマッチ。** 配列が入力と重なる行を返します。

    ```json theme={null}
    {
      "technologies": ["Python", "PostgreSQL", "Kubernetes"],
      "is_enable_similarity_search": true
    }
    ```

    企業のテックスタックが `Python`、`PostgreSQL`、`Kubernetes` の **いずれか** を含めば結果に含まれます。Postgres `column && ARRAY[...]` にコンパイルされます。

    用途: 広い網を投げたいとき — 「いずれかに関心がある」「いずれかの国に所在する」など。
  </Tab>

  <Tab title="AND">
    **すべての値にマッチ。** 配列がすべての入力値を含む行を返します。

    ```json theme={null}
    {
      "technologies": [37, 152, 408],
      "filter_conditions": [
        { "key": "technologies", "operator": "and" }
      ]
    }
    ```

    Numeric tag IDs come from `GET /technologies?search_term=python` (and similar). **Don't combine `is_enable_similarity_search: true` with AND on the same key** — similarity expands each free-text term into many tag IDs and `@>` then requires the row to contain all of them, which almost always returns zero.

    企業のテックスタックが `[37, 152, 408]` を **すべて** 含む場合のみ結果に含まれます。Postgres `column @> ARRAY[...]` にコンパイルされます。

    用途: 精度が必要なとき — 「これらの技術を *すべて* 使っている」「すべてのバーティカルがタグ付けされている」。
  </Tab>
</Tabs>

<Note>
  `filter_conditions` に列挙されていないフィルターはデフォルト演算子(配列内は OR、別フィルターキー間は AND)を使います。宣言するのはオーバーライドだけで、デフォルトは書かなくて構いません。
</Note>

***

## オーバーライドできるキー

エンドポイントごとに受け付けるキーセットが異なります。キーは各 `*_filter_conditions` スキーマの OpenAPI enum に由来します:

<CardGroup cols={3}>
  <Card title="企業エンドポイント" icon="building" href="/jp/api-reference/endpoint/companies/search">
    `company_filter_conditions` キー: `keywords`、`verticals`、`vertical_categories`、`vertical_sub_categories`、`technologies`、`categories`、`advertisement_target_locations`、`advertisement_exclude_target_locations`、`advertisement_search_terms`、`places`、`exclude_places`、`job_exclude_locations`。
  </Card>

  <Card title="人物エンドポイント" icon="user" href="/jp/api-reference/endpoint/people/search">
    `people_filter_conditions` キー(企業エンジンに委譲): `keywords`、`verticals`、`vertical_categories`、`vertical_sub_categories`、`technologies`、`categories`、`places`、`exclude_places`、加えて `social_media`。
  </Card>

  <Card title="広告エンドポイント" icon="bullhorn" href="/jp/api-reference/endpoint/companies/advertisements_search">
    `ads_filter_conditions` キー: `target_locations`、`exclude_target_locations`。広告は配信国でのみ絞り込むため、キーセットは小さめです。
  </Card>
</CardGroup>

<Tip>
  `/people/search` を使う際、企業レベルのロケーションに対する `filter_conditions[].key` は企業エンジンの **bare 名** — `places`、`exclude_places` — を使い、プレフィックス付きの人物 API 名(`company_places`)ではありません。詳細は [人物 + 企業フィルター](/jp/developer-guides/filters/people-with-company-filters#key-remap-reference) を参照してください。
</Tip>

***

## パフォーマンスのヒント

<AccordionGroup>
  <Accordion title="インデックス済みカラムで早めに絞り込む" icon="bolt">
    ロケーション、従業員レンジ、`founded_dates` はインデックス化されており、フリーテキストやバーティカルより速く候補集合を縮められます。1〜2 個の精密フィルターと組み合わせてから、類似検索に進みましょう。
  </Accordion>

  <Accordion title="大きな配列で AND を使いすぎない" icon="triangle-exclamation">
    `column @> ARRAY[a, b, c, …]` は全要素の存在を要求します。基数が急増し — 平均 3 タグのカテゴリで 10 件の tech に対して AND をかけると、ほぼ 0 行になりフルスキャンを誘発します。AND フィルターは 2〜4 値に抑え、探索クエリは OR で。
  </Accordion>

  <Accordion title="フリーテキスト入力には is_enable_similarity_search" icon="wand-magic-sparkles">
    slug ID(verticals、technologies、categories)を渡せず、フリーテキストしかない場合は、`is_enable_similarity_search: true` と `similarity_score: 0.7` を設定してください。エンジンがマッチを解決してからフィルター適用 — テキストスキャンよりずっと安価です。
  </Accordion>

  <Accordion title="サイズと売上は enum リストよりレンジを優先" icon="arrows-left-right">
    `employees: [[201, 500], [501, 1000]]`(レンジの配列)や `revenues: [1000000, 5000000]`(単一の最小/最大レンジ)は長い ID リストより速く、より自然です。
  </Accordion>
</AccordionGroup>

***

## 次のステップ

<CardGroup cols={2}>
  <Card title="filter_conditions" icon="code-merge" href="/jp/developer-guides/filters/filter-conditions">
    リファレンスページ — サポートされる全キー、デフォルト、コピー可能な AND/OR レシピ。
  </Card>

  <Card title="人物 + 企業フィルター" icon="users-rectangle" href="/jp/developer-guides/filters/people-with-company-filters">
    `/people/search` 内であらゆる企業フィルターを使う。統一エンジンの目玉機能です。
  </Card>

  <Card title="企業検索リファレンス" icon="building" href="/jp/api-reference/endpoint/companies/search">
    `/companies/search` の完全なリクエスト/レスポンススキーマ。
  </Card>

  <Card title="人物検索リファレンス" icon="user" href="/jp/api-reference/endpoint/people/search">
    `/people/search` の完全なリクエスト/レスポンススキーマ。
  </Card>
</CardGroup>

<Note>
  ダッシュボード側のフィルタリング解説をお探しですか? ナレッジベースの [連絡先のフィルタリングとエクスポート](/jp/knowledge-base/concepts/search-filters) をご覧ください。
</Note>