outputcsv

Writes field values of input records in CSV format to a specified file system path. Writes field names as a header in the first row, then writes each record's field values separated by commas.

Command properties

Property	Description
Command type	Transforming
Required permission	None
License usage	N/A
Parallel execution	Not supported
Distributed execution	Runs on Control Node (reducer)

Syntax

outputcsv [overwrite=BOOL] [append=BOOL] [encoding=STR] [bom=BOOL] [tab=BOOL] [partition=BOOL] [tmp=STR] [emptyfile=BOOL] [flush=INT{s|m|h|d}] FILE_PATH FIELD, ...

Options

overwrite=BOOL: When set to t, overwrites the destination file even if it already exists. If not set, the query fails if the file exists. Cannot be used together with the append option. (Default: f)
append=BOOL: When set to t, appends to the end of the destination file if it already exists. Cannot be used together with the overwrite option. (Default: f)
encoding=STR: Character encoding of the output file. (Default: utf-8)
bom=BOOL: When set to t, writes a UTF-8 byte order mark (BOM) at the beginning of the file. Use this option when Korean characters appear garbled when opening the CSV file in Microsoft Excel. (Default: f)
tab=BOOL: When set to t, uses a tab character as the delimiter instead of a comma. (Default: f)
partition=BOOL: When set to t, uses time-based macros in the file path to write to separate files by partition. The logtime macro (based on log time) and the now macro (based on current time) are available. (Default: f)
tmp=STR: Temporary file path. When set, writes to this temporary path during execution, then moves to the final file path when the query completes.
emptyfile=BOOL: When set to t, creates an empty file even if there are no input records. (Default: f)
flush=INT{s|m|h|d}: Interval at which the buffer is periodically flushed. For example, flush=10s flushes the buffer every 10 seconds.

Target

FILE_PATH: File system path where the CSV file is written. When used with partition=t, you can include time macros such as {logtime:yyyy}, {logtime:MM}, {logtime:dd}, {now:yyyy} in the path.
FIELD, ...: Names of fields to write to the CSV file. Separate multiple fields with commas (,).

Error codes

Parse errors

Error code	Message	Description
30200	Invalid outputcsv command query.	The command string ends with a comma.
30201	When the file path for the outputcsv command contains macros, the partition option is required.	The file path contains time macros but `partition=t` is not set.
30202	Enter the field names to export with the outputcsv command.	No output fields were specified.
30204	[encoding] is an unsupported encoding for the outputcsv command.	An unsupported encoding was specified.
30205	The overwrite and append options cannot be used simultaneously in the outputcsv command.	Both `overwrite=t` and `append=t` were specified.
30206	Access denied to the temporary file path [tmp_path] for the outputcsv command.	No access permission to the temporary file path.
30207	Access denied to the CSV file path [csv_path] for the outputcsv command.	No access permission to the CSV file path.

Runtime errors

Error code	Message	Description	Post-processing behavior
30203	An IO error occurred while running the outputcsv command: [msg].	An I/O error occurred while writing to the file.	Closes the file handle and cancels the query.
30207	Access denied to the CSV file path [csv_path] for the outputcsv command.	Cannot access the resolved file path in partition mode.	Cancels the query.

Description

The outputcsv command writes input records to a file in CSV format. Only the specified field values are written, and the first row includes the field names as a header. After writing, records are passed to the next command unchanged.

When partition=t is used, the time macro in the file path is resolved based on the _time field value (log time) of each record, and records are written to separate files by partition.

When the tmp option is used, records are written to the temporary file path during query execution, and the file is moved to the final path when the query completes normally. If the query is cancelled and the mode is not append, the temporary file or output file is deleted.

In a distributed environment, file writing is performed on the Control Node.

Examples

Write to a CSV file

json "[{'src_ip': '192.0.2.1', 'dst_ip': '198.51.100.1', 'bytes': 1024}, {'src_ip': '192.0.2.2', 'dst_ip': '203.0.113.5', 'bytes': 2048}]"
| outputcsv /opt/logpresso/output/result.csv src_ip, dst_ip, bytes

Writes the src_ip, dst_ip, and bytes fields to /opt/logpresso/output/result.csv in CSV format.

Overwrite an existing file

json "[{'name': 'Alice', 'score': 85}, {'name': 'Bob', 'score': 92}]"
| outputcsv overwrite=t /opt/logpresso/output/scores.csv name, score

Overwrites the destination file even if it already exists.

Add BOM and use tab delimiter

json "[{'name': 'Alice', 'score': 95}, {'name': 'Bob', 'score': 88}]"
| outputcsv bom=t tab=t /opt/logpresso/output/result.tsv name, score

Adds a BOM at the beginning of the file and uses a tab character as the delimiter.

Write to separate files by partition

table duration=1d web_logs
| outputcsv partition=t /opt/logpresso/output/{logtime:yyyy}/{logtime:MM}/{logtime:dd}/access.csv src_ip, method, status

Creates year/month/day directories based on log time and writes to separate CSV files by partition.

Append to an existing file

json "[{'host': 'web-01', 'cpu': 75.2}]"
| outputcsv append=t /opt/logpresso/output/metrics.csv host, cpu

Appends records to the end of an existing file.

Write using a temporary file
```
table duration=1h web_logs
| outputcsv tmp=/opt/logpresso/output/result.tmp /opt/logpresso/output/result.csv src_ip, dst_ip, bytes
```
Writes to a temporary file during query execution, then moves it to the final path when the query completes normally.