عميل Java

​

الإعداد

• Maven Central (صفحة المشروع على الويب): https://mvnrepository.com/artifact/com.clickhouse/client-v2
• الإصدارات الليلية (رابط المستودع): https://central.sonatype.com/repository/maven-snapshots/
• مستودع Artifactory القديم للإصدارات الليلية (رابط المستودع): https://s01.oss.sonatype.org/content/repositories/snapshots/

<dependency>
    <groupId>com.clickhouse</groupId>
    <artifactId>client-v2</artifactId>
    <version>0.9.8</version>
</dependency>

// https://mvnrepository.com/artifact/com.clickhouse/client-v2
implementation("com.clickhouse:client-v2:0.9.8")

// https://mvnrepository.com/artifact/com.clickhouse/client-v2
implementation 'com.clickhouse:client-v2:0.9.8'

​

التهيئة

 Client client = new Client.Builder()
                .addEndpoint("https://clickhouse-cloud-instance:8443/")
                .setUsername(user)
                .setPassword(password)
                .build();

​

المصادقة

 Client client = new Client.Builder()
        .addEndpoint("https://clickhouse-cloud-instance:8443/")
        .setUsername(user)
        .setPassword(password)
        .build();

 Client client = new Client.Builder()
        .addEndpoint("https://clickhouse-cloud-instance:8443/")
        .setAccessToken(userAccessToken)
        .build();

Client client = new Client.Builder()
        .useSSLAuthentication(true)
        .setUsername("some_user")
        .setClientCertificate("some_user.crt")
        .setClientKey("some_user.key")

​

التهيئة

​

إعداد العميل

​

تعريف العميل

client.setClientName("my-app-01/1.0");

my-app-01/1.0 clickhouse-java-v2/0.9.6-SNAPSHOT (Linux; jvm:17.0.17) Apache-HttpClient/5.4.4

​

تحديد العملية

QuerySettings querySettings = new QuerySettings();
querySettings.setQueryId("some-query-id");

QuerySettings querySettings = new QuerySettings();
querySettings.logComment("some-comment");

​

إعدادات الخادم

 try (Client client = new Client.Builder().addEndpoint(Protocol.HTTP, "localhost", mockServer.port(), false)
        .setUsername("default")
        .setPassword(ClickHouseServerForTest.getPassword())
        .compressClientRequest(true)

        // Client level
        .serverSetting("max_threads", "10")
        .serverSetting("async_insert", "1")
        .serverSetting("roles", Arrays.asList("role1", "role2"))

        .build()) {

	// Operation level
	QuerySettings querySettings = new QuerySettings();
	querySettings.serverSetting("session_timezone", "Europe/Zurich");

	...
}

​

HTTP Header مخصص

QuerySettings settings = new QuerySettings()
    .httpHeader(HttpHeaders.REFERER, clientReferer)
    .setQueryId(qId);

​

التعريفات الشائعة

​

ClickHouseFormat

• raw - يجب على المستخدم تحويل ترميز البيانات الخام
• full - يمكن للعميل تحويل ترميز البيانات بنفسه ويقبل تدفق بيانات خام
• - - هذه العملية غير مدعومة في ClickHouse لهذا التنسيق

​

واجهة برمجة تطبيقات الإدراج

​

insert(String tableName, InputStream data, ClickHouseFormat format)

CompletableFuture<InsertResponse> insert(String tableName, InputStream data, ClickHouseFormat format, InsertSettings settings)
CompletableFuture<InsertResponse> insert(String tableName, InputStream data, ClickHouseFormat format)

try (InputStream dataStream = getDataStream()) {
    try (InsertResponse response = client.insert(TABLE_NAME, dataStream, ClickHouseFormat.JSONEachRow,
            insertSettings).get(3, TimeUnit.SECONDS)) {

        log.info("Insert finished: {} rows written", response.getMetrics().getMetric(ServerMetrics.NUM_ROWS_WRITTEN).getLong());
    } catch (Exception e) {
        log.error("Failed to write JSONEachRow data", e);
        throw new RuntimeException(e);
    }
}

​

insert(String tableName, List<?> data, InsertSettings settings)

client.insert(String tableName, List<?> data, InsertSettings settings)
client.insert(String tableName, List<?> data)

