Command-line Client

    Install it from the clickhouse-client package and run it with the command clickhouse-client.

    Different client and server versions are compatible with one another, but some features may not be available in older clients. We recommend using the same version of the client as the server app. When you try to use a client of the older version, then the server, clickhouse-client displays the message:

    1. ClickHouse client version is older than ClickHouse server. It may lack support for new features.

    The client can be used in interactive and non-interactive (batch) mode.
    To use batch mode, specify the ‘query’ parameter, or send data to ‘stdin’ (it verifies that ‘stdin’ is not a terminal), or both.
    Similar to the HTTP interface, when using the ‘query’ parameter and sending data to ‘stdin’, the request is a concatenation of the ‘query’ parameter, a line feed, and the data in ‘stdin’. This is convenient for large INSERT queries.

    Example of using the client to insert data:

    In batch mode, the default data format is TabSeparated. You can set the format in the FORMAT clause of the query.

    By default, you can only process a single query in batch mode. To make multiple queries from a “script,” use the —multiquery parameter. This works for all queries except INSERT. Query results are output consecutively without additional separators.
    Similarly, to process a large number of queries, you can run ‘clickhouse-client’ for each query. Note that it may take tens of milliseconds to launch the ‘clickhouse-client’ program.

    In interactive mode, you get a command line where you can enter queries.

    If multiline is specified: To run a query, end it with a semicolon and press Enter. If the semicolon was omitted at the end of the entered line, you will be asked to enter the next line of the query.

    Only a single query is run, so everything after the semicolon is ignored.

    You can specify \G instead of or after the semicolon. This indicates Vertical format. In this format, each value is printed on a separate line, which is convenient for wide tables. This unusual feature was added for compatibility with the MySQL CLI.

    The command line is based on ‘replxx’ (similar to ‘readline’). In other words, it uses the familiar keyboard shortcuts and keeps a history.
    The history is written to ~/.clickhouse-client-history.

    By default, the format used is PrettyCompact. You can change the format in the FORMAT clause of the query, or by specifying \G at the end of the query, using the --format or --vertical argument in the command line, or using the client configuration file.

    To exit the client, press Ctrl+D (or Ctrl+C), or enter one of the following instead of a query: “exit”, “quit”, “logout”, “exit;”, “quit;”, “logout;”, “q”, “Q”, “:q”

    When processing a query, the client shows:

    1. Progress, which is updated no more than 10 times per second (by default). For quick queries, the progress might not have time to be displayed.
    2. The formatted query after parsing, for debugging.
    3. The result in the specified format.

    The command-line client allows passing external data (external temporary tables) for querying. For more information, see the section “External data for query processing”.

    You can create a query with parameters and pass values to them from client application. This allows to avoid formatting query with specific dynamic values on client side. For example:

    1. $ clickhouse-client --param_parName="[1, 2]"  -q "SELECT * FROM table WHERE a = {parName:Array(UInt16)}"

    Query Syntax

    Format a query as usual, then place the values that you want to pass from the app parameters to the query in braces in the following format:

    • name — Placeholder identifier. In the console client it should be used in app parameters as .
    • data type — Data type of the app parameter value. For example, a data structure like (integer, ('string', integer)) can have the Tuple(UInt8, Tuple(String, UInt8)) data type (you can also use another types).

    Example

    1. $ clickhouse-client --param_tuple_in_tuple="(10, ('dt', 10))" -q "SELECT * FROM table WHERE val = {tuple_in_tuple:Tuple(UInt8, Tuple(String, UInt8))}"

    Configuring

    You can pass parameters to clickhouse-client (all parameters have a default value) using:

    • From the Command Line

    Command-line options override the default values and settings in configuration files.

    • Configuration files.

    Settings in the configuration files override the default values.

    • --host, -h -– The server name, ‘localhost’ by default. You can use either the name or the IPv4 or IPv6 address.
    • --port – The port to connect to. Default value: 9000. Note that the HTTP interface and the native interface use different ports.
    • --user, -u – The username. Default value: default.
    • --password – The password. Default value: empty string.
    • --query, -q – The query to process when using non-interactive mode.
    • --multiline, -m – If specified, allow multiline queries (do not send the query on Enter).
    • – If specified, allow processing multiple queries separated by semicolons.
    • --format, -f – Use the specified default format to output the result.
    • --vertical, -E – If specified, use the Vertical format by default to output the result. This is the same as ‘—format=Vertical’. In this format, each value is printed on a separate line, which is helpful when displaying wide tables.
    • --time, -t – If specified, print the query execution time to ‘stderr’ in non-interactive mode.
    • --stacktrace – If specified, also print the stack trace if an exception occurs.
    • --config-file – The name of the configuration file.
    • --secure – If specified, will connect to server over secure connection.
    • --param_<name> — Value for a query with parameters.

    clickhouse-client uses the first existing file of the following:

    • Defined in the --config-file parameter.
    • ./clickhouse-client.xml
    • /etc/clickhouse-client/config.xml