Add support for query pass-through function in ClickHouse

docs/src/main/sphinx/connector/clickhouse.md

@@ -332,6 +332,42 @@ statements, the connector supports the following features:
 ```{include} alter-schema-limitation.fragment
 ```
 
+## Table functions
+
+The connector provides specific {doc}`table functions </functions/table>` to
+access ClickHouse.
+
+(clickhouse-query-function)=
+### `query(varchar) -> table`
+
+The `query` function allows you to query the underlying database directly. It
+requires syntax native to ClickHouse, because the full query is pushed down and
+processed in ClickHouse. This can be useful for accessing native features which
+are not available in Trino or for improving query performance in situations
+where running a query natively may be faster.
+
+```{include} query-passthrough-warning.fragment
+```
+
+As a simple example, query the `example` catalog and select an entire table:
+
+```
+SELECT
+  *
+FROM
+  TABLE(
+    example.system.query(
+      query => 'SELECT
+        *
+      FROM
+        tpch.nation'
+    )
+  );
+```
+
+```{include} query-table-function-ordering.fragment
+```
+
 ## Performance
 
 The connector includes a number of performance improvements, detailed in the

plugin/trino-clickhouse/src/main/java/io/trino/plugin/clickhouse/ClickHouseClientModule.java

@@ -29,10 +29,13 @@
 import io.trino.plugin.jdbc.JdbcClient;
 import io.trino.plugin.jdbc.JdbcMetadataConfig;
 import io.trino.plugin.jdbc.credential.CredentialProvider;
+import io.trino.plugin.jdbc.ptf.Query;
+import io.trino.spi.function.table.ConnectorTableFunction;
 
 import java.util.Properties;
 
 import static com.clickhouse.client.config.ClickHouseClientOption.USE_BINARY_STRING;
+import static com.google.inject.multibindings.Multibinder.newSetBinder;
 import static io.airlift.configuration.ConfigBinder.configBinder;
 import static io.trino.plugin.clickhouse.ClickHouseClient.DEFAULT_DOMAIN_COMPACTION_THRESHOLD;
 import static io.trino.plugin.jdbc.JdbcModule.bindSessionPropertiesProvider;
@@ -50,6 +53,7 @@ public void configure(Binder binder)
         bindTablePropertiesProvider(binder, ClickHouseTableProperties.class);
         configBinder(binder).bindConfigDefaults(JdbcMetadataConfig.class, config -> config.setDomainCompactionThreshold(DEFAULT_DOMAIN_COMPACTION_THRESHOLD));
         binder.install(new DecimalModule());
+        newSetBinder(binder, ConnectorTableFunction.class).addBinding().toProvider(Query.class).in(Scopes.SINGLETON);
     }
 
     @Provides

plugin/trino-clickhouse/src/test/java/io/trino/plugin/clickhouse/TestClickHouseConnectorTest.java

@@ -77,7 +77,6 @@ protected boolean hasBehavior(TestingConnectorBehavior connectorBehavior)
                  SUPPORTS_ARRAY,
                  SUPPORTS_DELETE,
                  SUPPORTS_DROP_NOT_NULL_CONSTRAINT,
-                 SUPPORTS_NATIVE_QUERY,
                  SUPPORTS_NEGATIVE_DATE,
                  SUPPORTS_PREDICATE_PUSHDOWN_WITH_VARCHAR_INEQUALITY,
                  SUPPORTS_ROW_TYPE,
@@ -788,6 +787,23 @@ public void testRenameTableToLongTableName()
         assertThat(getQueryRunner().tableExists(getSession(), invalidTargetTableName)).isFalse();
     }
 
+    @Test
+    @Override // Override because the failure message differs
+    public void testNativeQueryIncorrectSyntax()
+    {
+        assertThat(query("SELECT * FROM TABLE(system.query(query => 'some wrong syntax'))"))
+                .failure().hasMessage("Query not supported: ResultSetMetaData not available for query: some wrong syntax");
+    }
+
+    @Test
+    @Override // Override because the failure message differs
+    public void testNativeQueryInsertStatementTableDoesNotExist()
+    {
+        assertThat(getQueryRunner().tableExists(getSession(), "non_existent_table")).isFalse();
+        assertThat(query("SELECT * FROM TABLE(system.query(query => 'INSERT INTO non_existent_table VALUES (1)'))"))
+                .failure().hasMessage("Query not supported: ResultSetMetaData not available for query: INSERT INTO non_existent_table VALUES (1)");
+    }
+
     @Test
     public void testLargeDefaultDomainCompactionThreshold()
     {