Update java docs Dec 2025 #4756

chernser · 2025-11-14T19:13:09Z

Summary

Checklist

Delete items not relevant to your PR
URL changes should add a redirect to the old URL via https://github.com/ClickHouse/clickhouse-docs/blob/main/docusaurus.config.js
If adding a new integration page, also add an entry to the integrations list here: https://github.com/ClickHouse/clickhouse-docs/blob/main/docs/integrations/index.mdx

…gs configuration

vercel · 2025-11-14T19:13:16Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Preview	Comments	Updated (UTC)
clickhouse-docs	Error		Comment	Dec 6, 2025 7:48am
clickhouse-docs-jp	Building	Preview	Comment	Dec 6, 2025 7:48am

2 Skipped Deployments

Project	Deployment	Preview	Comments	Updated (UTC)
clickhouse-docs-ru	Ignored	Preview		Dec 6, 2025 7:48am
clickhouse-docs-zh	Ignored	Preview		Dec 6, 2025 7:48am

laeg

@chernser thank you for putting this together!! 🙏

@Blargian lets find some time to think through this in relation to the future docs build. seems like we need nicer ways to handle configuration options in programmatic settings.

laeg · 2025-11-17T10:01:58Z

docs/integrations/language-clients/java/client/_snippets/_v0_8.mdx

+import TOCInline from '@theme/TOCInline';
+
+
+<TOCInline toc={toc} />


Lets move this into the righthand navbar as it takes up a lot of the documentation

Haha! this is not so easy because we are using snippets. They break navbar.
I've spent two hours playing around with different configs but failed miserably.
I suggest we address it later.

@Blargian
I have a problem that when I create two separate pages under lets say JDBC I get one of them without any bars - just like a standalone page. I'm sure there is something in how these pages are defined in sidebars config.
But I failed to find a way to make it work. I've tried replicate approach from other places but no luck.
If you know the problem I will appreciate any help here.

Thanks!

laeg · 2025-11-17T10:05:54Z

docs/integrations/language-clients/java/client/_snippets/_v0_8.mdx

+Table below shows what old options are supported in the new client and there new meaning.
+✔	- supported
+✗ - dropped
+| V1 Configuration | Matching V2 Builder Method | Comments          |


I wonder if there is a nicer way to display this, the scroll is hard. @Blargian do you have any ideas of what we could do here?

@chernser is there a way to group them and break this up into digestible chunks/smaller tables to make it a bit more readable 🤔

+1 to collocate them in groups.

If the page is large, we can consider moving it to a dedicated page

Ok. I can group them by function.

laeg · 2025-11-17T10:07:34Z

docs/integrations/language-clients/java/client/_snippets/_v0_8.mdx

 | `addEndpoint(String endpoint)`          | - `endpoint` - URL formatted a server address.      | Adds a server endpoint to list of available servers. Currently only one endpoint is supported. <br/> <br/> Default: `none` <br/> Enum: `none` <br/> Key: `none`  |
 | `addEndpoint(Protocol protocol, String host, int port, boolean secure)` | - `protocol` - connection protocol `com.clickhouse.client.api.enums.Protocol#HTTP`.<br />- `host` - IP or hostname of a server.<br />- `secure` - if communication should use secure version of the protocol (HTTPS) | Adds a server endpoint to list of available servers. Currently only one endpoint is supported. <br/> <br/> Default: `none` <br/> Enum: `none` <br/> Key: `none` |
-| `setOption(String key, String value)`   | - `key` - String key of the client configuration option.<br /> - `value` - String value of the option | Sets raw value of client options. Useful when reading configuration from properties files. | 
+| `setOption(String key, String value)`   | - `key` - String key of the client configuration option.<br /> - `value` - String value of the option | Sets raw value of client options. Useful when reading configuration from properties files. |


same here @Blargian, the docs are a little tough to read if you havent got a wide screen

mshustov · 2025-11-17T17:25:34Z

docs/integrations/language-clients/java/jdbc/_snippets/_v0_8.mdx


+:::note Server Settings
+
+All server settings should be prefixed with `clickhouse_setting_` (same as for the client [configuration](/integrations/language-clients/java/client#server-settings)).


We need to add this to the client's list as it's been a constant source of customer complaints.

What can we do to make this breaking change self-servable? For example, detect unrecognized settings and log a warning to use clickhouse_setting_ prefix

ClickHouse/clickhouse-java#2658

mshustov · 2025-11-17T17:26:28Z

package.json

    "form-data": "^4.0.4"
-  }
+  },
+  "packageManager": "[email protected]+sha512.a6b2f7906b721bba3d67d4aff083df04dad64c399707841b7acf00f6b133b7ac24255f2652fa22ae3534329dc6180534e98d17432037ff6fd140556e2bb3137e"


