> 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/ko/manage/manage-datasets/dataset-search.md).

# 데이터세트 검색

## 소개

데이터셋 검색을 사용하면 파일 이름 조회, 구조화된 필터(태그, 분할, 클래스, 차원, 어노테이션 수), 불리언 로직, 자연어 의미 검색을 통해 프로젝트 전반에서 특정 이미지를 찾을 수 있습니다. 이를 사용해 데이터를 감사하고, 잘못 레이블링되었거나 누락된 어노테이션을 찾아내며, 검토나 내보내기를 위한 대상 하위 집합을 구축할 수 있습니다. 동일한 쿼리는 웹 앱과 검색 REST API에서 모두 사용할 수 있습니다.

## 웹 앱

Roboflow에서는 파일 이름, 검색 쿼리로 이미지 파일을 검색할 수 있으며, 쿼리와 필터를 조합해 특정 이미지를 찾고 데이터를 더 잘 이해할 수 있습니다.

* **특정 태그가 있는 분할의 이미지:**\
  `tag:factory split:train`\
  이는 태그 필터와 분할 필터를 사용합니다
* **의미 검색과 클래스 필터를 사용하여 누락된 레이블 찾기**:\
  `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/4714c6c13d2890cdd2c7960fd616c87fc27ad4fb" alt=""><figcaption></figcaption></figure>

### 파일 이름으로 검색

다음 필터를 사용해 파일 이름을 검색할 수 있습니다 `filename:` 또는 파일 이름 텍스트 상자를 사용하면 쿼리가 자동으로 만들어집니다.

<figure><img src="/files/66251fddb2d2b6f92de21931d4985f48654c23f0" alt="" width="192"><figcaption></figcaption></figure>

### 데이터셋 분할로 검색

데이터셋 분할(train, valid, test)로 이미지를 검색합니다

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

이미지를 다른 분할로 다시 할당하려면, 이미지를 선택한 뒤(또는 검색 결과에서 "모두 선택"을 선택한 뒤) 대량 작업 메뉴에서 "데이터셋 분할 변경"을 클릭하세요. 큰 선택 항목은 백그라운드에서 처리됩니다.

### 업로드 날짜로 검색

다음을 사용하여 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

REST API를 사용하여 Roboflow에 호스팅된 이미지를 검색할 수 있습니다. 엔드포인트는 두 가지가 있습니다. 프로젝트 범위의 `/:workspace/:project/search` 엔드포인트와 워크스페이스 전체의 `/:workspace/search/v1` 엔드포인트가 있으며, 이는 다음을 그대로 반영합니다 [웹 앱 데이터셋 검색](#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는 다음 구조의 응답을 반환합니다. 사용 가능한 값은 추가로 지정한 `필드` 에 따라 달라집니다:

```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-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`: 페이지당 반환할 결과 수(기본값: 50).
* `필드`: 응답에 포함할 필드 목록입니다. 가능한 값은 `"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`: 페이지네이션용 토큰.

**이미지 객체 필드**

다음에 요청한 필드에 따라 `필드` 매개변수:

* `id`: 이미지의 고유 식별자.
* `projectData`: 프로젝트 URL을 키로 하는 객체로, 프로젝트별 데이터를 포함합니다:
  * `split`: 데이터셋 분할을 나타냅니다(예: "test"). 다음일 때 반환됩니다 `"split"` 가 `필드`.
  * `inDataset`: 이미지가 데이터셋에 있는지 여부를 나타내는 불리언 값입니다. 다음일 때 반환됩니다 `"projects"` 가 `필드`.
  * `annotations`: 이 프로젝트의 이미지에 대한 어노테이션 데이터입니다. 여기에는 `annotationGroup`, `classes`및 `classCounts`. 다음일 때 반환됩니다 `"annotations"` 가 `필드`.
  * `labels`: 이 프로젝트의 이미지에 대한 레이블 데이터입니다. 다음일 때 반환됩니다 `"labels"` 가 `필드`.
