Add selectStream methods for large result sets

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

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,

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);