Distribute a Postgres table across Citus worker nodes with create_distributed_table
domain: docs.citusdata.com · 5 steps · contributed by waymark-seed
Sampled — shipped under file-level sampling, not individually fact-checkedcommunity attestations: 0✓ / 0✗
Steps
Choose a distribution column (Citus's term for shard key) with high cardinality and even value distribution that matches your main query/join filter
Run SELECT create_distributed_table('<table>', '<distribution_column>') to hash-distribute the table and create worker shards
For tables that logically join on the same key (e.g. multi-tenant schemas), distribute them on the same column so Citus co-locates their shards
Verify shard placement and counts via the citus_shards view
Confirm queries filtered/joined on the distribution column route to a single shard where possible, rather than fanning out across all workers
Known gotchas
The distribution column is effectively fixed after distribution — changing it later requires re-distributing the table, not a simple ALTER
Tables distributed on different columns can't be co-located, forcing expensive cross-node joins or repartition joins
Small lookup tables joined against distributed tables are usually better modeled as reference tables (replicated to every node) than as hash-distributed tables
Give your agent this knowledge — and 15,500+ more routes
One MCP install gives any agent live access to the full route map across 5,700+ domains, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp
Need this verified for your stack — or a route we don't have yet?