outputtxt

Writes field values of input records as a text file to a specified file system path. Connects each record's field values with a delimiter and writes them one line at a time.

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

outputtxt [overwrite=BOOL] [append=BOOL] [encoding=STR] [delimiter=STR] [gz=BOOL] [partition=BOOL] [tmp=STR] [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)
delimiter=STR: Delimiter to insert between field values. (Default: space character)
gz=BOOL: When set to t, compresses the output file in gzip format. (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.
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 text 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 text file. Separate multiple fields with commas (,).

Error codes

Parse errors

Error code	Message	Description
30400	Invalid outputtxt command query.	The command string ends with a comma.
30401	When the file path for the outputtxt command contains macros, the partition option is required.	The file path contains time macros but `partition=t` is not set.
30402	Enter the field names to export with the outputtxt command.	No output fields were specified.
30403	The temporary file [temp] for the outputtxt command already exists.	The temporary file already exists.
30404	Enter the output file name and field values for the outputtxt command.	No file path after parsing options.
30405	Enter the output file name and field values for the outputtxt command.	No file path token found.
30407	The overwrite and append options cannot be used simultaneously in the outputtxt command.	Both `overwrite=t` and `append=t` were specified.
30408	Access denied to the temporary file path [tmp_path] for the outputtxt command.	No access permission to the temporary file path.
30409	Access denied to the file path [file_path] for the outputtxt command.	No access permission to the text file path.

Runtime errors

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

Description

The outputtxt command writes field values of input records connected by a delimiter to a text file. Each record's field values are joined by the specified delimiter (default: space) and written as a single line. Unlike CSV, there is no header row, and field values are not quoted. After writing, records are passed to the next command unchanged.

When gz=t is used, the output file is compressed in gzip format.

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 text 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}]"
| outputtxt /opt/logpresso/output/result.txt src_ip, dst_ip, bytes

Writes the src_ip, dst_ip, and bytes fields to /opt/logpresso/output/result.txt, separated by spaces.

Write with a custom delimiter

json "[{'src_ip': '192.0.2.1', 'dst_ip': '198.51.100.1'}, {'src_ip': '192.0.2.2', 'dst_ip': '203.0.113.5'}]"
| outputtxt delimiter="|" /opt/logpresso/output/result.txt src_ip, dst_ip

Writes field values separated by the pipe (|) character.

Write as a gzip-compressed file

table duration=1d web_logs
| outputtxt gz=t /opt/logpresso/output/access.txt.gz src_ip, method, uri, status

Compresses the output file in gzip format.

Overwrite an existing file

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

Overwrites the destination file even if it already exists.

Write to separate files by partition

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

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

Append to an existing file

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

Appends records to the end of an existing file.