Supported Objects in ClickHouse

Atlas provides comprehensive support for managing ClickHouse database objects using HCL schema definitions. Below is an overview of the objects you can manage.

Schema & Tables

Atlas can manage ClickHouse databases with engines such as Atomic and Lazy, and tables with support for:

• Columns with types, defaults, compression codecs, TTLs, and nullability
• Primary keys and secondary indexes (e.g., minmax, bloom_filter)
• Partitioning, sort keys (ORDER BY), projections, and check constraints
• Table engines: MergeTree, SharedMergeTree, Memory, TimeSeries, and custom engines

schema "public" {
  ...
}

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

Views & Materialized Views

Atlas supports both regular views and materialized views with the following features:

• Materialized views with their own storage engine or routing data to an existing table
• Refreshable materialized views with configurable intervals, append mode, and retry settings
• SQL security options (DEFINER, INVOKER, NONE) for both view types

view "clean_users" {
  schema = schema.public
  as = "SELECT id, name FROM users WHERE active = 1"
  column "id" {
    type = int
  }
  ...
}

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

With refresh:

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
    }
  }
}

Dictionaries

Atlas supports ClickHouse dictionaries with:

• Source and layout configuration
• Typed keys and attributes with default values
• Lifetime settings for cache refresh

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

Functions (UDF)

Atlas supports user-defined functions (UDFs) as lambda expressions. Note that UDFs in ClickHouse are defined at the instance level, not within a specific database or schema.

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

Access Control

Atlas supports ClickHouse access control including:

• Users with password, authentication type, and role membership
• Roles with hierarchical membership (roles can inherit from other roles)
• Permissions with fine-grained privileges (SELECT, INSERT, ALTER, CREATE, DROP, ALL, etc.) on schemas, tables, views, materialized views, dictionaries, functions, and individual columns

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

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

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

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

Seed Data

Atlas supports defining seed or lookup data for tables, making it easy to manage reference data as part of your schema.

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

For full attribute details, child blocks, and HCL examples, see the ClickHouse HCL Reference.