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.

Field Summary

Fields

Modifier and Type	Field	Description
static final Logger	LOG

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()
static CompletableFuture<ClickHouseResponseSummary>	dump(ClickHouseNode server, String tableOrQuery, ClickHousePassThruStream stream)	Dumps a table or query result from server into the given pass-thru stream.
static CompletableFuture<ClickHouseResponseSummary>	dump(ClickHouseNode server, String tableOrQuery, OutputStream output, ClickHouseCompression compression, ClickHouseFormat format)	Dumps a table or query result from server into output stream.
static CompletableFuture<ClickHouseResponseSummary>	dump(ClickHouseNode server, String tableOrQuery, String file, ClickHouseCompression compression, ClickHouseFormat format)	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, ClickHousePassThruStream stream)	Loads data from the given pass-thru stream into a table.
static CompletableFuture<ClickHouseResponseSummary>	load(ClickHouseNode server, String table, ClickHouseWriter writer, ClickHouseCompression compression, ClickHouseFormat format)	Loads data from a customer writer into table using specified format and compression algorithm.
static CompletableFuture<ClickHouseResponseSummary>	load(ClickHouseNode server, String table, InputStream input, ClickHouseCompression compression, ClickHouseFormat format)	Loads data from input stream into a table using specified format and compression algorithm.
static CompletableFuture<ClickHouseResponseSummary>	load(ClickHouseNode server, String table, String file, ClickHouseCompression compression, ClickHouseFormat format)	Loads data from a file into table using specified format and compression algorithm.
static ClickHouseClient	newInstance(ClickHouseCredentials defaultCredentials, ClickHouseProtocol... preferredProtocols)	Creates a new instance with default credentials compatible with any of the given protocols.
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.
default ClickHouseRequest<?>	read(ClickHouseNode node)	Connects to a ClickHouse server to read.
default ClickHouseRequest<?>	read(ClickHouseNodes nodes)	Connects to a list of managed ClickHouse servers to read.
default ClickHouseRequest<?>	read(String endpoints)	Connects to one or more ClickHouse servers to read.
default ClickHouseRequest<?>	read(Function<ClickHouseNodeSelector,ClickHouseNode> nodeFunc, Map<ClickHouseOption,Serializable> options)	Connects to a ClickHouse server to read.
static void	run(Runnable task)	Runs the given task immediately in current thread.
static <T> T	run(Callable<T> task)	Runs the given task immediately in current thread.
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 CompletableFuture<Void>	submit(Runnable task)	Submits task for execution.
static <T> CompletableFuture<T>	submit(Callable<T> task)	Submits task for execution.
default ClickHouseRequest.Mutation	write(ClickHouseNode node)	Writes into a ClickHouse server.

Field Details

LOG

static final Logger LOG

Method Details

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, config.isAsync() is false, or request buffering mode is ClickHouseBufferingMode.RESOURCE_EFFICIENT, this method will be 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, config.isAsync() is false, or response buffering mode is ClickHouseBufferingMode.RESOURCE_EFFICIENT, this method will be 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

run

static <T> T run(Callable<T> task)

Runs the given task immediately in current thread. Exception will be wrapped as CompletionException.

Type Parameters:

T - return type of the task

Parameters:

task - non-null task to run

Returns:

result which may or may not be null

Throws:

CompletionException - when failed to execute the task

run

static void run(Runnable task)

Runs the given task immediately in current thread. Exception will be wrapped as CompletionException.

Parameters:

task - non-null task to run

Throws:

CompletionException - when failed to execute the task

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 in synchronous mode

submit

static CompletableFuture<Void> submit(Runnable task)

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

Parameters:

task - non-null task

Returns:

null

Throws:

CompletionException - when failed to complete the task in synchronous mode

dump

static CompletableFuture<ClickHouseResponseSummary> dump(ClickHouseNode server,
 String tableOrQuery,
 ClickHousePassThruStream stream)

Dumps a table or query result from server into the given pass-thru stream. Pass ClickHouseFile to dump data into a file, which may or may not be compressed.

Parameters:

server - non-null server to connect to

tableOrQuery - table name or a select query

stream - non-null pass-thru stream

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

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

compression - compression algorithm to use

format - output format to use

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,
 OutputStream output,
 ClickHouseCompression compression,
 ClickHouseFormat format)

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,
 ClickHousePassThruStream stream)

Loads data from the given pass-thru stream into a table. Pass ClickHouseFile to load data from a file, which may or may not be compressed.

Parameters:

server - non-null server to connect to

table - non-null target table

stream - non-null pass-thru stream

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,
 ClickHouseWriter writer,
 ClickHouseCompression compression,
 ClickHouseFormat format)

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

Parameters:

server - non-null server to connect to

table - non-null target table

writer - non-null custom writer to produce data

compression - compression algorithm to use

format - input format to use

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

Loads data from a file into table using specified format and compression algorithm. Same as load(server, table, ClickHouseFile.of(file, compression, format))

Parameters:

server - non-null server to connect to

table - non-null target table

file - file to load

compression - compression algorithm to use

format - input format to use

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,
 InputStream input,
 ClickHouseCompression compression,
 ClickHouseFormat format)

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

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

compression - compression algorithm to use

format - input format to use

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

newInstance

static ClickHouseClient newInstance(ClickHouseCredentials defaultCredentials,
 ClickHouseProtocol... preferredProtocols)

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

Parameters:

defaultCredentials - default credentials

preferredProtocols - preferred protocols

Returns:

new instance compatible with any of the given protocols using default credentials

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

read

default ClickHouseRequest<?> read(String endpoints)

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

Parameters:

endpoints - non-empty connection string separated by comma

Returns:

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

read

default ClickHouseRequest<?> read(ClickHouseNodes nodes)

Connects to a list of managed ClickHouse servers to read.

Parameters:

nodes - non-null list of servers for read

Returns:

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

read

default ClickHouseRequest<?> read(ClickHouseNode node)

Connects to a ClickHouse server to read.

Parameters:

node - non-null server for read

Returns:

non-null request object holding references to this client and server

read

default ClickHouseRequest<?> read(Function<ClickHouseNodeSelector,ClickHouseNode> nodeFunc,
 Map<ClickHouseOption,Serializable> options)

Connects to a ClickHouse server to read.

Parameters:

nodeFunc - function to get a ClickHouseNode to connect to

options - optional client options for connecting to the server

Returns:

non-null request object holding references to this client and server

write

default ClickHouseRequest.Mutation write(ClickHouseNode node)

Writes into a ClickHouse server.

Parameters:

node - non-null server for write

Returns:

non-null request object holding references to this client and server

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