ClickHouse Schema

dictionary

The dictionary block describes a dictionary in a database schema.

dictionary "name" {
  schema = schema.public
  source = sql("CLICKHOUSE(TABLE)")
  layout = sql("HASH()")
  key "id" {
	type = UInt64
  }
  attribute "name" {
	type = String
  }
  lifetime {
	min = 0
	max = 0
  }
  ...
}

dictionary attributes

Name	Required	Value
comment	false	string
layout	true	Raw expression defined with sql("expr")
schema	true	Object reference to schema
settings	false	map
source	true	Raw expression defined with sql("expr")

dictionary blocks

dictionary.attribute

dictionary.attribute attributes

Name	Required	Value
default	false	Column default expression can be one of: bool string number Raw expression defined with sql("expr")
null	false	bool
type	true	Attribute type can be one of: Schema type Raw expression defined with sql("expr")

dictionary.attribute constraints

Constraint	Value
Required	false
Require Name (e.g., dictionary.attribute "name" )	true

dictionary.key

dictionary.key attributes

Name	Required	Value
default	false	Column default expression can be one of: bool string number Raw expression defined with sql("expr")
null	false	bool
type	true	Attribute type can be one of: Schema type Raw expression defined with sql("expr")

dictionary.key constraints

Constraint	Value
Required	false
Require Name (e.g., dictionary.key "name" )	true

dictionary.lifetime

dictionary.lifetime attributes

Name	Required	Value
max	true	int
min	true	int

dictionary.lifetime constraints

Constraint	Value
Required	true
Require Name	false

dictionary constraints

Constraint	Value
Required	false
Require Name (e.g., dictionary "name" )	true
Allow Qualifier (e.g., dictionary "schema" "name" )	true

function

The function block describes a ClickHouse User-Defined Function (UDF).

function "plus_one" {
  as = "(x) -> x + 1"
}

function attributes

Name	Required	Value
as	true	string

function constraints

Constraint	Value
Required	false
Require Name (e.g., function "name" )	true

materialized

The materialized block describes a materialized view in a database schema.

materialized "name" {
  schema = schema.public
  column "total" {
    null = true
    type = numeric
  }
  ...
}

materialized attributes

Name	Required	Value
as	true	string
comment	false	string
depends_on	false	List of object references
engine	false	Table engine can be one of: enum (MergeTree, SharedMergeTree, Memory, TimeSeries) Raw expression defined with sql("expr")
populate	false	bool
schema	true	Object reference to schema
to	false	Define structure of view can be one of: Object reference to table Object reference to view

materialized blocks

materialized.column

materialized.column attributes

Name	Required	Value
comment	false	string
null	false	bool
type	true	Column type can be one of: Schema type Raw expression defined with sql("expr")

materialized.column constraints

Constraint	Value
Required	false
Require Name (e.g., materialized.column "name" )	true

materialized.primary_key

materialized.primary_key attributes

Name	Required	Value
columns	false	Primary key columns can be one of: List of object reference to column List of object reference to table.column
comment	false	string

materialized.primary_key blocks

materialized.primary_key.on

materialized.primary_key.on attributes

Name	Required	Value
column	false	Primary key column can be one of: Object reference to column Object reference to table.column
expr	false	string

materialized.primary_key.on constraints

Constraint	Value
Required	false
Require Name	false
Repeatable	true
Mutually exclusive sets	[column, expr]
One of required sets	[column, expr]

materialized.primary_key constraints

Constraint	Value
Required	false
Require Name	false
Mutually exclusive sets	[columns, on]
One of required sets	[columns, on]

materialized.refresh

The refresh block describes the refresh settings for a materialized view.

