Local File Sink¶

Save workflow data as files on the local filesystem, supporting CSV, JSON, and text file formats with configurable output modes for aggregating multiple entries into single files or saving each entry separately, enabling persistent data storage, logging, and file-based data export.

How This Block Works¶

This block writes string content from workflow steps to files on the local filesystem. The block:

1. Takes string content (from formatters, predictions, or other string-producing blocks) and file configuration as input
2. Validates filesystem access permissions (checks if local storage access is allowed based on environment configuration)
3. Verifies write permissions for the target directory (checks against allowed write directory restrictions if configured)
4. Selects the appropriate file saving strategy based on output_mode:
5. Separate Files Mode: Creates a new file for each input, generating unique filenames with timestamps
6. Append Log Mode: Appends content to an existing file (or creates a new one if needed), aggregating multiple entries
7. For separate files mode: Generates a unique file path using the target directory, file name prefix, file type, and a timestamp, then writes the content to the new file
8. For append log mode:
9. Opens or creates a file based on the file name prefix and type
10. Applies format-specific handling for appending:
    • CSV: Removes the header row from subsequent appends (CSV content must include headers on first write)
    • JSON: Converts to JSONL (JSON Lines) format, parsing and re-serializing each JSON document to fit on a single line
    • TXT: Appends content directly with newlines
11. Tracks entry count and creates a new file when max_entries_per_file limit is reached
12. Creates parent directories if they don't exist
13. Writes content to the file (ensuring newline termination)
14. Returns error status and messages indicating save success or failure

The block supports two distinct storage strategies: separate files mode creates individual timestamped files for each input (useful for organizing outputs by execution), while append log mode aggregates multiple entries into continuous log files (useful for time-series data logging). The file path generation includes timestamps (format: YYYY_MM_DD_HH_MM_SS_microseconds) to ensure unique filenames and chronological organization. In append log mode, the block maintains file handles across executions and automatically handles file rotation when entry limits are reached.

Requirements¶

Local Filesystem Access: This block requires write access to the local filesystem. Filesystem access can be controlled via environment variables: - Set ALLOW_WORKFLOW_BLOCKS_ACCESSING_LOCAL_STORAGE=False to disable local file sink functionality (block will raise an error) - Set WORKFLOW_BLOCKS_WRITE_DIRECTORY to an absolute path to restrict writes to a specific directory and its subdirectories only

Note on Append Log Mode Format Handling: - For CSV files in append mode, the content must include header rows on the first write; headers are automatically removed from subsequent appends - For JSON files in append mode, files are saved with .jsonl extension in JSON Lines format (one JSON object per line)

Common Use Cases¶

• Data Logging and Audit Trails: Save workflow execution data, detection results, or metrics to local log files (e.g., append CSV logs of detections, JSON logs of workflow outputs), enabling persistent logging and audit trails for production workflows
• File-Based Data Export: Export formatted workflow data to files for external processing (e.g., save CSV exports from CSV Formatter, JSON exports for downstream tools), enabling integration with file-based data processing pipelines
• Time-Series Data Collection: Aggregate workflow metrics over time into continuous log files (e.g., append CSV rows with timestamps, log detection counts per frame), creating persistent time-series datasets for analysis and reporting
• Batch Result Storage: Save individual results from batch processing workflows to separate files (e.g., save each image's detection results to separate JSON files), enabling organized storage of batch processing outputs with unique filenames
• Data Archival: Archive workflow outputs and results to local storage (e.g., save formatted reports, export analysis results), enabling long-term data retention and backup workflows
• Integration with File-Based Systems: Store workflow data in file formats compatible with external tools (e.g., save CSV for spreadsheet analysis, JSONL for data processing pipelines), enabling seamless data exchange with file-based systems

Connecting to Other Blocks¶

This block receives string content from workflow steps and saves it to files:

• After formatter blocks (e.g., CSV Formatter) to save formatted data (CSV, JSON, or text) to files, enabling persistent storage of structured workflow outputs
• After detection or analysis blocks that output string-format data to save inference results, metrics, or analysis outputs to files for logging or archival
• After data processing blocks (e.g., Expression, Property Definition) that produce string outputs to save computed or transformed data to files
• In logging workflows to create persistent audit trails and logs of workflow executions, enabling record-keeping and debugging for production deployments
• In batch processing workflows where multiple data points need to be saved (either aggregated into log files or stored as separate files), enabling organized data collection and storage
• Before external processing where workflow data needs to be saved to files for consumption by external tools, scripts, or systems that read from filesystem storage

Type identifier¶

Use the following identifier in step "type" field: roboflow_core/local_file_sink@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 Local File Sink in version v1 has.

{
    "name": "<your_step_name_here>",
    "type": "roboflow_core/local_file_sink@v1",
    "content": "$steps.csv_formatter.csv_content",
    "file_type": "csv",
    "output_mode": "append_log",
    "target_directory": "some/location",
    "file_name_prefix": "my_file",
    "max_entries_per_file": 1024
}