> 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/workflows/ko/blocks/blocks/data-storage/csv-formatter.md).

# CSV 포맷터

지정된 열로 CSV 파일을 만듭니다.

사용자 지정 열을 정의하고, 데이터 변환을 적용하고, 배치 데이터를 CSV 문서로 집계하여 자동 타임스탬프 추적으로 로깅, 보고, 데이터 내보내기 워크플로를 위한 구조화된 CSV 형식으로 워크플로 데이터를 변환합니다.

## 이 블록의 작동 방식

이 블록은 여러 소스의 데이터를 구조화된 열로 정리하여 워크플로 데이터를 CSV(쉼표로 구분된 값) 형식으로 포맷합니다. 이 블록은:

1. 다음에서 데이터 참조를 가져옵니다 `columns_data` 열 이름을 워크플로 데이터 소스(셀렉터, 정적 값 또는 워크플로 입력)에 매핑하는 딕셔너리
2. 선택적으로 다음을 사용하여 데이터 변환 작업을 적용합니다 `columns_operations`, 이는 쿼리 언어(UQL)를 사용하여 열 데이터를 변환합니다(예: 탐지에서 속성 추출, 계산 수행, 값 형식 지정)
3. 자동으로 `타임스탬프` 열을 현재 UTC 시간과 ISO 형식으로 추가합니다(예: `2024-10-18T14:09:57.622297+00:00`)를 각 행에 추가합니다. 참고로 "timestamp"는 예약된 열 이름입니다
4. 배치 입력을 여러 데이터 포인트를 행으로 집계하여 처리합니다:
   * 단일 입력의 경우(`batch_size=1`): 헤더 행과 하나의 데이터 행이 있는 CSV를 생성합니다
   * 배치 입력의 경우(`batch_size>1`): 헤더 행과 입력당 하나의 행이 있는 CSV를 생성하며, 모든 행을 하나의 CSV 문서로 집계하여 마지막 배치 요소에서만 출력합니다(이전 요소는 빈 CSV 콘텐츠를 반환합니다)
5. 여러 배치 입력이 제공되면 배치 파라미터를 정렬하고, 배치가 아닌 파라미터를 최대 배치 크기에 맞게 브로드캐스트합니다
6. 구조화된 데이터 딕셔너리를 pandas DataFrame 직렬화를 사용하여 CSV 형식으로 변환합니다
7. 반환값 `csv_content` 완전한 CSV 문서(헤더 및 데이터 행)를 포함하는 문자열로서

이 블록의 유연한 열 정의를 사용하면 각 열이 서로 다른 워크플로 데이터 소스(탐지 예측, 분류 결과, 워크플로 입력, 계산된 값 등)를 참조하고 필요에 따라 변환을 적용하여 특정 속성을 추출하거나 데이터를 형식화할 수 있습니다. 자동 타임스탬프 열은 각 CSV 행이 생성된 시점을 시간적으로 추적할 수 있게 해 주며, 로깅 및 시계열 데이터 수집에 유용합니다. 배치 집계를 통해 이 블록은 여러 워크플로 실행의 데이터를 수집하여 하나의 CSV 문서로 결합할 수 있으며, 이는 여러 탐지, 이미지 또는 분석 결과를 하나의 CSV 파일에 기록하려는 배치 처리 워크플로에서 특히 유용합니다.

## 일반적인 사용 사례

