Typorithm · medium

Distributed Table

distributed-tableclickhousedistributedshardingcluster

Saved on this device

Full lesson · 8 learning steps Open any exercise for focused practice

Step 1 of 8 · intro card

Learn Distributed Table

Scale & Ops

ENGINE = Distributed(cluster, db, local_table, sharding_key) is a query router over shards: reads fan out and merge, writes route by the sharding key.

A Distributed table stores no data itself — it is a thin layer that points at a local table on every shard of a cluster.

On reads, the query fans out to each shard, runs locally, and the coordinator merges the partial results into one answer.

On writes, the sharding key (here cityHash64(user_id)) decides which shard each row belongs to, spreading data evenly.

Distributed routes queries; it stores no data.

Reads fan out to shards, then merge.

The sharding key routes each written row.

CREATE TABLE events_dist AS events
ENGINE = Distributed(
    my_cluster,
    default,
    events,
    cityHash64(user_id)
);

Read the implementation

Connect each part of the code to the concept before you type.

1. Query router engine

Distributed is not a storage engine — it routes queries across the shards of a cluster.

ENGINE = Distributed(

2. Cluster name

The cluster name resolves to the set of shards and replicas defined in the server config.

my_cluster

3. Local table per shard

Each shard stores its slice in this local MergeTree table; the Distributed table just points at it.

events

4. Sharding key

The sharding key decides which shard each inserted row lands on; hashing user_id spreads load evenly.

cityHash64(user_id)

A complete learning loop

Understand

Read the concept map and follow the code breakdown.

Reconstruct

Type the implementation, repair mistakes and work through every recall exercise.

Verify

Use the final check without hints; revisit weak concepts in short practice sessions.