We value your privacy

This site uses cookies to improve your browsing experience, analyze site traffic, and show personalized content. See our Privacy Policy.

  1. MooseStack
  3. Table Engines
  5. Replicated Engines

Replicated Engines

Replicated engines provide high availability and data replication across multiple ClickHouse nodes. MooseStack supports all standard replicated MergeTree variants:

  • ReplicatedMergeTree - Replicated version of MergeTree
  • ReplicatedReplacingMergeTree - Replicated with deduplication
  • ReplicatedAggregatingMergeTree - Replicated with aggregation
  • ReplicatedSummingMergeTree - Replicated with summation
  • ReplicatedCollapsingMergeTree - Replicated with state collapsing
  • ReplicatedVersionedCollapsingMergeTree - Replicated with versioned collapsing
ReplicatedEngines.ts
import { OlapTable, ClickHouseEngines } from "@514labs/moose-lib"; // Basic replicated table with explicit pathsconst replicatedTable = new OlapTable<Record>("records", {  engine: ClickHouseEngines.ReplicatedMergeTree,  keeperPath: "/clickhouse/tables/{database}/{shard}/records",  replicaName: "{replica}",  orderByFields: ["id"]}); // Replicated with deduplicationconst replicatedDedup = new OlapTable<Record>("dedup_records", {  engine: ClickHouseEngines.ReplicatedReplacingMergeTree,  keeperPath: "/clickhouse/tables/{database}/{shard}/dedup_records",  replicaName: "{replica}",  ver: "updated_at",  isDeleted: "deleted",  orderByFields: ["id"]}); // For ClickHouse Cloud or Fiveonefour (no parameters needed)const cloudReplicated = new OlapTable<Record>("cloud_records", {  engine: ClickHouseEngines.ReplicatedMergeTree,  orderByFields: ["id"]});
Configuring Replication

Replicated engines support three configuration approaches. Choose the one that fits your deployment:

Default

Omit all replication parameters. Moose uses smart defaults that work in both ClickHouse Cloud and self-managed environments:

DefaultReplication.ts
const table = new OlapTable<Record>("my_table", {  engine: ClickHouseEngines.ReplicatedMergeTree,  orderByFields: ["id"]  // No keeper_path, replica_name, or cluster needed});

Moose auto-injects: /clickhouse/tables/{database}/{shard}/{table_name} and {replica} in local development. ClickHouse Cloud uses its own patterns automatically.

Cluster

For multi-node deployments, specify a cluster name to use ON CLUSTER DDL operations:

ClusterReplication.ts
const table = new OlapTable<Record>("my_table", {  engine: ClickHouseEngines.ReplicatedMergeTree,  orderByFields: ["id"],  cluster: "default"  // References cluster from moose.config.toml});

Configuration in moose.config.toml:

[[clickhouse_config.clusters]]name = "default"

Use when:

  • Running multi-node self-managed ClickHouse with cluster configuration
  • Need ON CLUSTER DDL for distributed operations
Replication Paths

For custom replication topology, specify both keeper_path and replica_name:

ExplicitReplication.ts
const table = new OlapTable<Record>("my_table", {  engine: ClickHouseEngines.ReplicatedMergeTree,  keeperPath: "/clickhouse/tables/{database}/{shard}/my_table",  replicaName: "{replica}",  orderByFields: ["id"]});

Use when:

  • Need custom replication paths for advanced configurations
  • Both parameters must be provided together
Warning:

Cannot mix approaches: Specifying both cluster and explicit keeper_path/replica_name will cause an error. Choose one approach.

Cluster is a deployment directive: Changing cluster won't recreate your table -— it only affects future DDL operations.

For more details, see the ClickHouse documentation on data replication.

FiveonefourFiveonefour
Fiveonefour Docs
MooseStackHostingTemplatesGuides
Release Notes
Source531
  • Overview
Build a New App
  • 5 Minute Quickstart
  • Browse Templates
  • Existing ClickHouse
Add to Existing App
  • Next.js
  • Fastify
Fundamentals
  • Moose Runtime
  • MooseDev MCP
  • Language Server
  • Data Modeling
Moose Modules
  • Moose OLAP
  • Moose Streaming
  • Moose Workflows
  • Moose APIs & Web Apps
Deployment & Lifecycle
  • Moose Dev
  • Moose Migrate
  • Moose Deploy
Reference
  • API Reference
  • Data Types
  • Table Engines
    • MergeTree
    • ReplacingMergeTree
    • AggregatingMergeTree
    • SummingMergeTree
    • Replicated Engines
  • CLI
  • Configuration
  • Observability Metrics
  • Help
  • Release Notes
Contribution
  • Documentation
  • Framework
ReplicatedEngines.ts
import { OlapTable, ClickHouseEngines } from "@514labs/moose-lib"; // Basic replicated table with explicit pathsconst replicatedTable = new OlapTable<Record>("records", {  engine: ClickHouseEngines.ReplicatedMergeTree,  keeperPath: "/clickhouse/tables/{database}/{shard}/records",  replicaName: "{replica}",  orderByFields: ["id"]}); // Replicated with deduplicationconst replicatedDedup = new OlapTable<Record>("dedup_records", {  engine: ClickHouseEngines.ReplicatedReplacingMergeTree,  keeperPath: "/clickhouse/tables/{database}/{shard}/dedup_records",  replicaName: "{replica}",  ver: "updated_at",  isDeleted: "deleted",  orderByFields: ["id"]}); // For ClickHouse Cloud or Fiveonefour (no parameters needed)const cloudReplicated = new OlapTable<Record>("cloud_records", {  engine: ClickHouseEngines.ReplicatedMergeTree,  orderByFields: ["id"]});
DefaultReplication.ts
const table = new OlapTable<Record>("my_table", {  engine: ClickHouseEngines.ReplicatedMergeTree,  orderByFields: ["id"]  // No keeper_path, replica_name, or cluster needed});
ClusterReplication.ts
const table = new OlapTable<Record>("my_table", {  engine: ClickHouseEngines.ReplicatedMergeTree,  orderByFields: ["id"],  cluster: "default"  // References cluster from moose.config.toml});
ExplicitReplication.ts
const table = new OlapTable<Record>("my_table", {  engine: ClickHouseEngines.ReplicatedMergeTree,  keeperPath: "/clickhouse/tables/{database}/{shard}/my_table",  replicaName: "{replica}",  orderByFields: ["id"]});