PolarDB:ベクターピラミッドモデル

前提条件

開始する前に、以下の条件を満たしていることを確認してください：

• PolarDB for PostgreSQL クラスター

• ジオメトリ列を含むテーブル

• ジオメトリ列に対する空間インデックス

拡張機能のインストール

CREATE EXTENSION ganos_geometry_pyramid CASCADE;

権限関連の問題を回避するため、拡張機能は public スキーマにインストールすることを推奨します。

CREATE EXTENSION ganos_geometry_pyramid WITH SCHEMA public;

ベクタータイルピラミッドの構築

-- "test" テーブル上にピラミッドを構築
-- id 列は int4 または int8 型である必要があります
-- sourceSRS はソースデータの座標系を指定します（ここでは EPSG:4326）
SELECT ST_BuildPyramid('test', 'geom', 'id', '{"sourceSRS":4326}');

構築が完了すると、ピラミッドはクエリにすぐに利用可能になります。

タイルのクエリ

タイルは z/x/y スキームでアドレス指定されます。z はズームレベル、x は列インデックス、y は行インデックスです。すべての値はゼロベースであり、タイルグリッドの左上を原点とします。ズームレベル 0 では世界全体が 1 枚のタイルでカバーされ、以降の各レベルではタイル数が 4 倍になります。API では、このアドレスは z_x_y 形式で表現されます。

ST_Tile を使用すると MVT 形式のベクタータイルを返し、ST_AsPNG を使用するとレンダリング済みの PNG イメージを返します。

-- ズームレベル 0、列 0、行 0 のタイルをクエリ
-- デフォルトの投影座標系は EPSG:3857 です
-- タイルが存在する場合は MVT 形式で返却し、存在しない場合は null を返却します
SELECT ST_Tile('test', '0_0_0');

ピラミッドの更新

テーブルの行を更新した後は、変更内容を反映するためにピラミッドを更新してください。

空間範囲が小さい更新（全エリアの 1 % 未満）の場合：

-- 新しいジオメトリレコードを挿入
INSERT INTO test(id, geom) VALUES (1, ST_GeomFromEWKT('SRID=4326;POINT(10.1 10.1)'));
INSERT INTO test(id, geom) VALUES (2, ST_GeomFromEWKT('SRID=4326;LINESTRING(10.1 10.1,11 11)'));
INSERT INTO test(id, geom) VALUES (3, ST_GeomFromEWKT('SRID=4326;POLYGON((10 10,11 11,11 12,10 10))'));

-- バウンディングボックスを用いて影響を受ける領域のみを更新
SELECT ST_UpdatePyramid('test', 'geom', 'id', ST_SetSRID(ST_MakeBox2D(ST_Point(9, 9), ST_Point(12, 12)), 4326));

データセットの大部分に影響を与える更新の場合、ピラミッドを再構築してください：

-- 異なる地理的エリアにまたがるレコードを挿入
INSERT INTO test(id, geom) VALUES (4, ST_GeomFromEWKT('SRID=4326;POINT(-59 -45)'));
INSERT INTO test(id, geom) VALUES (5, ST_GeomFromEWKT('SRID=4326;LINESTRING(110 60,115 70)'));
INSERT INTO test(id, geom) VALUES (6, ST_GeomFromEWKT('SRID=4326;POLYGON((-120 59,-110 65,-110 70,-120 59))'));

-- ピラミッドを再構築（既存のピラミッドは自動的に削除されます）
SELECT ST_BuildPyramid('test', 'geom', 'id', '{"sourceSRS":4326}');

ピラミッドおよび拡張機能の削除

-- ピラミッドを削除
SELECT ST_DeletePyramid('test');

-- 拡張機能を削除
DROP EXTENSION ganos_geometry_pyramid CASCADE;

ピラミッドへの名前付け

デフォルトでは、ピラミッドは対応するテーブル名と同じ名前になります。同一テーブル上に複数のピラミッドを作成する場合は、カスタム名を指定してください：

-- "test" テーブル上に "hello" という名前のピラミッドを作成
SELECT ST_BuildPyramid('test', 'geom', 'id', '{"name": "hello"}');

並列タスクによる構築

大規模なデータセットでは、並列タスクを活用することでピラミッド構築を高速化できます。0 を指定すると、許容される最大並列数が自動的に使用されます。

-- 4 つの並列タスクを使用して構築
SELECT ST_BuildPyramid('test', 'geom', 'id', '{"parallel": 4}');

制約事項：

