Skip to content
Coordinator DB
View as Markdown
View as Markdown

bson_each_row ​

Description ​

Consecutive binary BSON documents, one named document for each row.

Input and output. Select it with FORMAT bson_each_row. Names ignore ASCII case; use the snake_case name shown here.

Each row is one BSON document with a length and terminator. Documents follow one another without an outer array or separator. Field names identify columns; missing fields use defaults, and malformed lengths, unsupported tags or ambiguous fields are errors.

String output is binary by default; bson_strings selects BSON String for text and FixedString. Wide exact numbers use fixed-width binary coefficients rather than BSON decimal128. Use matching target declarations to recover their native types.

text
SELECT expressions FORMAT bson_each_row;
INSERT INTO table [(columns)] [SETTINGS ...] FORMAT bson_each_row
<data>

Example usage ​

Use the native client's --query mode to preserve binary output bytes. The server must be running, the executable available as ./coordinator, and database data selected.

sh
./coordinator client --database data --query "SELECT CAST(7 AS Int64) AS id FORMAT bson_each_row" > sample.bson_each_row
./coordinator client --database data --query "CREATE TABLE format_import(id Int64)" > /dev/null
./coordinator client --database data --query "INSERT INTO format_import FORMAT bson_each_row" < sample.bson_each_row > /dev/null
./coordinator client --database data --query "SELECT id FROM format_import FORMAT csv"
text
7

Create format_import in a fresh database before running this example.

Format settings ​

Use a statement SETTINGS clause; these options are not persisted by SET.

Setting Type Default Meaning
bson_strings Bool 0 Write text and fixed-width strings as BSON String instead of Binary.
snappy_mode String basic Read Snappy client files as basic (Hadoop blocks) or framed (standard streaming format).

Type mappings ​

Value BSON representation
NULL Null (0x0a).
Bool Boolean (0x08), one byte containing 0 or 1.
INTEGER, UInt64 Int64 (0x12). UInt64 retains all 64 bits. Top-level values do not retain narrow declared widths, so Int8/16/32 and UInt8/16 also write int64. Inside typed collections those widths use int32 (0x10); UInt32 uses int64. Input accepts either integer width and enforces the target range.
Enum8/16, Date/Date32, IPv4 Int32 (0x10): enum code, epoch days, or address bits.
Float32/64 Double (0x01).
DateTime Int64 (0x12) epoch seconds.
DateTime64 Datetime (0x09) containing the declared integer ticks. Read with the same precision; precision 3 uses standard BSON milliseconds. Input also accepts int64 ticks.
Decimal32/64 Int32/int64 containing the coefficient; the target declaration supplies the scale.
Decimal128/256, Int128/UInt128/Int256/UInt256 Generic binary (0x05, subtype 0) containing 16 or 32 little-endian coefficient bytes; signed values use two's complement. Input requires the exact byte width.
String/TEXT, FixedString Generic binary by default; BSON String (0x02) with bson_strings=1. FixedString keeps padding bytes. Native String requires valid UTF-8 on input; use BLOB or FixedString for arbitrary bytes.
BLOB, IPv6 Generic binary, preserving bytes; IPv6 requires 16 bytes. BLOB stays binary even when bson_strings=1.
UUID Binary subtype 4, 16 bytes stored as two little-endian 64-bit halves. Input also accepts subtype 3.
Array, positional Tuple BSON array (0x04); keys are zero-based for Array and one-based for Tuple, and input reads members positionally.
Named Tuple, Map Embedded document (0x03). Tuple fields match exact member names; Map keys use their scalar text and preserve order and duplicate keys.