not sure it needs to be committed to the repo

you are right.
@Blargian is it possible to move all dynamic files that part of a build under specific folder?
We usually use build or target so we can exclude them from git staging.

Thanks!

…unctionality

…sioning setup

chernser · 2025-12-01T19:18:05Z

@Blargian many thanks for grouping configuration parameters!

…into update_java_docs_nov_2025

mshustov · 2025-12-02T16:32:53Z

docs/integrations/language-clients/java/client/client.mdx

+                .build();
+```
+
+`Client` is `AutoCloseable` and should be closed when not needed anymore.


should be closed

Should we extend the example above to include this?

This is true for older client. I will add something about resource management.

mshustov · 2025-12-02T16:36:53Z

docs/integrations/language-clients/java/client/client.mdx

+## Client Configuration {#client-configuration}
+
+<Tabs groupId="client-config">
+<TabItem value="connection" label="Connection & Endpoints">


not a blocker for the PR, @Blargian what can we do to make the table easy readable? right now, the Default column might be disproportionately large

mshustov · 2025-12-02T16:38:44Z

docs/integrations/language-clients/java/client/client.mdx

+	...
+}
+```
+When options are set via `setOption` method (either the `Client.Builder` or operation settings class) then server settings name should be prefixed with `clickhouse_setting_`. The `com.clickhouse.client.api.ClientConfigProperties#serverSetting()` may be handy in this case.


Should we wrap this wrapper into an note snippet?

note snipped I think is quite heavy. I've put ⚠️ to attract attention to the following information.

mshustov · 2025-12-02T16:48:29Z

docs/integrations/language-clients/java/client/client.mdx

+- Client V2 `async` settings is `off` by default. It means no extra threads and more application control over client. This setting should be `off` for majority of use cases. Enabling `async` will create a separate thread for a request. It only make sense when using application controlled
+executor (see `com.clickhouse.client.api.Client.Builder#setSharedOperationExecutor`)
+
+### Writing Data


is there an example in the repository comparing the snippets back to back? like

examples/insert_v1.java
examples/insert_v2.java

mshustov · 2025-12-02T16:50:56Z

docs/integrations/language-clients/java/client/client.mdx

+| `ClickHouseClientOption#RETRY` | `Client.Builder#setMaxRetries` | See also `retryOnFailures` |
+| `ClickHouseHttpOption#AHC_RETRY_ON_FAILURE` | `Client.Builder#retryOnFailures` | |
+| `ClickHouseClientOption#FAILOVER` | ✗ | |
+| `ClickHouseClientOption#REPEAT_ON_SESSION_LOCK` | ✗ | |


one of the problem with TabIteams, is that none Cmd + F nor search able to find the settings.

May be we need to extract reference information to another page?
So any client doc will be in two parts: Narrative about client, its features and reference information.
GCP is a good example.

mshustov · 2025-12-02T16:51:47Z

docs/integrations/language-clients/java/jdbc/jdbc.mdx

+We recommend using the latest java client directly if performance/direct access is critical.
+:::
+
+## Changes from 0.7.x {#changes-from-07x}


Should it be Migration guide?

mshustov · 2025-12-02T16:52:44Z

docs/integrations/language-clients/java/jdbc/jdbc.mdx

+
+## Supported data types {#supported-data-types}
+
+JDBC Driver supports the same data formats as the underlying [java client](/integrations/language-clients/java/client/client.mdx).


Should it be a link to a specific section of the client documentation?

mshustov · 2025-12-02T16:54:04Z

docs/integrations/language-clients/java/jdbc/jdbc.mdx

