jq · lesson 23 of 32 · Tables & lookups
Quoting & escaping
Values with commas, quotes or line breaks need care. @csv puts every string in double quotes and doubles any quote inside it; @tsv quotes nothing and writes tabs, line breaks and backslashes as escapes instead.
Examples
Example 1CSV: quotes around strings, doubled quotes inside
Document
[
{ "name": "Smith, Jo", "note": "said \"hi\"" },
{ "name": "Ada", "note": "two\nlines" },
{ "name": "Tab\tman", "note": "C:\\temp" }
]Query
.[] | [.name, .note] | @csv
.[]Each record in turn.[.name, .note]Two cells per row.@csvStrings go in double quotes, and the"insaid "hi"becomes"". A comma or a line break inside the quotes stays as it is: it can't be taken for the end of the cell.
Result
"Smith, Jo","said ""hi""" "Ada","two lines" "Tab man","C:\temp"
Example 2TSV: no quotes, escapes instead
Document
[
{ "name": "Smith, Jo", "note": "said \"hi\"" },
{ "name": "Ada", "note": "two\nlines" },
{ "name": "Tab\tman", "note": "C:\\temp" }
]Query
.[] | [.name, .note] | @tsv
.[]Each record in turn.[.name, .note]The same two cells.@tsvCells are joined with tabs and never quoted. A tab inside a value is written\t, a line break\nand a backslash\\, so a record always stays on one line.
Result
Smith, Jo said "hi" Ada two\nlines Tab\tman C:\\temp
Example 3Only an array makes a row
Document
[
{ "name": "Smith, Jo", "note": "said \"hi\"" },
{ "name": "Ada", "note": "two\nlines" },
{ "name": "Tab\tman", "note": "C:\\temp" }
]Query
try (.[0] | @csv) catch .
try (Run what is inside the parentheses; if it fails….[0] | @csv…as it does here, because the first record is an object and@csvwants an array…catch .…hand back the error message instead (.is the message).
Result
"object ({\"name\":\"Smith, Jo\",\"not...) cannot be csv-formatted, only an array can be"Good to know
- In both formats a number or a boolean is written bare (
3,true) andnullis an empty cell. - A tool that reads TSV should turn
\t,\n,\rand\\back into the characters they stand for.