Package com.clickhouse.client.api

Class Client

java.lang.Object
com.clickhouse.client.api.Client
All Implemented Interfaces:
AutoCloseable
public class Client extends Object implements AutoCloseable

Client is the starting point for all interactions with ClickHouse.

Client.Builder is designed to construct a client object with required configuration:



  Client client = new Client.Builder()
        .addEndpoint(Protocol.HTTP, node.getHost(), node.getPort())
        .addUsername("default")
        .build();

When client object is created any operation method can be called on it:



  if (client.ping()) {
      QuerySettings settings = new QuerySettings().setFormat(ClickHouseFormat.RowBinaryWithNamesAndTypes);
      Future<QueryResponse> response = client.query("SELECT * FROM " + table, settings);
      QueryResponse queryResponse = response.get();
  }

Client is thread-safe. It uses exclusive set of object to perform an operation.

  • Method Details

    • getDefaultDatabase

      public String getDefaultDatabase()
      Returns default database name that will be used by operations if not specified.
      Returns:
      String - actual default database name.

    • close

      public void close()
      Frees the resources associated with the client.
      • Shuts down the shared operation executor by calling shutdownNow()
      Specified by:
      close in interface AutoCloseable

    • ping

      public boolean ping()
      Pings the server to check if it is alive
      Returns:
      true if the server is alive, false otherwise

    • ping

      public boolean ping(long timeout)
      Pings the server to check if it is alive. Maximum timeout is 10 minutes.
      Parameters:
      timeout - timeout in milliseconds
      Returns:
      true if the server is alive, false otherwise

    • register

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

      Registers a POJO class and maps its fields to a table schema

      Parameters:
      clazz - - class of a POJO
      schema - - correlating table schema

    • insert

      public CompletableFuture<InsertResponse> insert(String tableName, List<?> data)

      Sends write request to database. List of objects is converted into a most suitable format then it is sent to a server. Members of the list must be pre-registered using register(Class, TableSchema) method:

      
 client.register(SamplePOJO.class, tableSchema);
 List<Object> input = new ArrayList<>();
 // ... Insert some items into input list
 Future<InsertResponse> response = client.insert(tableName, simplePOJOs, settings);
      Parameters:
      tableName - - destination table name
      data - - data stream to insert
      Returns:
      CompletableFuture<InsertResponse> - a promise to insert response

    • insert

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

      Sends write request to database. List of objects is converted into a most suitable format then it is sent to a server. Members of the list must be pre-registered using register(Class, TableSchema) method:

      
 client.register(SamplePOJO.class, tableSchema);
 List<Object> input = new ArrayList<>();
 // ... Insert some items into input list
 Future<InsertResponse> response = client.insert(tableName, simplePOJOs, settings);
      Parameters:
      tableName - - destination table name
      data - - data stream to insert
      settings - - insert operation settings
      Returns:
      CompletableFuture<InsertResponse> - a promise to insert response

    • insert

      public CompletableFuture<InsertResponse> insert(String tableName, InputStream data, com.clickhouse.data.ClickHouseFormat format)

      Sends write request to database. Input data is read from the input stream.

      Parameters:
      tableName - - destination table name
      data - - data stream to insert
      format - - format of the data in the stream
      Returns:
      CompletableFuture<InsertResponse> - a promise to insert response

    • insert

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

      Sends write request to database. Input data is read from the input stream.

      Parameters:
      tableName - - destination table name
      data - - data stream to insert
      format - - format of the data in the stream
      settings - - insert operation settings
      Returns:
      CompletableFuture<InsertResponse> - a promise to insert response

    • query

      public CompletableFuture<QueryResponse> query(String sqlQuery)
      Sends SQL query to server. Default settings are applied.
      Parameters:
      sqlQuery - - complete SQL query.
      Returns:
      CompletableFuture<QueryResponse> - a promise to query response.

    • query

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

      Sends SQL query to server.

      Notes:
      • Server response format can be specified thru `settings` or in SQL query.
      • If specified in both, the `sqlQuery` will take precedence.
      Parameters:
      sqlQuery - - complete SQL query.
      settings - - query operation settings.
      Returns:
      CompletableFuture<QueryResponse> - a promise to query response.

    • query

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

      Sends SQL query to server with parameters. The map `queryParams` should contain keys that match the placeholders in the SQL query.

      For a parametrized query like:

      
 SELECT * FROM table WHERE int_column = {id:UInt8} and string_column = {phrase:String}

      Code to set the queryParams would be:

      
      Map<String, Object> queryParams = new HashMap<>();
      queryParams.put("id", 1);
      queryParams.put("phrase", "hello");
      Notes:
      • Server response format can be specified thru settings or in SQL query.
      • If specified in both, the sqlQuery will take precedence.
      Parameters:
      sqlQuery - - complete SQL query.
      settings - - query operation settings.
      queryParams - - query parameters that are sent to the server. (Optional)
      Returns:
      CompletableFuture<QueryResponse> - a promise to query response.

    • queryRecords

      public CompletableFuture<Records> queryRecords(String sqlQuery)

      Queries data in one of descriptive format and creates a reader out of the response stream.

      Format is selected internally so is ignored when passed in settings. If query contains format statement then it may cause incompatibility error.

      Parameters:
      sqlQuery -
      Returns:

    • queryRecords

      public CompletableFuture<Records> queryRecords(String sqlQuery, QuerySettings settings)

      Queries data in one of descriptive format and creates a reader out of the response stream.

      Format is selected internally so is ignored when passed in settings. If query contains format statement then it may cause incompatibility error.

      Parameters:
      sqlQuery -
      settings -
      Returns:

    • queryAll

      public List<GenericRecord> queryAll(String sqlQuery)

      Queries data in descriptive format and reads result to a collection.

      Use this method for queries that would return only a few records only because client will read whole dataset and convert it into a list of GenericRecord

      Parameters:
      sqlQuery - - SQL query
      Returns:
      - complete list of records

    • getTableSchema

      public TableSchema getTableSchema(String table)

      Fetches schema of a table and returns complete information about each column. Information includes column name, type, default value, etc.

      See register(Class, TableSchema)

      Parameters:
      table - - table name
      Returns:
      TableSchema - Schema of the table

    • getTableSchema

      public TableSchema getTableSchema(String table, String database)

      Fetches schema of a table and returns complete information about each column. Information includes column name, type, default value, etc.

      See register(Class, TableSchema)

      Parameters:
      table - - table name
      database - - database name
      Returns:
      TableSchema - Schema of the table

    • execute

      public CompletableFuture<CommandResponse> execute(String sql, CommandSettings settings)

      Executes a SQL command and doesn't care response. Useful for DDL statements, like `CREATE`, `DROP`, `ALTER`. Method however returns execution errors from a server or summary in case of successful execution.

      Parameters:
      sql - - SQL command
      settings - - execution settings
      Returns:
      CompletableFuture<CommandResponse> - a promise to command response

    • execute

      public CompletableFuture<CommandResponse> execute(String sql)

      Executes a SQL command and doesn't care response. Useful for DDL statements, like `CREATE`, `DROP`, `ALTER`. Method however returns execution errors from a server or summary in case of successful execution.

      Parameters:
      sql - - SQL command
      Returns:
      CompletableFuture<CommandResponse> - a promise to command response

    • newBinaryFormatReader

      public static ClickHouseBinaryFormatReader newBinaryFormatReader(QueryResponse response, TableSchema schema)

      Create an instance of ClickHouseBinaryFormatReader based on response. Table schema is option and only required for ClickHouseFormat.RowBinaryWithNames, ClickHouseFormat.RowBinary. Format ClickHouseFormat.RowBinaryWithDefaults is not supported for output (read operations).

      Parameters:
      response -
      schema -
      Returns:

    • newBinaryFormatReader

      public static ClickHouseBinaryFormatReader newBinaryFormatReader(QueryResponse response)

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • getConfiguration

      public Map<String,String> getConfiguration()
      Returns unmodifiable map of configuration options.
      Returns:
      - configuration options

    • getOperationTimeout

      protected int getOperationTimeout()
      Returns operation timeout in seconds

    • getEndpoints

      public Set<String> getEndpoints()
      Returns unmodifiable set of endpoints.
      Returns:
      - set of endpoints