# 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.                                                                                                                                                       |