Package com.clickhouse.client

Interface ClickHouseClient

All Superinterfaces:

AutoCloseable

All Known Implementing Classes:

AbstractClient

public interface ClickHouseClient
extends AutoCloseable

A unified interface defines Java client for ClickHouse. A client can only connect to one ClickHouseNode at a time. When switching from one node to another, connection made to previous node will be closed automatically before new connection being established.

To decouple from concrete implementation tied to specific protocol, it is recommended to use builder() for instantiation. In order to register a new type of client, please add META-INF/services/com.clickhouse.client.ClickHouseClient into your artifact, so that java.util.SerivceLoader can discover the implementation properly in runtime.

Method Summary

Modifier and Type	Method	Description
default boolean	accept(ClickHouseProtocol protocol)	Tests whether the given protocol is supported or not.
static ClickHouseClientBuilder	builder()	Returns a builder for creating a new client.
void	close()
default ClickHouseRequest<?>	connect(ClickHouseNode node)	Connects to a ClickHouse server.
default ClickHouseRequest<?>	connect(ClickHouseNodes nodes)	Connects to a list of managed ClickHouse servers.
default ClickHouseRequest<?>	connect(String enpoints)	Connects to one or more ClickHouse servers.
default ClickHouseRequest<?>	connect(Function<ClickHouseNodeSelector,ClickHouseNode> nodeFunc)	Connects to a ClickHouse server defined by the given Function.
static CompletableFuture<ClickHouseResponseSummary>	dump(ClickHouseNode server, String tableOrQuery, ClickHouseFile file)	Dumps a table or query result from server into a file.
static CompletableFuture<ClickHouseResponseSummary>	dump(ClickHouseNode server, String tableOrQuery, ClickHouseFormat format, ClickHouseCompression compression, OutputStream output)	Dumps a table or query result from server into output stream.
static CompletableFuture<ClickHouseResponseSummary>	dump(ClickHouseNode server, String tableOrQuery, ClickHouseFormat format, ClickHouseCompression compression, String file)	Dumps a table or query result from server into a file.
CompletableFuture<ClickHouseResponse>	execute(ClickHouseRequest<?> request)	Creates an immutable copy of the request if it's not sealed, and sends it to a node hold by the request(e.g.
default ClickHouseResponse	executeAndWait(ClickHouseRequest<?> request)	Synchronous version of execute(ClickHouseRequest).
static ClickHouseOutputStream	getAsyncRequestOutputStream(ClickHouseConfig config, OutputStream output, Runnable postCloseAction)	Gets piped output stream for writing data into request asynchronously.
static ClickHouseInputStream	getAsyncResponseInputStream(ClickHouseConfig config, InputStream input, Runnable postCloseAction)	Gets piped input stream for reading data from response asynchronously.
ClickHouseConfig	getConfig()	Gets the immutable configuration associated with this client.
static ExecutorService	getExecutorService()	Gets default ExecutorService for static methods like dump(), load(), send(), and submit().
default Class<? extends ClickHouseOption>	getOptionClass()	Gets class defining client-specific options.
static ClickHouseOutputStream	getRequestOutputStream(ClickHouseConfig config, OutputStream output, Runnable postCloseAction)	Gets wrapped output stream for writing data into request.
static ClickHouseInputStream	getResponseInputStream(ClickHouseConfig config, InputStream input, Runnable postCloseAction)	Gets wrapped input stream for reading data from response.
default void	init(ClickHouseConfig config)	Initializes the client using immutable configuration extracted from the builder using ClickHouseClientBuilder.getConfig().
static CompletableFuture<ClickHouseResponseSummary>	load(ClickHouseNode server, String table, ClickHouseFile file)	Loads data from given file into a table.
static CompletableFuture<ClickHouseResponseSummary>	load(ClickHouseNode server, String table, ClickHouseFormat format, ClickHouseCompression compression, ClickHouseWriter writer)	Loads data from a custom writer into a table using specified format and compression algorithm.
static CompletableFuture<ClickHouseResponseSummary>	load(ClickHouseNode server, String table, ClickHouseFormat format, ClickHouseCompression compression, InputStream input)	Loads data from input stream into a table using specified format and compression algorithm.
static CompletableFuture<ClickHouseResponseSummary>	load(ClickHouseNode server, String table, ClickHouseFormat format, ClickHouseCompression compression, String file)	Loads data from a file into table using specified format and compression algorithm.
static ClickHouseClient	newInstance(ClickHouseProtocol... preferredProtocols)	Creates a new instance compatible with any of the given protocols.
default boolean	ping(ClickHouseNode server, int timeout)	Tests if the given server is alive or not.
static CompletableFuture<List<ClickHouseResponseSummary>>	send(ClickHouseNode server, String sql, ClickHouseValue[] templates, Object[]... params)	Sends SQL query along with template objects and raw parameters to specified server.
static CompletableFuture<List<ClickHouseResponseSummary>>	send(ClickHouseNode server, String sql, String... more)	Sends one or more SQL queries to specified server, and execute them one by one.
static CompletableFuture<List<ClickHouseResponseSummary>>	send(ClickHouseNode server, String sql, String[][] params)	Sends SQL query along with stringified parameters to specified server.
static CompletableFuture<List<ClickHouseResponseSummary>>	send(ClickHouseNode server, String sql, List<ClickHouseColumn> columns, Object[]... params)	Sends SQL query along with raw parameters(e.g.
static CompletableFuture<ClickHouseResponseSummary>	send(ClickHouseNode server, String sql, Map<String,String> params)	Sends SQL query along with stringified parameters to specified server.
static <T> CompletableFuture<T>	submit(Callable<T> task)	Submits task for execution.

Method Detail

builder

static ClickHouseClientBuilder builder()

Returns a builder for creating a new client.

Returns:

non-null builder, which is mutable and not thread-safe

getExecutorService

static ExecutorService getExecutorService()

Gets default ExecutorService for static methods like dump(), load(), send(), and submit(). It will be shared among all client instances when ClickHouseClientOption.MAX_THREADS_PER_CLIENT is less than or equals to zero.

Returns:

non-null default executor service

getRequestOutputStream

static ClickHouseOutputStream getRequestOutputStream(ClickHouseConfig config,
                                                     OutputStream output,
                                                     Runnable postCloseAction)

Gets wrapped output stream for writing data into request.

Parameters:

config - optional configuration

output - non-null output stream

postCloseAction - custom action will be performed right after closing the output stream

Returns:

wrapped output, or the same output if it's instance of ClickHouseOutputStream

getAsyncRequestOutputStream

static ClickHouseOutputStream getAsyncRequestOutputStream(ClickHouseConfig config,
                                                          OutputStream output,
                                                          Runnable postCloseAction)

Gets piped output stream for writing data into request asynchronously. When config is null or config.isAsync() is false, this method is same as getRequestOutputStream(ClickHouseConfig, OutputStream, Runnable).

Parameters:

config - optional configuration

output - non-null output stream

postCloseAction - custom action will be performed right after closing the output stream

Returns:

wrapped output, or the same output if it's instance of ClickHouseOutputStream

getResponseInputStream

static ClickHouseInputStream getResponseInputStream(ClickHouseConfig config,
                                                    InputStream input,
                                                    Runnable postCloseAction)

Gets wrapped input stream for reading data from response.

Parameters:

config - optional configuration

input - non-null input stream

postCloseAction - custom action will be performed right after closing the input stream

Returns:

wrapped input, or the same input if it's instance of ClickHouseInputStream

getAsyncResponseInputStream

static ClickHouseInputStream getAsyncResponseInputStream(ClickHouseConfig config,
                                                         InputStream input,
                                                         Runnable postCloseAction)

Gets piped input stream for reading data from response asynchronously. When config is null or config.isAsync() is false, this method is same as getResponseInputStream(ClickHouseConfig, InputStream, Runnable).

Parameters:

config - optional configuration

input - non-null input stream

postCloseAction - custom action will be performed right after closing the input stream

Returns:

wrapped input, or the same input if it's instance of ClickHouseInputStream

submit

static <T> CompletableFuture<T> submit(Callable<T> task)

Submits task for execution. Depending on ClickHouseDefaults.ASYNC, it may or may not use getExecutorService() to run the task in a separate thread.

Type Parameters:

T - return type of the task

Parameters:

task - non-null task

Returns:

non-null future object to get result

Throws:

CompletionException - when failed to complete the task

dump

static CompletableFuture<ClickHouseResponseSummary> dump(ClickHouseNode server,
                                                         String tableOrQuery,
                                                         ClickHouseFile file)

Dumps a table or query result from server into a file. File will be created/overwrited as needed.

Parameters:

server - non-null server to connect to

tableOrQuery - table name or a select query

file - output file

Returns:

non-null future object to get result

Throws:

IllegalArgumentException - if any of server, tableOrQuery, and output is null

CompletionException - when error occurred during execution

dump

static CompletableFuture<ClickHouseResponseSummary> dump(ClickHouseNode server,
                                                         String tableOrQuery,
                                                         ClickHouseFormat format,
                                                         ClickHouseCompression compression,
                                                         String file)

Dumps a table or query result from server into a file. File will be created/overwrited as needed.

Parameters:

server - non-null server to connect to

tableOrQuery - table name or a select query

format - output format to use

compression - compression algorithm to use

file - output file

Returns:

non-null future object to get result

Throws:

IllegalArgumentException - if any of server, tableOrQuery, and output is null

CompletionException - when error occurred during execution

dump

static CompletableFuture<ClickHouseResponseSummary> dump(ClickHouseNode server,
                                                         String tableOrQuery,
                                                         ClickHouseFormat format,
                                                         ClickHouseCompression compression,
                                                         OutputStream output)

Dumps a table or query result from server into output stream.

Parameters:

server - non-null server to connect to

tableOrQuery - table name or a select query

format - output format to use, null means ClickHouseFormat.TabSeparated

compression - compression algorithm to use, null means ClickHouseCompression.NONE

output - output stream, which will be closed automatically at the end of the call

Returns:

future object to get result

Throws:

IllegalArgumentException - if any of server, tableOrQuery, and output is null

CompletionException - when error occurred during execution

load

static CompletableFuture<ClickHouseResponseSummary> load(ClickHouseNode server,
                                                         String table,
                                                         ClickHouseFile file)

Loads data from given file into a table.

Parameters:

server - non-null server to connect to

table - non-null target table

file - non-null file

Returns:

future object to get result

Throws:

IllegalArgumentException - if any of server, table, and input is null

CompletionException - when error occurred during execution

load

static CompletableFuture<ClickHouseResponseSummary> load(ClickHouseNode server,
                                                         String table,
                                                         ClickHouseFormat format,
                                                         ClickHouseCompression compression,
                                                         String file)

Loads data from a file into table using specified format and compression algorithm.

Parameters:

server - non-null server to connect to

table - non-null target table

format - input format to use

compression - compression algorithm to use

file - file to load

Returns:

future object to get result

Throws:

IllegalArgumentException - if any of server, table, and input is null

CompletionException - when error occurred during execution

load

static CompletableFuture<ClickHouseResponseSummary> load(ClickHouseNode server,
                                                         String table,
                                                         ClickHouseFormat format,
                                                         ClickHouseCompression compression,
                                                         ClickHouseWriter writer)

Loads data from a custom writer into a table using specified format and compression algorithm.

Parameters:

server - non-null server to connect to

table - non-null target table

format - input format to use

compression - compression algorithm to use

writer - non-null custom writer to generate data

Returns:

future object to get result

Throws:

IllegalArgumentException - if any of server, table, and writer is null

CompletionException - when error occurred during execution

load

static CompletableFuture<ClickHouseResponseSummary> load(ClickHouseNode server,
                                                         String table,
                                                         ClickHouseFormat format,
                                                         ClickHouseCompression compression,
                                                         InputStream input)

Loads data from input stream into a table using specified format and compression algorithm.

Parameters:

server - non-null server to connect to

table - non-null target table

format - input format to use

compression - compression algorithm to use

input - input stream, which will be closed automatically at the end of the call

Returns:

future object to get result

Throws:

IllegalArgumentException - if any of server, table, and input is null

CompletionException - when error occurred during execution

newInstance

static ClickHouseClient newInstance(ClickHouseProtocol... preferredProtocols)

Creates a new instance compatible with any of the given protocols.

Parameters:

preferredProtocols - preferred protocols

Returns:

new instance compatible with any of the given protocols

send

static CompletableFuture<List<ClickHouseResponseSummary>> send(ClickHouseNode server,
                                                               String sql,
                                                               String... more)

Sends one or more SQL queries to specified server, and execute them one by one. Session will be created automatically if there's more than one SQL query.

Parameters:

server - non-null server to connect to

sql - non-null SQL query

more - more SQL queries if any

Returns:

list of ClickHouseResponseSummary one for each execution

Throws:

IllegalArgumentException - if server or sql is null

CompletionException - when error occurred during execution

send

static CompletableFuture<ClickHouseResponseSummary> send(ClickHouseNode server,
                                                         String sql,
                                                         Map<String,String> params)

Sends SQL query along with stringified parameters to specified server.

Parameters:

server - non-null server to connect to

sql - non-null SQL query

params - non-null stringified parameters

Returns:

list of ClickHouseResponseSummary one for each execution

Throws:

IllegalArgumentException - if any of server, sql, and params is null

CompletionException - when error occurred during execution

send

static CompletableFuture<List<ClickHouseResponseSummary>> send(ClickHouseNode server,
                                                               String sql,
                                                               List<ClickHouseColumn> columns,
                                                               Object[]... params)

Sends SQL query along with raw parameters(e.g. byte value for Int8) to specified server. Parameters will be stringified based on given column types.

Parameters:

server - non-null server to connect to

sql - non-null SQL query

columns - non-empty column list

params - non-empty raw parameters

Returns:

list of ClickHouseResponseSummary one for each execution

Throws:

IllegalArgumentException - if columns is null, empty or contains null column

CompletionException - when error occurred during execution

send

static CompletableFuture<List<ClickHouseResponseSummary>> send(ClickHouseNode server,
                                                               String sql,
                                                               ClickHouseValue[] templates,
                                                               Object[]... params)

Sends SQL query along with template objects and raw parameters to specified server.

Parameters:

server - non-null server to connect to

sql - non-null SQL query

templates - non-empty template objects to stringify parameters

params - non-empty raw parameters

Returns:

list of ClickHouseResponseSummary one for each execution

Throws:

IllegalArgumentException - if no named parameter in the query, or templates or params is null or empty

CompletionException - when error occurred during execution

send

static CompletableFuture<List<ClickHouseResponseSummary>> send(ClickHouseNode server,
                                                               String sql,
                                                               String[][] params)

Sends SQL query along with stringified parameters to specified server.

Parameters:

server - non-null server to connect to

sql - non-null SQL query

params - non-null stringified parameters

Returns:

list of ClickHouseResponseSummary one for each execution

Throws:

IllegalArgumentException - if any of server, sql, or params is null; or no named parameter in the query

CompletionException - when error occurred during execution

accept

default boolean accept(ClickHouseProtocol protocol)

Tests whether the given protocol is supported or not. An advanced client can support as many protocols as needed.

Parameters:

protocol - protocol to test, null is treated as ClickHouseProtocol.ANY

Returns:

true if the given protocol is ClickHouseProtocol.ANY or supported by this client; false otherwise

connect

default ClickHouseRequest<?> connect(String enpoints)

Connects to one or more ClickHouse servers. Same as connect(ClickHouseNodes.of(uri)).

Parameters:

enpoints - non-empty URIs separated by comman

Returns:

non-null request object holding references to this client and node provider

connect

default ClickHouseRequest<?> connect(ClickHouseNodes nodes)

Connects to a list of managed ClickHouse servers.

Parameters:

nodes - non-null list of servers to connect to

Returns:

non-null request object holding references to this client and node provider

connect

default ClickHouseRequest<?> connect(ClickHouseNode node)

Connects to a ClickHouse server.

Parameters:

node - non-null server to connect to

Returns:

non-null request object holding references to this client and node provider

connect

default ClickHouseRequest<?> connect(Function<ClickHouseNodeSelector,ClickHouseNode> nodeFunc)

Connects to a ClickHouse server defined by the given Function. You can pass either ClickHouseCluster, ClickHouseNodes or ClickHouseNode here, as all of them implemented the same interface.

Please be aware that this is nothing but an intention, so no network communication happens until execute(ClickHouseRequest) is invoked(usually triggered by request.execute()).

Parameters:

nodeFunc - function to get a ClickHouseNode to connect to

Returns:

non-null request object holding references to this client and node provider

execute

CompletableFuture<ClickHouseResponse> execute(ClickHouseRequest<?> request)

Creates an immutable copy of the request if it's not sealed, and sends it to a node hold by the request(e.g. ClickHouseNode returned from request.getServer()). Connection will be made for the first-time invocation, and then it will be reused in subsequential calls to the extract same ClickHouseNode until close() is invoked.

Parameters:

request - request object which will be sealed(immutable copy) upon execution, meaning you're free to make any change to this object(e.g. prepare for next call using different SQL statement) without impacting the execution

Returns:

non-null future object to get result

Throws:

CompletionException - when error occurred during execution

executeAndWait

default ClickHouseResponse executeAndWait(ClickHouseRequest<?> request)
                                   throws ClickHouseException

Synchronous version of execute(ClickHouseRequest).

Parameters:

request - request object which will be sealed(immutable copy) upon execution

Returns:

non-null response

Throws:

ClickHouseException - when error occurred during execution

getConfig

ClickHouseConfig getConfig()

Gets the immutable configuration associated with this client. In most cases it's the exact same one passed to init(ClickHouseConfig) method for initialization.

Returns:

non-null configuration associated with this client

getOptionClass

default Class<? extends ClickHouseOption> getOptionClass()

Gets class defining client-specific options.

Returns:

class defining client-specific options, null means no specific option

init

default void init(ClickHouseConfig config)

Initializes the client using immutable configuration extracted from the builder using ClickHouseClientBuilder.getConfig(). In general, it's ClickHouseClientBuilder's responsiblity to call this method to initialize the client at the end of ClickHouseClientBuilder.build(). However, sometimes, you may want to call this method explicitly in order to (re)initialize the client based on certain needs. If that's the case, please consider the environment when calling this method to avoid concurrent modification, and keep in mind that 1) ClickHouseConfig is immutable but ClickHouseClient is NOT; and 2) no guarantee that this method is thread-safe.

Parameters:

config - immutable configuration extracted from the builder

ping

default boolean ping(ClickHouseNode server,
                     int timeout)

Tests if the given server is alive or not. It always returns false when server is null or timeout is less than one. Pay attention that it's a synchronous call with minimum overhead(e.g. tiny buffer, no compression and no deserialization etc).

Parameters:

server - non-null server to test

timeout - timeout in millisecond, should be greater than zero

Returns:

true if the server is alive; false otherwise

close

void close()

Specified by:

close in interface AutoCloseable