ClickHouse Schema

data

The data block defines seed/lookup data for a table.

data {
  table = table.countries
  rows = [
    { code = "US", name = "United States" },
    { code = "CA", name = "Canada" },
  ]
}

data attributes

Name	Required	Value
rows	true	Any value
table	true	Object reference to table

data constraints

Constraint	Value
Required	false
Require Name	false
Repeatable	true

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
depends_on	false	List of object references
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 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 blocks

function.annotation

function.annotation constraints

Constraint	Value
Required	false
Require Name	false
Allow unknown blocks	true
Allow unknown attributes	true

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
definer	false	User or role that defines the view can be one of: string Raw expression defined with sql("expr")
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
security	false	enum (DEFINER, INVOKER, NONE)
to	false	Define structure of view can be one of: Object reference to table Object reference to view

materialized blocks

materialized.annotation

materialized.annotation constraints

Constraint	Value
Required	false
Require Name	false
Allow unknown blocks	true
Allow unknown attributes	true

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 blocks

materialized.column.annotation

materialized.column.annotation constraints

Constraint	Value
Required	false
Require Name	false
Allow unknown blocks	true
Allow unknown attributes	true

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.sort

materialized.sort attributes

Name	Required	Value
columns	false	List of object reference to column

materialized.sort blocks

materialized.sort.on

materialized.sort.on attributes

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

materialized.sort.on constraints

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

materialized.sort constraints

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

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]

named_collection

The named_collection block describes a ClickHouse named collection (key-value store).

named_collection "my_conn" {
  item "host" {
    value = "127.0.0.1"
  }
  item "port" {
    value = 5432
  }
  item "user" {
    value = "admin"
  }
  item "use_ssl" {
    value = 1
  }
}

named_collection blocks

named_collection.item

named_collection.item attributes

Name	Required	Value
value	true	Any value

named_collection.item constraints

Constraint	Value
Required	false
Require Name	false
Repeatable	true

named_collection constraints

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

permission

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

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

permission {
  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 named_collection 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	Role or user can be one of: string Object reference to role Object reference to user

permission constraints

Constraint	Value
Required	false
Require Name	false
Repeatable	true

policy

The policy block describes a ClickHouse row-level security policy.

policy "filter_tenant" {
  schema = schema.public
  on     = table.users
  using  = "tenant_id = 1"
  to     = [role.admin]
  restrictive = true
}

policy attributes

Name	Required	Value
on	true	Table or view the policy applies to can be one of: Object reference to table string
restrictive	false	bool
to	false	List of object references
to_all	false	bool
to_all_except	false	List of object references
using	false	string

policy constraints

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

role

The role block describes a database role.

role "admin" {
  comment   = "Admin role"
  member_of = [role.viewer]
}

role attributes

Name	Required	Value
comment	false	string
member_of	false	List of object references
storage	false	string

role constraints

Constraint	Value
Required	false
Require Name (e.g., role "name" )	true
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 blocks

schema.annotation

schema.annotation constraints

Constraint	Value
Required	false
Require Name	false
Allow unknown blocks	true
Allow unknown attributes	true

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
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")
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.annotation

table.annotation constraints

Constraint	Value
Required	false
Require Name	false
Allow unknown blocks	true
Allow unknown attributes	true

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 blocks

table.column.annotation

table.column.annotation constraints

Constraint	Value
Required	false
Require Name	false
Allow unknown blocks	true
Allow unknown attributes	true

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

user

The user block describes a database user.

user "john" {
  comment   = "John Doe"
  member_of = [role.admin]
}

user attributes

Name	Required	Value
auth_type	false	string
comment	false	string
member_of	false	List of object references
password	false	string
storage	false	string

user constraints

Constraint	Value
Required	false
Require Name (e.g., user "name" )	true
Repeatable	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
definer	false	User or role that defines the view can be one of: string Raw expression defined with sql("expr")
depends_on	false	List of object references
schema	true	Object reference to schema
security	false	enum (DEFINER, INVOKER, NONE)

view blocks

view.annotation

view.annotation constraints

Constraint	Value
Required	false
Require Name	false
Allow unknown blocks	true
Allow unknown attributes	true

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 blocks

view.column.annotation

view.column.annotation constraints

Constraint	Value
Required	false
Require Name	false
Allow unknown blocks	true
Allow unknown attributes	true

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]