Query parameters can not be parsed in `DESCRIBE TABLE` query with client-v2

[jnd77]

Description

Bug with Client#query(sql, params) for a DESCRIBE TABLE query.

Steps to reproduce

See the unit test below.
The parameter name is not substituted.

Error Log or Exception StackTrace

com.clickhouse.client.api.ServerException: Code: 62. DB::Exception: Syntax error: failed at position 33 (}): }. Expected substitution type (identifier). (SYNTAX_ERROR)

Expected Behaviour

Code Example

  @Test
  void testWeirdBugWithParams() throws Exception {
    final Client client = new Client.Builder()
        .addEndpoint(Protocol.HTTP, "localhost", 8123, false)
        .setUsername("default")
        .setPassword("")
        .build();
    final Map<String, Object> params = Map.of("table_name", "`system`.`tables`");
    // This query should not throw an exception
    client.query("DESCRIBE TABLE {table_name:String}", params).get();
  }

Configuration

Client Configuration

See above.

Environment

• Cloud
• Client version: 0.8.6
• Language version: Java 17
• OS: Linux

ClickHouse Server

• ClickHouse Server version: 25.3.3.42 (official build)

[chernser]

/triage

[github-actions]

Triage Report

Effort to Fix: Small
Type: Bug
Affected Module: client-v2 (client-api-v2)

Summary

When calling Client#query("DESCRIBE TABLE {table_name:String}", params), the server rejects the query with a syntax error at position 33 (the closing } of the substitution). The client correctly passes param_table_name as a URL query parameter, but ClickHouse cannot apply {name:String} substitution in a DESCRIBE TABLE table-name position because String-typed parameters are resolved as quoted string literals — making the resulting SQL (DESCRIBE TABLE 'system.tables') syntactically invalid. The correct ClickHouse type for substituting an identifier (table/column name) is Identifier, not String. It is not yet confirmed whether this is a pure user-education issue or whether the client should detect and surface a clearer error.

Recommended Labels & Priority

• Labels: bug, client-api-v2, area:client-read

Missing Information / Questions for User

1. Does changing the query to DESCRIBE TABLE {table_name:Identifier} (type Identifier instead of String) resolve the error?
2. Can you share the raw HTTP request (enable debug logging with -Dorg.slf4j.simpleLogger.defaultLogLevel=DEBUG) to confirm param_table_name is included in the URL?
3. Is the issue reproducible with other ClickHouse server versions (e.g., 24.x)?

Tests to Add

Test 1: DESCRIBE TABLE with Identifier-typed query parameter

@Test(groups = {"integration"})
public void testQueryParamsInDescribeTable() throws Exception {
    // {name:Identifier} is the correct ClickHouse type for a table-name substitution
    final Map<String, Object> params = Map.of("table_name", "system.tables");
    try (QueryResponse response =
             client.query("DESCRIBE TABLE {table_name:Identifier}", params).get()) {
        Assert.assertNotNull(response);
    }
}

Test 2: DESCRIBE TABLE with String-typed parameter should fail with a clear error

@Test(groups = {"integration"})
public void testQueryParamsInDescribeTableStringTypeFails() {
    // String type resolves to a quoted literal, which is invalid in the table-name position;
    // verify the client surfaces a ServerException rather than an opaque failure.
    final Map<String, Object> params = Map.of("table_name", "system.tables");
    try {
        client.query("DESCRIBE TABLE {table_name:String}", params).get();
        Assert.fail("Expected ServerException");
    } catch (ExecutionException e) {
        Assert.assertTrue(e.getCause() instanceof ServerException,
            "Expected ServerException, got: " + e.getCause());
    }
}

[kishansinghifs1]

Hii @chernser I would like to work on it.

[chernser]

@kishansinghifs1
What would be the fix?
please describe briefly.

Thanks!