---
title: "pg_clickhouse 0.11.1: pgvector と UPDATE、DELETE プッシュダウンに対応"
date: "2026-11-20T06:06:14.818Z"
author: "David Wheeler"
category: "Engineering"
excerpt: "pg_clickhouse 0.11.1 では、ClickHouse Managed Postgres に pgvector 検索や UPDATE、DELETE、TRUNCATE プッシュダウンが追加され、PostgreSQL との互換性がさらに高まりました。"
---

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

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

## pgvector の型マッピング {#pgvector_type_mapping}

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

<pre><code type='click-ui' language='sql'>
CALL clickhouse_perform('ch_server', $$
    CREATE TABLE items (
        id       Int32,
        category String,
        v        Array(Float32)
    ) ENGINE = MergeTree ORDER BY (id);
$$);
</code></pre>

[pg_clickhouse v0.11.1](https://github.com/ClickHouse/pg_clickhouse/releases/tag/v0.11.1) では、`v` カラムを `vector` 型にマッピングできます:

<pre><code type='click-ui' language='sql'>
CREATE EXTENSION vector;
CREATE FOREIGN TABLE items (
    id       int NOT NULL,
    category text NOT NULL,
    v        vector(4) NOT NULL
) SERVER ch_server;
</code></pre>

ここでは ClickHouse の `Array(Float32)` カラムを PostgreSQL の `vector` カラムにマッピングするため、[IMPORT FOREIGN SCHEMA](https://clickhouse.com/docs/ja/products/managed-postgres/extensions/pg_clickhouse/reference#import-foreign-schema) ではなく明示的な [CREATE FOREIGN TABLE](https://clickhouse.com/docs/ja/products/managed-postgres/extensions/pg_clickhouse/reference#create-foreign-table) を使っています。ClickHouse の `Array(Float64)` カラムに対しても同様に機能します。これで `vector` 配列の値を挿入できるようになります:

<pre><code type='click-ui' language='sql'>
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;
</code></pre>

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

<pre><code type='click-ui' language='sql'>
SELECT * FROM items ORDER BY id LIMIT 5;
</code></pre>

```shell
 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](https://github.com/ClickHouse/pg_clickhouse/releases/tag/v0.11.1) は、[pgvector](https://github.com/pgvector/pgvector) の演算子や関数も多数プッシュダウンします。もっとも単純な例として `=` も含まれており、`EXPLAIN (VERBOSE)` の「Remote SQL」行で確認できます:

<pre><code type='click-ui' language='sql'>
EXPLAIN (COSTS OFF, VERBOSE) SELECT * FROM items WHERE v = '[0,0,0,0]';
</code></pre>

```shell
                                               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)
```

結果は予想どおりです:

<pre><code type='click-ui' language='sql'>
SELECT * FROM items WHERE v = '[0,0,0,0]';
</code></pre>

```shell
 id | category |     v     
----+----------+-----------
  0 | a        | [0,0,0,0]
(1 row)
```

さらにうれしいことに、pg_clickhouse は [pgvector の距離演算子](https://pgxn.org/dist/vector/#Querying)もプッシュダウンします。たとえば `<->` は ClickHouse の [L2Distance](https://clickhouse.com/docs/ja/reference/functions/regular-functions/distance-functions#L2Distance) 関数へとプッシュダウンされ、これも `EXPLAIN (VERBOSE)` の「Remote SQL」行で確認できます:

<pre><code type='click-ui' language='sql'>
EXPLAIN (VERBOSE, COSTS OFF)
SELECT id FROM items ORDER BY v &lt;-&gt; '[0.3,-0.2,0.5,0.1]' LIMIT 5;
</code></pre>

```shell
                                                               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)
```

実行結果はこちらです:

<pre><code type='click-ui' language='sql'>
SELECT id FROM items ORDER BY v &lt;-&gt; '[0.3,-0.2,0.5,0.1]' LIMIT 5;
</code></pre>

```shell
 id 
----
  0
 33
 77
 58
 14
