ClickHouse Distributed Tables with Spring Boot Applications

December 10, 2025

#1

Distributed tables in ClickHouse allow queries to scale across multiple nodes. Let’s use them in Spring Boot for high-performance applications.

1. Create a Local Table

CREATE TABLE orders_local (
  id UInt32,
  customer String,
  amount Float32,
  created_at DateTime
) ENGINE = MergeTree()
ORDER BY id;

Each node stores its local shard.

2. Create a Distributed Table

CREATE TABLE orders_dist AS orders_local
ENGINE = Distributed('cluster_name', 'default', 'orders_local', rand());

This table queries all shards seamlessly.

3. Insert Data from Spring Boot

jdbcTemplate.update(
  "INSERT INTO orders_dist (id, customer, amount, created_at) VALUES (?,?,?,?)",
  1, "Alice", 120.50, LocalDateTime.now()
);

Data is distributed automatically across nodes.

4. Query Data

List<Map<String,Object>> orders = jdbcTemplate.queryForList(
  "SELECT customer, sum(amount) AS total FROM orders_dist GROUP BY customer"
);

Aggregations run in parallel across shards.

5. Expose REST API

@GetMapping("/api/orders/summary")
public List<Map<String,Object>> getSummary() {
    return jdbcTemplate.queryForList(
      "SELECT customer, sum(amount) AS total FROM orders_dist GROUP BY customer"
    );
}

Your app delivers results quickly even on large datasets.