Package com.clickhouse.client

Class ClickHouseRequest<SelfT extends ClickHouseRequest<SelfT>>

    • Method Detail

      • changeProperty

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

      • 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

      • 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.
        Returns:
        true if there's input stream; 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

      • 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

      • getInputFormat

        public ClickHouseFormat getInputFormat()
        Gets data format used for input(e.g. writing data into server).
        Returns:
        data format for input

      • 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

      • getSettings

        public Map<String,​Object> 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,
                                    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,
                                     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

      • 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

      • 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

      • output

        public SelfT output​(ClickHouseFile file)
        Sets output file, to which response will be redirected.
        Parameters:
        file - non-null output file
        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​(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

      • 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[] 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.
        Parameters:
        settings - 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

      • 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