// Important step (done once) - register class to pre-compile object serializer according to the table schema.
client.register(ArticleViewEvent.class, client.getTableSchema(TABLE_NAME));

List<ArticleViewEvent> events = loadBatch();

try (InsertResponse response = client.insert(TABLE_NAME, events).get()) {
    // handle response, then it will be closed and connection that served request will be released.
}

​

InsertSettings

​

استجابة الإدراج

​

واجهة برمجة تطبيقات الاستعلام

​

query(String sqlQuery)

CompletableFuture<QueryResponse> query(String sqlQuery, QuerySettings settings)
CompletableFuture<QueryResponse> query(String sqlQuery)

final String sql = "select * from " + TABLE_NAME + " where title <> '' limit 10";

// Default format is RowBinaryWithNamesAndTypesFormatReader so reader have all information about columns
try (QueryResponse response = client.query(sql).get(3, TimeUnit.SECONDS);) {

    // Create a reader to access the data in a convenient way
    ClickHouseBinaryFormatReader reader = client.newBinaryFormatReader(response);

    while (reader.hasNext()) {
        reader.next(); // Read the next record from stream and parse it

        // get values
        double id = reader.getDouble("id");
        String title = reader.getString("title");
        String url = reader.getString("url");

        // collecting data
    }
} catch (Exception e) {
    log.error("Failed to read data", e);
}

// put business logic outside of the reading block to release http connection asap.

​

query(String sqlQuery, Map<String, Object> queryParams, QuerySettings settings)

CompletableFuture<QueryResponse> query(String sqlQuery, Map<String, Object> queryParams, QuerySettings settings)

// define parameters. They will be sent to the server along with the request.
Map<String, Object> queryParams = new HashMap<>();
queryParams.put("param1", 2);

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

    // Create a reader to access the data in a convenient way
    ClickHouseBinaryFormatReader reader = client.newBinaryFormatReader(response);

    while (reader.hasNext()) {
        reader.next(); // Read the next record from stream and parse it

        // reading data
    }

} catch (Exception e) {
    log.error("Failed to read data", e);
}

​

queryAll(String sqlQuery)

List<GenericRecord> queryAll(String sqlQuery)

try {
    log.info("Reading whole table and process record by record");
    final String sql = "select * from " + TABLE_NAME + " where title <> ''";

    // Read whole result set and process it record by record
    client.queryAll(sql).forEach(row -> {
        double id = row.getDouble("id");
        String title = row.getString("title");
        String url = row.getString("url");

        log.info("id: {}, title: {}, url: {}", id, title, url);
    });
} catch (Exception e) {
    log.error("Failed to read data", e);
}

​

QuerySettings

​

QueryResponse

​

أمثلة

• شيفرة المثال متاحة في المستودع
• التنفيذ المرجعي لخدمة Spring متاح في implementation

​

واجهة برمجة التطبيقات المشتركة

​

getTableSchema(String table)

TableSchema getTableSchema(String table)
TableSchema getTableSchema(String table, String database)

​

getTableSchemaFromQuery(String sql)

TableSchema getTableSchemaFromQuery(String sql)

​

TableSchema

​

register(Class<?> clazz, TableSchema schema)

void register(Class<?> clazz, TableSchema schema)

client.register(ArticleViewEvent.class, client.getTableSchema(TABLE_NAME));

​

أمثلة الاستخدام

• client-v2 - المجموعة الأساسية من الأمثلة.
• demo-service - مثال على كيفية استخدام العميل في تطبيق Spring Boot.
• demo-kotlin-service - مثال على كيفية استخدام العميل في تطبيق Ktor ‏(Kotlin).

​

قراءة البيانات

• الطريقة query() التي تُرجع الكائن منخفض المستوى QueryResponse، والذي يحتوي على InputStream للبيانات. تُستخدم عادةً مع ClickHouseBinaryFormatReader لإجراء عمليات قراءة متدفقة، لكنها يمكن استخدامها أيضًا مع أي تنفيذ مخصص آخر للقارئ. كما يوفّر QueryResponse إمكانية الوصول إلى البيانات الوصفية لمجموعة النتائج والمقاييس.
• الطريقة queryAll() مع استخدام GenericRecord للوصول بسهولة إلى الصفوف. في هذه الحالة، تُحمَّل مجموعة النتائج بالكامل إلى الذاكرة.
• الطريقة queryRecords() التي تُرجع com.clickhouse.client.api.query.Records - وهو مكرّر لكائنات GenericRecord. تستخدم هذه الطريقة نهجًا متدفقًا (من دون تحميل أي بيانات إلى الذاكرة) وتستفيد من GenericRecord للوصول إلى البيانات.

