Using ClickHouse as a Time-Series Database in Spring Boot

November 13, 2025

#1

This guide shows how to use ClickHouse as a time-series database with Spring Boot for storing and querying time-based data.

1. Create a Time-Series Table

ClickHouse supports time-series with MergeTree engines.

CREATE TABLE metrics (
  timestamp DateTime,
  service String,
  value Float32
) ENGINE = MergeTree()
PARTITION BY toYYYYMM(timestamp)
ORDER BY (service, timestamp);

2. Spring Boot Configuration

spring.datasource.url=jdbc:clickhouse://localhost:8123/default
spring.datasource.username=default
spring.datasource.password=
spring.datasource.driver-class-name=com.clickhouse.jdbc.ClickHouseDriver

3. Define an Entity

@Entity
@Table(name = "metrics")
public class Metric {
    @Id
    private LocalDateTime timestamp;
    private String service;
    private Float value;
}

4. Repository for Time-Series

public interface MetricRepository extends JpaRepository<Metric, LocalDateTime> {
    @Query(value = "SELECT * FROM metrics WHERE service = :service AND timestamp BETWEEN :start AND :end ORDER BY timestamp", nativeQuery = true)
    List<Metric> findByServiceAndTimeRange(String service, LocalDateTime start, LocalDateTime end);
}

5. Insert Metrics

Metric metric = new Metric();
metric.setTimestamp(LocalDateTime.now());
metric.setService("payment");
metric.setValue(23.7f);
repo.save(metric);

6. Query Data by Time Range

List<Metric> results = repo.findByServiceAndTimeRange(
    "payment",
    LocalDateTime.now().minusHours(1),
    LocalDateTime.now()
);

7. Aggregations for Analysis

@Query(value = "SELECT toStartOfMinute(timestamp) as minute, avg(value) as avgValue " +
               "FROM metrics WHERE service=:service GROUP BY minute ORDER BY minute", nativeQuery = true)
List<Object[]> avgPerMinute(String service);