+## Supplying Credentials and Settings {#supplying-credentials-and-settings}
+
+```java showLineNumbers
+String url = "jdbc:ch://localhost:8123?jdbc_ignore_unsupported_values=true&socket_timeout=10";


could you add an example of a server setting configuration?

mshustov · 2025-12-02T16:56:15Z

docs/integrations/language-clients/java/client/client.mdx

+queryParams.put("param1", 2);
+
+try (QueryResponse response =
+        client.query("SELECT * FROM " + table + " WHERE col1 >= {param1:UInt32}", queryParams, new QuerySettings()).get()) {


I wonder if we should a section for query parametrisation

yes we need.

chernser · 2025-12-03T06:52:02Z

@mshustov thank you for the review! I will correct doc this week and will add more information. So I've returned it to the draft state.

chernser added 2 commits November 3, 2025 10:17

Updated version to latest and gave reference in JDBC to server settin…

3c598ef

…gs configuration

Complete configuration mapping table

99db042

vercel bot deployed to Preview – clickhouse-docs November 14, 2025 19:25 View deployment

chernser requested review from mshustov and mzitnik November 14, 2025 20:37

laeg reviewed Nov 17, 2025

View reviewed changes

mshustov reviewed Nov 17, 2025

View reviewed changes

dhtclk added the Don't Merge Don't merge yet label Nov 17, 2025

chernser requested a review from mshustov November 17, 2025 19:03

Blargian added 3 commits November 18, 2025 15:59

modify versioned pages to make use of updated page level versioning f…

0c07e2b

…unctionality

merge main and adjust client and jdbc pages to work with new page ver…

b399e07

…sioning setup

restore package.json

f207f72

vercel bot deployed to Preview – clickhouse-docs November 18, 2025 18:12 View deployment

single table to categorised tabs with tables

27633fc

vercel bot had a problem deploying to Preview – clickhouse-docs November 20, 2025 14:29 Failure

Merge branch 'main' into update_java_docs_nov_2025

afea1b7

vercel bot deployed to Preview – clickhouse-docs-jp November 26, 2025 23:06 View deployment

vercel bot deployed to Preview – clickhouse-docs-zh November 26, 2025 23:06 View deployment

vercel bot deployed to Preview – clickhouse-docs-ru November 26, 2025 23:07 View deployment

vercel bot deployed to Preview – clickhouse-docs November 26, 2025 23:09 View deployment

chernser changed the title ~~[DO NOT MERGE] Update java docs nov 2025~~ [DO NOT MERGE] Update java docs Dec 2025 Dec 1, 2025

Added information about insert and read

3e7cc63

chernser marked this pull request as ready for review December 1, 2025 19:18

chernser requested review from a team as code owners December 1, 2025 19:18

chernser changed the title ~~[DO NOT MERGE] Update java docs Dec 2025~~ Update java docs Dec 2025 Dec 1, 2025

vercel bot had a problem deploying to Preview – clickhouse-docs December 1, 2025 19:26 Failure

Merge branch 'main' of https://github.com/ClickHouse/clickhouse-docs …

005b656

…into update_java_docs_nov_2025

vercel bot deployed to Preview – clickhouse-docs-ru December 2, 2025 15:15 View deployment

vercel bot deployed to Preview – clickhouse-docs-zh December 2, 2025 15:16 View deployment

vercel bot deployed to Preview – clickhouse-docs December 2, 2025 15:17 View deployment

vercel bot deployed to Preview – clickhouse-docs-jp December 2, 2025 15:19 View deployment

mshustov reviewed Dec 2, 2025

View reviewed changes

mshustov approved these changes Dec 2, 2025

View reviewed changes

chernser marked this pull request as draft December 3, 2025 06:51

added more information. fixed links

1dc7e0f

chernser marked this pull request as ready for review December 6, 2025 07:40

vercel bot had a problem deploying to Preview – clickhouse-docs December 6, 2025 07:48 Failure

		import TOCInline from '@theme/TOCInline';


		<TOCInline toc={toc} />


		:::note Server Settings

		All server settings should be prefixed with `clickhouse_setting_` (same as for the client [configuration](/integrations/language-clients/java/client#server-settings)).


		## Supported data types {#supported-data-types}

		JDBC Driver supports the same data formats as the underlying [java client](/integrations/language-clients/java/client/client.mdx).

Update java docs Dec 2025 #4756

Are you sure you want to change the base?

Update java docs Dec 2025 #4756

Uh oh!

Conversation

chernser commented Nov 14, 2025

Summary

Checklist

Uh oh!

vercel bot commented Nov 14, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

laeg left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

chernser commented Dec 1, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mshustov Dec 2, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

chernser commented Dec 3, 2025

Uh oh!

Reviewers

vercel bot commented Nov 14, 2025 •

edited

Loading

mshustov Dec 2, 2025 •

edited

Loading