(5 rows)
```

ClickHouse の関数へプッシュダウンされる [pgvector](https://github.com/pgvector/pgvector) の演算子および関数の一覧は次のとおりです:

| pgvector 演算子 | pgvector 関数       | 名前              | ClickHouse       |
| --------------- | ------------------- | ----------------- | ---------------- |
| `=`             |                     | [equals](https://clickhouse.com/docs/ja/reference/functions/regular-functions/comparison-functions#equals)                 | `=`              |
| `<>`            |                     | [notEquals](https://clickhouse.com/docs/ja/reference/functions/regular-functions/comparison-functions#notEquals)              | `<>`             |
| `<->`           | `l2_distance()`     | L2 距離           | [L2Distance](https://clickhouse.com/docs/ja/reference/functions/regular-functions/distance-functions#L2Distance)     |
| `<+>`           | `l1_distance()`     | L1 距離           | [L1Distance](https://clickhouse.com/docs/ja/reference/functions/regular-functions/distance-functions#L1Distance)     |
| `<=>`           | `cosine_distance()` | コサイン距離      | [cosineDistance](https://clickhouse.com/docs/ja/reference/functions/regular-functions/distance-functions#cosineDistance) |
| `<#>`           |                     | (負の) 内積       | [dotProduct](https://clickhouse.com/docs/ja/reference/functions/regular-functions/array-functions#arrayDotProduct)     |
|                 | `inner_product()`   | 内積              | [dotProduct](https://clickhouse.com/docs/ja/reference/functions/regular-functions/array-functions#arrayDotProduct)     |
|                 | `vector_dims()`     | 次元数            | [length](https://clickhouse.com/docs/ja/reference/functions/regular-functions/array-functions)         |

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

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

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

この `Vector Index Not Used` という行から、クエリが[ベクトル類似度インデックス](https://clickhouse.com/docs/ja/reference/engines/table-engines/mergetree-family/annindexes#vector-similarity-index)を使っていないことがはっきりとわかります。では、インデックスを使うことはできるのでしょうか? インデックスを追加して確かめてみましょう:

<pre><code type='click-ui' language='sql'>
CALL clickhouse_perform('ch_server', $$
    ALTER TABLE items ADD INDEX v_idx v TYPE vector_similarity('hnsw', 'L2Distance', 4);
$$);
</code></pre>

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

<pre><code type='click-ui' language='sql'>
EXPLAIN (VERBOSE, COSTS OFF)
SELECT id FROM items ORDER BY v &lt;-&gt; '[0.3,-0.2,0.5,0.1]' LIMIT 5;
</code></pre>

```shell
                                                               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 のエグゼキュータがこのクエリでそのインデックスを使用した可能性があることを検出するようになりました。クエリの結果は変わりません:

<pre><code type='click-ui' language='sql'>
SELECT id FROM items ORDER BY v &lt;-&gt; '[0.3,-0.2,0.5,0.1]' LIMIT 5;
</code></pre>

```shell
 id 
----
  0
 33
 77
 58
 14
(5 rows)
```

pg_clickhouse は、サポート対象の演算子に対応する類似度関数 ([cosineDistance](https://clickhouse.com/docs/ja/reference/functions/regular-functions/distance-functions#cosineDistance)、[L1Distance](https://clickhouse.com/docs/ja/reference/functions/regular-functions/distance-functions#L1Distance) など) を用いた `vector_similarity` インデックスの ClickHouse 側での使用状況を検出し、レポートします。

## UPDATE、DELETE、TRUNCATE {#update_delete_truncate}

[pg_clickhouse v0.11.1](https://github.com/ClickHouse/pg_clickhouse/releases/tag/v0.11.1) では、[MergeTree](https://clickhouse.com/docs/ja/reference/engines/table-engines/mergetree-family/mergetree) ファミリーのテーブルに対する `UPDATE`、`DELETE`、`TRUNCATE` 文のサポートも導入されました。`UPDATE` 文と `DELETE` 文はそれぞれ軽量な [UPDATE](https://clickhouse.com/docs/ja/reference/statements/update) 文または [DELETE](https://clickhouse.com/docs/ja/concepts/features/operations/delete/lightweight-delete) 文としてプッシュダウンされ、`TRUNCATE` 文はもちろんそのまま [TRUNCATE](https://clickhouse.com/docs/ja/reference/statements/truncate) 文としてプッシュダウンされます。

`items` テーブルで実際に試してみましょう。まず、[UPDATE](https://clickhouse.com/docs/ja/reference/statements/update) を使うには ClickHouse 側でいくつかの設定を有効にする必要があります:

<pre><code type='click-ui' language='sql'>
CALL clickhouse_perform('ch_server', $$
    ALTER TABLE items
    MODIFY SETTING enable_block_number_column = 1, enable_block_offset_column = 1;
$$);
</code></pre>

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

<pre><code type='click-ui' language='sql'>
UPDATE items SET v = '[1,1,1,1]' WHERE id = 0;
</code></pre>

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

<pre><code type='click-ui' language='sql'>
select * FROM items where id = 0;
</code></pre>

```shell
 id | category |     v     
----+----------+-----------
  0 | a        | [1,1,1,1]
(1 row)
```

続いて `DELETE` です:

<pre><code type='click-ui' language='sql'>
DELETE FROM items where id = 0;
</code></pre>

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

<pre><code type='click-ui' language='sql'>
select * FROM items where id = 0;
</code></pre>

```shell
 id | category | v 
----+----------+---
(0 rows)
```

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

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

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

<pre><code type='click-ui' language='sql'>
TRUNCATE items;
</code></pre>

すべて消えました:

<pre><code type='click-ui' language='sql'>
select COUNT(*) from items;
</code></pre>

```shell
 count 
-------
     0
(1 row)
```

## その他のハイライト {#other_highlights}

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

[pg_clickhouse v0.11.1](https://github.com/ClickHouse/pg_clickhouse/releases/tag/v0.11.1) では、[ClickHouse に線形回帰集約関数が追加された](https://www.linkedin.com/posts/alasdair-brown_clickhouse-269-adds-the-regr-family-familiar-ugcPost-7507187538965688320-ChAW/) ClickHouse 26.9 以降に対して、`regr_*` ファミリーのプッシュダウンも追加されました。対象は次のとおりです:

*   [regr_avgx](https://clickhouse.com/docs/ja/reference/functions/aggregate-functions/regr_avgx)
*   [regr_avgy](https://clickhouse.com/docs/ja/reference/functions/aggregate-functions/regr_avgy)
*   [regr_count](https://clickhouse.com/docs/ja/reference/functions/aggregate-functions/regr_count)
*   [regr_intercept](https://clickhouse.com/docs/ja/reference/functions/aggregate-functions/regr_intercept)
*   [regr_r2](https://clickhouse.com/docs/ja/reference/functions/aggregate-functions/regr_r2)
*   [regr_slope](https://clickhouse.com/docs/ja/reference/functions/aggregate-functions/regr_slope)
*   [regr_sxx](https://clickhouse.com/docs/ja/reference/functions/aggregate-functions/regr_sxx)
*   [regr_sxy](https://clickhouse.com/docs/ja/reference/functions/aggregate-functions/regr_sxy)
*   [regr_syy](https://clickhouse.com/docs/ja/reference/functions/aggregate-functions/regr_syy)

例:

<pre><code type='click-ui' language='sql'>
EXPLAIN (VERBOSE, COSTS OFF)
      SELECT regr_avgy(b, a) FROM agg_bin.agg_numbers;
</code></pre>

```shell
                              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 の挙動と一致するようになります:

<pre><code type='click-ui' language='sql'>
EXPLAIN (VERBOSE, COSTS OFF) SELECT SUM(id) FROM items;
</code></pre>

```shell
                      QUERY PLAN                       
-------------------------------------------------------
 Foreign Scan
   Output: (sum(id))
   Relations: Aggregate on (items)
   Remote SQL: SELECT sumOrNull(id) FROM default.items
(4 rows)
```

<pre><code type='click-ui' language='sql'>
SELECT SUM(id) FROM items;
</code></pre>

```shell
 sum 
-----
    
(1 row)
```

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

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

<pre><code type='click-ui' language='sql'>
EXPLAIN (VERBOSE, COSTS OFF)
      SELECT id FROM json_http.events WHERE props['address']['city'] = '"Paris"';
</code></pre>

```shell
                                              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` 値の互換性が保たれます:

<pre><code type='click-ui' language='sql'>
EXPLAIN (VERBOSE, COSTS OFF)
      SELECT percentile_cont(0.95) WITHIN GROUP (
        ORDER BY date_part('epoch', timezone('UTC', c))
      ) FROM t1;
</code></pre>

```shell
                                                                  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)` を使用するようになり、それを超える長さの値に対してはエラーを送出するようになりました。また、[コミュニティからのコントリビューション](https://github.com/ClickHouse/pg_clickhouse/pull/459)により、こうした値の末尾のゼロも適切に除去されるようになりました:

<pre><code type='click-ui' language='sql'>
EXPLAIN (VERBOSE, COSTS OFF)
      SELECT round(regr_syy(b, a)::numeric, 4), regr_syy(b, a)::numeric FROM agg_numbers;
</code></pre>

```shell
                                                                                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)
```

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

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

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

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

## その他の変更点 {#and_the_rest}

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

---

## ClickHouse Managed Postgres を今すぐ始める

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

[サインアップ](https://console.clickhouse.cloud/signUp?intent=pg&loc=blog-cta-3109-clickhouse-managed-postgres&utm_blogctaid=3109)

---