tencent cloud

Feedback

ClickHouse SQL Syntax Reference

Last updated: 2024-01-19 16:45:30

    Data Type

    ClickHouse supports multiple data types such as integer, floating point, character, date, enumeration, and array.

    Type list

    Type
    Name
    Type ID
    Data Range or Description
    Integer
    1-byte integer
    Int8
    [-128, 127]
    2-byte integer
    Int16
    [-32768, 32767]
    4-byte integer
    Int32
    [-2147483648, 2147483647]
    8-byte integer
    Int64
    [-9223372036854775808, 9223372036854775807]
    1-byte unsigned integer
    UInt8
    [ 0, 255]
    2-byte unsigned integer
    UInt16
    [ 0, 65535]
    4-byte unsigned integer
    UInt32
    [ 0, 4294967295]
    8-byte unsigned integer
    UInt64
    [ 0, 18446744073709551615]
    Floating point
    Single-precision floating point
    Float32
    6–7 significant digits
    Double-precision floating point
    Float64
    15–16 significant digits
    Custom-precision floating point
    Decimal32(S)
    1–9 significant digits (specified by `S`)
    Decimal64(S)
    10–18 significant digits (specified by `S`)
    Decimal128(S)
    19–38 significant digits (specified by `S`)
    Character
    Varchar
    String
    The string length is unlimited
    Char
    FixedString(N)
    The string length is fixed
    UUID
    UUID
    The `UUID` is generated by the built-in function `generateUUIDv4`
    Time
    Date
    Date
    It stores the year, month, and day in the format of `yyyy-MM-dd`
    Timestamp (s)
    DateTime(timezone)
    Unix timestamp accurate down to the second
    Timestamp (custom precision)
    DateTime(precision, timezone)
    You can specify the time precision
    Enumeration
    1-byte enumeration
    Enum8
    [-128, 127], 256 values in total
    2-byte enumeration
    Enum16
    [-32768, 32767], 65536 values in total
    Array
    Array
    Array(T)
    It indicates an array consisting of data in `T` type. You are not advised to use nested arrays
    
    Note:
    
    You can use UInt8 to store boolean values and limit the value to 0 or 1.
    For more information on other data types, see the official documentation.

    Use cases

    Enumeration

    The following sample code is used to store the gender information of users in a site:
    CREATE TABLE user (uid Int16, name String, gender Enum('male'=1, 'female'=2)) ENGINE=Memory;
    INSERT INTO user VALUES (1, 'Gary', 'male'), (2, 'Jaco', 'female');
    # Query data: SELECT * FROM user;
    
    ┌─uid─┬─name─┬─gender─┐
    1 │ Gary │ male │
    2 │ Jaco │ female │
    └─────┴──────┴────────┘
    # Use the CAST function to query the enumerated integers: SELECT uid, name, CAST(gender, 'Int8') FROM user;
    
    ┌─uid─┬─name─┬─CAST(gender, 'Int8')─┐
    1 │ Gary │ 1
    2 │ Jaco │ 2
    └─────┴──────┴──────────────────────┘

    Array

    The following sample code is used to record the IDs of users who log in to the site every day so as to analyze active users.
    CREATE TABLE userloginlog (logindate Date, uids Array(String)) ENGINE=TinyLog;
    INSERT INTO userloginlog VALUES ('2020-01-02', ['Gary', 'Jaco']), ('2020-02-03', ['Jaco', 'Sammie']);
    # Query result: SELECT * FROM userloginlog;
    
    ┌──logindate─┬─uids──────────────┐
    2020-01-02 │ ['Gary','Jaco']
    2020-02-03 │ ['Jaco','Sammie']
    └────────────┴───────────────────┘

    Creating Database/Table

    ClickHouse uses the CREATE statement to create a database or table.
    CREATE DATABASE [IF NOT EXISTS] db_name [ON CLUSTER cluster] [ENGINE = engine(...)]
    CREATE TABLE [IF NOT EXISTS] [db.]table_name [ON CLUSTER cluster]
    (
    name1 [type1] [DEFAULT|MATERIALIZED|ALIAS expr1] [compression_codec] [TTL expr1],
    name2 [type2] [DEFAULT|MATERIALIZED|ALIAS expr2] [compression_codec] [TTL expr2],
    ...
    ) ENGINE = engine
    Databases and tables can be created on local disks or in a distributed manner. Distributed creation can be implemented in the following two methods:
    Run the CREATE statement on all servers where clickhouse-server resides.
    Use the ON CLUSTER command to create a database or table on any server in the cluster. When the command is executed successfully, the database or table will be created successfully on each node of the current V-cluster.
    If you use clickhouse-client to query a local table of server B on server A, the error "Table xxx doesn't exist." will be reported. If you want that all servers in the cluster can query a table, you are advised to use distributed tables.
    For more information, see CREATE Queries.

    Query

    ClickHouse uses the SELECT statement to query data.
    SELECT [DISTINCT] expr_list
    [FROM [db.]table | (subquery) | table_function] [FINAL]
    [SAMPLE sample_coeff]
    [GLOBAL] [ANY|ALL] [INNER|LEFT|RIGHT|FULL|CROSS] [OUTER] JOIN (subquery)|table USING columns_list
    [PREWHERE expr]
    [WHERE expr]
    [GROUP BY expr_list] [WITH TOTALS]
    [HAVING expr]
    [ORDER BY expr_list]
    [LIMIT [offset_value, ]n BY columns]
    [LIMIT [n, ]m]
    [UNION ALL ...]
    [INTO OUTFILE filename]
    [FORMAT format]
    For more information, see SELECT Queries Syntax.

    Batch Write

    ClickHouse uses the INSERT INTO statement to write data.
    INSERT INTO [db.]table [(c1, c2, c3)] VALUES (v11, v12, v13), (v21, v22, v23), ...
    INSERT INTO [db.]table [(c1, c2, c3)] SELECT ...
    For more information, see INSERT.

    Data Deletion

    ClickHouse uses the DROP or TRUNCATE statement to delete data.
    Note:
    Use DROP to delete metadata and data, or use TRUNCATE to delete data only.
    DROP DATABASE [IF EXISTS] db [ON CLUSTER cluster]DROP [TEMPORARY] TABLE [IF EXISTS] [db.]name [ON CLUSTER cluster]
    TRUNCATE TABLE [IF EXISTS] [db.]name [ON CLUSTER cluster]

    Table Structure Modification

    ClickHouse uses the ALTER statement to modify the table structure.
    # Column operations on table
    ALTER TABLE [db].name [ON CLUSTER cluster] ADD COLUMN [IF NOT EXISTS] name [type] [default_expr] [codec] [AFTER name_after]ALTER TABLE [db].name [ON CLUSTER cluster] DROP COLUMN [IF EXISTS] nameALTER TABLE [db].name [ON CLUSTER cluster] CLEAR COLUMN [IF EXISTS] name IN PARTITION partition_nameALTER TABLE [db].name [ON CLUSTER cluster] COMMENT COLUMN [IF EXISTS] name 'comment'ALTER TABLE [db].name [ON CLUSTER cluster] MODIFY COLUMN [IF EXISTS] name [type] [default_expr] [TTL]
    
    # Partition operations on table
    ALTER TABLE table_name DETACH PARTITION partition_exprALTER TABLE table_name DROP PARTITION partition_exprALTER TABLE table_name CLEAR INDEX index_name IN PARTITION partition_expr
    
    # Attribute operations on table
    ALTER TABLE table-name MODIFY TTL ttl-expression
    For more information, see ALTER.

    Information Viewing

    SHOW statement

    It is used to display information such as databases, processing lists, tables, and dictionaries.
    SHOW DATABASES [INTO OUTFILE filename] [FORMAT format]SHOW PROCESSLIST [INTO OUTFILE filename] [FORMAT format]SHOW [TEMPORARY] TABLES [{FROM | IN} <db>] [LIKE '<pattern>' | WHERE expr] [LIMIT <N>] [INTO OUTFILE <filename>] [FORMAT <format>]SHOW DICTIONARIES [FROM <db>] [LIKE '<pattern>'] [LIMIT <N>] [INTO OUTFILE <filename>] [FORMAT <format>]
    For more information, see SHOW Queries.

    DESCRIBE statement

    It is used to view table metadata.
    DESC|DESCRIBE TABLE [db.]table [INTO OUTFILE filename] [FORMAT format]

    Functions

    There are two types of ClickHouse functions: regular functions and aggregate functions. The difference is that a regular function can generate the result for each row, while an aggregate function needs a set of data to generate the result.

    Regular functions

    Arithmetic functions

    In this type of functions, all fields in the table engage in the arithmetic calculation.
    Function Name
    Purpose
    Use Case
    plus(a, b), a + b
    Calculates the sum of two fields
    plus(table.field1, table.field2)
    minus(a, b), a - b
    Calculates the difference between two fields
    minus(table.field1, table.field2)
    multiply(a, b), a * b
    Calculates the product of two fields
    multiply(table.field1, table.field2)
    divide(a, b), a / b
    Calculates the quotient of two fields
    divide(table.field1, table.field2)
    modulo(a, b), a % b
    Calculates the remainder between two fields
    modulo(table.field1, table.field2)
    abs(a)
    Calculates absolute value
    abs(table.field1)
    negate(a)
    Calculates opposite
    negate(table.field1)

    Comparison functions

    Function Name
    Purpose
    Use Case
    =, ==
    Determines whether the values are the same
    table.field1 = value
    !=, <>
    Determines whether the values are different
    table.field1 != value
    >
    Determines whether the former value is greater than the latter value
    table.field1 > value
    >=
    Determines whether the former value is greater than or equal to the latter value
    table.field1 >= value
    <
    Determines whether the former value is smaller than the latter value
    table.field1 < value
    <=
    Determines whether the former value is smaller than or equal to the latter value
    table.field1 <= value

    Logical operation functions

    Function Name
    Purpose
    Use Case
    AND
    Returns result if both two conditions are met
    -
    OR
    Returns result if either condition is met
    -
    NOT
    Returns result if no condition is met
    -

    Type conversion functions

    Overflow may occur when you use a type conversion function. The data types of overflowed values are the same as those in C.
    Function Name
    Purpose
    Use Case
    toInt(8|16|32|64)
    Converts String value to Int value
    The result of toInt8('128') is -127
    toUInt(8|16|32|64)
    Converts String value to UInt value
    The result of toUInt8('128') is 128
    toInt(8|16|32|64)OrZero
    Converts String value to Int value and returns 0 if failed
    The result of toInt8OrZero('a') is 0
    toUInt(8|16|32|64)OrZero
    Converts String value to UInt value and returns 0 if failed
    The result of toUInt8OrZero('a') is 0
    toInt(8|16|32|64)OrNull
    Converts String value to Int value and returns NULL if failed
    The result of toInt8OrNull('a') is NULL
    toUInt(8|16|32|64)OrNull
    Converts String value to UInt value and returns NULL if failed
    The result of toUInt8OrNull('a') is NULL
    Functions similar to those above are also provided for the floating point and date types.
    For more information, see Type Conversion Functions.

    Date functions

    String functions

    For more information, see Functions for Working with Strings.

    UUID

    For more information, see Functions for Working with UUID.

    JSON processing functions

    For more information, see Functions for Working with JSON.

    Aggregate functions

    Function Name
    Purpose
    Use Case
    count
    Counts the number of rows or non-NULL values
    count(expr), COUNT(DISTINCT expr), count(), count(*)
    Returns the first encountered value. The result is indeterminate
    any(column)
    Returns a frequently occurring value using the heavy hitters algorithm. The result is generally indeterminate
    anyHeavy(column)
    Returns the last encountered value. The result is indeterminate
    anyLast(column)
    Applies bitwise AND
    groupBitAnd(expr)
    Applies bitwise OR
    groupBitOr(expr)
    Applies bitwise XOR
    groupBitXor(expr)
    Returns cardinality
    groupBitmap(expr)
    Calculates the minimum value
    min(column)
    Calculates the maximum value
    max(x)
    Returns the arg value for a minimal val value
    argMin(c1, c2)
    Returns the arg value for a maximum val value
    argMax(c1, c2)
    Calculates the sum
    sum(x)
    Calculates the sum. If the sum exceeds the maximum value for this data type, the function will return an error
    sumWithOverflow(x)
    Sums the value array of the same key and returns the tuples of value and key arrays: keys in sorted order, and value ​​sum of corresponding keys
    -
    Calculates skewness
    skewPop(expr)
    Calculates sample skewness
    skewSamp(expr)
    Calculates kurtosis
    kurtPop(expr)
    Calculates sample kurtosis
    kurtSamp(expr)
    Sums the timestamps in time-series grouped by uid. It uses linear interpolation to add missing sample timestamps before summing the values
    -
    Calculates the rate of time-series grouped by uid and then sum rates together
    -
    Calculates the average value
    -
    Calculates the approximate number of different values
    uniq(x[, ...])
    Calculates the approximate number of different values. Compared with uniq, it consumes less memory and is more accurate but has slightly lower performance
    uniqCombined(HLL_precision)(x[, ...]), uniqCombined(x[, ...])
    Functions in the same way as uniqCombined but uses 64-bit values to reduce the probability of result value overflow
    -
    Calculates the approximate number of different values. It is not recommended. Please use uniq and uniqCombined instead
    -
    Calculates the exact number of different values
    uniqExact(x[, ...])
    Returns an array of x values. The array size can be specified by max_size
    -
    Inserts value into array at specified position
    -
    -
    -
    -
    -
    -
    -
    -
    -
    -
    -
    -
    -
    -
    -
    -
    -
    -
    -
    -
    -
    -
    -
    -
    -
    -
    -
    -
    -
    -
    -
    -
    -
    -
    -
    -
    -
    -
    -
    -
    -
    -
    -
    -
    -
    -
    -
    -
    -
    -
    -
    -
    -
    -
    -
    -
    -
    -
    -

    Dictionary

    A dictionary is a mapping between a key and attributes and can be used as a function for query, which is simpler and more efficient than the method of combining referencing tables with a JOIN clause.
    There are two types of data dictionaries: internal and external dictionaries.

    Internal dictionary

    ClickHouse supports one type of internal dictionaries, i.e., geobase. For more information on the supported functions, see Functions for Working with Yandex.Metrica Dictionaries.

    External dictionary

    ClickHouse allows you to add external dictionaries from multiple data sources. For more information on the supported data sources, see Sources of External Dictionaries.
    Contact Us

    Contact our sales team or business advisors to help your business.

    Technical Support

    Open a ticket if you're looking for further assistance. Our Ticket is 7x24 avaliable.

    7x24 Phone Support