csv and delimited
Comma-separated and other delimited text: the csv format and delimited format, from the csv package. Declare the package once in dependencies.yml; DRE installs it on demand:
plugins: - csvcsv format: options
Section titled “csv format: options”Set in a report’s output: (or format_options.csv in dre_project.yml).
| Option | Type | Default | Notes |
|---|---|---|---|
delimiter |
char | , |
Separates fields. |
quote |
char | " |
Wraps quoted fields; doubled inside them. |
quoting |
string | minimal |
Which fields are quoted: only where needed, all, text columns, or none. One of minimal, all, strings, none. |
formula_guard |
boolean | true |
Prefix formula-leading text cells with an apostrophe. |
header |
boolean | true |
Write the column names first. |
line_ending |
string | "\r\n" |
Ends each line. One of "\n", "\r\n". |
encoding |
string | utf-8 |
Text encoding, e.g. utf-8, latin1, windows-1252. |
null |
string | "" |
Written for a null value. |
byte_order_mark |
boolean | false |
Start a UTF-8 file with a byte order mark. |
delimited format: options
Section titled “delimited format: options”Set in a report’s output: (or format_options.delimited in dre_project.yml).
| Option | Type | Default | Notes |
|---|---|---|---|
delimiter |
char | , |
Separates fields. |
quote |
char | " |
Wraps quoted fields; doubled inside them. |
quoting |
string | minimal |
Which fields are quoted: only where needed, all, text columns, or none. One of minimal, all, strings, none. |
formula_guard |
boolean | true |
Prefix formula-leading text cells with an apostrophe. |
header |
boolean | true |
Write the column names first. |
line_ending |
string | "\r\n" |
Ends each line. One of "\n", "\r\n". |
encoding |
string | utf-8 |
Text encoding, e.g. utf-8, latin1, windows-1252. |
null |
string | "" |
Written for a null value. |
byte_order_mark |
boolean | false |
Start a UTF-8 file with a byte order mark. |
Writing
Section titled “Writing”formula_guard defaults to true for both formats. A text cell starting with =, +, -,
@, tab or carriage return gets a leading apostrophe (') before CSV quoting and encoding.
This keeps spreadsheet applications from treating row values as formulas. Column headers are
protected too. Numbers, booleans, dates and other typed columns are unchanged, as are nulls.
Set formula_guard: false in the output or project format options when a downstream importer
needs the original text. This opt-out also allows spreadsheet formulas through.
-
quoting(csv, delimited) picks which fields are wrapped inquote:minimal(the default): only fields holding the delimiter, the quote or a line break;all: every field but nulls;strings: every value of a text, date, time or timestamp column, and the header; numbers, booleans and nulls stay bare unless they hold the delimiter;none: no field. A value that can’t be written without quotes fails the run, naming the row and column.
A doubled quote escapes a quote inside a quoted field. For tab- or pipe-separated text, use
delimitedwithdelimiter: "\t"and, say,extension: tsv. -
null: "NULL"(csv, delimited) writes that marker for nulls instead of an empty field. It can be written unquoted as above: DRE reads a YAMLnull:key as the optionnull.
Export for a downstream importer
Section titled “Export for a downstream importer”Use CSV for a standard table export, or delimited for a receiver requiring tabs, pipes or a
different extension. Starting with the tutorial project, replace its
report output with:
output: format: delimited extension: tsv delimiter: "\t" header: true quoting: minimal quote: '"' null: "NULL" encoding: utf-8 line_ending: "\n" byte_order_mark: falseDeclare csv in dependencies for either format. dre run <report> --preview 5 writes a sample
without delivery. Check the importer with a null, an embedded delimiter and a quoted value,
not only plain numbers. Use byte_order_mark: true when a receiver needs a UTF-8 BOM; use
encoding: windows-1252 only when every required character fits that encoding.
With quoting: none, the actual error is
row <row>, column <col>: the value contains the delimiter, quote or a line break, which quoting: none can't represent
(the message quotes the column and option with backticks). Restore minimal rather than
removing characters silently. An unsupported option yields invalid-output-option; move a
destination option out of the output map if it belongs to delivery.
See output keys, error codes,
and format and output.