docs

Author: DatGuyJonathan

apps/framework-docs/llm-docs/python/table-setup.md

@@ -396,6 +396,59 @@ Available replicated engines:
 - `ReplicatedAggregatingMergeTreeEngine` - Replicated with aggregation
 - `ReplicatedSummingMergeTreeEngine` - Replicated with summation
 
+### Cluster-Aware Replicated Tables
+
+For multi-node ClickHouse deployments, you can specify a cluster name to use `ON CLUSTER` DDL operations:
+
+```python
+from moose_lib import OlapTable, OlapConfig
+from moose_lib.blocks import ReplicatedMergeTreeEngine
+from pydantic import BaseModel
+from datetime import datetime
+
+class ReplicatedData(BaseModel):
+    id: str
+    data: str
+    timestamp: datetime
+
+# Replicated table on a cluster
+clustered_table = OlapTable[ReplicatedData](
+    "ClusteredTable",
+    OlapConfig(
+        order_by_fields=["id"],
+        engine=ReplicatedMergeTreeEngine(),
+        cluster="default"  # References cluster from moose.config.toml
+    )
+)
+```
+
+**Configuration in `moose.config.toml`:**
+```toml
+[[clickhouse_config.clusters]]
+name = "default"
+```
+
+**When to omit all parameters (recommended):**
+- ✅ **ClickHouse Cloud** - Platform manages replication automatically
+- ✅ **Local development** - Moose auto-injects params: `/clickhouse/tables/{database}/{shard}/{table_name}`
+- ✅ **Most production deployments** - Works out of the box
+
+**When to use `cluster`:**
+- ✅ Multi-node self-managed ClickHouse with cluster configuration
+- ✅ Need `ON CLUSTER` DDL for distributed operations
+- ✅ Works without explicit `keeper_path`/`replica_name` parameters
+
+**When to use explicit `keeper_path`/`replica_name`:**
+- ✅ Custom replication topology required
+- ✅ Advanced ZooKeeper/Keeper configuration
+- ✅ Specific self-managed deployment requirements
+
+**Important:** Cannot specify both `cluster` and explicit `keeper_path`/`replica_name` - choose one approach.
+
+**Local Development:** Moose configures cluster names to point to your local ClickHouse instance, letting you develop with `ON CLUSTER` DDL without running multiple nodes.
+
+**Production:** Cluster names must match your ClickHouse `remote_servers` configuration.
+
 ### S3Queue Engine Tables
 
 The S3Queue engine enables automatic processing of files from S3 buckets as they arrive.

apps/framework-docs/llm-docs/typescript/table-setup.md

@@ -229,8 +229,55 @@ export const ReplicatedDedup = new OlapTable<ReplicatedSchema>("ReplicatedDedup"
 **Note**: The `keeperPath` and `replicaName` parameters are optional:
 - **Self-managed ClickHouse**: Both parameters are required for configuring ZooKeeper/ClickHouse Keeper paths
 - **ClickHouse Cloud / Boreal**: Omit both parameters - the platform manages replication automatically
+
+### Cluster-Aware Replicated Tables
+
+For multi-node ClickHouse deployments, you can specify a cluster name to use `ON CLUSTER` DDL operations:
+
+```typescript
+import { OlapTable, ClickHouseEngines, Key } from '@514labs/moose-lib';
+
+interface ReplicatedSchema {
+  id: Key<string>;
+  data: string;
+  timestamp: Date;
+}
+
+// Replicated table on a cluster
+export const ClusteredTable = new OlapTable<ReplicatedSchema>("ClusteredTable", {
+  engine: ClickHouseEngines.ReplicatedMergeTree,
+  orderByFields: ["id"],
+  cluster: "default"  // References cluster from moose.config.toml
+});
 ```
 
+**Configuration in `moose.config.toml`:**
+```toml
+[[clickhouse_config.clusters]]
+name = "default"
+```
+
+**When to omit all parameters (recommended):**
+- ✅ **ClickHouse Cloud** - Platform manages replication automatically
+- ✅ **Local development** - Moose auto-injects params: `/clickhouse/tables/{database}/{shard}/{table_name}`
+- ✅ **Most production deployments** - Works out of the box
+
+**When to use `cluster`:**
+- ✅ Multi-node self-managed ClickHouse with cluster configuration
+- ✅ Need `ON CLUSTER` DDL for distributed operations
+- ✅ Works without explicit `keeperPath`/`replicaName` parameters
+
+**When to use explicit `keeperPath`/`replicaName`:**
+- ✅ Custom replication topology required
+- ✅ Advanced ZooKeeper/Keeper configuration
+- ✅ Specific self-managed deployment requirements
+
+**Important:** Cannot specify both `cluster` and explicit `keeperPath`/`replicaName` - choose one approach.
+
+**Local Development:** Moose configures cluster names to point to your local ClickHouse instance, letting you develop with `ON CLUSTER` DDL without running multiple nodes.
+
+**Production:** Cluster names must match your ClickHouse `remote_servers` configuration.
+
 ### S3Queue Engine Tables
 
 The S3Queue engine allows you to automatically process files from S3 buckets as they arrive.

apps/framework-docs/src/pages/moose/configuration.mdx

@@ -243,6 +243,14 @@ native_port = 9000
 # Optional list of additional databases to create on startup (Default: [])
 # additional_databases = ["analytics", "staging"]
 
+# ClickHouse cluster configuration for replicated tables (optional)
+# Define clusters for use with ON CLUSTER DDL operations and distributed tables
+# In local dev, Moose creates single-node clusters. In production, names must match your ClickHouse remote_servers config.
+# [[clickhouse_config.clusters]]
+# name = "default"
+# [[clickhouse_config.clusters]]
+# name = "my_cluster"
+
 # HTTP server configuration for local development
 [http_server_config]
 # Host to bind the webserver to (Default: "localhost")