### Compile Examples with Maven Source: https://github.com/clickhouse/clickhouse-java/blob/main/examples/client-v2/README.md Compile the client-v2 examples using Maven. This is a prerequisite for running the executable examples. ```shell mvn clean compile ``` -------------------------------- ### Example: Test client-v2 Module Source: https://github.com/clickhouse/clickhouse-java/blob/main/AGENTS.md An example of running tests specifically for the `client-v2` module. ```bash mvn -pl client-v2 test ``` -------------------------------- ### Run General End-to-End Example Source: https://github.com/clickhouse/clickhouse-java/blob/main/examples/client-v2/README.md Execute the main client-v2 example using Maven. This demonstrates existing read and write flows. ```shell mvn exec:java -Dexec.mainClass="com.clickhouse.examples.client_v2.Main" ``` -------------------------------- ### Running the Gradle Example Source: https://github.com/clickhouse/clickhouse-java/blob/main/examples/client-v2-apache-arrow/README.md Execute the example using Gradle. Connection properties can be provided as system properties. ```shell ./gradlew run ``` -------------------------------- ### Custom Connection Properties for Gradle Example Source: https://github.com/clickhouse/clickhouse-java/blob/main/examples/client-v2-apache-arrow/README.md Example of running the Gradle example with custom connection properties for ClickHouse endpoint, user, password, and database. ```shell ./gradlew run \ -DchEndpoint=http://localhost:8123 \ -DchUser=default \ -DchPassword= \ -DchDatabase=default ``` -------------------------------- ### Example: Test jdbc-v2 Module Source: https://github.com/clickhouse/clickhouse-java/blob/main/AGENTS.md An example of running tests specifically for the `jdbc-v2` module. ```bash mvn -pl jdbc-v2 test ``` -------------------------------- ### Run Sessions Example Source: https://github.com/clickhouse/clickhouse-java/blob/main/examples/client-v2/README.md Execute the sessions example using Maven. This demonstrates client-wide and operation-wide session configuration, including using multiple sessions and handling timeouts. ```shell mvn exec:java -Dexec.mainClass="com.clickhouse.examples.client_v2.Sessions" ``` -------------------------------- ### Example: Test clickhouse-data Module Source: https://github.com/clickhouse/clickhouse-java/blob/main/AGENTS.md An example of running tests specifically for the `clickhouse-data` module. ```bash mvn -pl clickhouse-data test ``` -------------------------------- ### Run Sessions Example with Custom Properties Source: https://github.com/clickhouse/clickhouse-java/blob/main/examples/client-v2/README.md Execute the sessions example with custom connection properties like endpoint, user, password, and database. This allows for flexible connection configurations. ```shell mvn exec:java \ -Dexec.mainClass="com.clickhouse.examples.client_v2.Sessions" \ -DchEndpoint="http://localhost:8123" \ -DchUser="default" \ -DchPassword="" \ -DchDatabase="default" ``` -------------------------------- ### Running Gradle Example with Debug Logging Source: https://github.com/clickhouse/clickhouse-java/blob/main/examples/client-v2-apache-arrow/README.md Run the Gradle example with increased SLF4J log level to DEBUG to observe wire-level data flow. ```shell ./gradlew run -Dorg.slf4j.simpleLogger.defaultLogLevel=DEBUG ``` -------------------------------- ### Run ClickHouse JDBC Example Source: https://github.com/clickhouse/clickhouse-java/blob/main/examples/jdbc/README.md Executes the main class of the JDBC example application using Maven. Supports custom system properties for connection URL and driver versioning. ```shell mvn exec:java -Dexec.mainClass="com.clickhouse.examples.jdbc.Basic" ``` -------------------------------- ### Run Runtime Credentials Switch Demo (Endpoint Only) Source: https://github.com/clickhouse/clickhouse-java/blob/main/examples/client-v2/README.md Execute the runtime credentials switch demo with only the endpoint specified. The example will use default admin credentials. ```shell mvn exec:java -Dexec.mainClass="com.clickhouse.examples.client_v2.RuntimeCredentialsTwoUsers" -Dexec.args="http://localhost:8123" ``` -------------------------------- ### Compile ClickHouse JDBC Example Source: https://github.com/clickhouse/clickhouse-java/blob/main/examples/jdbc/README.md Uses Maven to clean and compile the project source code. This is a prerequisite step before running the application. ```shell mvn clean compile ``` -------------------------------- ### Build and Run ClickHouse R2DBC Application Source: https://github.com/clickhouse/clickhouse-java/blob/main/examples/r2dbc/README.md Commands to compile the project using Maven and launch the Spring WebFlux application. Requires Maven installed in the environment. ```shell mvn clean compile cd clickhouse-r2dbc-spring-webflux-sample mvn exec:java -Dclickhouse.database=default -Dexec.mainClass="com.clickhouse.r2dbc.spring.webflux.sample.Application" ``` -------------------------------- ### Java: Stream ClickHouse Data with Piped Streams Source: https://github.com/clickhouse/clickhouse-java/blob/main/clickhouse-data/README.md Explains how to use ClickHousePipedOutputStream and ClickHouseInputStream for streaming data. This example demonstrates creating a piped output stream with specified buffer size, queue length, and timeout, and then reading from the corresponding input stream. ```java /*** streaming ***/ int bufferSize = 8192; int queueLength = 0; // unlimited int timeout = 30000; // 30 seconds ClickHousePipedOutputStream output = ClickHouseDataStreamFactory.getInstance() .createPipedOutputStream(bufferSize, queueLength, timeout); // write and read in separate threads CompletableFuture future = CompletableFuture.supplyAsync(() -> { try (ClickHouseOuputStream out = output) { for (int i = 0; i<50_000; i++) { out.writeByte(0) } return true; } }); // read will be blocked until there's data available in the "pipe" try (ClickHouseInputStream input = ClickHouseInputStream.of(output.getInputStream(), new FileInputStream("/tmp/mine.txt"))) { // read consolidated input streams byte b = input.readByte(); } ``` -------------------------------- ### Test ClickHouse API Endpoints Source: https://github.com/clickhouse/clickhouse-java/blob/main/examples/r2dbc/README.md Shell commands using curl to interact with the running application. Includes a POST request to add data and a GET request to retrieve click counters. ```shell # add clicks curl -v -X POST -H "application/json" -d '{"domain": "example.org", "path": "/test"}' http://localhost:8080/clicks # get counters curl -v http://localhost:8080/clicks/example.org/ ``` -------------------------------- ### Run Runtime Credentials Switch Demo (Explicit Credentials) Source: https://github.com/clickhouse/clickhouse-java/blob/main/examples/client-v2/README.md Execute the runtime credentials switch demo with explicit admin credentials provided. This demonstrates switching users on the same client instance at runtime. ```shell mvn exec:java -Dexec.mainClass="com.clickhouse.examples.client_v2.RuntimeCredentialsTwoUsers" -Dexec.args="http://localhost:8123 admin_user admin_password" ``` -------------------------------- ### Initialize ClickHouse Database Schema Source: https://github.com/clickhouse/clickhouse-java/blob/main/examples/r2dbc/README.md SQL script to create a database and a SummingMergeTree table for tracking click counts. This schema is intended to be executed against a ClickHouse server instance. ```sql create database clickdb; create table if not exists clickdb.clicks ( domain String, path String, cdate DateTime, count UInt64 ) engine = SummingMergeTree(count) order by (domain, path, cdate); ``` -------------------------------- ### Java: Compress and Decompress ClickHouse Data Source: https://github.com/clickhouse/clickhouse-java/blob/main/clickhouse-data/README.md Shows how to perform compression and decompression using ClickHouseCompressionAlgorithm with supported algorithms like ZSTD and LZ4. It demonstrates decompressing data from an input stream and compressing data to an output stream. ```java /*** compression/decompression ***/ int level = -1; ClickHouseInputStream input = ClickHouseCompressionAlgorithm.of(ClickHouseCompression.ZSTD) .decompress(null, new FileInputStream("/tmp/compressed.data"), bufferSize, level, null); ClickHouseOutputStream output = ClickHouseCompressionAlgorithm.of(ClickHouseCompression.LZ4) .compress(null, new FileInputStream("/tmp/compressed.data"), bufferSize, level, null); input.pipe(output); ``` -------------------------------- ### Compression and Decompression Source: https://github.com/clickhouse/clickhouse-java/blob/main/clickhouse-data/README.md Shows how to use `ClickHouseCompressionAlgorithm` for compressing and decompressing data using algorithms like ZSTD and LZ4. ```APIDOC ## Compression/Decompression ### Description This section illustrates how to perform compression and decompression operations using the `ClickHouseCompressionAlgorithm` class. Examples are provided for ZSTD decompression and LZ4 compression, specifying buffer size, compression level, and input/output streams. ### Method N/A (Code Example) ### Endpoint N/A (Library Usage) ### Parameters N/A ### Request Example ```java /*** compression/decompression ***/ int level = -1; ClickHouseInputStream input = ClickHouseCompressionAlgorithm.of(ClickHouseCompression.ZSTD) .decompress(null, new FileInputStream("/tmp/compressed.data"), bufferSize, level, null); ClickHouseOutputStream output = ClickHouseCompressionAlgorithm.of(ClickHouseCompression.LZ4) .compress(null, new FileInputStream("/tmp/compressed.data"), bufferSize, level, null); input.pipe(output); ``` ### Response N/A (Code Example) ### Response Example N/A ``` -------------------------------- ### Build Native JDBC Binary Source: https://github.com/clickhouse/clickhouse-java/blob/main/CONTRIBUTING.md Maven commands to build a native JDBC driver binary using GraalVM and optionally compress it with UPX. ```bash cd clickhouse-java mvn -DskipTests clean install cd clickhouse-jdbc mvn -DskipTests -Pnative clean package upx -7 -k target/clickhouse-jdbc-bin ``` -------------------------------- ### Generate Benchmark Dataset Source: https://github.com/clickhouse/clickhouse-java/blob/main/performance/README.md Uses the Maven exec plugin to run the DataSetGenerator class. It requires an input SQL file and specifies the dataset name and row count. ```shell mvn compile exec:exec -Dexec.executable=java -Dexec.args="-classpath %classpath com.clickhouse.benchmark.data.DataSetGenerator -input sample_dataset.sql -name default -rows 10" ``` -------------------------------- ### Run Module with Dependencies using Maven Source: https://github.com/clickhouse/clickhouse-java/blob/main/AGENTS.md Execute tests for a module and its dependencies. Specify the module using `-pl` and include dependencies with `-am`. ```bash mvn -pl -am test ``` -------------------------------- ### Basic Authentication with Username and Password Source: https://github.com/clickhouse/clickhouse-java/blob/main/docs/authentication.md Configure username and password for basic authentication when initializing the client. Use this for standard username/password protected ClickHouse instances. ```java Client client = new Client.Builder() .addEndpoint("http://localhost:8123") .setUsername("my_user") .setPassword("my_password") .build(); ``` -------------------------------- ### Clone Repository Source: https://github.com/clickhouse/clickhouse-java/blob/main/CONTRIBUTING.md Commands to clone the ClickHouse-Java repository and navigate to the project directory. ```bash git clone https://github.com/[YOUR_USERNAME]/clickhouse-java cd clickhouse-java ``` -------------------------------- ### Execute JMH Benchmarks Source: https://github.com/clickhouse/clickhouse-java/blob/main/performance/README.md Commands to run benchmarks using Maven. Includes default execution and custom configurations for measurement iterations. ```shell mvn compile exec:exec ``` ```shell mvn compile exec:exec -Dexec.executable=java -Dexec.args="-classpath %classpath com.clickhouse.benchmark.BenchmarkRunner -m 3" ``` -------------------------------- ### Dependency and Serialization/Deserialization Source: https://github.com/clickhouse/clickhouse-java/blob/main/clickhouse-data/README.md Shows how to add the clickhouse-data dependency and demonstrates the process of serializing and deserializing data using ClickHouseDataConfig, ClickHouseColumn, and ClickHouseDataProcessor. ```APIDOC ## Dependency and Serialization/Deserialization ### Description This section covers adding the `clickhouse-data` library as a Maven dependency and provides an example of serializing and deserializing data. It utilizes `ClickHouseDataConfig` for configuration, `ClickHouseColumn` for defining data structure, and `ClickHouseDataProcessor` for handling the data transformation. ### Method N/A (Code Example) ### Endpoint N/A (Library Usage) ### Parameters N/A ### Request Example ```xml com.clickhouse clickhouse-data 0.4.2 ``` ```java /*** serialization/deserialization ***/ ClickHouseDataConfig config = ...; List columns = ClickHouseColumn.parse("a String, b Int32"); ByteArrayOutputStream out = new ByteArrayOutputStream(); try (ClickHouseOutputStream output = ClickHouseOutputStream.of(out)) { // find a suitable processor based on config.getFormat() ClickHouseDataProcessor processor = ClickHouseDataStreamFactory.getInstance() .getProcessor(config, null, output, null, columns); // let's reuse same wrapper class for both columns ClickHouseValue v = ClickHouseIntegerValue.ofNull(); for (int i=0; i<50_000; i++) { v.update(i); for (ClickHouseSerializer s : processor.getSerializers()) { s.serialize(v, output); } } } byte[] bytes = out.toByteArray(); ``` ### Response N/A (Code Example) ### Response Example N/A ``` -------------------------------- ### Configure Maven Toolchains Source: https://github.com/clickhouse/clickhouse-java/blob/main/CONTRIBUTING.md XML configuration for ~/.m2/toolchains.xml to specify JDK 17 for multi-release JAR builds. ```xml jdk 17 /usr/lib/jvm/java-17-openjdk ``` -------------------------------- ### Run Module Tests with Maven Source: https://github.com/clickhouse/clickhouse-java/blob/main/AGENTS.md Use this command to run tests for a specific module. Replace `` with the target module name. ```bash mvn -pl test ``` -------------------------------- ### Type Conversion Source: https://github.com/clickhouse/clickhouse-java/blob/main/clickhouse-data/README.md Illustrates how to perform type conversions using the `ClickHouseValue` class, converting string values to various primitive types and updating values. ```APIDOC ## Type Conversion ### Description This section demonstrates the type conversion capabilities of the `clickhouse-data` library. It shows how to create a `ClickHouseValue` from a string, convert it to different primitive types (byte, int, long), and update its value. ### Method N/A (Code Example) ### Endpoint N/A (Library Usage) ### Parameters N/A ### Request Example ```java /*** type conversion ***/ ClickHouseValue value = ClickHouseStringValue.of("123"); byte b = value.asByte(); int i = value.asInteger(); long l = value.asLong(); value.update(l + i + b); // "369" ``` ### Response N/A (Code Example) ### Response Example N/A ``` -------------------------------- ### Test Integration Properties Source: https://github.com/clickhouse/clickhouse-java/blob/main/CONTRIBUTING.md Configuration file for test.properties to define custom ClickHouse server connection details for integration tests. ```properties # ClickHouse server for integration test clickhouseServer=x.x.x.x # custom HTTP proxy for integration test proxyAddress=: ``` -------------------------------- ### Streaming Data Source: https://github.com/clickhouse/clickhouse-java/blob/main/clickhouse-data/README.md Explains how to handle streaming data using `ClickHousePipedOutputStream` and `ClickHouseInputStream`, including writing data in one thread and reading in another. ```APIDOC ## Streaming Data ### Description This section details the streaming capabilities of the library, using `ClickHousePipedOutputStream` for writing and `ClickHouseInputStream` for reading. It demonstrates a common pattern of writing data in a separate thread and reading it concurrently, with configurable buffer sizes, queue lengths, and timeouts. ### Method N/A (Code Example) ### Endpoint N/A (Library Usage) ### Parameters N/A ### Request Example ```java /*** streaming ***/ int bufferSize = 8192; int queueLength = 0; // unlimited int timeout = 30000; // 30 seconds ClickHousePipedOutputStream output = ClickHouseDataStreamFactory.getInstance() .createPipedOutputStream(bufferSize, queueLength, timeout); // write and read in separate threads CompletableFuture future = CompletableFuture.supplyAsync(() -> { try (ClickHouseOuputStream out = output) { for (int i = 0; i<50_000; i++) { out.writeByte(0) } return true; } }); // read will be blocked until there's data available in the "pipe" try (ClickHouseInputStream input = ClickHouseInputStream.of(output.getInputStream(), new FileInputStream("/tmp/mine.txt"))) { // read consolidated input streams byte b = input.readByte(); } ``` ### Response N/A (Code Example) ### Response Example N/A ``` -------------------------------- ### Token-based Authentication with Custom Access Token Source: https://github.com/clickhouse/clickhouse-java/blob/main/docs/authentication.md Configure the client with a custom access token, including the scheme prefix if necessary. The provided value is used directly in the Authorization header. ```java Client client = new Client.Builder() .addEndpoint("http://localhost:8123") .setAccessToken("Bearer my_access_token") // value used as-is .build(); ``` -------------------------------- ### JVM Arguments for Apache Arrow Source: https://github.com/clickhouse/clickhouse-java/blob/main/examples/client-v2-apache-arrow/README.md These JVM arguments are required for Apache Arrow to access direct memory and internal JDK APIs. They are typically configured in the Gradle build script. ```text --add-opens=java.base/java.nio=ALL-UNNAMED --add-opens=java.base/sun.nio.ch=ALL-UNNAMED --add-opens=java.base/jdk.internal.misc=ALL-UNNAMED ``` -------------------------------- ### Java: Convert ClickHouse Data Types Source: https://github.com/clickhouse/clickhouse-java/blob/main/clickhouse-data/README.md Illustrates type conversion capabilities within the clickhouse-data library. It shows how to create a ClickHouseStringValue and convert it to various primitive types like byte, int, and long, and then update the value. ```java /*** type conversion ***/ ClickHouseValue value = ClickHouseStringValue.of("123"); byte b = value.asByte(); int i = value.asInteger(); long l = value.asLong(); value.update(l + i + b); // "369" ``` -------------------------------- ### Token-based Authentication with Bearer Token Source: https://github.com/clickhouse/clickhouse-java/blob/main/docs/authentication.md Configure the client to use a bearer token for authentication. The client automatically prepends 'Bearer ' to the provided token. ```java Client client = new Client.Builder() .addEndpoint("http://localhost:8123") .useBearerTokenAuth("my_access_token") .build(); ``` -------------------------------- ### Configure Client with Custom HTTP Headers Source: https://github.com/clickhouse/clickhouse-java/blob/main/docs/authentication.md Inject arbitrary HTTP headers into all client requests using the builder's httpHeader method. Useful for passing custom API keys or authorization tokens. ```java Client client = new Client.Builder() .addEndpoint("http://localhost:8123") // Example: Passing a custom API key header .httpHeader("X-API-Key", "my_custom_api_key") // Example: Passing a custom Authorization header .httpHeader("Authorization", "CustomScheme my_token") .build(); ``` -------------------------------- ### Update Access Token at Runtime Source: https://github.com/clickhouse/clickhouse-java/blob/main/docs/authentication.md Dynamically update the access token at runtime, including any necessary scheme prefix. The value is used verbatim in the Authorization header. ```java client.updateAccessToken("Bearer new_access_token"); // -> Authorization: Bearer new_access_token ``` -------------------------------- ### Java: Serialize and Deserialize ClickHouse Data Source: https://github.com/clickhouse/clickhouse-java/blob/main/clickhouse-data/README.md Demonstrates how to serialize and deserialize ClickHouse data using ClickHouseDataConfig, ClickHouseColumn, and ClickHouseDataProcessor. It handles data writing to a ByteArrayOutputStream and reading it back, supporting various data types and formats. ```java /*** serialization/deserialization ***/ ClickHouseDataConfig config = ...; List columns = ClickHouseColumn.parse("a String, b Int32"); ByteArrayOutputStream out = new ByteArrayOutputStream(); try (ClickHouseOutputStream output = ClickHouseOutputStream.of(out)) { // find a suitable processor based on config.getFormat() ClickHouseDataProcessor processor = ClickHouseDataStreamFactory.getInstance() .getProcessor(config, null, output, null, columns); // let's reuse same wrapper class for both columns ClickHouseValue v = ClickHouseIntegerValue.ofNull(); for (int i=0; i<50_000; i++) { v.update(i); for (ClickHouseSerializer s : processor.getSerializers()) { s.serialize(v, output); } } } byte[] bytes = out.toByteArray(); ``` -------------------------------- ### Mutual TLS (mTLS) Authentication Configuration Source: https://github.com/clickhouse/clickhouse-java/blob/main/docs/authentication.md Configure the client for Mutual TLS authentication using client certificates and private keys. Ensure SSL authentication is enabled and provide paths to the certificate and key files. ```java Client client = new Client.Builder() .addEndpoint("https://localhost:8443") .useSSLAuthentication(true) .setClientCertificate("/path/to/client.crt") .setClientKey("/path/to/client.key") // Optionally provide the root CA certificate if the server uses a self-signed cert .setRootCertificate("/path/to/ca.crt") .build(); ``` -------------------------------- ### Update Username and Password at Runtime Source: https://github.com/clickhouse/clickhouse-java/blob/main/docs/authentication.md Dynamically update username and password for subsequent requests without re-initializing the client. This method is thread-safe and applies to new requests. ```java client.updateUserAndPassword("new_user", "new_password"); ``` -------------------------------- ### Update Bearer Token at Runtime Source: https://github.com/clickhouse/clickhouse-java/blob/main/docs/authentication.md Dynamically update the bearer token for subsequent requests. This method adds the 'Bearer ' prefix automatically. ```java client.updateBearerToken("new_access_token"); // -> Authorization: Bearer new_access_token ``` === COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.