​

قراءة المصفوفات

• getList(...) - يقرأ أي Array(...) باعتباره List<T>. خيار افتراضي جيد لعمليات القراءة المرنة المقيّدة بالنوع. يدعم المصفوفات المتداخلة.
• getByteArray(...), getShortArray(...), getIntArray(...), getLongArray(...), getFloatArray(...), getDoubleArray(...), getBooleanArray(...) - الأفضل للمصفوفات أحادية البعد ذات القيم المتوافقة مع الأنواع الأولية.
• getStringArray(...) - مخصّص لـ Array(String) (وكذلك لقيم enum الممثلة كأسماء).
• getObjectArray(...) - خيار عام لأي نوع عنصر في Array(...)، بما في ذلك المصفوفات المتداخلة. استخدمه لقراءة المصفوفات التي تحتوي على قيم يمكن أن تكون NULL والمصفوفات المتداخلة.

try (QueryResponse response = client.query("SELECT * FROM my_table").get()) {
    ClickHouseBinaryFormatReader reader = client.newBinaryFormatReader(response);
    while (reader.next() != null) {
        
        Object[] uint64 = reader.getObjectArray("uint64_arr"); // Array(UInt64) -> BigInteger[]
        Object[] arr2d = reader.getObjectArray("arr2d");       // Array(Array(Int64)) -> Object[]

        // nested arrays are returned as nested Object[]:
        Object[] firstInner = (Object[]) arr2d[0];
        Long firstValue = (Long) firstInner[0];
    }
}

• getList(...) - يقرأ أي Array(...) باعتباره List<T>. خيار افتراضي جيد لعمليات القراءة المرنة المقيّدة بالأنواع. يدعم المصفوفات المتداخلة.
• getByteArray(...), getShortArray(...), getIntArray(...), getLongArray(...), getFloatArray(...), getDoubleArray(...), getBooleanArray(...) - الأفضل للمصفوفات أحادية البعد ذات القيم المتوافقة مع الأنواع البدائية.
• getStringArray(...) - لـ Array(String) (وقيم enum الممثلة على شكل أسماء).
• getObjectArray(...) - خيار عام لأي نوع عنصر في Array(...)، بما في ذلك المصفوفات المتداخلة. استخدمه لقراءة المصفوفات التي تحتوي على قيم قابلة لأن تكون NULL والمصفوفات المتداخلة.

try (QueryResponse response = client.query("SELECT * FROM my_table").get()) {
    List<GenericRecord> rows = client.queryAll(
        "SELECT int_arr, arr2d_nullable FROM test_arrays ORDER BY id");

    for (GenericRecord row : rows) {
        Object[] intArr = row.getObjectArray("int_arr");                 // Array(Int32) -> Integer[]
        Object[] arr2d = row.getObjectArray("arr2d_nullable");           // Array(Array(Nullable(Int32)))

        Object[] inner = (Object[]) arr2d[0];
        Object maybeNull = inner[1]; // may be null
    }
}

​

دليل الترحيل

• لا يُستخدم أي service loader لجلب التنفيذ الفعلي. وتمثّل com.clickhouse.client.api.Client فئة واجهة لمختلف أنواع التنفيذ مستقبلًا.
• عدد مصادر التهيئة أقل: يُمرَّر أحدها إلى الـ builder، ويكون الآخر ضمن إعدادات العملية (QuerySettings، InsertSettings). كان الإصدار السابق يتضمّن تهيئة لكل عقدة، وكان يقرأ متغيرات البيئة في بعض الحالات.

​

تطابق معاملات الإعداد

• com.clickhouse.client.config.ClickHouseDefaults - معلمات التهيئة التي يُفترض تعيينها في معظم حالات الاستخدام، مثل USER وPASSWORD.
• com.clickhouse.client.config.ClickHouseClientOption - معلمات تهيئة خاصة بالعميل، مثل HEALTH_CHECK_INTERVAL.
• com.clickhouse.client.http.config.ClickHouseHttpOption - معلمات تهيئة خاصة بواجهة HTTP، مثل RECEIVE_QUERY_PROGRESS.

