Package com.clickhouse.client

Class ClickHouseRequest<SelfT extends ClickHouseRequest<SelfT>>

java.lang.Object
com.clickhouse.client.ClickHouseRequest<SelfT>
All Implemented Interfaces:
Serializable
Direct Known Subclasses:
ClickHouseRequest.Mutation
public class ClickHouseRequest<SelfT extends ClickHouseRequest<SelfT>> extends Object implements Serializable
Request object holding references to ClickHouseClient, ClickHouseNode, format, sql, options and settings etc. for execution.
See Also:

  • Field Details

  • Constructor Details

  • Method Details

    • changeProperty

      protected <T> T changeProperty(String property, T oldValue, T newValue)

    • changeServer

      protected ClickHouseNode changeServer(ClickHouseNode currentServer, ClickHouseNode newServer)

    • checkSealed

      protected void checkSealed()

    • getClient

      protected ClickHouseClient getClient()
      Gets client associated with the request.
      Returns:
      non-null client

    • getQuery

      protected String getQuery()
      Gets query, either set by query() or table().
      Returns:
      sql query

    • resetCache

      protected void resetCache()

    • copy

      public ClickHouseRequest<SelfT> copy()
      Creates a copy of this request including listeners. Please pay attention that the same node reference (returned from getServer()) will be copied to the new request as well, meaning failover will change node for both requests.
      Returns:
      copy of this request

    • getManager

      public ClickHouseRequestManager getManager()
      Gets manager for the request, which defaults to ClickHouseRequestManager.getInstance().
      Returns:
      non-null request manager

    • isSealed

      public boolean isSealed()
      Checks if the request is sealed(immutable).
      Returns:
      true if the request is sealed; false otherwise

    • isTransactional

      public boolean isTransactional()
      Checks if the request is bounded with a transaction.
      Returns:
      true if the request is bounded with a transaction; false otherwise

    • hasInputStream

      public boolean hasInputStream()
      Checks if the request contains any input stream or custom writer.
      Returns:
      true if there's input stream or customer writer; false otherwise

    • hasOutputStream

      public boolean hasOutputStream()
      Checks if the response should be redirected to an output stream, which was defined by one of output(*) methods.
      Returns:
      true if response should be redirected to an output stream; false otherwise

    • getServer

      public final ClickHouseNode getServer()
      Gets the server currently connected to. The initial value was determined by the Function passed to constructor, and it may be changed over time when failover is enabled.
      Returns:
      non-null node

    • getConfig

      public ClickHouseConfig getConfig()
      Gets request configuration.
      Returns:
      request configuration

    • getTransaction

      public ClickHouseTransaction getTransaction()

    • getChangeListener

      public final ClickHouseConfigChangeListener<ClickHouseRequest<?>> getChangeListener()

    • getServerListener

      public final BiConsumer<ClickHouseNode,ClickHouseNode> getServerListener()

    • getInputStream

      public Optional<ClickHouseInputStream> getInputStream()
      Gets input stream.
      Returns:
      input stream

    • getWriter

      public Optional<ClickHouseWriter> getWriter()
      Gets custom writer for writing raw request.
      Returns:
      custom writer

    • getOutputStream

      public Optional<ClickHouseOutputStream> getOutputStream()
      Gets output stream.
      Returns:
      output stream

    • getExternalTables

      public List<ClickHouseExternalTable> getExternalTables()
      Gets immutable list of external tables.
      Returns:
      immutable list of external tables

    • getFormat

      public ClickHouseFormat getFormat()
      Gets data format used for communication between server and client.
      Returns:
      data format used for communication between server and client

    • getQueryId

      public Optional<String> getQueryId()
      Gets query id.
      Returns:
      query id

    • getPreparedQuery

      public ClickHouseParameterizedQuery getPreparedQuery()
      Gets prepared query, which is a loosely parsed query with the origianl query and list of parameters.
      Returns:
      prepared query

    • freezeSettings

      public SelfT freezeSettings()
      Freezes settings to discard future changes.
      Returns:
      the request itself

    • unfreezeSettings

      public SelfT unfreezeSettings()
      Unfreezes settings to accept future changes.
      Returns:
      the request itself

    • getSetting

      public <T extends Serializable> T getSetting(String setting, Class<T> valueType)
      Gets typed setting value.
      Type Parameters:
      T - type of the setting value
      Parameters:
      setting - non-null setting key
      valueType - non-null value type
      Returns:
      non-null value

    • getSetting

      public <T extends Serializable> T getSetting(String setting, T defaultValue)
      Gets typed setting value.
      Type Parameters:
      T - type of the setting value
      Parameters:
      setting - non-null setting key
      defaultValue - non-null default value
      Returns:
      non-null value

    • hasSetting

      public boolean hasSetting(String setting)
      Checks if a setting has been defined or not.
      Parameters:
      setting - setting
      Returns:
      true if the setting has been defined; false otherwise

    • getSettings

      public Map<String,Serializable> getSettings()
      Gets immutable settings.
      Returns:
      immutable settings

    • getSessionId

      public Optional<String> getSessionId()
      Gets session id.
      Returns:
      session id

    • getStatements

      public List<String> getStatements()
      Gets list of SQL statements. Same as getStatements(true).
      Returns:
      list of SQL statements

    • getStatements

      public List<String> getStatements(boolean withSettings)
      Gets list of SQL statements.
      Parameters:
      withSettings - true to treat settings as SQL statement; false otherwise
      Returns:
      list of SQL statements

    • compressServerResponse

      public SelfT compressServerResponse(boolean enable)
      Enable or disable compression of server response. Pay attention that ClickHouseClientOption.COMPRESS_ALGORITHM and ClickHouseClientOption.COMPRESS_LEVEL will be used.
      Parameters:
      enable - true to enable compression of server response; false otherwise
      Returns:
      the request itself

    • compressServerResponse

      public SelfT compressServerResponse(ClickHouseCompression compressAlgorithm)
      Enable or disable compression of server response. Pay attention that ClickHouseClientOption.COMPRESS_ALGORITHM and ClickHouseClientOption.COMPRESS_LEVEL will be used.
      Parameters:
      compressAlgorithm - compression algorihtm, null or ClickHouseCompression.NONE means no compression
      Returns:
      the request itself

    • compressServerResponse

      public SelfT compressServerResponse(boolean enable, ClickHouseCompression compressAlgorithm)
      Enable or disable compression of server response. Pay attention that ClickHouseClientOption.COMPRESS_LEVEL will be used.
      Parameters:
      enable - true to enable compression of server response; false otherwise
      compressAlgorithm - compression algorithm, null is treated as ClickHouseCompression.NONE or ClickHouseClientOption.COMPRESS_ALGORITHM depending on whether enabled
      Returns:
      the request itself

    • compressServerResponse

      public SelfT compressServerResponse(boolean enable, ClickHouseCompression compressAlgorithm, int compressLevel)
      Enable or disable compression of server response.
      Parameters:
      enable - true to enable compression of server response; false otherwise
      compressAlgorithm - compression algorithm, null is treated as ClickHouseCompression.NONE or ClickHouseClientOption.COMPRESS_ALGORITHM depending on whether enabled
      compressLevel - compression level
      Returns:
      the request itself

    • decompressClientRequest

      public SelfT decompressClientRequest(boolean enable)
      Enable or disable compression of client request. Pay attention that ClickHouseClientOption.DECOMPRESS_ALGORITHM and ClickHouseClientOption.DECOMPRESS_LEVEL will be used.
      Parameters:
      enable - true to enable compression of client request; false otherwise
      Returns:
      the request itself

    • decompressClientRequest

      public SelfT decompressClientRequest(ClickHouseCompression compressAlgorithm)
      Enable or disable compression of client request. Pay attention that ClickHouseClientOption.DECOMPRESS_LEVEL will be used.
      Parameters:
      compressAlgorithm - compression algorithm, null is treated as ClickHouseCompression.NONE or ClickHouseClientOption.DECOMPRESS_ALGORITHM depending on whether enabled
      Returns:
      the request itself

    • decompressClientRequest

      public SelfT decompressClientRequest(boolean enable, ClickHouseCompression compressAlgorithm)
      Enable or disable compression of client request. Pay attention that ClickHouseClientOption.DECOMPRESS_LEVEL will be used.
      Parameters:
      enable - true to enable compression of client request; false otherwise
      compressAlgorithm - compression algorithm, null is treated as ClickHouseCompression.NONE or ClickHouseClientOption.DECOMPRESS_ALGORITHM depending on whether enabled
      Returns:
      the request itself

    • decompressClientRequest

      public SelfT decompressClientRequest(boolean enable, ClickHouseCompression compressAlgorithm, int compressLevel)
      Enable or disable compression of client request.
      Parameters:
      enable - true to enable compression of client request; false otherwise
      compressAlgorithm - compression algorithm, null is treated as ClickHouseCompression.NONE
      compressLevel - compression level
      Returns:
      the request itself

    • addExternal

      public SelfT addExternal(ClickHouseExternalTable table)
      Adds an external table.
      Parameters:
      table - non-null external table
      Returns:
      the request itself

    • external

      public SelfT external(ClickHouseExternalTable table, ClickHouseExternalTable... more)
      Sets one or more external tables.
      Parameters:
      table - non-null external table
      more - more external tables
      Returns:
      the request itself

    • external

      public SelfT external(Collection<ClickHouseExternalTable> tables)
      Sets external tables.
      Parameters:
      tables - non-null external tables
      Returns:
      the request itself

    • format

      public SelfT format(ClickHouseFormat format)
      Sets format to be used for communication between server and client.
      Parameters:
      format - preferred format, null means reset to default
      Returns:
      the request itself

    • manager

      public SelfT manager(ClickHouseRequestManager manager)
      Sets request manager which is responsible for generating query ID and session ID, as well as transaction creation.
      Parameters:
      manager - request manager
      Returns:
      the request itself

    • freezeOptions

      public SelfT freezeOptions()
      Freezes options to discard future changes.
      Returns:
      the request itself

    • unfreezeOptions

      public SelfT unfreezeOptions()
      Unfreezes options to accept future changes.
      Returns:
      the request itself

    • option

      public SelfT option(ClickHouseOption option, Serializable value)
      Sets an option. option is for configuring client's behaviour, while setting is for server.
      Parameters:
      option - option
      value - value
      Returns:
      the request itself

    • options

      public SelfT options(Map<ClickHouseOption,Serializable> options)
      Sets all options. option is for configuring client's behaviour, while setting is for server.
      Parameters:
      options - options
      Returns:
      the request itself

    • options

      public SelfT options(Properties options)
      Sets all options. option is for configuring client's behaviour, while setting is for server.
      Parameters:
      options - options
      Returns:
      the request itself

    • hasOption

      public boolean hasOption(ClickHouseOption option)
      Checks if a option has been defined or not.
      Parameters:
      option - option
      Returns:
      true if the option has been defined; false otherwise

    • hasOption

      public boolean hasOption(String key)
      Checks if a option has been defined or not.
      Parameters:
      key - key of the option
      Returns:
      true if the option has been defined; false otherwise

    • output

      public SelfT output(ClickHousePassThruStream stream)
      Sets pass-thru stream, to which response will be redirected.
      Parameters:
      stream - non-null pass-thru stream
      Returns:
      the request itself

    • output

      public SelfT output(String file)
      Sets output file, to which response will be redirected.
      Parameters:
      file - non-empty path to the file
      Returns:
      the request itself

    • output

      public SelfT output(String file, ClickHouseCompression compression)
      Sets compressed output file, to which response will be redirected.
      Parameters:
      file - non-empty path to the file
      compression - compression algorithm, null or ClickHouseCompression.NONE means no compression
      Returns:
      the request itself

    • output

      public SelfT output(String file, ClickHouseCompression compression, int compressionLevel)
      Sets compressed output file, to which response will be redirected.
      Parameters:
      file - non-empty path to the file
      compression - compression algorithm, null or ClickHouseCompression.NONE means no compression
      compressionLevel - compression level
      Returns:
      the request itself

    • output

      public SelfT output(OutputStream output)
      Sets output stream, to which response will be redirected.
      Parameters:
      output - non-null output stream
      Returns:
      the request itself

    • output

      public SelfT output(ClickHouseOutputStream output)
      Sets output stream, to which response will be redirected.
      Parameters:
      output - non-null output stream
      Returns:
      the request itself

    • output

      public SelfT output(ClickHouseDeferredValue<ClickHouseOutputStream> output)
      Sets output stream, to which response will be redirected.
      Parameters:
      output - non-null output stream
      Returns:
      the request itself

    • params

      public SelfT params(Collection<String> values)
      Sets stringified parameters. Be aware of SQL injection risk as mentioned in params(String, String...).
      Parameters:
      values - stringified parameters
      Returns:
      the request itself

    • params

      public SelfT params(ClickHouseValue value, ClickHouseValue... more)
      Sets parameters wrapped by ClickHouseValue. Safer but a bit slower than params(String, String...). Consider to reuse ClickHouseValue object and its update methods for less overhead in batch processing.
      Parameters:
      value - parameter
      more - more parameters
      Returns:
      the request itself

    • params

      public SelfT params(ClickHouseValue[] values)
      Sets parameters wrapped by ClickHouseValue. Safer but a bit slower than params(String, String...). Consider to reuse ClickHouseValue object and its update methods for less overhead in batch processing.
      Parameters:
      values - parameters
      Returns:
      the request itself

    • params

      public SelfT params(String value, String... more)
      Sets stringified parameters which are used to substitude named parameters in SQL query without further transformation and validation. Keep in mind that stringified parameter is a SQL expression, meaning it could be a sub-query(SQL injection) in addition to value like number and string.
      Parameters:
      value - stringified parameter
      more - more stringified parameters
      Returns:
      the request itself

    • params

      public SelfT params(String[] values)
      Sets stringified parameters which are used to substitude named parameters in SQL query without further transformation and validation. Keep in mind that stringified parameter is a SQL expression, meaning it could be a sub-query(SQL injection) in addition to value like number and string.
      Parameters:
      values - stringified parameters
      Returns:
      the request itself

    • params

      public SelfT params(Object value, Object... more)
      Set raw parameters, which will later be stringified using ClickHouseValues.convertToSqlExpression(Object). Although it is convenient to use, it's NOT recommended in most cases except for a few parameters and/or testing.
      Parameters:
      value - raw parameter
      more - more raw parameters
      Returns:
      the request itself

    • params

      public SelfT params(Object[] values)
      Set raw parameters, which will later be stringified using ClickHouseValues.convertToSqlExpression(Object). Although it is convenient to use, it's NOT recommended in most cases except for a few parameters and/or testing.
      Parameters:
      values - raw parameters
      Returns:
      the request itself

    • params

      public SelfT params(Map<String,String> namedParams)
      Sets named parameters. Be aware of SQL injection risk as mentioned in params(String, String...).
      Parameters:
      namedParams - named parameters
      Returns:
      the request itself

    • query

      public SelfT query(ClickHouseParameterizedQuery query)
      Sets parameterized query. Same as query(query, null).
      Parameters:
      query - non-null parameterized query
      Returns:
      the request itself

    • query

      public SelfT query(String sql)
      Sets query. Same as query(sql, null).
      Parameters:
      sql - non-empty query
      Returns:
      the request itself

    • query

      public SelfT query(ClickHouseParameterizedQuery query, String queryId)
      Sets parameterized query and optinally query id.
      Parameters:
      query - non-null parameterized query
      queryId - query id, null means no query id
      Returns:
      the request itself

    • query

      public SelfT query(String query, String queryId)
      Sets query and optinally query id.
      Parameters:
      query - non-empty query
      queryId - query id, null means no query id
      Returns:
      the request itself

    • settings

      public SelfT settings(Map<String,Serializable> settings)
      Sets all server settings. When settings is null or empty, it's same as clearSettings().
      Parameters:
      settings - settings
      Returns:
      the request itself

    • clearSettings

      public SelfT clearSettings()
      Clears server settings.
      Returns:
      the request itself

    • clearSession

      public SelfT clearSession()
      Clears session configuration including session id, session check(whether to validate the id), and session timeout. Transaction will be removed as well.
      Returns:
      the request itself

    • session

      public SelfT session(String sessionId)
      Sets current session using custom id. Same as session(sessionId, null, null).
      Parameters:
      sessionId - session id, null means no session
      Returns:
      the request itself

    • session

      public SelfT session(String sessionId, Boolean check)
      Sets session. Same as session(sessionId, check, null).
      Parameters:
      sessionId - session id, null means no session
      check - whether the server should check if the session id exists or not
      Returns:
      the request itself

    • session

      public SelfT session(String sessionId, Integer timeout)
      Sets current session. Same as session(sessionId, null, timeout).
      Parameters:
      sessionId - session id, null means no session
      timeout - timeout in seconds
      Returns:
      the request itself

    • session

      public SelfT session(String sessionId, Boolean check, Integer timeout)
      Sets current session.
      Parameters:
      sessionId - session id, null means no session
      check - whether the server should check if the session id exists or not
      timeout - timeout in seconds
      Returns:
      the request itself

    • set

      public SelfT set(String setting, Serializable value)
      Sets a setting. See https://clickhouse.tech/docs/en/operations/settings/settings/ for more information.
      Parameters:
      setting - non-empty setting to set
      value - value of the setting
      Returns:
      the request itself

    • set

      public SelfT set(String setting, String value)
      Sets a setting. See https://clickhouse.tech/docs/en/operations/settings/settings/ for more information.
      Parameters:
      setting - non-empty setting to set
      value - value of the setting
      Returns:
      the request itself

    • setChangeListener

      public final SelfT setChangeListener(ClickHouseConfigChangeListener<ClickHouseRequest<?>> listener)
      Sets thread-safe change listener. Please keep in mind that the same listener might be shared by multiple requests.
      Parameters:
      listener - thread-safe change listener which may or may not be null
      Returns:
      the request itself

    • setServerListener

      public final SelfT setServerListener(BiConsumer<ClickHouseNode,ClickHouseNode> listener)
      Sets thread-safe server change listener. Please keep in mind that the same listener might be shared by multiple requests.
      Parameters:
      listener - thread-safe server listener which may or may not be null
      Returns:
      the request itself

    • table

      public SelfT table(String table)
      Sets target table. Same as table(table, null).
      Parameters:
      table - non-empty table name
      Returns:
      the request itself

    • table

      public SelfT table(String table, String queryId)
      Sets target table and optionally query id. This will generate a query like SELECT * FROM [table] and override the one set by query(String, String).
      Parameters:
      table - non-empty table name
      queryId - query id, null means no query id
      Returns:
      the request itself

    • transaction

      public SelfT transaction() throws ClickHouseException
      Creates and starts a transaction. Same as transaction(0).
      Returns:
      the request itself
      Throws:
      ClickHouseException - when failed to start or reuse transaction

    • transaction

      public SelfT transaction(int timeout) throws ClickHouseException
      Creates and starts a transaction immediately. Please pay attention that unlike other methods in this class, it will connect to ClickHouse server, allocate session and start transaction right away.
      Parameters:
      timeout - transaction timeout in seconds, zero or negative means same as session timeout
      Returns:
      the request itself
      Throws:
      ClickHouseException - when failed to start or reuse transaction

    • transaction

      public SelfT transaction(ClickHouseTransaction transaction) throws ClickHouseException
      Sets transaction. Any existing transaction, regardless its state, will be replaced by the given one.
      Parameters:
      transaction - transaction
      Returns:
      the request itself
      Throws:
      ClickHouseException - when failed to set transaction

    • use

      public SelfT use(String database)
      Changes current database.
      Parameters:
      database - database name, null means reset to default
      Returns:
      the request itself

    • removeExternal

      public SelfT removeExternal(ClickHouseExternalTable external)
      Removes an external table.
      Parameters:
      external - non-null external table
      Returns:
      the request itself

    • removeExternal

      public SelfT removeExternal(String name)
      Removes an external table by name.
      Parameters:
      name - non-empty external table name
      Returns:
      the request itself

    • removeOption

      public SelfT removeOption(ClickHouseOption option)
      Removes an option.
      Parameters:
      option - option to be removed
      Returns:
      the request itself

    • removeSetting

      public SelfT removeSetting(String setting)
      Removes a setting.
      Parameters:
      setting - name of the setting
      Returns:
      the request itself

    • reset

      public SelfT reset()
      Resets the request to start all over.
      Returns:
      the request itself

    • seal

      public ClickHouseRequest<SelfT> seal()
      Creates a sealed request, which is an immutable copy of the current request. Listeners won't be copied to the sealed instance, because it's immutable.
      Returns:
      sealed request, an immutable copy of the current request

    • write

      public ClickHouseRequest.Mutation write()
      Creates a new request for mutation.
      Returns:
      request for mutation

    • execute

      public CompletableFuture<ClickHouseResponse> execute()
      Executes the request. Same as client.execute(request.seal()).
      Returns:
      non-null future to get response
      Throws:
      CompletionException - when error occurred during execution

    • executeAndWait

      public ClickHouseResponse executeAndWait() throws ClickHouseException
      Synchronous version of execute().
      Returns:
      non-null response
      Throws:
      ClickHouseException - when error occurred during execution

    • executeWithinTransaction

      public ClickHouseResponse executeWithinTransaction() throws ClickHouseException
      Executes the request within an implicit transaction. New transaction will be always created and started right before the query, and it will be committed or rolled back afterwards automatically.
      Returns:
      non-null response
      Throws:
      ClickHouseException - when error occurred during execution

    • executeWithinTransaction

      @Deprecated public ClickHouseResponse executeWithinTransaction(boolean useImplicitTransaction) throws ClickHouseException
      Deprecated.
      will be removed in the future, once the minimum supported version of ClickHouse is 22.7 or above
      Executes the request within an implicit transaction. When useImplicitTransaction is set to true, it enforces the client to use implicit_transaction setting which is only available in ClickHouse 22.7+. Otherwise, new transaction will be always created and started right before the query, and it will be committed or rolled back afterwards automatically.
      Parameters:
      useImplicitTransaction - true to use native implicit transaction requiring ClickHouse 22.7+ with minimum overhead(no session on server side and no additional objects on client side); false to use auto-commit transaction
      Returns:
      non-null response
      Throws:
      ClickHouseException - when error occurred during execution