> For the complete documentation index, see [llms.txt](https://docs.roboflow.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.roboflow.com/datasets/ja/guan-li/manage-datasets/dataset-search.md).

# データセットを検索

## 概要

データセット検索を使うと、ファイル名検索、構造化フィルタ（タグ、split、クラス、寸法、アノテーション数）、ブール論理、自然言語のセマンティック検索を使って、プロジェクト全体から特定の画像を見つけられます。データの監査、ラベルの誤りや不足しているアノテーションの検出、レビューやエクスポート用の対象サブセット作成に利用できます。同じクエリは Web アプリと検索 REST API の両方で利用できます。

## Web アプリ

Roboflow では、ファイル名や検索クエリで画像ファイルを検索し、クエリとフィルタを組み合わせて特定の画像を見つけたり、データをより深く理解したりできます。

* **特定のタグを持つ split 内の画像:**\
  `tag:factory split:train`\
  これはタグフィルタと split フィルタを使用します
* **セマンティック検索とクラスフィルタを使って不足しているラベルを見つける**:\
  `person -class:helmet`\
  これはセマンティック検索と、クラスフィルタに対する反転フィルタを使用します
* **クラスを持つすべての画像に特定のフィルタを適用したい場合:**\
  `class:helmet AND NOT (tag:v1 OR tag:v2)`\
  これはクラスフィルタ、ブール論理、タグフィルタを使用します
* **アノテーション数の少ない横長の画像を見つける:**\
  `min-width:1000 max-annotations:1`\
  これは最小幅フィルタと最大アノテーション数フィルタを使用します

利用可能な一覧をすべて見る [検索フィルタ](#search-filters)、および以下の例も参照してください

{% hint style="info" %}
これらの検索フィルタとクエリはすべて組み合わせることができます
{% endhint %}

### セマンティック検索

画像を説明することで検索できます。これらのクエリは検索語に最も関連する画像を探し、オブジェクトがまだラベル付けされていない場合でも画像を見つけるのに役立ちます。

フィルタセレクタを使わずにテキストクエリを入力すると、セマンティック検索が実行されます（例: `filename:`)

<figure><img src="/files/a09b0265f6fdb3013b3e1a510fb9c0e4316c9ca0" alt=""><figcaption></figcaption></figure>

### ファイル名で検索

次を使ってファイル名を検索できます: `filename:` フィルタまたはファイル名のテキストボックス。クエリは自動で生成されます。

<figure><img src="/files/0d93a4cf0d882e2e243a0df08325e29f82398d9d" alt="" width="192"><figcaption></figcaption></figure>

### データセットの分割で検索

データセットの分割（train、valid、test）で画像を検索します

<figure><img src="/files/8a893fc8ea771a92a8f9cc69eec4b9c4accbb0c5" alt="" width="257"><figcaption></figcaption></figure>

画像を別の split に再割り当てするには、画像を選択するか、検索結果から「Select all matching」を選び、バルク操作メニューの「Change Dataset Split」をクリックします。大量の選択はバックグラウンドで処理されます。

### アップロード日で検索

Roboflow に最初にアップロードされた日付で画像を絞り込むには、次のものを使います: `date:` フィルタ。アップロード日は変更不可で、画像を編集、再アノテーション、分割間の移動をしても変わりません。

を使って `date:YYYY-MM-DD` で特定の日を指定するか、比較演算子を組み合わせて範囲を検索します:

`date>=2026-01-01 date<2026-02-01`

### 検索フィルタ

利用可能なフィルタは次のとおりです:

* `like-image:<IMAGE_ID>`：画像の内容に基づくセマンティック検索
* `tag` ：ユーザーが付けたタグで絞り込みます。
* `filename` ：指定したファイル名に一致するファイル名を検索します。部分一致を行うには、クエリの先頭と末尾に \* を付けます。
* `split` ：分割（train、test、valid）で絞り込みます。
* `job:<JOB_ID>` ：指定したジョブ ID を持つ画像を表示します。
* `min-width:X` ：X より大きい幅の画像を表示します。
* `max-width:X` ：X より小さい幅の画像を表示します。
* `min-height:X` ：X より大きい高さの画像を表示します。
* `max-height:X` ：X より小さい高さの画像を表示します。
* `min-annotations:X` ：指定した数より多くのアノテーションを持つ画像を絞り込みます。
* `max-annotations:X` ：指定した数より少ないアノテーションを持つ画像を表示します。
* `class:CLASS`：指定したラベルを少なくとも 1 件持つ画像を表示します。
* `date:YYYY-MM-DD` ：画像がアップロードされた変更不可の日付で絞り込みます。比較演算子に対応しています（例: `date>=2026-01-01 date<2026-02-01`).