​

الفروق العامة

• يستخدم Client V2 عددًا أقل من الفئات الخاصة لزيادة قابلية النقل. على سبيل المثال، يعمل V2 مع أي تنفيذ لـ java.io.InputStream من أجل كتابة البيانات إلى الخادم.
• يكون إعداد async في Client V2 مضبوطًا على off افتراضيًا. وهذا يعني عدم وجود مؤشرات ترابط إضافية وتحكمًا أكبر من التطبيق في العميل. ينبغي أن يكون هذا الإعداد off في معظم حالات الاستخدام. سيؤدي تمكين async إلى إنشاء مؤشر ترابط منفصل لكل طلب. ولا يكون ذلك منطقيًا إلا عند استخدام منفّذ يتحكم فيه التطبيق (انظر com.clickhouse.client.api.Client.Builder#setSharedOperationExecutor)

​

كتابة البيانات

• استخدم أي تنفيذ لـ java.io.InputStream. الإصدار V1 com.clickhouse.data.ClickHouseInputStream مدعوم، لكنه غير مستحسن.
• بمجرد اكتشاف نهاية مجرى الإدخال، ستتم معالجتها وفقًا لذلك. في السابق، كان يجب إغلاق مجرى الإخراج الخاص بالطلب.

InputStream inData = getInData();
ClickHouseRequest.Mutation request = client.read(server)
        .write()
        .table(tableName)
        .format(ClickHouseFormat.TSV);
ClickHouseConfig config = request.getConfig();
CompletableFuture<ClickHouseResponse> future;
try (ClickHousePipedOutputStream requestBody = ClickHouseDataStreamFactory.getInstance()
        .createPipedOutputStream(config)) {
    // start the worker thread which transfer data from the input into ClickHouse
    future = request.data(requestBody.getInputStream()).execute();

    // Copy data from inData stream to requestBody stream

    // We need to close the stream before getting a response
    requestBody.close();

    try (ClickHouseResponse response = future.get()) {
        ClickHouseResponseSummary summary = response.getSummary();
        Assert.assertEquals(summary.getWrittenRows(), numRows, "Num of written rows");
    }
}

InputStream inData = getInData();
InsertSettings settings = new InsertSettings().setInputStreamCopyBufferSize(8198 * 2); // set copy buffer size
try (InsertResponse response = client.insert(tableName, inData, ClickHouseFormat.TSV, settings).get(30, TimeUnit.SECONDS)) {

  // Insert is complete at this point

} catch (Exception e) {
 // Handle exception
}

• توجد طريقة واحدة فقط لاستدعائها. لا حاجة إلى إنشاء كائن طلب إضافي.
• يُغلَق تدفّق جسم الطلب تلقائيًا عند نسخ جميع البيانات.
• تتوفر واجهة برمجة تطبيقات جديدة منخفضة المستوى com.clickhouse.client.api.Client#insert(java.lang.String, java.util.List<java.lang.String>, com.clickhouse.client.api.DataStreamWriter, com.clickhouse.data.ClickHouseFormat, com.clickhouse.client.api.insert.InsertSettings). صُمِّم com.clickhouse.client.api.DataStreamWriter لتطبيق منطق مخصص لكتابة البيانات. على سبيل المثال، لقراءة البيانات من قائمة انتظار.

​

قراءة البيانات

• تُقرأ البيانات بتنسيق RowBinaryWithNamesAndTypes افتراضيًا. وحاليًا لا يُدعَم عند الحاجة إلى ربط البيانات سوى هذا التنسيق.
• يمكن قراءة البيانات كمجموعة من السجلات باستخدام الأسلوب List<GenericRecord> com.clickhouse.client.api.Client#queryAll(java.lang.String). يقرأ هذا الأسلوب البيانات إلى الذاكرة ثم يحرّر الاتصال. ولا حاجة إلى أي معالجة إضافية. يتيح GenericRecord الوصول إلى البيانات، ويجري بعض التحويلات.

Collection<GenericRecord> records = client.queryAll("SELECT * FROM table");
for (GenericRecord record : records) {
    int rowId = record.getInteger("rowID");
    String name = record.getString("name");
    LocalDateTime ts = record.getLocalDateTime("ts");
}