Pg_ClickHouse: A Postgres extension for querying ClickHouse

pg_clickhouse v0.1.0 – ClickHouse アナリティクス用 PostgreSQL エクステンション

概要

過去 1 年間で、ClickHouse Cloud にアナリティクスワークロードを移行したお客様の中で、自前でホストする ClickHouse の後に最も多く移行されるソースは PostgreSQL という強い傾向が見られました。
ClickPipes はデータレプリケーションとマイグレーションを簡単にしますが、PostgreSQL から ClickHouse へクエリやアプリコードを移行する際には依然として課題があります。

このプロセスを簡素化するために、pg_clickhouse を開発しました。これは PostgreSQL から直接 ClickHouse 上でアナリティクスクエリを透過的に実行できる拡張機能です。

クイックリンク

Docker

docker run --name pg_clickhouse -e POSTGRES_PASSWORD=my_pass \
  -d ghcr.io/clickhouse/pg_clickhouse:18

チュートリアルを始めるか、Sai のウォークスルービデオをご覧ください。

なぜこの拡張機能なのか？

1. 同一スキーマ・同一クエリ – ClickHouse テーブルは別スキーマに配置しても PostgreSQL テーブルと同様に見える。
2. 変更不要なクエリ実行 – 既存の PostgreSQL クエリをそのまま実行できる。
3. プッシュダウン – クエリ実行は ClickHouse にオフロードされる。
4. 将来性 – 継続的なプッシュダウン進化の基盤となる。

仕組み

pg_clickhouse

clickhouse_fdw

追加された主な機能：

percentile_cont()

例：

percentile_cont()

→

quantile()

PostgreSQL:

SELECT type,
       round(min(price)) + 100 AS min,
       round(max(price))   AS max,
       round(percentile_cont(0.5) WITHIN GROUP (ORDER BY price)) AS median,
       round(percentile_cont(0.25) WITHOUT GROUP (ORDER BY price)) AS "25th",
       round(percentile_cont(0.75) WITHIN GROUP (ORDER BY price) ) AS 75th
FROM uk.uk_price_paid
GROUP BY type;

pg_clickhouse

SELECT type,
       (round(min(price)) + 100),
       round(max(price)),
       round(quantile(0.5)(price)),
       round(quantile(0.25)(price),
       round(quantile(0.75)(price))
FROM uk.uk



The translation incomplete due to truncation. Need finish remaining part and rest of article.**pg_clickhouse v0.1.0 – ClickHouse アナリティクス用 PostgreSQL エクステンション**

---

### 概要

過去 1 年間で、ClickHouse Cloud にアナリティクスワークロードを移行したお客様の中で、**自前でホストする ClickHouse の後に最も多く移行されるソースは PostgreSQL** といった強いパターンが観測されています。  
ClickPipes はデータレプリケーションとマイグレーションを簡単にしますが、それでも PostgreSQL から ClickHouse へクエリやアプリコードを移行する際には依然として苦労しています。

このプロセスを簡素化するため、*pg_clickhouse* を開発しました。これは PostgreSQL から直接 ClickHouse 上でアナリティクスクエリを透過的に実行できる拡張機能です。

---

### クイックリンク

| プラットフォーム | リンク |
|-----------------|--------|
| **PGXN** | <https://pgxn.org/package/pg_clickhouse> |
| **GitHub** | <https://github.com/clickhouse/pg_clickhouse> |

**Docker**

```bash
docker run --name pg_clickhouse -e POSTGRES_PASSWORD=my_pass \
  -d ghcr.io/clickhouse/pg_clickhouse:18

チュートリアルを始めるか、Sai のウォークスルービデオをご覧ください。

なぜこの拡張機能なのか？

1. 同一スキーマ・同一クエリ – ClickHouse テーブルは別スキーマに置いても PostgreSQL テーブルと同じように扱える。
2. 変更不要なクエリ実行 – 既存の PostgreSQL クエリをそのまま実行できる。
3. プッシュダウン – クエリ処理は ClickHouse にオフロードされる。
4. 将来性 – 継続的にプッシュダウン機能を拡張していく基盤になる。

仕組み

pg_clickhouse

clickhouse_fdw

追加された主な機能：

percentile_cont()

例：

percentile_cont()

→

quantile()

PostgreSQL:

SELECT type,
       round(min(price)) + 100 AS min,
       round(max(price))   AS max,
       round(percentile_cont(0.5) WITHIN GROUP (ORDER BY price)) AS median,
       round(percentile_cont(0.25) WITHIN GROUP (ORDER BY price)) AS "25th",
       round(percentile_cont(0.75) WITHIN GROUP (ORDER BY price)) AS "75th"
FROM uk.uk_price_paid
GROUP BY type;

pg_clickhouse

SELECT type,
       (round(min(price)) + 100),
       round(max(price)),
       round(quantile(0.5)(price)),
       round(quantile(0.25)(price)),
       round(quantile(0.75)(price))
FROM uk.uk_price_paid
GROUP BY type;

FILTER (WHERE …)

…If(...) > 0

プッシュダウン実行例

（完全表は省略）

SEMI‑JOIN プッシュダウンにより、ほとんどのクエリが数ミリ秒で実行されるようになりました。

ロードマップ

• 残り TPC‑H クエリのプッシュダウン網羅を完了
• ClickBench のプッシュダウンテストと修正
• すべて の PostgreSQL 集計関数・機能をプッシュダウン
• サブクエリの完全なプッシュダウン

• CREATE SERVER

  /

  CREATE USER

  でサーバー／ユーザー単位の ClickHouse 設定を行う
• すべての ClickHouse データ型に対応
• 軽量な

  DELETE

  /

  UPDATE

  サポート
• バッチ

  COPY

  インジェスト
• 任意の ClickHouse クエリを実行しテーブルとして返す関数
• 同一リモートへ向かう全ブランチで

  UNION

  をプッシュダウン

取得方法

GitHub または PGXN からインストールし、実際のワークロードで試してみてください。プッシュダウン失敗があればプロジェクトの issue トラッカーへ報告してください – 私たちが修正します。

Happy querying!