refactor(clickhouse): rationalize insertFormat/bulkInsert boundary

lohanidamodar · lohanidamodar · commit ddf9377fa3ee · 2026-07-06T04:45:03.000Z
bulkInsert() is the recommended bulk-ingest entry point; insertFormat()
stays as a lower-level setter for callers that stream the body
separately. Both paths now share a single private envelope emitter
(compileFormatInsertEnvelope) so they cannot diverge on table quoting,
column resolution, or column-name validation.

Also aligns insertFormat()+insert() with bulkInsert() by accepting the
no-columns envelope form (INSERT INTO t FORMAT name) — ClickHouse
treats the column list as optional, and the two paths now match.
diff --git a/README.md b/README.md
@@ -1551,7 +1551,7 @@ $statement = (new Builder())
 
 The `Format` enum currently supports `Format::JSONEachRow` and `Format::TabSeparated`. JSONEachRow rows are encoded with `JSON_THROW_ON_ERROR | JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE` (slashes and non-ASCII are preserved verbatim); TabSeparated escapes `\\`, `\t`, `\n`, `\r` and emits `\N` for `null`. An empty row iterable produces an empty body, which ClickHouse accepts as a zero-row ingest. The iterable is consumed eagerly — pass a generator if you want to defer row construction, but the serialized body is materialized in full before the statement is returned.
 
-For envelopes only (no body — e.g. when streaming the payload from elsewhere), the lower-level `insertFormat()` setter remains available and pairs with `insert()` as before:
+`bulkInsert()` is the recommended entry point for FORMAT-based ingest — it covers the full envelope + body contract in one typed call. The lower-level `insertFormat()` setter pairs with `insert()` for the envelope-only path (returns `body = null`) and is retained for callers that stream the payload separately. Both paths share the same envelope emitter, so the resulting `query` is identical for equivalent inputs:
 
 ```php
 $statement = (new Builder())
diff --git a/src/Query/Builder/ClickHouse.php b/src/Query/Builder/ClickHouse.php
@@ -141,35 +141,12 @@ public function hint(string $hint): static
     }
 
     /**
-     * Declare a ClickHouse FORMAT pragma for the next INSERT.
-     *
-     * When a format is set, `insert()` emits
-     * `INSERT INTO \`t\` (\`col1\`, \`col2\`) FORMAT <name>` with no VALUES.
-     * The row payload must be streamed into the HTTP body by the caller.
-     * Column names are derived from the most recent `set()` call (values are
-     * ignored). Pass `$columns` to declare them explicitly when no `set()`
-     * call has been made.
-     *
-     * @param  list<string>  $columns
-     */
-    public function insertFormat(string $format, array $columns = []): static
-    {
-        if (!\preg_match('/^[A-Za-z][A-Za-z0-9_]*$/', $format)) {
-            throw new ValidationException('Invalid ClickHouse INSERT format: ' . $format);
-        }
-
-        $this->insertFormat = $format;
-        $this->insertFormatColumns = $columns;
-
-        return $this;
-    }
-
-    /**
-     * Build a single statement that carries both the `INSERT INTO <table>
-     * FORMAT <name>` envelope and the serialized row payload for a
-     * ClickHouse bulk ingest. Returns a `FormattedInsertStatement` whose
-     * `->query` is the envelope and whose `->body` is the formatted
-     * payload to send as the HTTP request body.
+     * Recommended bulk-ingest entry point. Emits the canonical `INSERT INTO
+     * <table> [(<cols>)] FORMAT <name>` envelope alongside the serialized row
+     * payload in a single typed call. The returned `FormattedInsertStatement`
+     * exposes `->query` (envelope, no bindings) and `->body` (format-specific
+     * payload) so the caller can ship both to ClickHouse's HTTP interface
+     * without hand-assembling either side.
      *
      * The target table must be set via `into()` first. Columns are derived
      * from the keys of the first row when `$columns` is omitted; pass
@@ -182,9 +159,6 @@ public function insertFormat(string $format, array $columns = []): static
      */
     public function bulkInsert(Format $format, iterable $rows, array $columns = []): FormattedInsertStatement
     {
-        $this->bindings = [];
-        $this->validateTable();
-
         $materialized = [];
         foreach ($rows as $row) {
             /** @phpstan-ignore function.alreadyNarrowedType */
@@ -198,22 +172,7 @@ public function bulkInsert(Format $format, iterable $rows, array $columns = []):
             $columns = \array_keys($materialized[0]);
         }
 
-        foreach ($columns as $col) {
-            if ($col === '') {
-                throw new ValidationException('Column names for bulkInsert() must be non-empty strings.');
-            }
-        }
-
-        $wrappedColumns = empty($columns)
-            ? ''
-            : ' (' . \implode(', ', \array_map(
-                fn (string $col): string => $this->resolveAndWrap($col),
-                $columns
-            )) . ')';
-
-        $sql = 'INSERT INTO ' . $this->quote($this->table)
-            . $wrappedColumns
-            . ' FORMAT ' . $format->value;
+        $sql = $this->compileFormatInsertEnvelope($format->value, $columns);
 
         $body = $format->serialize($materialized, empty($columns) ? null : $columns);
 
@@ -230,6 +189,63 @@ public function bulkInsert(Format $format, iterable $rows, array $columns = []):
         );
     }
 
