CSV Formatter¶

Convert workflow data into structured CSV format by defining custom columns, applying data transformations, and aggregating batch data into CSV documents with automatic timestamp tracking for logging, reporting, and data export workflows.

How This Block Works¶

This block formats workflow data into CSV (Comma-Separated Values) format by organizing data from multiple sources into structured columns. The block:

1. Takes data references from columns_data dictionary that maps column names to workflow data sources (selectors, static values, or workflow inputs)
2. Optionally applies data transformation operations using columns_operations, which uses the Query Language (UQL) to transform column data (e.g., extract properties from detections, perform calculations, format values)
3. Automatically adds a timestamp column with the current UTC time in ISO format (e.g., 2024-10-18T14:09:57.622297+00:00) to each row - note that "timestamp" is a reserved column name
4. Handles batch inputs by aggregating multiple data points into rows:
5. For single input (batch_size=1): Creates CSV with header row and one data row
6. For batch inputs (batch_size>1): Creates CSV with header row and one row per input, aggregating all rows into a single CSV document that is output only in the last batch element (earlier elements return empty CSV content)
7. Aligns batch parameters when multiple batch inputs are provided, broadcasting non-batch parameters to match the maximum batch size
8. Converts the structured data dictionary into CSV format using pandas DataFrame serialization
9. Returns csv_content as a string containing the complete CSV document (header and data rows)

The block supports flexible column definition where each column can reference different workflow data sources (detection predictions, classification results, workflow inputs, computed values, etc.) and optionally apply transformations to extract specific properties or format data. The automatic timestamp column enables temporal tracking of when each CSV row was generated, useful for logging and time-series data collection. Batch aggregation allows the block to collect data from multiple workflow executions and combine them into a single CSV document, which is particularly useful for batch processing workflows where you want to log multiple detections, images, or analysis results into one CSV file.

Common Use Cases¶

• Detection Logging and Reporting: Create CSV logs of detection results (e.g., log class names, confidence scores, bounding box coordinates from object detection models), enabling structured logging of inference results for analysis, debugging, or audit trails
• Time-Series Data Collection: Aggregate workflow metrics, counts, or analysis results over time into CSV format (e.g., log line counter counts, zone occupancy, detection frequencies), creating time-stamped datasets for trend analysis or reporting
• Batch Data Export: Collect and aggregate data from batch processing workflows into CSV files (e.g., export all detections from a batch of images, collect metrics from multiple workflow runs), enabling efficient bulk data export and reporting
• Structured Data Transformation: Extract and format specific properties from complex workflow outputs (e.g., extract class names from detections, convert nested data structures into flat CSV columns), enabling data transformation for downstream analysis or external systems
• Integration with External Systems: Format workflow data for compatibility with external tools (e.g., create CSV files for spreadsheet analysis, database import, or business intelligence tools), enabling seamless data export and integration workflows
• Data Aggregation and Analysis: Combine data from multiple workflow sources into structured CSV format (e.g., merge detection results with metadata, combine model outputs with reference data), enabling comprehensive data collection and analysis workflows

Connecting to Other Blocks¶

The CSV content from this block can be connected to:

• Detection or analysis blocks (e.g., Object Detection Model, Instance Segmentation Model, Classification Model, Keypoint Detection Model, Line Counter, Time in Zone) to format their outputs into CSV columns, enabling structured logging and export of inference results and analytics data
• Data storage blocks (e.g., Local File Sink) to save CSV files to disk, enabling persistent storage of formatted workflow data for later analysis or reporting
• Notification blocks (e.g., Email Notification, Slack Notification) to attach or include CSV content in notifications, enabling CSV reports to be sent as email attachments or included in message bodies
• Webhook blocks (e.g., Webhook Sink) to send CSV content to external APIs or services, enabling integration with external systems that consume CSV data
• Other formatter blocks (e.g., JSON Parser, Expression) to further process CSV content or convert it to other formats, enabling multi-stage data transformation workflows
• Batch processing workflows where multiple data points need to be aggregated into a single CSV document, allowing comprehensive logging and export of batch processing results

Type identifier¶

Use the following identifier in step "type" field: roboflow_core/csv_formatter@v1to add the block as as step in your workflow.

Properties¶

The Refs column marks possibility to parametrise the property with dynamic values available in workflow runtime. See Bindings for more info.

Available Connections¶

Input and Output Bindings¶

The available connections depend on its binding kinds. Check what binding kinds CSV Formatter in version v1 has.

{
    "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"
            }
        ]
    }
}