Merge pull request #2820 from ClickHouse/04/06/26/apache_arrow_experimental

[client-v2] Apache Arrow Example

Author: chernser

examples/client-v2-apache-arrow/.gitattributes

@@ -0,0 +1,12 @@
+#
+# https://help.github.com/articles/dealing-with-line-endings/
+#
+# Linux start script should use lf
+/gradlew        text eol=lf
+
+# These are Windows script files and should use crlf
+*.bat           text eol=crlf
+
+# Binary files should be left untouched
+*.jar           binary
+

examples/client-v2-apache-arrow/.gitignore

@@ -0,0 +1,5 @@
+# Ignore Gradle project-specific cache directory
+.gradle
+
+# Ignore Gradle build output directory
+build

examples/client-v2-apache-arrow/README.md

@@ -0,0 +1,79 @@
+# Client V2 Apache Arrow Example
+
+## Overview
+
+This module contains a runnable example demonstrating how to use `client-v2`
+to insert and read data using the [Apache Arrow Stream](https://clickhouse.com/docs/en/interfaces/formats/#arrowstream)
+format (`ClickHouseFormat.ArrowStream`).
+
+The example shows:
+
+- writing a batch into ClickHouse from an Arrow `VectorSchemaRoot` via
+  `ArrowStreamWriter`, using `Decimal256Vector` and `TimeStampMilliVector`;
+- reading rows back from ClickHouse with `ArrowStreamReader` and copying them
+  into another table by streaming the same `VectorSchemaRoot` straight back to
+  `client.insert(...)`.
+
+Unlike the other examples in this repository, this one is built with **Gradle**
+(JDK 17 toolchain) and is not part of the Maven multi-module build.
+
+## Requirements
+
+- JDK 17 or newer (the Gradle toolchain will fetch one if it is missing).
+- A running ClickHouse server reachable from the machine running the example.
+
+Apache Arrow needs access to direct memory and a few internal JDK APIs. The
+required `--add-opens` flags are already wired into `applicationDefaultJvmArgs`
+in `build.gradle.kts`, so running the example through Gradle just works:
+
+```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
+```
+
+If you run the produced jar manually, pass these flags to the JVM yourself.
+
+## How to Run
+
+From this directory:
+
+```shell
+./gradlew run
+```
+
+Connection properties can be supplied as system properties:
+
+- `-DchEndpoint` - Endpoint to connect in the format of URL (default: `http://localhost:8123`)
+- `-DchUser` - ClickHouse user name (default: `default`)
+- `-DchPassword` - ClickHouse user password (default: empty)
+- `-DchDatabase` - ClickHouse database name (default: `default`)
+
+Example with custom connection properties:
+
+```shell
+./gradlew run \
+  -DchEndpoint=http://localhost:8123 \
+  -DchUser=default \
+  -DchPassword= \
+  -DchDatabase=default
+```
+
+To see the wire-level data flow, raise the SLF4J log level:
+
+```shell
+./gradlew run -Dorg.slf4j.simpleLogger.defaultLogLevel=DEBUG
+```
+
+## Executable Example
+
+`com.clickhouse.examples.arrow_format.ReadWriteArrow`
+
+- Creates table `arrow_example (ts DateTime64, val1 Decimal(76,39))` and
+  inserts a batch of 10 000 rows from Arrow vectors using
+  `ClickHouseFormat.ArrowStream`.
+- Creates tables `arrow_read_example` and `arrow_read_example_copy`
+  (`ts DateTime(3), val1 Decimal(76,62)`), populates the first one, reads it
+  back with `ArrowStreamReader`, and streams each batch into the copy table.
+
+The example truncates the demo tables on every run, so it is safe to rerun.

examples/client-v2-apache-arrow/build.gradle.kts

@@ -0,0 +1,58 @@
+/*
+ * This file was generated by the Gradle 'init' task.
+ *
+ * This generated file contains a sample Java application project to get you started.
+ * For more details on building Java & JVM projects, please refer to https://docs.gradle.org/9.2.1/userguide/building_java_projects.html in the Gradle documentation.
+ */
+
+plugins {
+    // Apply the application plugin to add support for building a CLI application in Java.
+    application
+}
+
+repositories {
+    // Use Maven Central for resolving dependencies.
+    mavenCentral()
+    mavenLocal()
+}
+
+dependencies {
+    // Use TestNG framework, also requires calling test.useTestNG() below
+    testImplementation(libs.testng)
+
+    implementation(libs.clickhouseClient)
+
+    // BOM used to keep versions consistent across all Arrow libraries
+    implementation(platform(libs.arrowBom))
+    implementation(libs.arrowVector)
+    implementation(libs.arrowMemory)
+    implementation(libs.arrowCompression)
+
+    // Logging
+    implementation(libs.slf4jSimple)
+    implementation(libs.slf4jApi)
+
+}
+
+// Apply a specific Java toolchain to ease working on different environments.
+java {
+    toolchain {
+        languageVersion = JavaLanguageVersion.of(17)
+    }
+}
+
+application {
+    // Define the main class for the application.
+    mainClass = "com.clickhouse.examples.arrow_format.ReadWriteArrow"
+    applicationDefaultJvmArgs = listOf(
+        "-Dorg.slf4j.simpleLogger.defaultLogLevel=INFO", // change to DEBUG to see wire data flow
+        "--add-opens=java.base/java.nio=ALL-UNNAMED", // needed for Apache Arrow
+        "--add-opens=java.base/sun.nio.ch=ALL-UNNAMED", // needed for Apache Arrow
+        "--add-opens=java.base/jdk.internal.misc=ALL-UNNAMED" // needed for Apache Arrow
+    )
+}
+
+tasks.named<Test>("test") {
+    // Use TestNG for unit tests.
+    useTestNG()
+}

examples/client-v2-apache-arrow/gradle.properties

@@ -0,0 +1,5 @@
+# This file was generated by the Gradle 'init' task.
+# https://docs.gradle.org/current/userguide/build_environment.html#sec:gradle_configuration_properties
+
+org.gradle.configuration-cache=true
+

examples/client-v2-apache-arrow/gradle/libs.versions.toml

@@ -0,0 +1,22 @@
+# This file was generated by the Gradle 'init' task.
+# https://docs.gradle.org/current/userguide/platforms.html#sub::toml-dependencies-format
+
+[versions]
+testng = "7.5.1"
+arrowBom = "19.0.0"
+slf4j = "2.0.17"
+clickhouseClient = "0.9.8"
+
+[libraries]
+testng = { module = "org.testng:testng", version.ref = "testng" }
+clickhouseClient = { module = "com.clickhouse:client-v2", version.ref = "clickhouseClient" }
+
+# Arrow support
+arrowBom = {module = "org.apache.arrow:arrow-bom", version.ref = "arrowBom"}
+arrowVector = {module = "org.apache.arrow:arrow-vector" }
+arrowMemory = {module = "org.apache.arrow:arrow-memory-netty" }
+arrowCompression = { module = "org.apache.arrow:arrow-compression" }
+
+# Logging
+slf4jSimple = { module = "org.slf4j:slf4j-simple", version.ref = "slf4j"}
+slf4jApi = { module = "org.slf4j:slf4j-api", version.ref = "slf4j"}

examples/client-v2-apache-arrow/gradle/wrapper/gradle-wrapper.jar

@@ -0,0 +1,7 @@
+distributionBase=GRADLE_USER_HOME
+distributionPath=wrapper/dists
+distributionUrl=https\://services.gradle.org/distributions/gradle-9.2.1-bin.zip
+networkTimeout=10000
+validateDistributionUrl=true
+zipStoreBase=GRADLE_USER_HOME
+zipStorePath=wrapper/dists