• 並列数は、設定済みコア数の 4 倍を超えてはなりません。

• 並列構築では 2 相コミット機構が使用されます。PostgreSQL の設定ファイルで max_prepared_transactions を 100 以上に設定し、クラスターを再起動してください。

タイルパラメーターの設定

-- タイルサイズを 512、タイル拡張量を 8 に設定
SELECT ST_BuildPyramid('test', 'geom', 'id', '{
  "tileSize": 512,
  "tileExtend": 8
}');

最大ピラミッドレベルの設定

最大レベルは、事前に構築されるズームレベル数を制御します。このレベルを超えるズームレベルでは、タイルが動的に生成されます。設定しない場合、システムはデータ密度に基づいて最大レベルを算出し、デフォルト値は 16 です。

-- ズームレベル 0～12 を事前に構築し、それより高いレベルは動的に生成
SELECT ST_BuildPyramid('test', 'geom', 'id', '{"maxLevel": 12}');

buildRules を用いたレベルごとのフィルタリング

buildRules を使用すると、各ズームレベルで表示される特徴量およびタイルに格納される属性を制御できます。これにより、粗いズームレベルにおけるタイルサイズを削減でき、最上位のピラミッドレベルのタイル生成（時間のかかる処理）を回避できます。

-- レベル 0～5：空のタイル（"1!=1" というフィルターは常に偽）
-- レベル 6～9：code=1 の特徴量のみ、"name" 属性を含む
-- レベル 10～15：すべての特徴量、"name" および "width" 属性を含む
SELECT ST_BuildPyramid('test', 'geom', 'id', '{
  "buildRules":[
    {
      "level":[0,1,2,3,4,5],
      "value": {
        "filter": "1!=1"
      }
    },
    {
      "level":[6,7,8,9],
      "value": {
        "filter": "code=1",
        "attrFields": ["name"]
      }
    },
    {
      "level":[10,11,12,13,14,15],
      "value": {
        "attrFields": ["name", "width"]
      }
    }
  ]
}');

特徴量のマージ

merge を buildRules 内で使用すると、同じ属性値を持つ隣接する特徴量を結合できます。これにより、粗いズームレベルにおける特徴量の総数を削減できます。

-- レベル 0～5 で、code=1 または code=2 の特徴量をマージ
SELECT ST_BuildPyramid('test', 'geom', 'id', '{
  "buildRules":[
    {
      "level":[0,1,2,3,4,5],
      "value": {
        "merge": ["code=1","code=2"]
      }
    }
  ]
}');

ST_BuildPyramidUseGeomSideLen を用いた高速な構築および更新

ST_BuildPyramidUseGeomSideLen は、ST_BuildPyramid と比較して、構築および増分更新の両方において効率性が向上しています。ただし、各ジオメトリの最大バウンディングボックス幅（X 軸または Y 軸方向）を格納する追加列と、その列に対する B ツリーインデックスが必要です。

-- ステップ 1：ジオメトリの最大バウンディングボックス幅を格納する列を追加
ALTER TABLE test
ADD COLUMN geom_side_len DOUBLE PRECISION;

-- ステップ 2：列を埋める
CREATE OR REPLACE FUNCTION add_max_len_values() RETURNS VOID AS $$
DECLARE
  t_curs CURSOR FOR
    SELECT * FROM test;
  t_row test%ROWTYPE;
  gm GEOMETRY;
  x_min DOUBLE PRECISION;
  x_max DOUBLE PRECISION;
  y_min DOUBLE PRECISION;
  y_max DOUBLE PRECISION;
BEGIN
  FOR t_row IN t_curs LOOP
    SELECT t_row.geom INTO gm;
    SELECT ST_XMin(gm) INTO x_min;
    SELECT ST_XMax(gm) INTO x_max;
    SELECT ST_YMin(gm) INTO y_min;
    SELECT ST_YMax(gm) INTO y_max;
    UPDATE test
      SET geom_side_len = GREATEST(x_max - x_min, y_max - y_min)
    WHERE CURRENT OF t_curs;
  END LOOP;
END;
$$ LANGUAGE plpgsql;

SELECT add_max_len_values();

-- ステップ 3：列に対する B ツリーインデックスを作成
CREATE INDEX ON test USING btree(geom_side_len);

-- ステップ 4：幅を格納する列を用いてピラミッドを構築
SELECT ST_BuildPyramidUseGeomSideLen('roads', 'geom', 'geom_side_len', 'id',
  '{"sourceSRS":4326}');