* `tags`: 이미지와 연결된 태그 배열.
* `width`: 이미지의 픽셀 너비.
* `height`: 이미지의 픽셀 높이.
* `filename`: 이미지 파일 이름.
* `aspectRatio`: 이미지의 종횡비.
* `owner`: 이미지의 소유자 식별자.
* `url`: 원본 이미지 파일로의 직접 URL.

**페이지네이션 및 `continuationToken`**

해당 `continuationToken` 응답에 반환된 는 검색 결과와 일치하는 페이지 사이를 이동할 수 있게 해줍니다. 다음 요청에 `continuationToken` 가 포함되면 다음 결과 집합을 가져옵니다.

사용하려면 `continuationToken`를 다음 API 호출의 요청 본문에 포함하세요. 이렇게 하면 원래 쿼리를 기반으로 다음 결과 페이지를 가져옵니다.

**오류 응답**

* `400` - 다음일 때 반환됩니다 `query` 가 누락되었거나 비어 있거나, 또는 `project:` 필터가 워크스페이스에 속하지 않는 프로젝트를 참조하는 경우.
* `500` - 내부 서버 오류.

**프로젝트 및 데이터셋 필터**

다음에서 사용 가능한 모든 필터 외에도 [앱 내 데이터셋 검색](#web-app), 워크스페이스 전체 검색은 다음에 대한 필터도 지원합니다 `프로젝트` 및 `데이터셋` . 예를 들어 다음과 같은 쿼리를 사용할 수 있습니다 `project:foo project:bar` 두 프로젝트 모두에 있는 모든 이미지를 찾기 위해 `foo` 및 `bar`.\
\
다음과 같은 쿼리는 `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, optional) - 자연어 검색 프롬프트(CLIP 임베딩을 통한 의미 검색).
* `like_image` (str, optional) - 텍스트 대신 시각적 유사도로 검색할 이미지 ID.
* `tag` (str, optional) - 이 태그가 있는 이미지만.
* `class_name` (str, optional) - 이 클래스의 어노테이션이 있는 이미지만.
* `in_dataset` (str, optional) - 이미지가 속해야 하는 데이터셋의 이름(해당 데이터셋의 이미지로 제한되며, 배치/어노테이션 작업 스테이징 영역은 제외).
* `batch` (bool, optional) 및 `batch_id` (str, optional) - 특정 업로드 배치로 제한합니다.
* `annotation_job` (bool, 키워드 전용) 및 `annotation_job_id` (str, 키워드 전용) - 특정 어노테이션 작업으로 제한합니다.
* `offset` (int, 기본값 `0`) - 페이지네이션 오프셋.
* `limit` (int, 기본값 `100`) - 페이지 크기.
* `필드` (list\[str], optional) - 응답 크기를 줄이기 위해 결과당 나열된 필드만 요청합니다.

`search_all()` 는 제너레이터입니다. 각 반복은 최대 `limit` 개의 결과가 있는 한 페이지를 반환하고, offset을 자동으로 증가시킵니다. 한 번만 실행하는 단일 페이지 호출의 경우 `project.search(...)` 를 동일한 인자로 사용하세요.

### 워크스페이스 전체 검색

워크스페이스의 모든 프로젝트를 대상으로 검색하려면 `Workspace.search()` / `Workspace.search_all()`를 사용하세요. 프로젝트별 메서드와 달리, 이들은 단일 RoboQL `query` 문자열(예: `"class:forklift"`, `"tag:review"`또는 의미 CLIP 검색을 위한 자유 텍스트)과 선택적 `page_size` 및 `필드`. 각 반환된 페이지는 결과 행의 목록이며, 행에는 소스 프로젝트가 하나의 `프로젝트` 필드 아래에 포함됩니다.

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

### 검색 결과를 다운로드 가능한 데이터셋으로 내보내기

`Workspace.search_export()` 검색을 실행하고 결과를 다운로드 가능한 데이터셋(COCO / YOLO / VOC 등)으로 패키징합니다. 자세한 내용은 [데이터 내보내기(REST)](/datasets/ko/versions/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/ko/manage/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
```