+    /**
+     * Lower-level setter for the FORMAT envelope. Use `bulkInsert()` for the
+     * typed entry point; this method is retained for callers that need to
+     * stream the body payload separately (e.g. piping a pre-serialized stream
+     * straight into the HTTP request) — the subsequent `insert()` call emits
+     * the envelope only, with `body = null`.
+     *
+     * Column names are derived from the most recent `set()` call (values are
+     * ignored). Pass `$columns` to declare them explicitly when no `set()`
+     * call has been made.
+     *
+     * @param  list<string>  $columns
+     */
+    public function insertFormat(string $format, array $columns = []): static
+    {
+        if (!\preg_match('/^[A-Za-z][A-Za-z0-9_]*$/', $format)) {
+            throw new ValidationException('Invalid ClickHouse INSERT format: ' . $format);
+        }
+
+        $this->insertFormat = $format;
+        $this->insertFormatColumns = $columns;
+
+        return $this;
+    }
+
+    /**
+     * Build the shared `INSERT INTO <table> [(<cols>)] FORMAT <name>`
+     * envelope. Validates the table, validates column names, quotes the
+     * table identifier, and wraps each column via `resolveAndWrap()`.
+     * Resets bindings so callers don't accumulate stale values from prior
+     * builder operations.
+     *
+     * @param  list<string>  $columns
+     */
+    private function compileFormatInsertEnvelope(string $format, array $columns): string
+    {
+        $this->bindings = [];
+        $this->validateTable();
+
+        foreach ($columns as $col) {
+            if ($col === '') {
+                throw new ValidationException('Column names for FORMAT INSERT must be non-empty strings.');
+            }
+        }
+
+        $wrappedColumns = empty($columns)
+            ? ''
+            : ' (' . \implode(', ', \array_map(
+                fn (string $col): string => $this->resolveAndWrap($col),
+                $columns
+            )) . ')';
+
+        return 'INSERT INTO ' . $this->quote($this->table)
+            . $wrappedColumns
+            . ' FORMAT ' . $format;
+    }
+
     /**
      * @param  array<string, string>  $settings
      */
@@ -685,31 +701,11 @@ public function insert(): Statement
             return $this->applyNamedTypedBindings(parent::insert());
         }
 
-        $this->bindings = [];
-        $this->validateTable();
-
         $columns = !empty($this->insertFormatColumns)
             ? $this->insertFormatColumns
             : (!empty($this->rows) ? \array_keys($this->rows[0]) : []);
 
