Skip to content

pg_clickhouse 0.11.1: pgvector と UPDATE、DELETE プッシュダウンに対応

image 512x512 1
2026年11月19日 · 13分で読む

マイナーバージョンアップだからといって侮ることはできません。先週リリースされた pg_clickhouse v0.11.1 には、UPDATE、DELETE、TRUNCATE、そして pgvector 検索のプッシュダウンをはじめ、数多くの機能改善とバグ修正が含まれています。

pgvector の型マッピング

まずは最後の項目、pgvector の型マッピングから見ていきましょう。次のような ClickHouse テーブルがあるとします:

CALL clickhouse_perform('ch_server', $$
    CREATE TABLE items (
        id       Int32,
        category String,
        v        Array(Float32)
    ) ENGINE = MergeTree ORDER BY (id);
$$);

pg_clickhouse v0.11.1 では、v カラムを vector 型にマッピングできます:

CREATE EXTENSION vector;
CREATE FOREIGN TABLE items (
    id       int NOT NULL,
    category text NOT NULL,
    v        vector(4) NOT NULL
) SERVER ch_server;

ここでは ClickHouse の Array(Float32) カラムを PostgreSQL の vector カラムにマッピングするため、IMPORT FOREIGN SCHEMA ではなく明示的な CREATE FOREIGN TABLE を使っています。ClickHouse の Array(Float64) カラムに対しても同様に機能します。これで vector 配列の値を挿入できるようになります:

INSERT INTO items VALUES (0, 'a', '[0,0,0,0]');

INSERT INTO items
SELECT i, (ARRAY['a', 'b', 'c'])[i % 3 + 1],
       format('[%s,%s,%s,%s]', sin(i), cos(i), sin(i * 2), cos(i * 3))::vector
  FROM generate_series(1, 100) i;

もちろん SELECT で取得することもできます:

SELECT * FROM items ORDER BY id LIMIT 5;
id | category |                       v                       
----+----------+-----------------------------------------------
  0 | a        | [0,0,0,0]
  1 | b        | [0.84147096,0.5403023,0.9092974,-0.9899925]
  2 | c        | [0.9092974,-0.41614684,-0.7568025,0.96017027]
  3 | a        | [0.14112,-0.9899925,-0.2794155,-0.91113025]
  4 | b        | [-0.7568025,-0.6536436,0.98935825,0.84385395]
(5 rows)

pgvector 演算子のプッシュダウン

pg_clickhouse v0.11.1 は、pgvector の演算子や関数も多数プッシュダウンします。もっとも単純な例として = も含まれており、EXPLAIN (VERBOSE) の「Remote SQL」行で確認できます:

EXPLAIN (COSTS OFF, VERBOSE) SELECT * FROM items WHERE v = '[0,0,0,0]';
QUERY PLAN                                                
---------------------------------------------------------------------------------------------------------
 Foreign Scan on public.items
   Output: id, category, v
   Remote SQL: SELECT id, category, v FROM default.items WHERE ((v = cast([0,0,0,0] as Array(Float32))))
(3 rows)

結果は予想どおりです:

SELECT * FROM items WHERE v = '[0,0,0,0]';
id | category |     v     
----+----------+-----------
  0 | a        | [0,0,0,0]
(1 row)

さらにうれしいことに、pg_clickhouse は pgvector の距離演算子もプッシュダウンします。たとえば <-> は ClickHouse の L2Distance 関数へとプッシュダウンされ、これも EXPLAIN (VERBOSE) の「Remote SQL」行で確認できます:

EXPLAIN (VERBOSE, COSTS OFF)
SELECT id FROM items ORDER BY v <-> '[0.3,-0.2,0.5,0.1]' LIMIT 5;
QUERY PLAN                                                                
-----------------------------------------------------------------------------------------------------------------------------------------
 Foreign Scan on public.items
   Output: id, (v <-> '[0.3,-0.2,0.5,0.1]'::vector)
   Vector Search: L2Distance on v
   Vector Index: none
   Vector Index Not Used: column "v" has no vector index
   Remote SQL: SELECT id, v FROM default.items ORDER BY L2Distance(v, cast([0.3,-0.2,0.5,0.1] as Array(Float32))) ASC NULLS LAST LIMIT 5
(6 rows)

実行結果はこちらです:

SELECT id FROM items ORDER BY v <-> '[0.3,-0.2,0.5,0.1]' LIMIT 5;
id 
----
  0
 33
 77
 58
 14
(5 rows)

ClickHouse の関数へプッシュダウンされる pgvector の演算子および関数の一覧は次のとおりです:

pgvector 演算子pgvector 関数名前ClickHouse
=equals=
<>notEquals<>
<->l2_distance()L2 距離L2Distance
<+>l1_distance()L1 距離L1Distance
<=>cosine_distance()コサイン距離cosineDistance
<#>(負の) 内積dotProduct
inner_product()内積dotProduct
vector_dims()次元数length

