v2: spec batch 2 — strict input JSON, the positional export with mixed-body decline, column_defaults, error reasons, known-crash list (ABI v2 d5323993)

docs/guides/batches.md

@@ -291,6 +291,57 @@ Three payload states, and they are distinct: absent means no export was requeste
 
 Attaching a compiled filter to this same call narrows the export further, to the rows the filter admits, from the same one parse: [`filters.md` → Exporting only the rows a filter admits](filters.md#exporting-only-the-rows-a-filter-admits).
 
+## Overriding a column's DEFAULT for one call (ABI v2)
+
+`column_defaults` is a per-call list of `{name, value}`. In a cell the server would have filled from the column's DEFAULT, the call uses your `value` instead. The library decides which cells those are, by ClickHouse's own reader and the call's format settings: a field the record omits, a `null` for a non-Nullable column under `input_format_null_as_default`, an empty CSV field under `input_format_csv_empty_as_default`. A field the record supplied is never overridden, and `""` is a value like any other. A cell an override fills reads `default_override` (`Source` in each binding), which is stored, and the export carries it as a present value, so inserting the export needs no override.
+
+The binding only passes the list: `name` and `value` are byte strings (UTF-8, else the `name_b64` and `value_b64` forms), the order is kept, and an empty list is sent as `[]`. It validates nothing. An entry that names an unknown, non-insertable, MATERIALIZED or ALIAS column, or a value that does not read as the column's type, is `CHS_INVALID_ARGUMENT` at the call, naming `column_defaults[i]`. A build that does not implement the member declines it. The option exists on the four calls that model an INSERT of a body: row, rows, parse a block and filter rows.
+
+<details open><summary><b>Go</b></summary>
+
+```go
+batch, err := schema.Rows(chtypes.JSONEachRow, body,
+	chtypes.WithColumnDefaults([]chtypes.ColumnDefault{{Name: "region", Value: "eu"}}))
+// a cell filled from the override: batch.Rows[i].Columns[j].Source == chtypes.SourceDefaultOverride
+```
+
+</details>
+
+<details><summary><b>Python</b></summary>
+
+```python
+batch = schema.rows(
+    Format.JSON_EACH_ROW, body, column_defaults=[ColumnDefault("region", "eu")]
+)
+# a cell filled from the override has source == Source.DEFAULT_OVERRIDE
+```
+
+</details>
+
+<details><summary><b>TypeScript</b></summary>
+
+```ts
+const batch = schema.rows(Format.JSONEachRow, body, {
+  columnDefaults: [{ name: 'region', value: 'eu' }],
+});
+// a cell filled from the override has source Source.DefaultOverride
+```
+
+</details>
+
+<details><summary><b>Rust</b></summary>
+
+```rust
+let options = RowsOptions {
+    column_defaults: Some(vec![ColumnDefault { name: b"region".to_vec(), value: b"eu".to_vec() }]),
+    ..Default::default()
+};
+let batch = schema.rows(Format::JsonEachRow, body, &options)?;
+// a cell filled from the override has source Source::DefaultOverride
+```
+
+</details>
+
 ## Next
 
 - [`transformations.md`](transformations.md) — what the accepted rows were silently changed into.

docs/guides/settings.md

@@ -98,7 +98,16 @@ This has cost real bugs, so v1 makes it one rule in all four bindings: **a setti
 
 The reason is one setting in particular. `chtypes_now_epoch_nanos` is a 19-digit nanosecond epoch, and 19 digits do not survive an IEEE double: `1700000000123456789` becomes `1.7e+18`. Sent as a JSON number, the setting would be **silently ignored** — the batch keeps stamping the real wall clock, and nothing anywhere says so. A loud `TypeError` is the whole point.
 
-A value whose bytes are not valid UTF-8 cannot be passed as a setting or a query parameter in 1.0. Inline it in the SQL as `unhex('<hex>')`, built from hex digits only ([`limitations.md`](../limitations.md#binary-input-parameters-must-be-utf-8)).
+A value whose bytes are not valid UTF-8 is sent in the object form `{"b64": "<standard base64, padded>"}` (ABI v2): a setting value, a query-parameter value, a `Setup` default and a value of a server profile's `settings`. The binding writes it in place of the string, so the library sees the exact bytes; a value that is valid UTF-8 stays a plain string. Three of the bindings can send one:
+
+| Binding    | How a non-UTF-8 value is passed                                                                    |
+| ---------- | -------------------------------------------------------------------------------------------------- |
+| Go         | a `string` holding the bytes (a Go `string` is a byte string)                                      |
+| Python     | a `str` carrying the bytes with `surrogateescape`                                                  |
+| TypeScript | a `Uint8Array` (a `string` holding a lone surrogate has no bytes and is refused, as a key is)      |
+| Rust       | **cannot**: settings and query parameters take `String`, so a non-UTF-8 value is unreachable there |
+
+A key that is not valid UTF-8 cannot be carried in any binding (a JSON object has no byte form for a key), and neither can a macro's name or value. Each is refused before any call. Where a binding cannot send the bytes, inline them in the SQL as `unhex('<hex>')`, built from hex digits only ([`limitations.md`](../limitations.md#binary-input-parameters-must-be-utf-8)).
 
 ## An unknown name refuses the whole call