* **탐지 로깅 및 보고**: 탐지 결과의 CSV 로그를 생성합니다(예: 객체 탐지 모델의 클래스 이름, 신뢰도 점수, 바운딩 박스 좌표를 기록), 이를 통해 분석, 디버깅 또는 감사 추적을 위한 추론 결과의 구조화된 로깅을 가능하게 합니다
* **시계열 데이터 수집**: 워크플로 메트릭, 카운트 또는 분석 결과를 시간에 따라 CSV 형식으로 집계합니다(예: 라인 카운터 수, 구역 점유율, 탐지 빈도 기록), 추세 분석 또는 보고를 위한 타임스탬프가 있는 데이터셋을 생성합니다
* **배치 데이터 내보내기**: 배치 처리 워크플로의 데이터를 CSV 파일로 수집 및 집계합니다(예: 이미지 배치의 모든 탐지를 내보내기, 여러 워크플로 실행에서 메트릭 수집), 효율적인 대량 데이터 내보내기 및 보고를 가능하게 합니다
* **구조화된 데이터 변환**: 복잡한 워크플로 출력에서 특정 속성을 추출하고 형식화합니다(예: 탐지에서 클래스 이름 추출, 중첩된 데이터 구조를 평면 CSV 열로 변환), 다운스트림 분석 또는 외부 시스템을 위한 데이터 변환을 가능하게 합니다
* **외부 시스템과의 통합**: 외부 도구와의 호환성을 위해 워크플로 데이터를 포맷합니다(예: 스프레드시트 분석, 데이터베이스 가져오기 또는 비즈니스 인텔리전스 도구용 CSV 파일 생성), 원활한 데이터 내보내기 및 통합 워크플로를 가능하게 합니다
* **데이터 집계 및 분석**: 여러 워크플로 소스의 데이터를 구조화된 CSV 형식으로 결합합니다(예: 탐지 결과와 메타데이터 병합, 모델 출력과 참조 데이터 결합), 포괄적인 데이터 수집 및 분석 워크플로를 가능하게 합니다

## 다른 블록과 연결하기

이 블록의 CSV 콘텐츠는 다음에 연결할 수 있습니다:

* **탐지 또는 분석 블록** (예: 객체 탐지 모델, 인스턴스 세분화 모델, 분류 모델, 키포인트 탐지 모델, 라인 카운터, 구역 체류 시간)에서 출력을 CSV 열로 포맷하여 추론 결과와 분석 데이터의 구조화된 로깅 및 내보내기를 가능하게 합니다
* **데이터 저장 블록** (예: 로컬 파일 싱크) CSV 파일을 디스크에 저장하여 이후 분석이나 보고를 위해 포맷된 워크플로 데이터를 영구 저장할 수 있게 합니다
* **알림 블록** (예: 이메일 알림, Slack 알림) 알림에 CSV 콘텐츠를 첨부하거나 포함하여 CSV 보고서를 이메일 첨부 파일로 보내거나 메시지 본문에 포함할 수 있게 합니다
* **웹훅 블록** (예: Webhook Sink) CSV 콘텐츠를 외부 API나 서비스로 전송하여 CSV 데이터를 소비하는 외부 시스템과의 통합을 가능하게 합니다
* **기타 포맷터 블록** (예: JSON 파서, Expression) CSV 콘텐츠를 추가로 처리하거나 다른 형식으로 변환하여 다단계 데이터 변환 워크플로를 가능하게 합니다
* **배치 처리 워크플로** 여러 데이터 포인트를 하나의 CSV 문서로 집계해야 하는 경우, 배치 처리 결과의 포괄적인 로깅 및 내보내기를 가능하게 합니다

### 유형 식별자

다음 식별자를 단계의 `"type"` 필드에 사용하세요: `roboflow_core/csv_formatter@v1` 를 워크플로우의 단계로 추가하려면.

### 속성

