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

# 検索

> 1 回の API 呼び出しで、組織内のプロジェクト、スタディ、シミュレーション、モデル、最適化、セルを検索します

検索を使うと、エンドポイントごとに個別に問い合わせることなく、組織内のリソースを素早く見つけられます。1 つのクエリで、一致するプロジェクト、スタディ、シミュレーション、モデル、パラメータ化モデル、最適化、最適化テンプレート、実験テンプレート、パイプライン、セル仕様、セルインスタンス、セル測定、材料、サイクラー、およびチャネルを返します。

検索は REST API と Ionworks Studio のグローバル検索バーの両方から利用できます。Studio では任意のページ上部から検索バーを開けます。また、独自のスクリプトやツールから `/search` エンドポイントを直接呼び出すこともできます。

## 検索可能な対象

| リソース種別    | マッチする内容の例             |
| --------- | --------------------- |
| プロジェクト    | プロジェクト名と説明            |
| スタディ      | アクセス可能なプロジェクト内のスタディ名  |
| シミュレーション  | シミュレーション名とメタデータ       |
| モデル       | モデル名と説明               |
| パラメータ化モデル | パラメータ化モデル名            |
| 最適化       | 最適化実行名                |
| 最適化テンプレート | 組み込み・カスタムのテンプレート名     |
| 実験テンプレート  | 組み込み・カスタムのプロトコルテンプレート |
| パイプライン    | パイプライン名と説明            |
| セル仕様      | セル名、化学、識別子            |
| セルインスタンス  | シリアル番号とインスタンス識別子      |
| セル測定      | 測定名とメタデータ             |
| 材料        | 負極、正極、電解液の材料          |
| サイクラー     | サイクラー名と説明             |
| チャネル      | サイクラー内のチャネル名と識別子      |

検索は各リソース種別の名前、説明、その他の識別フィールドに対してマッチングを行います。結果は現在の組織にスコープされ、プロジェクトレベルの権限を尊重します。アクセスできるリソースのみが表示されます。

## API 経由で検索を使用する

検索は `/search` エンドポイントで利用できます。完全なリクエスト/レスポンススキーマについては[API リファレンス](/api-reference)を参照してください。

典型的なリクエストはクエリ文字列を指定し、リソース種別ごとにグループ化されたマッチを返します:

```bash theme={null}
curl -X GET "https://api.ionworks.com/search?q=NMC622" \
  -H "Authorization: Bearer $IONWORKS_API_KEY"
```

結果は API キーがアクセス可能なリソースにフィルタリングされます。

### クエリパラメータ

| パラメータ          | 型             | デフォルト | 説明                                                                                                                                                                  |
| -------------- | ------------- | ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `q`            | string        | —     | 検索クエリ。最低 2 文字。必須。                                                                                                                                                   |
| `limit`        | int           | `25`  | このページで返す結果の最大件数（1–100）。                                                                                                                                             |
| `offset`       | int           | `0`   | このページの前にスキップする結果数。`limit` と組み合わせてページネーションを行います。                                                                                                                     |
| `per_type`     | int           | `5`   | ページネーション適用前にエンティティ種別ごとに返す結果の最大件数（1–20）。                                                                                                                             |
| `entity_types` | string（繰り返し可） | —     | 結果をこれらのエンティティ種別に限定します。省略するとすべての種別を検索します。未知の値は無視されます。                                                                                                                |
| `project_id`   | string        | —     | プロジェクトでフィルタリングされるエンティティ（スタディ、パイプライン、最適化）を 1 つのプロジェクトに絞り込みます。その他のエンティティタイプ（セル仕様、セルインスタンス、セル測定、材料、テンプレート）は、この値に関係なく返されます。セル仕様は現在プロジェクトに属していますが、検索はそれによってフィルタリングされません。 |

### レスポンス形式

レスポンスには一致した `results`、元の `query`、およびクライアントがページネーション UI を描画できるよう、`total`、`limit`、`offset` のページネーションフィールドが含まれます:

```json theme={null}
{
  "query": "NMC622",
  "results": [ /* ... */ ],
  "total": 42,
  "limit": 25,
  "offset": 0
}
```

`total` は、検索対象となったエンティティ種別全体で取得された一致件数を反映します（`per_type` × 検索対象となったエンティティ種別数で上限が設定されます）。したがって `total` はデータベース内で実際に一致するレコードの総数ではなく、取得段階での上限値です。たとえばデフォルトの `per_type=5` で 14 種別を検索した場合、何千件一致しても `total` は 70 を超えません。大きな結果セットでは `total / limit` で正確なページ数を計算しないでください。

### ページネーションとフィルタリングの例

セルと材料の一致の 2 ページ目を取得し、種別ごとに最大 10 件返す例。ここでの `project_id` は、プロジェクトでフィルタリングされるタイプ（スタディ、パイプライン、最適化）のみを絞り込みます。セルと材料の結果は関係なく返されます:

```bash theme={null}
curl -G "https://api.ionworks.com/search" \
  -H "Authorization: Bearer $IONWORKS_API_KEY" \
  --data-urlencode "q=NMC622" \
  --data-urlencode "limit=20" \
  --data-urlencode "offset=20" \
  --data-urlencode "per_type=10" \
  --data-urlencode "entity_types=cell" \
  --data-urlencode "entity_types=material" \
  --data-urlencode "project_id=proj_01HXYZ..."
```

### 結果のフィールド

各結果には `entity_type`、`id`、`name`、および (プロジェクト配下のリソースの場合) `project_id` が含まれます。ネストされたリソースの結果には、含まれる親リソースを指す `parent_id` も含まれます。たとえば `cell_instance` の結果の `parent_id` は、それが属するセル仕様を指す ID であり、`channel` の結果の `parent_id` はその親サイクラーを指す ID です。`parent_id` を使って親リソースへ遷移したり、直接クエリしたりできます。

### サイクラーとチャネルの検索

クエリをハードウェアのみに絞り込むには、`entity_types=cycler` と `entity_types=channel` を指定します。どちらもプロジェクトスコープのため、`project_id` を指定すると 1 つのプロジェクトに結果を絞り込めます:

```bash theme={null}
curl -G "https://api.ionworks.com/search" \
  -H "Authorization: Bearer $IONWORKS_API_KEY" \
  --data-urlencode "q=maccor" \
  --data-urlencode "entity_types=cycler" \
  --data-urlencode "entity_types=channel"
```

各 `channel` の結果は、`parent_id` に親サイクラーの `cycler_id` を持ち、そこから直接サイクラーを取得できます。

<Tip>
  検索は、部分的な名前（例: セル化学、顧客名、プロトコルキーワード）は覚えているが、どのプロジェクトやスタディに含まれているかわからない場合に便利です。
</Tip>

<Note>
  検索はサーバー上で Postgres の全文インデックスを使用するため、組織にリソースが多く蓄積されてもクエリは高速に返されます。インデックスは自動的に維持されるため、設定は不要です。
</Note>