-        if (empty($columns)) {
-            throw new ValidationException('No columns specified for FORMAT INSERT. Pass columns to insertFormat() or call set() before insert().');
-        }
-
-        foreach ($columns as $col) {
-            if ($col === '') {
-                throw new ValidationException('Column names for FORMAT INSERT must be non-empty strings.');
-            }
-        }
-
-        $wrappedColumns = \array_map(
-            fn (string $col): string => $this->resolveAndWrap($col),
-            $columns
-        );
-
-        $sql = 'INSERT INTO ' . $this->quote($this->table)
-            . ' (' . \implode(', ', $wrappedColumns) . ')'
-            . ' FORMAT ' . $format;
+        $sql = $this->compileFormatInsertEnvelope($format, $columns);
 
         return new FormattedInsertStatement(
             $sql,
diff --git a/tests/Query/Builder/Feature/ClickHouse/BulkInsertTest.php b/tests/Query/Builder/Feature/ClickHouse/BulkInsertTest.php
@@ -305,4 +305,51 @@ public function testInsertFormatEnvelopeStillEmitsNullBodyForBackCompat(): void
         $this->assertInstanceOf(FormattedInsertStatement::class, $result);
         $this->assertNull($result->body);
     }
+
+    public function testBulkInsertAndInsertFormatEmitIdenticalEnvelopeForSameInputs(): void
+    {
+        $bulk = (new Builder())
+            ->into('events')
+            ->bulkInsert(Format::JSONEachRow, [
+                ['id' => 1, 'event' => 'login'],
+            ]);
+
+        $envelope = (new Builder())
+            ->into('events')
+            ->insertFormat('JSONEachRow', ['id', 'event'])
+            ->insert();
+
+        $this->assertInstanceOf(FormattedInsertStatement::class, $envelope);
+        $this->assertSame($bulk->query, $envelope->query);
+        $this->assertSame($bulk->columns, $envelope->columns);
+        $this->assertSame($bulk->format, $envelope->format);
+    }
+
+    public function testInsertFormatEnvelopeQuotesTableWithLiteralDot(): void
+    {
+        $envelope = (new Builder())
+            ->into('my.namespace')
+            ->insertFormat('JSONEachRow', ['id'])
+            ->insert();
+
+        $bulk = (new Builder())
+            ->into('my.namespace')
+            ->bulkInsert(Format::JSONEachRow, [['id' => 1]]);
+
+        $this->assertSame(
+            'INSERT INTO `my`.`namespace` (`id`) FORMAT JSONEachRow',
+            $envelope->query,
+        );
+        $this->assertSame($envelope->query, $bulk->query);
+    }
+
+    public function testInsertFormatRejectsEmptyColumnNameMatchingBulkInsert(): void
+    {
+        $this->expectException(ValidationException::class);
+
+        (new Builder())
+            ->into('events')
+            ->insertFormat('JSONEachRow', ['id', ''])
+            ->insert();
+    }
 }
diff --git a/tests/Query/Builder/Feature/ClickHouse/InsertFormatTest.php b/tests/Query/Builder/Feature/ClickHouse/InsertFormatTest.php
@@ -112,14 +112,20 @@ public function testInsertFormatRejectsEmptyColumnName(): void
             ->insert();
     }
 
-    public function testInsertFormatRequiresColumns(): void
+    public function testInsertFormatWithoutColumnsEmitsBareEnvelope(): void
     {
-        $this->expectException(ValidationException::class);
-
-        (new Builder())
+        $result = (new Builder())
             ->into('events')
             ->insertFormat('JSONEachRow')
             ->insert();
+
+        $this->assertInstanceOf(FormattedInsertStatement::class, $result);
+        $this->assertSame(
+            'INSERT INTO `events` FORMAT JSONEachRow',
+            $result->query
+        );
+        $this->assertSame([], $result->columns);
+        $this->assertNull($result->body);
     }
 
     public function testInsertWithoutFormatStillEmitsValues(): void