| **이름**               | **유형**                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | **설명**                                                                                                                                                                                                                                                                                                                                                                                                                                   | 참조 |
| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -- |
| `name`               | `str`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | 이 단계에 대한 고유 식별자를 입력하세요..                                                                                                                                                                                                                                                                                                                                                                                                                 | ❌  |
| `columns_data`       | `Dict[str, Union[bool, float, int, str]]`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | CSV 열을 구성하기 위해 열 이름을 데이터 소스에 매핑하는 딕셔너리입니다. 키는 열 이름입니다(참고: 'timestamp'는 예약되어 있으며 사용할 수 없습니다). 값은 워크플로 데이터(예: '$steps.model.predictions', '$inputs.data')를 참조하는 셀렉터, 정적 값(문자열, 숫자, 불리언) 또는 이들의 조합일 수 있습니다. 각 키-값 쌍은 하나의 CSV 열을 만듭니다. 배치 입력을 지원합니다 - 값이 배치인 경우 CSV는 모든 배치 요소를 행으로 집계합니다. 예: {'predictions': '$steps.object\_detection.predictions', 'count': '$steps.line\_counter.count\_in'}는 'predictions'와 'count'라는 이름의 CSV 열을 생성합니다.. | ✅  |
| `columns_operations` | `Dict[str, List[Union[ClassificationPropertyExtract, ConvertDictionaryToJSON, ConvertImageToBase64, ConvertImageToJPEG, DetectionsFilter, DetectionsOffset, DetectionsPropertyExtract, DetectionsRename, DetectionsSelection, DetectionsShift, DetectionsToDictionary, Divide, ExtractDetectionProperty, ExtractFrameMetadata, ExtractImageProperty, LookupTable, Multiply, NumberRound, NumericSequenceAggregate, PickDetectionsByParentClass, RandomNumber, SequenceAggregate, SequenceApply, SequenceElementsCount, SequenceJoin, SequenceLength, SequenceMap, SortDetections, StringMatches, StringSubSequence, StringToLowerCase, StringToUpperCase, TimestampToISOFormat, ToBoolean, ToNumber, ToString]]]` | CSV 형식 지정 전에 열 데이터를 변환하기 위한 쿼리 언어(UQL) 작업 정의를 열 이름별로 매핑하는 선택적 딕셔너리입니다. 키는 columns\_data에 정의된 열 이름과 일치해야 합니다. 값은 열의 원시 데이터를 변환하는 UQL 작업 목록입니다(예: 탐지에서 클래스 이름을 추출하는 DetectionsPropertyExtract, 문자열 작업, 계산). 작업은 각 열의 데이터에 순서대로 적용됩니다. 열 이름이 이 딕셔너리에 없으면 데이터는 변환 없이 그대로 사용됩니다. 예: {'predictions': \[{'type': 'DetectionsPropertyExtract', 'property\_name': 'class\_name'}]}는 탐지 예측에서 클래스 이름을 추출합니다..                                       | ❌  |

이 **참조** 열은 속성을 워크플로우 런타임에서 사용 가능한 동적 값으로 매개변수화할 수 있음을 나타냅니다. `워크플로우` 런타임입니다. 자세한 내용은 *바인딩* 을 참조하세요.

### 입력 및 출력 바인딩

사용 가능한 연결은 바인딩 종류에 따라 달라집니다. OpenAI가 `CSV 포맷터` 버전에서 `v1` 지원하는지 확인하세요.

<details>

<summary>입력 및 출력 바인딩</summary>

* input
  * `columns_data` ([*`*`*](https://docs.roboflow.com/workflows/ko/developer-guide/developer-guide/kinds/wildcard.md)): CSV 열을 구성하기 위해 열 이름을 데이터 소스에 매핑하는 딕셔너리입니다. 키는 열 이름입니다(참고: 'timestamp'는 예약되어 있으며 사용할 수 없습니다). 값은 워크플로 데이터(예: '$steps.model.predictions', '$inputs.data')를 참조하는 셀렉터, 정적 값(문자열, 숫자, 불리언) 또는 이들의 조합일 수 있습니다. 각 키-값 쌍은 하나의 CSV 열을 만듭니다. 배치 입력을 지원합니다 - 값이 배치인 경우 CSV는 모든 배치 요소를 행으로 집계합니다. 예: {'predictions': '$steps.object\_detection.predictions', 'count': '$steps.line\_counter.count\_in'}는 'predictions'와 'count'라는 이름의 CSV 열을 생성합니다..
* 출력
  * `csv_content` ([`string`](https://docs.roboflow.com/workflows/ko/developer-guide/developer-guide/kinds/string.md)): 문자열 값입니다.

</details>

<details>

<summary>예시 JSON 정의</summary>

```json
{
	    "name": "<your_step_name_here>",
	    "type": "roboflow_core/csv_formatter@v1",
	    "columns_data": {
	        "predictions": "$steps.model.predictions",
	        "reference": "$inputs.reference_class_names"
	    },
	    "columns_operations": {
	        "predictions": [
	            {
	                "property_name": "class_name",
	                "type": "DetectionsPropertyExtract"
	            }
	        ]
	    }
	}
```

</details>