materialized "name" {
  schema = schema.public
  as = sql("SELECT * FROM table")
  refresh {
    expr = "EVERY 1 MINUTE"
    append = true
    depends_on = [materialized.other_view]
    settings = {
      refresh_retries = 4
    }
  }

materialized.refresh attributes

Name	Required	Value
append	false	bool
depends_on	false	List of object reference to materialized
expr	true	string
settings	false	map

materialized constraints

Constraint	Value
Required	false
Require Name (e.g., materialized "name" )	true
Allow Qualifier (e.g., materialized "schema" "name" )	true
Mutually exclusive sets	[to, engine], [to, populate]
One of required sets	[to, engine]

permission

The permission block describes permissions (privileges) granted on database objects.

permission "grant_select" {
  to         = "user1"
  for        = table.users
  privileges = [SELECT]
}

permission "grant_all" {
  to         = "admin"
  for        = schema.public
  privileges = [ALL]
  grantable  = true
}

permission attributes

Name	Required	Value
for	true	Permission target resource can be one of: Object reference to schema Object reference to table Object reference to view Object reference to materialized Object reference to dictionary Object reference to function Object reference to table.column Object reference to view.column Object reference to materialized.column
grantable	false	bool
privileges	true	List of strings or/and enums (SELECT, INSERT, ALTER, ALTER_DATABASE, ALTER_DATABASE_SETTINGS, ALTER_TABLE, ALTER_COLUMN, ALTER_ADD_COLUMN, ALTER_DROP_COLUMN, ALTER_MODIFY_COLUMN, ALTER_COMMENT_COLUMN, ALTER_CLEAR_COLUMN, ALTER_RENAME_COLUMN, ALTER_MATERIALIZE_COLUMN, ALTER_INDEX, ALTER_ADD_INDEX, ALTER_DROP_INDEX, ALTER_MATERIALIZE_INDEX, ALTER_CLEAR_INDEX, ALTER_ORDER_BY, ALTER_SAMPLE_BY, ALTER_CONSTRAINT, ALTER_ADD_CONSTRAINT, ALTER_DROP_CONSTRAINT, ALTER_TTL, ALTER_MATERIALIZE_TTL, ALTER_SETTINGS, ALTER_MOVE_PARTITION, ALTER_FETCH_PARTITION, ALTER_FREEZE_PARTITION, ALTER_PROJECTION, ALTER_STATISTICS, ALTER_ADD_STATISTICS, ALTER_DROP_STATISTICS, ALTER_MATERIALIZE_STATISTICS, ALTER_MODIFY_STATISTICS, ALTER_DELETE, ALTER_UPDATE, ALTER_MODIFY_COMMENT, ALTER_VIEW, ALTER_VIEW_MODIFY_QUERY, ALTER_VIEW_REFRESH, ALTER_VIEW_MODIFY_SQL_SECURITY, CREATE, CREATE_DATABASE, CREATE_TABLE, CREATE_ARBITRARY_TEMPORARY_TABLE, CREATE_TEMPORARY_TABLE, CREATE_VIEW, CREATE_DICTIONARY, CREATE_FUNCTION, CREATE_RESOURCE, CREATE_WORKLOAD, DROP, DROP_DATABASE, DROP_TABLE, DROP_VIEW, DROP_DICTIONARY, DROP_FUNCTION, DROP_RESOURCE, DROP_WORKLOAD, UNDROP_TABLE, TRUNCATE, OPTIMIZE, BACKUP, SHOW, SHOW_DATABASES, SHOW_TABLES, SHOW_COLUMNS, SHOW_DICTIONARIES, SHOW_FILESYSTEM_CACHES, KILL_QUERY, KILL_TRANSACTION, MOVE_PARTITION_BETWEEN_SHARDS, CLUSTER, ACCESS_MANAGEMENT, CREATE_USER, ALTER_USER, DROP_USER, CREATE_ROLE, ALTER_ROLE, DROP_ROLE, ROLE_ADMIN, CREATE_ROW_POLICY, ALTER_ROW_POLICY, DROP_ROW_POLICY, CREATE_QUOTA, ALTER_QUOTA, DROP_QUOTA, CREATE_SETTINGS_PROFILE, ALTER_SETTINGS_PROFILE, DROP_SETTINGS_PROFILE, SHOW_ACCESS, SHOW_USERS, SHOW_ROLES, SHOW_ROW_POLICIES, SHOW_QUOTAS, SHOW_SETTINGS_PROFILES, ALLOW_SQL_SECURITY_NONE, SYSTEM, SYSTEM_SHUTDOWN, SYSTEM_DROP_CACHE, SYSTEM_DROP_DNS_CACHE, SYSTEM_DROP_MARK_CACHE, SYSTEM_DROP_UNCOMPRESSED_CACHE, SYSTEM_DROP_COMPILED_EXPRESSION_CACHE, SYSTEM_DROP_CONNECTIONS_CACHE, SYSTEM_DROP_DISTRIBUTED_CACHE, SYSTEM_DROP_FILESYSTEM_CACHE, SYSTEM_DROP_FORMAT_SCHEMA_CACHE, SYSTEM_DROP_MMAP_CACHE, SYSTEM_DROP_PAGE_CACHE, SYSTEM_DROP_PRIMARY_INDEX_CACHE, SYSTEM_DROP_QUERY_CACHE, SYSTEM_DROP_S3_CLIENT_CACHE, SYSTEM_DROP_SCHEMA_CACHE, SYSTEM_DROP_REPLICA, SYSTEM_FAILPOINT, SYSTEM_FETCHES, SYSTEM_FLUSH, SYSTEM_FLUSH_ASYNC_INSERT_QUEUE, SYSTEM_FLUSH_LOGS, SYSTEM_FLUSH_DISTRIBUTED, SYSTEM_JEMALLOC, SYSTEM_KILL_QUERY, SYSTEM_KILL_TRANSACTION, SYSTEM_LISTEN, SYSTEM_LOAD_PRIMARY_KEY, SYSTEM_MERGES, SYSTEM_MOVES, SYSTEM_PULLING_REPLICATION_LOG, SYSTEM_REDUCE_BLOCKING_PARTS, SYSTEM_REPLICATION_QUEUES, SYSTEM_REPLICA_READINESS, SYSTEM_RESTART_DISK, SYSTEM_RESTART_REPLICA, SYSTEM_RESTORE_REPLICA, SYSTEM_RELOAD, SYSTEM_RELOAD_ASYNCHRONOUS_METRICS, SYSTEM_RELOAD_CONFIG, SYSTEM_RELOAD_DICTIONARY, SYSTEM_RELOAD_EMBEDDED_DICTIONARIES, SYSTEM_RELOAD_FUNCTION, SYSTEM_RELOAD_MODEL, SYSTEM_RELOAD_USERS, SYSTEM_SENDS, SYSTEM_DISTRIBUTED_SENDS, SYSTEM_REPLICATED_SENDS, SYSTEM_SYNC_DATABASE_REPLICA, SYSTEM_SYNC_FILE_CACHE, SYSTEM_SYNC_FILESYSTEM_CACHE, SYSTEM_SYNC_REPLICA, SYSTEM_SYNC_TRANSACTION_LOG, SYSTEM_THREAD_FUZZER, SYSTEM_TTL_MERGES, SYSTEM_UNFREEZE, SYSTEM_UNLOAD_PRIMARY_KEY, SYSTEM_VIEWS, SYSTEM_VIRTUAL_PARTS_UPDATE, SYSTEM_WAIT_LOADING_PARTS, SYSTEM_CLEANUP, INTROSPECTION, addressToLine, addressToLineWithInlines, addressToSymbol, demangle, READ, WRITE, AZURE, FILE, HDFS, HIVE, JDBC, KAFKA, MONGO, MYSQL, NATS, ODBC, POSTGRES, RABBITMQ, REDIS, REMOTE, S3, SQLITE, URL, dictGet, displaySecretsInShowAndSelect, SET_DEFINER, NAMED_COLLECTION_ADMIN, CREATE_NAMED_COLLECTION, DROP_NAMED_COLLECTION, ALTER_NAMED_COLLECTION, SHOW_NAMED_COLLECTIONS, SHOW_NAMED_COLLECTIONS_SECRETS, NAMED_COLLECTION, TABLE_ENGINE, ALL, NONE)
to	true	string

permission constraints

Constraint	Value
Required	false
Require Name	false
Repeatable	true

schema

The schema block describes a database schema.

schema "public" {
  ...
}

schema attributes

Name	Required	Value
comment	false	string
engine	false	Schema engine can be one of: enum (Atomic, Lazy) Raw expression defined with sql("expr")
name	false	string

schema constraints

Constraint	Value
Required	false
Require Name (e.g., schema "name" )	true

table

The table block describes a table in a database schema.

table "users" {
  schema = schema.public
  column "id" {
    type = int
  }
  ...
}

table attributes

Name	Required	Value
comment	false	string
engine	false	Table engine can be one of: enum (MergeTree, SharedMergeTree, Memory, TimeSeries) Raw expression defined with sql("expr")
schema	true	Object reference to schema
settings	false	map
ttl	false	Column ttl can be one of: string Raw expression defined with sql("expr")

table blocks

table.check

table.check attributes

Name	Required	Value
comment	false	string
expr	true	string

table.check constraints

Constraint	Value
Required	false
Require Name	false
Repeatable	true

table.column

table.column attributes

Name	Required	Value
codec	false	Column codec can be one of: string Raw expression defined with sql("expr") enum (NONE, ZSTD, LZ4, LZ4HC, DoubleDelta, Gorilla, FPC, T64, AES_128_GCM_SIV, AES_256_GCM_SIV)
comment	false	string
default	false	Column default expression can be one of: bool string number Raw expression defined with sql("expr")
default_kind	false	Column default kind can be one of: enum (DEFAULT, MATERIALIZED, EPHEMERAL, ALIAS)
null	false	bool
ttl	false	Column ttl can be one of: string Raw expression defined with sql("expr")
type	true	Column type can be one of: Schema type Raw expression defined with sql("expr")

table.column constraints

Constraint	Value
Required	false
Require Name (e.g., table.column "name" )	true
Repeatable	true

table.engine.TimeSeries

table.engine.TimeSeries attributes

Name	Required	Value
data	false	Object reference to table
metrics	false	Object reference to table
tags	false	Object reference to table

table.index

table.index attributes

Name	Required	Value
comment	false	string
granularity	false	int
type	true	Index type can be one of: Raw expression defined with sql("expr") string enum (minmax, bloom_filter)

table.index blocks

table.index.on

table.index.on attributes

Name	Required	Value
expr	true	string

table.index.on constraints

Constraint	Value
Required	true
Require Name	false

table.index constraints

Constraint	Value
Required	false
Require Name (e.g., table.index "name" )	true

table.partition

table.partition attributes

Name	Required	Value
columns	false	List of object reference to column

table.partition blocks

table.partition.on

table.partition.on attributes

Name	Required	Value
column	false	Object reference to column
expr	false	string

table.partition.on constraints

Constraint	Value
Required	false
Require Name	false
Repeatable	true
Mutually exclusive sets	[column, expr]
One of required sets	[column, expr]

table.partition constraints

Constraint	Value
Required	false
Require Name	false
Mutually exclusive sets	[columns, on]
One of required sets	[columns, on]

table.primary_key

table.primary_key attributes

Name	Required	Value
columns	false	Primary key columns can be one of: List of object reference to column List of object reference to table.column
comment	false	string

table.primary_key blocks

table.primary_key.on

table.primary_key.on attributes

Name	Required	Value
column	false	Primary key column can be one of: Object reference to column Object reference to table.column
expr	false	string

table.primary_key.on constraints

Constraint	Value
Required	false
Require Name	false
Repeatable	true
Mutually exclusive sets	[column, expr]
One of required sets	[column, expr]

table.primary_key constraints

Constraint	Value
Required	false
Require Name	false
Mutually exclusive sets	[columns, on]
One of required sets	[columns, on]

table.projection

The projection block describes a projection for a table

table "name" {
  schema = schema.public
  projection "name" {
    as = "SELECT * FROM table WHERE condition"
  }
  projection "another" {
    as = "SELECT * FROM table WHERE another_condition"
  }
}

table.projection attributes

Name	Required	Value
as	true	string

table.projection constraints

Constraint	Value
Required	false
Require Name	false
Repeatable	true

table.sort

table.sort attributes

Name	Required	Value
columns	false	List of object reference to column

table.sort blocks

table.sort.on

table.sort.on attributes

Name	Required	Value
column	false	Object reference to column
expr	false	string

table.sort.on constraints

Constraint	Value
Required	false
Require Name	false
Repeatable	true
Mutually exclusive sets	[column, expr]
One of required sets	[column, expr]

table.sort constraints

Constraint	Value
Required	false
Require Name	false
Mutually exclusive sets	[columns, on]
One of required sets	[columns, on]

table constraints

Constraint	Value
Required	false
Require Name (e.g., table "name" )	true
Allow Qualifier (e.g., table "schema" "name" )	true

view

The view block describes a view in a database schema.

view "clean_users" {
  schema = schema.public
  column "id" {
    type = int
  }
  ...
}

view attributes

Name	Required	Value
as	true	string
comment	false	string
depends_on	false	List of object references
schema	true	Object reference to schema

view blocks

view.column

view.column attributes

Name	Required	Value
comment	false	string
null	false	bool
type	true	Column type can be one of: Schema type Raw expression defined with sql("expr")

view.column constraints

Constraint	Value
Required	false
Require Name (e.g., view.column "name" )	true

view constraints

Constraint	Value
Required	false
Require Name (e.g., view "name" )	true
Allow Qualifier (e.g., view "schema" "name" )	true
Mutually exclusive sets	[latest, git]