From 3926932870e81a1b1085909be3c63bb844106541 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Fri, 27 Mar 2026 10:32:20 +0000
Subject: [PATCH 1/2] Add selectStream methods for memory-efficient large
 result sets

Returns raw PSR-7 StreamInterface instead of loading the full response
into memory, allowing incremental processing of large query results.

https://claude.ai/code/session_01YX19TXMGf89gacogUmxHJM
---
 src/Client/ClickHouseClient.php    | 32 ++++++++++++++++++++++++++++
 src/Client/PsrClickHouseClient.php | 34 ++++++++++++++++++++++++++++++
 2 files changed, 66 insertions(+)

diff --git a/src/Client/ClickHouseClient.php b/src/Client/ClickHouseClient.php
index 1e691bb..af2461a 100644
--- a/src/Client/ClickHouseClient.php
+++ b/src/Client/ClickHouseClient.php
@@ -75,6 +75,38 @@ public function selectWithParams(
         SettingsProvider $settings = new EmptySettingsProvider(),
     ): Output;
 
+    /**
+     * @param Format<O> $outputFormat
+     *
+     * @throws ClientExceptionInterface
+     * @throws ServerError
+     *
+     * @template O of Output
+     */
+    public function selectStream(
+        string $query,
+        Format $outputFormat,
+        SettingsProvider $settings = new EmptySettingsProvider(),
+    ): StreamInterface;
+
+    /**
+     * @param array<string, mixed> $params
+     * @param Format<O> $outputFormat
+     *
+     * @throws ClientExceptionInterface
+     * @throws ServerError
+     * @throws UnsupportedParamType
+     * @throws UnsupportedParamValue
+     *
+     * @template O of Output
+     */
+    public function selectStreamWithParams(
+        string $query,
+        array $params,
+        Format $outputFormat,
+        SettingsProvider $settings = new EmptySettingsProvider(),
+    ): StreamInterface;
+
     /**
      * @param array<array<mixed>> $values
      * @param list<string>|array<string, string>|null $columns
diff --git a/src/Client/PsrClickHouseClient.php b/src/Client/PsrClickHouseClient.php
index a4f768d..08aa348 100644
--- a/src/Client/PsrClickHouseClient.php
+++ b/src/Client/PsrClickHouseClient.php
@@ -109,6 +109,40 @@ public function selectWithParams(
         return $outputFormat::output($response->getBody()->__toString());
     }
 
+    public function selectStream(
+        string $query,
+        Format $outputFormat,
+        SettingsProvider $settings = new EmptySettingsProvider(),
+    ): StreamInterface {
+        try {
+            return $this->selectStreamWithParams($query, params: [], outputFormat: $outputFormat, settings: $settings);
+        } catch (UnsupportedParamValue | UnsupportedParamType) {
+            absurd();
+        }
+    }
+
+    public function selectStreamWithParams(
+        string $query,
+        array $params,
+        Format $outputFormat,
+        SettingsProvider $settings = new EmptySettingsProvider(),
+    ): StreamInterface {
+        $formatClause = $outputFormat::toSql();
+
+        $sql = $this->sqlFactory->createWithParameters($query, $params);
+
+        $response = $this->executeRequest(
+            <<<CLICKHOUSE
+            $sql
+            $formatClause
+            CLICKHOUSE,
+            params: $params,
+            settings: $settings,
+        );
+
+        return $response->getBody();
+    }
+
     public function insert(
         Table|string $table,
         array $values,

From 73797d627f7bbd00ca05e70e32cde5a41fb68e58 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Fri, 27 Mar 2026 10:48:08 +0000
Subject: [PATCH 2/2] Add tests for selectStream and selectStreamWithParams

https://claude.ai/code/session_01YX19TXMGf89gacogUmxHJM
---
 tests/Client/SelectTest.php | 18 ++++++++++++++++++
 1 file changed, 18 insertions(+)

diff --git a/tests/Client/SelectTest.php b/tests/Client/SelectTest.php
index b17c04c..d95e48f 100644
--- a/tests/Client/SelectTest.php
+++ b/tests/Client/SelectTest.php
@@ -164,6 +164,24 @@ public function testNull(): void
         self::assertTrue(true);
     }
 
+    public function testSelectStream(): void
+    {
+        $stream = self::$client->selectStream('SELECT 1 AS data', new TabSeparated());
+
+        self::assertSame("1\n", $stream->__toString());
+    }
+
+    public function testSelectStreamWithParams(): void
+    {
+        $stream = self::$client->selectStreamWithParams(
+            'SELECT {p1:UInt8} AS data',
+            ['p1' => 3],
+            new TabSeparated(),
+        );
+
+        self::assertSame("3\n", $stream->__toString());
+    }
+
     public function testSettingsArePassed(): void
     {
         self::expectException(ServerError::class);