pgvector インデックスのプッシュダウン

鋭い読者の方は、実行計画の出力に「Vector」という行があることにお気づきでしょう:

Vector Search: L2Distance on v
   Vector Index: none
   Vector Index Not Used: column "v" has no vector index

この Vector Index Not Used という行から、クエリがベクトル類似度インデックスを使っていないことがはっきりとわかります。では、インデックスを使うことはできるのでしょうか? インデックスを追加して確かめてみましょう:

CALL clickhouse_perform('ch_server', $$
    ALTER TABLE items ADD INDEX v_idx v TYPE vector_similarity('hnsw', 'L2Distance', 4);
$$);

もう一度 L2 距離演算子を使ってみます:

EXPLAIN (VERBOSE, COSTS OFF)
SELECT id FROM items ORDER BY v <-> '[0.3,-0.2,0.5,0.1]' LIMIT 5;
QUERY PLAN                                                                
-----------------------------------------------------------------------------------------------------------------------------------------
 Foreign Scan on public.items
   Output: id, (v <-> '[0.3,-0.2,0.5,0.1]'::vector)
   Vector Search: L2Distance on v
   Vector Index: v_idx
   Remote SQL: SELECT id, v FROM default.items ORDER BY L2Distance(v, cast([0.3,-0.2,0.5,0.1] as Array(Float32))) ASC NULLS LAST LIMIT 5
(5 rows)

ご覧のとおりです! ClickHouse テーブルに L2Distance() インデックスがあり、ClickHouse のエグゼキュータがこのクエリでそのインデックスを使用した可能性があることを検出するようになりました。クエリの結果は変わりません:

SELECT id FROM items ORDER BY v <-> '[0.3,-0.2,0.5,0.1]' LIMIT 5;
id 
----
  0
 33
 77
 58
 14
(5 rows)

pg_clickhouse は、サポート対象の演算子に対応する類似度関数 (cosineDistance、L1Distance など) を用いた vector_similarity インデックスの ClickHouse 側での使用状況を検出し、レポートします。

UPDATE、DELETE、TRUNCATE

pg_clickhouse v0.11.1 では、MergeTree ファミリーのテーブルに対する UPDATE、DELETE、TRUNCATE 文のサポートも導入されました。UPDATE 文と DELETE 文はそれぞれ軽量な UPDATE 文または DELETE 文としてプッシュダウンされ、TRUNCATE 文はもちろんそのまま TRUNCATE 文としてプッシュダウンされます。

items テーブルで実際に試してみましょう。まず、UPDATE を使うには ClickHouse 側でいくつかの設定を有効にする必要があります:

CALL clickhouse_perform('ch_server', $$
    ALTER TABLE items
    MODIFY SETTING enable_block_number_column = 1, enable_block_offset_column = 1;
$$);

これで更新を実行できるようになります:

UPDATE items SET v = '[1,1,1,1]' WHERE id = 0;

結果を確認してみましょう:

select * FROM items where id = 0;
id | category |     v     
----+----------+-----------
  0 | a        | [1,1,1,1]
(1 row)

続いて DELETE です:

DELETE FROM items where id = 0;

消えたでしょうか? 消えていますね:

select * FROM items where id = 0;
id | category | v 
----+----------+---
(0 rows)

なお、PostgreSQL の UPDATE と DELETE は ClickHouse とは異なり、WHERE 句が必須ではない点にご注意ください。WHERE 句がない場合、pg_clickhouse は PostgreSQL の挙動に合わせるため WHERE true を挿入します。とはいえ、ClickHouse テーブルの全行を更新したり削除したりしたいケースはまずないはずです! ドキュメントにも次のように記載されています:

軽量更新は、少量の行 (テーブル全体の最大約 10%) を更新するよう設計されています。

すべての行を削除する代わりに、TRUNCATE を使用してください:

TRUNCATE items;

すべて消えました:

select COUNT(*) from items;
count 
-------
     0
(1 row)

その他のハイライト

線形回帰集約関数のプッシュダウン

pg_clickhouse v0.11.1 では、ClickHouse に線形回帰集約関数が追加された ClickHouse 26.9 以降に対して、regr_* ファミリーのプッシュダウンも追加されました。対象は次のとおりです:

例:

EXPLAIN (VERBOSE, COSTS OFF)
      SELECT regr_avgy(b, a) FROM agg_bin.agg_numbers;
QUERY PLAN                              
----------------------------------------------------------------------
 Foreign Scan
   Output: (regr_avgy((b)::double precision, (a)::double precision))
   Relations: Aggregate on (agg_numbers)
   Remote SQL: SELECT regr_avgyOrNull(b, a) FROM agg_test.agg_numbers
(4 rows)

集約結果の NULL 対応

