> 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(쉼표로 구분된 값) 형식으로 포맷합니다. 이 블록은:
1. 다음에서 데이터 참조를 가져옵니다 `columns_data` 열 이름을 워크플로 데이터 소스(선택기, 정적 값 또는 워크플로 입력)에 매핑하는 딕셔너리
2. 선택적으로 다음을 사용해 데이터 변환 연산을 적용합니다 `columns_operations`, 이는 Query Language(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 보고서를 이메일 첨부 파일로 보내거나 메시지 본문에 포함할 수 있습니다
* **웹훅 블록** (예: 웹훅 싱크)와 연결하여 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, SequenceLength, SequenceMap, SortDetections, StringMatches, StringSubSequence, StringToLowerCase, StringToUpperCase, TimestampToISOFormat, ToBoolean, ToNumber, ToString]]]` | CSV 포맷팅 전에 열 데이터를 변환하기 위한 Query Language(UQL) 연산 정의를 열 이름별로 매핑하는 선택적 딕셔너리입니다. 키는 columns\_data에 정의된 열 이름과 일치해야 합니다. 값은 UQL 연산 목록(예: 탐지에서 클래스 이름을 추출하는 DetectionsPropertyExtract, 문자열 연산, 계산)으로, 원시 열 데이터를 변환합니다. 연산은 각 열의 데이터에 순서대로 적용됩니다. 열 이름이 이 딕셔너리에 없으면 데이터는 변환 없이 그대로 사용됩니다. 예: {'predictions': \[{'type': 'DetectionsPropertyExtract', 'property\_name': 'class\_name'}]} 는 탐지 예측에서 클래스 이름을 추출합니다.. | ❌ |
이 **참조** 열은 워크플로우 런타임에서 사용 가능한 동적 값으로 속성을 매개변수화할 수 있는 가능성을 나타냅니다 `워크플로우` 런타임입니다. 자세한 내용은 *바인딩* 을 참조하세요.
### 입력 및 출력 바인딩
사용 가능한 연결은 바인딩 유형에 따라 달라집니다. 어떤 바인딩 유형인지 확인하세요 `CSV 포맷터` 버전 `v1` 을 가지고 있는지.
입력 및 출력 바인딩
* 입력
* `columns_data` ([*`*`*](/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`](/workflows/ko/developer-guide/developer-guide/kinds/string.md)): 문자열 값.
예시 JSON 정의
```json
{
"name": "",
"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"
}
]
}
}
```