From 0d683f51b5536f63c37db5b223fce1cfaee49dbd Mon Sep 17 00:00:00 2001 From: Sergey Chernov Date: Fri, 20 Dec 2024 11:34:22 -0800 Subject: [PATCH 1/2] doc updates for configuration --- .../language-clients/java/client-v1.md | 10 ++++++---- .../language-clients/java/client-v2.md | 19 +++++++++++++------ .../language-clients/java/jdbc-driver.md | 10 +++++----- 3 files changed, 24 insertions(+), 15 deletions(-) diff --git a/docs/en/integrations/language-clients/java/client-v1.md b/docs/en/integrations/language-clients/java/client-v1.md index dac7376b6ed..d7c650da7f9 100644 --- a/docs/en/integrations/language-clients/java/client-v1.md +++ b/docs/en/integrations/language-clients/java/client-v1.md @@ -14,7 +14,9 @@ import CodeBlock from '@theme/CodeBlock'; Java client library to communicate with a DB server thru its protocols. Current implementation supports only [HTTP interface](/docs/en/interfaces/http). The library provides own API to send requests to a server. -*Note*: this component will be deprecated soon. +:::warning Deprecation +This library will be depreceted on `February, 28, 2025`. It means no releases after and support. +::: ## Setup @@ -26,7 +28,7 @@ Java client library to communicate with a DB server thru its protocols. Current com.clickhouse clickhouse-http-client - 0.7.1 + 0.7.2 ``` @@ -35,14 +37,14 @@ Java client library to communicate with a DB server thru its protocols. Current ```kotlin // https://mvnrepository.com/artifact/com.clickhouse/clickhouse-http-client -implementation("com.clickhouse:clickhouse-http-client:0.7.1") +implementation("com.clickhouse:clickhouse-http-client:0.7.2") ``` ```groovy // https://mvnrepository.com/artifact/com.clickhouse/clickhouse-http-client -implementation 'com.clickhouse:clickhouse-http-client:0.7.1' +implementation 'com.clickhouse:clickhouse-http-client:0.7.2' ``` diff --git a/docs/en/integrations/language-clients/java/client-v2.md b/docs/en/integrations/language-clients/java/client-v2.md index 2e5cbd88fc9..5d074411e41 100644 --- a/docs/en/integrations/language-clients/java/client-v2.md +++ b/docs/en/integrations/language-clients/java/client-v2.md @@ -26,7 +26,7 @@ Java client library to communicate with a DB server through its protocols. The c com.clickhouse client-v2 - 0.7.1 + 0.7.2 ``` @@ -35,14 +35,14 @@ Java client library to communicate with a DB server through its protocols. The c ```kotlin // https://mvnrepository.com/artifact/com.clickhouse/client-v2 -implementation("com.clickhouse:client-v2:0.7.1") +implementation("com.clickhouse:client-v2:0.7.2") ``` ```groovy // https://mvnrepository.com/artifact/com.clickhouse/client-v2 -implementation 'com.clickhouse:client-v2:0.7.1' +implementation 'com.clickhouse:client-v2:0.7.2' ``` @@ -157,7 +157,7 @@ Configuration is defined during client creation. See `com.clickhouse.client.api. | setServerTimeZone(String timeZone) | `timeZone` - string value of java valid timezone ID (see `java.time.ZoneId`) | Sets server side timezone. UTC timezone will be used by default. | | useAsyncRequests(boolean async) | `async` - flag that indicates if the option should be enabled. | Sets if client should execute request in a separate thread. Disabled by default because application knows better how to organize multithreaded tasks and running tasks in separate thread do not help with performance. | | setSharedOperationExecutor(ExecutorService executorService) | `executorService` - instance of executor service. | Sets executor service for operation tasks. | -| setClientNetworkBufferSize(int size) | - `size` - size in bytes | Sets size of a buffer in application memory space that is used to copy data back-and-forth between socket and application. Greater reduces system calls to TCP stack, but affects how much memory is spent on every connection. This buffer is also subject for GC because connections are shortlive. Also keep in mind that allocating big continious block of memory might be a problem. | +| setClientNetworkBufferSize(int size) | - `size` - size in bytes | Sets size of a buffer in application memory space that is used to copy data back-and-forth between socket and application. Greater reduces system calls to TCP stack, but affects how much memory is spent on every connection. This buffer is also subject for GC because connections are shortlive. Also keep in mind that allocating big continious block of memory might be a problem. Default is `300,000` bytes | | retryOnFailures(ClientFaultCause ...causes) | - `causes` - enum constant of `com.clickhouse.client.api.ClientFaultCause` | Sets recoverable/retriable fault types. | | setMaxRetries(int maxRetries) | - `maxRetries` - number of retries | Sets maximum number of retries for failures defined by `retryOnFailures(ClientFaultCause ...causes)` | | allowBinaryReaderToReuseBuffers(boolean reuse) | - `reuse` - flag that indicates if the option should be enabled | Most datasets contain numeric data encoded as small byte sequences. By default reader will allocate required buffer, read data into it and then transform into a target Number class. That may cause significant GC preasure because of many small objects are being allocated and released. If this option is enabled then reader will use preallocated buffers to do numbers transcoding. It is safe because each reader has own set of buffers and readers are used by one thread. | @@ -168,7 +168,9 @@ Configuration is defined during client creation. See `com.clickhouse.client.api. | serverSetting(String name, Collection values) | - `name` - name of a query level setting.
- `values` - string values of the setting. |Sets what settings to pass to server along with each query. Individual operation settings may override it. The [List of settings](/docs/en/operations/settings/query-level). This method is useful to set settings with multiple values, for example [roles](/docs/en/interfaces/http#setting-role-with-query-parameters) | | columnToMethodMatchingStrategy(ColumnToMethodMatchingStrategy strategy) | - `strategy` - implementation of a column-field matching strategy | Sets custom strategy to be used for matching DTO class fields and DB columns when registering DTO. | | useHTTPBasicAuth(boolean useBasicAuth) | - `useBasicAuth` - flag that indicates if the option should be enabled | Sets if basic HTTP authentication should be used for user-password authentication. Default is enabled. Using this type of authentication resolves issues with passwords containing special characters that cannot be transferred over HTTP headers. | - +| setClientName(String clientName) | - `clientName` - a string representing application name | Sets additional information about calling application. This string will be passed to server as a client name. In case of HTTP protocol it will be passed as a `User-Agent` header. | +| useBearerTokenAuth(String bearerToken) | - `bearerToken` - an encoded bearer token | Specifies whether to use Bearer Authentication and what token to use. The token will be sent as is, so it should be encoded before passing to this method. | +| ## Common Definitions @@ -363,13 +365,16 @@ Configuration options for insert operations.
Copy buffer size. The buffer is used during write operations to copy data from user provided input stream to an output stream. Default: 8196
serverSetting(String name, String value)
-
Sets individual server settings for an operation
+
Sets individual server settings for an operation.
serverSetting(String name, Collection values)
Sets individual server settings with multiple values for an operation. Items of the collection should `String` values
setDBRoles(Collection dbRoles)
Sets DB roles to be set before executing an operation. Items of the collection should be `String` values
+ +
setOption(String option, Object value)
+
Sets a configuration option in raw format. This is not a server settings.
### InsertResponse @@ -547,6 +552,8 @@ Configuration options for query operations.
Sets individual server settings with multiple values for an operation. Items of the collection should `String` values
setDBRoles(Collection dbRoles)
Sets DB roles to be set before executing an operation. Items of the collection should be `String` values
+
setOption(String option, Object value)
+
Sets a configuration option in raw format. This is not a server settings.
### QueryResponse diff --git a/docs/en/integrations/language-clients/java/jdbc-driver.md b/docs/en/integrations/language-clients/java/jdbc-driver.md index 537e0ff058b..88471cc3cd9 100644 --- a/docs/en/integrations/language-clients/java/jdbc-driver.md +++ b/docs/en/integrations/language-clients/java/jdbc-driver.md @@ -16,7 +16,7 @@ import CodeBlock from '@theme/CodeBlock'; `clickhouse-jdbc` implements the standard JDBC interface. Being built on top of [clickhouse-client](/docs/en/integrations/sql-clients/sql-console), it provides additional features like custom type mapping, transaction support, and standard synchronous `UPDATE` and `DELETE` statements, etc., so that it can be easily used with legacy applications and tools. :::note - Latest JDBC (0.7.1) version uses Client-V1 + Latest JDBC (0.7.2) version uses Client-V1 ::: `clickhouse-jdbc` API is synchronous, and generally, it has more overheads(e.g., SQL parsing and type mapping/conversion, etc.). Consider [clickhouse-client](/docs/en/integrations/sql-clients/sql-console) when performance is critical or if you prefer a more direct way to access ClickHouse. @@ -36,9 +36,9 @@ import CodeBlock from '@theme/CodeBlock'; com.clickhouse clickhouse-jdbc - 0.7.1 + 0.7.2 - all + shaded-all ``` @@ -48,7 +48,7 @@ import CodeBlock from '@theme/CodeBlock'; ```kotlin // https://mvnrepository.com/artifact/com.clickhouse/clickhouse-jdbc // use uber jar with all dependencies included, change classifier to http for smaller jar -implementation("com.clickhouse:clickhouse-jdbc:0.7.1:all") +implementation("com.clickhouse:clickhouse-jdbc:0.7.2:shaded-all") ``` @@ -56,7 +56,7 @@ implementation("com.clickhouse:clickhouse-jdbc:0.7.1:all") ```groovy // https://mvnrepository.com/artifact/com.clickhouse/clickhouse-jdbc // use uber jar with all dependencies included, change classifier to http for smaller jar -implementation 'com.clickhouse:clickhouse-jdbc:0.7.1:all' +implementation 'com.clickhouse:clickhouse-jdbc:0.7.2:shaded-all' ``` From 183acacc98d5163aba4fe40978d72f2acf521345 Mon Sep 17 00:00:00 2001 From: Sergey Chernov Date: Fri, 27 Dec 2024 11:24:23 -0800 Subject: [PATCH 2/2] fixed spelling and other review comments --- .../language-clients/java/client-v1.md | 2 +- .../language-clients/java/client-v2.md | 31 +++++++++---------- 2 files changed, 16 insertions(+), 17 deletions(-) diff --git a/docs/en/integrations/language-clients/java/client-v1.md b/docs/en/integrations/language-clients/java/client-v1.md index d7c650da7f9..7884b2b3ff8 100644 --- a/docs/en/integrations/language-clients/java/client-v1.md +++ b/docs/en/integrations/language-clients/java/client-v1.md @@ -15,7 +15,7 @@ import CodeBlock from '@theme/CodeBlock'; Java client library to communicate with a DB server thru its protocols. Current implementation supports only [HTTP interface](/docs/en/interfaces/http). The library provides own API to send requests to a server. :::warning Deprecation -This library will be depreceted on `February, 28, 2025`. It means no releases after and support. +This library will be deprecated soon. Use Client-v2 for new projects ::: ## Setup diff --git a/docs/en/integrations/language-clients/java/client-v2.md b/docs/en/integrations/language-clients/java/client-v2.md index 5d074411e41..35e0974251a 100644 --- a/docs/en/integrations/language-clients/java/client-v2.md +++ b/docs/en/integrations/language-clients/java/client-v2.md @@ -157,7 +157,7 @@ Configuration is defined during client creation. See `com.clickhouse.client.api. | setServerTimeZone(String timeZone) | `timeZone` - string value of java valid timezone ID (see `java.time.ZoneId`) | Sets server side timezone. UTC timezone will be used by default. | | useAsyncRequests(boolean async) | `async` - flag that indicates if the option should be enabled. | Sets if client should execute request in a separate thread. Disabled by default because application knows better how to organize multithreaded tasks and running tasks in separate thread do not help with performance. | | setSharedOperationExecutor(ExecutorService executorService) | `executorService` - instance of executor service. | Sets executor service for operation tasks. | -| setClientNetworkBufferSize(int size) | - `size` - size in bytes | Sets size of a buffer in application memory space that is used to copy data back-and-forth between socket and application. Greater reduces system calls to TCP stack, but affects how much memory is spent on every connection. This buffer is also subject for GC because connections are shortlive. Also keep in mind that allocating big continious block of memory might be a problem. Default is `300,000` bytes | +| setClientNetworkBufferSize(int size) | - `size` - size in bytes | Sets size of a buffer in application memory space that is used to copy data back-and-forth between socket and application. Greater reduces system calls to TCP stack, but affects how much memory is spent on every connection. This buffer is also subject for GC because connections are shortlive. Also keep in mind that allocating big continious block of memory might be a problem. Default is `300,000` bytes. | | retryOnFailures(ClientFaultCause ...causes) | - `causes` - enum constant of `com.clickhouse.client.api.ClientFaultCause` | Sets recoverable/retriable fault types. | | setMaxRetries(int maxRetries) | - `maxRetries` - number of retries | Sets maximum number of retries for failures defined by `retryOnFailures(ClientFaultCause ...causes)` | | allowBinaryReaderToReuseBuffers(boolean reuse) | - `reuse` - flag that indicates if the option should be enabled | Most datasets contain numeric data encoded as small byte sequences. By default reader will allocate required buffer, read data into it and then transform into a target Number class. That may cause significant GC preasure because of many small objects are being allocated and released. If this option is enabled then reader will use preallocated buffers to do numbers transcoding. It is safe because each reader has own set of buffers and readers are used by one thread. | @@ -169,8 +169,7 @@ Configuration is defined during client creation. See `com.clickhouse.client.api. | columnToMethodMatchingStrategy(ColumnToMethodMatchingStrategy strategy) | - `strategy` - implementation of a column-field matching strategy | Sets custom strategy to be used for matching DTO class fields and DB columns when registering DTO. | | useHTTPBasicAuth(boolean useBasicAuth) | - `useBasicAuth` - flag that indicates if the option should be enabled | Sets if basic HTTP authentication should be used for user-password authentication. Default is enabled. Using this type of authentication resolves issues with passwords containing special characters that cannot be transferred over HTTP headers. | | setClientName(String clientName) | - `clientName` - a string representing application name | Sets additional information about calling application. This string will be passed to server as a client name. In case of HTTP protocol it will be passed as a `User-Agent` header. | -| useBearerTokenAuth(String bearerToken) | - `bearerToken` - an encoded bearer token | Specifies whether to use Bearer Authentication and what token to use. The token will be sent as is, so it should be encoded before passing to this method. | -| +| useBearerTokenAuth(String bearerToken) | - `bearerToken` - an encoded bearer token | Specifies whether to use Bearer Authentication and what token to use. The token will be sent as is, so it should be encoded before passing to this method. | ## Common Definitions @@ -356,25 +355,25 @@ Configuration options for insert operations.
setQueryId(String queryId)
-
Sets query ID that will be assigned to the operation. Default: null
+
Sets query ID that will be assigned to the operation. Default: `null`.
setDeduplicationToken(String token)
-
Sets the deduplication token. This token will be sent to the server and can be used to identify the query. Default: null
+
Sets the deduplication token. This token will be sent to the server and can be used to identify the query. Default: `null`.
setInputStreamCopyBufferSize(int size)
-
Copy buffer size. The buffer is used during write operations to copy data from user provided input stream to an output stream. Default: 8196
+
Copy buffer size. The buffer is used during write operations to copy data from user provided input stream to an output stream. Default: `8196`.
serverSetting(String name, String value)
Sets individual server settings for an operation.
serverSetting(String name, Collection values)
-
Sets individual server settings with multiple values for an operation. Items of the collection should `String` values
+
Sets individual server settings with multiple values for an operation. Items of the collection should `String` values.
setDBRoles(Collection dbRoles)
-
Sets DB roles to be set before executing an operation. Items of the collection should be `String` values
+
Sets DB roles to be set before executing an operation. Items of the collection should be `String` values.
setOption(String option, Object value)
-
Sets a configuration option in raw format. This is not a server settings.
+
Sets a configuration option in raw format. This is not a server setting.
### InsertResponse @@ -387,7 +386,7 @@ This object should be closed as soon as possible to release a connection because
OperationMetrics getMetrics()
-
Returns object with operation metrics
+
Returns object with operation metrics.
String getQueryId()
Returns query ID assigned for the operation by application (thru operation settings or by server).
@@ -535,7 +534,7 @@ Configuration options for query operations.
setQueryId(String queryId)
-
Sets query ID that will be assigned to the operation
+
Sets query ID that will be assigned to the operation.
setFormat(ClickHouseFormat format)
Sets response format. See `RowBinaryWithNamesAndTypes` for the full list.
setMaxExecutionTime(Integer maxExecutionTime)
@@ -543,17 +542,17 @@ Configuration options for query operations.
waitEndOfQuery(Boolean waitEndOfQuery)
Requests the server to wait for the and of the query before sending response.
setUseServerTimeZone(Boolean useServerTimeZone)
-
Server timezone (see client config) will be used to parse date/time types in the result of an operation. Default `false`
+
Server timezone (see client config) will be used to parse date/time types in the result of an operation. Default `false`.
setUseTimeZone(String timeZone)
Requests server to use `timeZone` for time conversion. See session_timezone.
serverSetting(String name, String value)
-
Sets individual server settings for an operation
+
Sets individual server settings for an operation.
serverSetting(String name, Collection values)
-
Sets individual server settings with multiple values for an operation. Items of the collection should `String` values
+
Sets individual server settings with multiple values for an operation. Items of the collection should `String` values.
setDBRoles(Collection dbRoles)
-
Sets DB roles to be set before executing an operation. Items of the collection should be `String` values
+
Sets DB roles to be set before executing an operation. Items of the collection should be `String` values.
setOption(String option, Object value)
-
Sets a configuration option in raw format. This is not a server settings.
+
Sets a configuration option in raw format. This is not a server setting.
### QueryResponse