データセットを検索する

テキストベースの検索クエリとフィルターを使って、Roboflow のデータセットをよりよく理解します。

概要

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

Web アプリ

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

• 特定のタグを持つ分割内の画像: tag:factory split:train これはタグフィルターと分割フィルターを使っています

• セマンティック検索とクラスフィルターを使って、欠落ラベルを見つける: person -class:helmet これはセマンティック検索とクラスフィルターに対する反転フィルターを使っています

• 特定のクラスを持つすべての画像に特定のフィルターが必要な場合: class:helmet AND NOT (tag:v1 OR tag:v2) これはクラスフィルター、ブール論理、タグフィルターを使っています

• アノテーション数の少ない幅の広い画像を見つける: min-width:1000 max-annotations:1 これは最小幅フィルターと最大アノテーション数フィルターを使っています

利用可能な 検索フィルターの全一覧を確認し、以下の例も参照してください

これらの検索フィルターとクエリはすべて組み合わせて使えます

セマンティック検索

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

セマンティック検索は、フィルター選択子を付けずにテキストクエリを入力したときに発生します（例: filename:)

ファイル名で検索

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

データセット分割で検索

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

画像を別の分割に再割り当てするには、画像を選択するか（または検索結果から「一致するものをすべて選択」を選び）、一括操作メニューの「データセット分割を変更」をクリックします。大きな選択はバックグラウンドで処理されます。

アップロード日時で検索

最初に Roboflow にアップロードされた日付を使って、以下の date: フィルターで画像を絞り込みます。アップロード日時は固定であり、画像の編集、再アノテーション、分割間の移動を行っても変更されません。

使用します date:YYYY-MM-DD 正確な 1 日を指定するか、比較演算子を組み合わせて範囲検索できます:

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 上のデータセットや画像は、 Search API.

HTTP API

REST API を使って、Roboflow にホストされた画像を検索できます。エンドポイントは 2 つあります。プロジェクト単位の /:workspace/:project/search エンドポイントと、ワークスペース全体の /:workspace/search/v1 エンドポイントです。こちらは Web アプリのデータセット検索.

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

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

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

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

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 本文に次の値を受け付けます:

{
     // 指定した場合、セマンティック類似度でソートされた結果を返します
     "like_image": string,
     
     // 指定した場合、セマンティック類似度でソートされた結果を返します
     "prompt": string,
     
     // デフォルトは 0
     "offset": int,
     
     // デフォルトは 50（最大: 250）
     "limit": int,
     
     // 指定したタグを持つ画像をフィルタリングします
     "tag": string,
     
     // 指定したクラス名を持つ画像をフィルタリングします
     "class_name": string,
     
     // true の場合、URL のプロジェクト内にある画像をフィルタリングします
     "in_dataset": boolean,
     
     // 指定した場合、任意のバッチに含まれる画像のみを返します
     "batch": boolean,
     
     // 指定した場合、指定したバッチに含まれる画像のみを返します
     "batch_id": string,

     // 指定した場合、任意のアノテーションジョブに含まれる画像のみを返します
     "annotation_job": boolean,

     // 指定した場合、指定したアノテーションジョブに含まれる画像のみを返します
     "annotation_job_id": string,

     // 返すメディア: "image"、"video"、または両方。デフォルトは ["image"]
     "mediaTypes": string[],
     
     // 返すフィールドを指定します。デフォルトは ["id", "created"]
     // 使用可能な値は ["id", "name", "annotations", "labels", "split", "tags", "owner", "url", "embedding", "created"]
     "fields": string[]
}

各結果には mediaType があり、値は image または videoです。 urlを要求すると、動画の結果ではポスター画像が url に、短時間のみ有効なダウンロードリンクが videoUrl.

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

{
    "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 画像検索 API を使うと、ワークスペース内の画像を一覧表示・検索できます。

この API では、Roboflow Web アプリケーションの画像検索機能に似たクエリ文字列を使って、フィルタリング、並べ替え、セマンティック検索を行えます Roboflow Web アプリケーションの画像検索機能.

エンドポイント

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

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

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

ワークスペース ID の見つけ方を学ぶ.

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".

• mediaTypes：返すメディア: "image", "video"、または両方（デフォルト: ["image"]）。結果には mediaType と videoUrl が プロジェクト検索.

リクエスト例

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 パラメータに 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 - サーバー内部エラー。

プロジェクトとデータセットのフィルター

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

Python SDK

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

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=True,
    limit=100,
    fields=["id", "created", "name", "labels"],
):
    records.extend(page)

print(len(records))

パラメータ

• prompt （str、任意）- 自然言語の検索プロンプト（CLIP 埋め込みによるセマンティック検索）。

• like_image (str, optional) - テキストではなく視覚的類似性で検索する画像 ID。

• tag (str, optional) - このタグを持つ画像のみ。

• class_name (str, optional) - このクラスのアノテーションがある画像のみ。

• in_dataset (bool, optional) - 結果をプロジェクトのデータセット内の画像に限定するかどうか。batch / annotation-job のステージング領域は除外します。

• batch (bool, optional) および batch_id (str, optional) - 特定のアップロードバッチに限定します。

• annotation_job (bool, kw-only) および annotation_job_id (str, kw-only) - 特定のアノテーションジョブに限定します。

• offset (int, デフォルト 0) - ページネーションのオフセット。

• limit (int, デフォルト 100) - ページサイズ。

• fields (list[str], optional) - レスポンスサイズを減らすため、各結果についてリストされたフィールドのみを要求します。

search_all() はジェネレーターです。各反復で最大 limit 件の結果を返し、オフセットを自動的に進めます。1回だけの単一ページ呼び出しには、次を使用します。 project.search(...) 同じ引数で。

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

ワークスペース内のすべてのプロジェクトを検索するには、次を使用します。 Workspace.search() / Workspace.search_all()。個々のプロジェクト向けメソッドとは異なり、これらは単一の RoboQL query 文字列（例: "class:forklift", "tag:review"、またはセマンティックな CLIP 検索用の自由テキスト）に加えて、オプションの page_size と fieldsを取ります。各ページには結果行のリストが含まれ、行には元のプロジェクトが projects フィールドとして含まれます。

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

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

Workspace.search_export() は検索を実行し、結果をダウンロード可能なデータセット（COCO / YOLO / VOC など）としてパッケージ化します。詳細は Export Data (REST) の基盤となるエンドポイントについては

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

CLI

ワークスペース全体の画像を次を使って検索できます: RoboQL また、必要に応じて一致する結果をダウンロード可能なデータセットとしてエクスポートできます。

検索

roboflow search "<query>"

オプション

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

例

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

roboflow search "tag:reviewed"

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

roboflow search "class:person" --limit 100

検索結果をエクスポート

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

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

エクスポートオプション

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

例

レビュー済みのすべての画像を COCO 形式でエクスポート:

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

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

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

JSON 出力

roboflow search "tag:reviewed" --json

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

次の cursor 値をページネーションに使用します:

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

MCP サーバー

AI エージェントを次に接続すると MCP サーバー すると、これらのツールで画像を見つけられます:

ツール	説明
images_search	プロジェクト内の画像を検索します。
images_workspace_search	RoboQL を使用してワークスペース全体の画像を検索します。