#### ブール論理

AND、OR、NOT、かっこを使って複数のフィルタを組み合わせ、複雑なクエリを作成できます。

`class:helmet AND NOT (tag:v1 OR tag:v2)`

#### 反転フィルタ

フィルタの前にマイナス記号を付けると、そのフィルタに一致する画像を除外できます。

`class:helmet -class:vest`

#### 数値付きクラスフィルタ

画像内のラベル付けされた項目数で絞り込みます。

`class:helmet=3 class:vest>=4`

### API

Roboflow 上のデータセットや画像も次のものを使って検索できます: [検索 API](#http-api).

## HTTP API

Roboflow でホストされている画像は REST API を使って検索できます。エンドポイントは 2 つあります。1 つはプロジェクト単位の `/:workspace/:project/search` エンドポイント、もう 1 つはワークスペース全体の `/:workspace/search/v1` エンドポイントで、次の機能を反映しています: [Web アプリのデータセット検索](#web-app).

### プロジェクト内の画像を検索

Roboflow でホストされている画像を検索するには、次の API エンドポイントに POST リクエストを送信します:

```url
https://api.roboflow.com/:workspace/:project/search
```

API へのリクエスト例は次のとおりです:

```bash
curl -X POST "https://api.roboflow.com/my-workspace/my-project-name/search?api_key=$ROBOFLOW_API_KEY" \\
-H 'Content-Type: application/json' \\
--data \\
'{
    "like_image": "image_id",
    "in_dataset": true,
    "limit": 125
}'
```

このエンドポイントは、POST ボディに次の値を受け付けます:

```json
{
     // 指定した場合、結果をセマンティック類似度で並べ替えて返します
     "like_image": string,
     
     // 指定した場合、結果をセマンティック類似度で並べ替えて返します
     "prompt": string,
     
     // 既定値は 0
     "offset": int,
     
     // 既定値は 50（最大: 250）
     "limit": int,
     
     // 指定したタグを持つ画像で絞り込みます
     "tag": string,
     
     // 指定したクラス名を持つ画像で絞り込みます
     "class_name": string,
     
     // 指定したプロジェクト内の画像で絞り込みます
     "in_dataset": string,
     
     // 存在する場合は、いずれかのバッチに含まれる画像のみを返します
     "batch": boolean,
     
     // 存在する場合は、指定したバッチに含まれる画像のみを返します
     "batch_id": string,

     // 存在する場合は、いずれかのアノテーションジョブに含まれる画像のみを返します
     "annotation_job": boolean,

     // 存在する場合は、指定したアノテーションジョブに含まれる画像のみを返します
     "annotation_job_id": string,
     
     // 返すフィールドを指定します。既定値は ["id", "created"] です
     // 使用可能な値は ["id", "name", "annotations", "labels", "split", "tags", "owner", "url", "embedding", "created"] です
     "fields": string[]
}
```

検索 API は次の構造のレスポンスを返します。利用可能な値は、追加で指定した `fields` により異なります:

```json
{
    "offset": 0,
    "total": 292,
    "results": [
        {
            "id": "image123",
            "name": "humpbackwhale.jpg",
            "owner": "owner123",
            "url": "https://source.roboflow.com/owner123/image123/original.jpg",
            "annotations": {
                "count": 5,
                "classes": {
                    "whale": 1,
                    "fish": 4
                }
            },
            "labels": [],
            "tags": [
                "cam_x13"
            ]
        }
        // ... など
    ]
}
```

### ワークスペース全体で画像を検索

Workspace Image Search API を使うと、ワークスペース内の画像を一覧表示したり検索したりできます。

この API を使うと、検索文字列を使って絞り込み、並べ替え、セマンティック検索を実行できます。これは [Roboflow Web アプリケーションの画像検索機能に似ています](#web-app).

#### エンドポイント

API にリクエストを送るには、 `POST` リクエストを次のエンドポイントに送信します:

```
https://api.roboflow.com/{WORKSPACE}/search/v1?api_key=API_KEY
```

ここで `WORKSPACE` はワークスペース ID であり、 `API_KEY` は API キーです。

[ワークスペース ID の確認方法](https://docs.roboflow.com/reference/authentication/authentication/workspace-and-project-ids).

[API キーの確認方法](https://docs.roboflow.com/reference/platform/rest-api/authenticate-with-the-rest-api)

#### 認証

API にアクセスするには、リクエストに API キーを含める必要があります。API キーはクエリパラメータとして渡します。

例: `?api_key={YOUR_API_KEY}`

#### リクエスト形式

**ヘッダー**

* `Content-Type: application/json`

**ボディパラメータ**

* `query` **（必須）**：絞り込み、並べ替え、またはセマンティック検索を行うための空でない文字列です。例: `"nighttime project:{my-project-url}"` は次の `my-project-url` プロジェクト内の画像を絞り込み、 `nighttime`に一致する画像をセマンティックソートで並べ替えます。指定されていないか空の場合は 400 エラーを返します。
* `pageSize`：1 ページあたりに返す結果数（既定値: 50）。
* `fields`：レスポンスに含めるフィールドの一覧。指定可能な値は `"tags"`, `"width"`, `"height"`, `"filename"`, `"aspectRatio"`, `"split"`, `"projects"`, `"annotations"`, `"labels"`, `"owner"`, `"url"`.

**リクエスト例**

```bash
curl --location 'https://api.roboflow.com/{WORKSPACE}/search/v1?api_key={API_KEY}' \\
--header 'Content-Type: application/json' \\
--data '{
    "query": "project:foo nightime",
    "pageSize": 10,
    "fields": ["tags", "width", "height", "filename", "aspectRatio", "split"]
}'

```

#### レスポンス形式

レスポンスは、次のフィールドを含む JSON オブジェクトです:

* `results`：画像オブジェクトの配列。
* `total`：見つかった画像の総数。
* `continuationToken`：ページネーション用のトークン。

**画像オブジェクトのフィールド**

リクエストした `fields` パラメータによって異なります:

* `ID`：画像の一意識別子。
* `projectData`：プロジェクト URL をキーとするオブジェクトで、プロジェクト固有のデータを含みます:
  * `split`：データセットの分割（例: "test"）を示します。次の場合に返されます: `"split"` が `fields`.
  * `inDataset`：画像がデータセット内にあるかどうかを示すブール値。次の場合に返されます: `"projects"` が `fields`.
  * `annotations`：このプロジェクトにおける画像のアノテーションデータ。次を含みます: `annotationGroup`, `classes`、および `classCounts`。次の場合に返されます: `"annotations"` が `fields`.
  * `labels`：このプロジェクトにおける画像のラベルデータ。次の場合に返されます: `"labels"` が `fields`.
* `tags`：画像に関連付けられたタグの配列。
* `width`：画像のピクセル幅。
* `height`：画像のピクセル高。
* `filename`：画像ファイル名。
* `aspectRatio`：画像のアスペクト比。
* `owner`：画像の所有者 ID。
* `url`：元の画像ファイルへの直接 URL。

**ページネーションと `continuationToken`**

その `continuationToken` レスポンスで返されるトークンを使うと、検索結果に一致するページ間を移動できます。 `continuationToken` が後続のリクエストに含まれると、次の結果セットを取得します。

を使用するには、 `continuationToken`を次の API 呼び出しのリクエスト本文に含めてください。これにより、元のクエリに基づく次の結果ページを取得できます。

**エラーレスポンス**

* `400` - 次の場合に返されます: `query` が空、または `project:` フィルタが、あなたのワークスペースに属さないプロジェクトを参照している場合。
* `500` - 内部サーバーエラー。

**プロジェクトおよびデータセットのフィルタ**

次で利用できるすべてのフィルタに加えて [アプリ内のデータセット検索](#web-app)、ワークスペース全体の検索では次のフィルタもサポートされます: `project` と `dataset` 。たとえば、次のようなクエリを使用できます: `project:foo project:bar` で、両方のプロジェクトに含まれるすべての画像を見つけられます `foo` と `bar`。\n\n次のようなクエリ: `dataset:foo`はプロジェクト内の画像を返します `foo` で、ラベル付けされ、プロジェクト内のデータセットに追加されている画像です。

## Python SDK

`Project.search_all()` は、プロジェクト内の画像全体にわたる検索結果のページネーション対応イテレータを返します。検索モードは組み合わせ可能です。クラスで絞ったテキストプロンプト、単一バッチに絞り込んだ既存画像類似度検索などができます。

```python
import roboflow

rf = roboflow.Roboflow(api_key="YOUR_API_KEY")
project = rf.workspace().project("my-detector")

records = []
for page in project.search_all(
    prompt="mug on a desk",
    class_name="mug",
    in_dataset="my-detector",
    limit=100,
    fields=["id", "created", "name", "labels"],
):
    records.extend(page)

print(len(records))
```

### パラメータ

* `prompt` （str、任意）- 自然言語の検索プロンプト（CLIP 埋め込みによるセマンティック検索）。
* `like_image` （str、任意）- テキストではなく画像 ID による視覚的類似度検索。
* `tag` （str、任意）- このタグを持つ画像のみ。
* `class_name` （str、任意）- このクラスのアノテーションを持つ画像のみ。
* `in_dataset` （str、任意）- 画像が属している必要があるデータセット名（そのデータセット内の画像に限定し、バッチ / アノテーションジョブのステージング領域は除外します）。
* `batch` （bool、任意）と `batch_id` （str、任意）- 特定のアップロードバッチに限定します。
* `annotation_job` （bool、キーワード専用）と `annotation_job_id` （str、キーワード専用）- 特定のアノテーションジョブに限定します。
* `offset` （int、既定値 `0`）- ページネーションのオフセット。
* `limit` （int、既定値 `100`）- 1 ページのサイズ。
* `fields` （list\[str]、任意）- レスポンスサイズを減らすため、結果ごとに一覧されたフィールドのみを要求します。

`search_all()` はジェネレータです。各反復で最大 `limit` 件の結果を返し、offset を自動的に進めます。1 回限りの 1 ページ呼び出しには `project.search(...)` を同じ引数で使用します。

### ワークスペース全体の検索

ワークスペース内のすべてのプロジェクトを検索するには、 `Workspace.search()` / `Workspace.search_all()`を使用します。プロジェクトごとのメソッドとは異なり、これらは 1 つの RoboQL `query` 文字列（例 `"class:forklift"`, `"tag:review"`、またはセマンティック CLIP 検索用の自由文）に加えて、任意の `page_size` と `fields`。返された各ページは結果行のリストで、各行にはソースプロジェクトがある `プロジェクト` フィールド。

```python
records = []
for page in rf.workspace().search_all(query="class:forklift"):
    records.extend(page)
```

### 検索結果をダウンロード可能なデータセットとしてエクスポート

`Workspace.search_export()` 検索を実行し、結果をダウンロード可能なデータセット（COCO / YOLO / VOC など）としてパッケージ化します。参照先： [データのエクスポート（REST）](/datasets/ja/bjon/dataset-versions/exporting-data.md#http-api) 基盤となるエンドポイントについては

```python
path = rf.workspace().search_export(
    query="forklift",
    format="coco",
    location="./forklift-search",
)
print(path)
```

## CLI

ワークスペース全体の画像を検索するには [RoboQL](/datasets/ja/guan-li/manage-datasets/dataset-search.md) を使い、必要に応じて一致する結果をダウンロード可能なデータセットとしてエクスポートできます。

### 検索

```bash
roboflow search "<query>"
```

#### オプション

| フラグ        | 説明                 |
| ---------- | ------------------ |
| `--limit`  | 返す最大結果数（既定値: 50）   |
| `--cursor` | ページネーション用の継続トークン   |
| `--fields` | 含めるフィールドのカンマ区切りリスト |

#### 例

特定のタグを持つ画像を検索する:

```bash
roboflow search "tag:reviewed"
```

特定のクラスを含む画像を検索する:

```bash
roboflow search "class:person" --limit 100
```

### 検索結果をエクスポート

追加 `--export` 一致する画像をデータセットとしてダウンロードするには:

```bash
roboflow search "<query>" --export -f <format> -l <location>
```

#### エクスポートオプション

| フラグ                        | 説明                    |
| -------------------------- | --------------------- |
| `--export`                 | エクスポートモードを有効にする       |
| `-f`, `--format`           | アノテーション形式（既定値: coco）  |
| `-l`, `--location`         | エクスポートを保存するローカルディレクトリ |
| `-d`, `--dataset`          | 特定のプロジェクトに限定する        |
| `-g`, `--annotation-group` | 特定のアノテーショングループに限定する   |
| `--name`                   | エクスポートの任意の名前          |
| `--no-extract`             | zipファイルを保持し、展開をスキップする |

#### 例

確認済み画像をすべてCOCO形式でエクスポートする:

```bash
roboflow search "tag:reviewed" --export -f coco -l ./reviewed-export
```

特定のプロジェクトの画像をYOLOv8形式でエクスポートする:

```bash
roboflow search "class:car" --export -d my-project -f yolov8 -l ./cars
```

### JSON出力

```bash
roboflow search "tag:reviewed" --json
```

```json
{
  "results": [...],
  "total": 42,
  "cursor": "next-page-token"
}
```

次のものを使用してください: `カーソル` ページネーションに使用する値:

```bash
roboflow search "tag:reviewed" --cursor "next-page-token" --json
```