先ほどのサンプル出力に regr_avgyOrNull() が登場していたためネタバレになってしまいましたが、改めて説明しておくと、今回のリリースでは NULL を返しうる集約関数が集約対象の値を持たない場合に、ClickHouse のデフォルト値 (例: 0) ではなく実際に NULL を返すようになりました。pg_clickhouse は sum、avg、min などの代わりに sumOrNull、avgOrNull、minOrNull をプッシュダウンするようになり、これによって Postgres の挙動と一致するようになります:

EXPLAIN (VERBOSE, COSTS OFF) SELECT SUM(id) FROM items;
QUERY PLAN                       
-------------------------------------------------------
 Foreign Scan
   Output: (sum(id))
   Relations: Aggregate on (items)
   Remote SQL: SELECT sumOrNull(id) FROM default.items
(4 rows)
SELECT SUM(id) FROM items;
sum 
-----
    
(1 row)

JSON 添字構文のプッシュダウン

JSONB の添字構文である data['a']['b'] が、ClickHouse カラムの「ドット記法」へプッシュダウンされるようになりました:

EXPLAIN (VERBOSE, COSTS OFF)
      SELECT id FROM json_http.events WHERE props['address']['city'] = '"Paris"';
QUERY PLAN                                              
------------------------------------------------------------------------------------------------------
 Foreign Scan on json_http.events
   Output: id
   Remote SQL: SELECT id FROM json_test.events WHERE ((toJSONString(props.address.city) = '"Paris"'))
(3 rows)

TimeZone のプッシュダウン

ClickHouse 23.6 以降では、pg_clickhouse が常に PostgreSQL の TimeZone に合わせて session_timezone を設定し、DateTime 関数にも PostgreSQL の TimeZone を渡すようになりました。これにより、timestamp 値と timestamptz 値の互換性が保たれます:

EXPLAIN (VERBOSE, COSTS OFF)
      SELECT percentile_cont(0.95) WITHIN GROUP (
        ORDER BY date_part('epoch', timezone('UTC', c))
      ) FROM t1;
QUERY PLAN                                                                   
-----------------------------------------------------------------------------------------------------------------------------------------------
 Foreign Scan
   Output: (percentile_cont('0.95'::double precision) WITHIN GROUP (ORDER BY (date_part('epoch'::text, timezone('UTC'::text, c)))))
   Relations: Aggregate on (t1)
   Remote SQL: SELECT quantileOrNull(0.95)(toUnixTimestamp(toDateTime64(toString(c, 'America/Los_Angeles'), 6, 'UTC'))) FROM functions_test.t1
(4 rows)

精度指定なしの NUMERIC

精度指定のない numeric カラムに対して、pg_clickhouse は ClickHouse で指定可能な最大の Decimal サイズである Decimal(76, 38) を使用するようになり、それを超える長さの値に対してはエラーを送出するようになりました。また、コミュニティからのコントリビューションにより、こうした値の末尾のゼロも適切に除去されるようになりました:

EXPLAIN (VERBOSE, COSTS OFF)
      SELECT round(regr_syy(b, a)::numeric, 4), regr_syy(b, a)::numeric FROM agg_numbers;
QUERY PLAN                                                                                 
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------
 Foreign Scan
   Output: (round((regr_syy((b)::double precision, (a)::double precision))::numeric, 4)), ((regr_syy((b)::double precision, (a)::double precision))::numeric)
   Relations: Aggregate on (agg_numbers)
   Remote SQL: SELECT round(cast(regr_syyOrNull(b, a), 'Nullable(Decimal(76, 38))'), 4), cast(regr_syyOrNull(b, a), 'Nullable(Decimal(76, 38))') FROM agg_test.agg_numbers
(4 rows)

このクエリを実行すると、以前の出力は次のようになっていました:

round                     |                   regr_syy                   
----------------------------------------------+----------------------------------------------
 68756.21570000000000000000000000000000000000 | 68756.21569392930381649593538520770884423405
(1 row)

現在は次のようになります:

round    |                   regr_syy                   
------------+----------------------------------------------
 68756.2157 | 68756.21569392930381649593538520770884423405
(1 row)

その他の変更点

ここまで主な変更点を紹介してきましたが、すべての変更内容については変更履歴をご覧ください。もちろん、pg_clickhouse v0.11.1 は本日より新規および既存のすべての ClickHouse Managed Postgres サーバーでご利用いただけます。マイナーリリースのため、すべての環境で特別な操作なしに今回の改善が適用されます。ただし、v0.10 以前からアップグレードする場合は ALTER EXTENSION pg_clickhouse UPDATE; を実行してください。

ClickHouse Managed Postgres を今すぐ始める

手元のデータで ClickHouse Managed Postgres がどのように動作するか試してみませんか。数分で ClickHouse Cloud の利用を開始でき、$300 分の無料クレジットを受け取れます。

サインアップ

この記事をシェア

  • Y Combinator icon
  • X icon
  • Bluesky icon
  • Facebook icon
  • LinkedIn icon

Subscribe to our newsletter

Stay informed on feature releases, product roadmap, support, and cloud offerings!

Follow us

XBlueskySlackGithubTelegramMeetupRSS