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(Function<ClickHouseNodeSelector,ClickHouseNode> nodeFunc)	Connects to a ClickHouse server defined by the given Function.
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.
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() when ClickHouseDefaults.ASYNC is true.
default Class<? extends ClickHouseOption>	getOptionClass()	Gets class defining client-specific options.
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, 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() when ClickHouseDefaults.ASYNC is true. It will be shared among all client instances when ClickHouseClientOption.MAX_THREADS_PER_CLIENT is less than or equals to zero.

Returns:

default executor service

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:

future object to get result

Throws:

CompletionException - when failed to complete the task

dump

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

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:

future object to get result

Throws:

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

CompletionException - when error occurred during execution

IOException - when failed to create the file or its parent directories

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,
                                                         ClickHouseFormat format,
                                                         ClickHouseCompression compression,
                                                         String file)
                                                  throws FileNotFoundException

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

FileNotFoundException - when file not found

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(Function<ClickHouseNodeSelector,ClickHouseNode> nodeFunc)

Connects to a ClickHouse server defined by the given Function. You can pass either ClickHouseCluster or ClickHouseNode here, as both 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:

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:

future object to get result

Throws:

CompletionException - 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:

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. Pay attention that it's a synchronous call with minimum overhead(e.g. tiny buffer, no compression and no deserialization etc).

Parameters:

server - server to test

timeout - timeout in millisecond

Returns:

true if the server is alive; false otherwise

close

void close()

Specified by:

close in interface AutoCloseable