概要
MVTEncodeGeom— ジオメトリをスリッピーマップ タイル内のローカルなピクセル空間に投影し、 タイルの範囲にクリップするスカラー関数です。MVTEncode— グループ内の投影済みジオメトリを集約し、単一レイヤーのタイルのバイナリ バイト列に変換する 集約関数です。
MVTBoundingBox と MVTBoundingBoxMercator はタイルのバウンディング ボックスを返すため、行を
WHERE 句でその範囲内に絞り込み、索引を使用できます。
Point、line、polygon のジオメトリがサポートされており、Geometry 型と具体的な Geo 型 (Point,
LineString, MultiLineString, Ring, Polygon, MultiPolygon) も含まれます。
結果として得られるバイト列は完全なタイルであり、FORMAT RawBLOB を使って HTTPインターフェイス 経由で直接返すことができます。
これらの関数は PostGIS のワークフローに対応しており、別名として PostGIS 名でも利用できます。MVTEncodeGeom の別名が ST_AsMVTGeom、
MVTEncode の別名が ST_AsMVT です。
MVTEncodeGeom
zoom、tile_x、tile_y で識別される
slippy-map タイルのタイル内ローカルなピクセル空間に投影し、タイルにクリップして整数ピクセルグリッドにスナップし、
タイル空間のジオメトリを返します。
投影には、UInt32 の座標範囲全体にわたる Web Mercator を使用します。返される座標の始点はタイルの
左上隅で、y 軸は下向きです。これは Mapbox Vector
Tile フォーマットの座標規約であるため、結果はそのまま MVTEncode に渡せます。座標は整数ピクセルに丸められるため、
MVTEncodeGeom でグループ化すると、同じグリッド上にあるジオメトリは 1 つのクラスターに集約されます。
clip が有効な場合 (デフォルト) 、ジオメトリは buffer ピクセルだけ拡張されたタイル (各軸で
[-buffer, extent + buffer] の範囲) にクリップされます。完全に外側にあるジオメトリは NULL になります。これは
PostGIS の ST_AsMVTGeom に相当します。
出力ジオメトリの型は入力に応じて決まります。Point は Point を返します。LineString または MultiLineString は
MultiLineString を返します。Ring、Polygon、MultiPolygon は MultiPolygon を返します (クリッピングによりジオメトリが
複数のパーツに分割される場合があります) 。
構文
geometry— 経度/緯度 (度単位) の Geometry。経度は[-180, 180]に、緯度は Web Mercator の範囲[-85.05112878, 85.05112878]に収まるように丸められます。Point/LineString/MultiLineString/Ring/Polygon/MultiPolygon/Geometry。zoom— Slippy-map のズームレベル。範囲は[0, 32]です。UInt8。tile_x— タイルの列インデックス。範囲は[0, 2^zoom - 1]です。UInt32。tile_y— タイルの行インデックス。範囲は[0, 2^zoom - 1]です。UInt32。extent— 省略可能なタイル extent (1 辺あたりのピクセル数) 。範囲は[1, 2147483647]です。既定値は Mapbox Vector Tile の既定値である4096です。UInt32。buffer— 省略可能なクリップバッファ (ピクセル単位) 。範囲は[0, 2147483647]です。既定値は1です。UInt32。clip— 省略可能なフラグです。0 以外 (既定値) の場合、ジオメトリはタイルとバッファを含む範囲にクリップされます。UInt8。
NULL を返します。Geometry。
例
MVTEncode
MVTEncodeGeom に対応する集約関数です。各入力行は 1 つのフィーチャになり、Point、line、Polygon のジオメトリをサポートします。
geometry 引数はタイル空間座標の Geometry で、通常は MVTEncodeGeom によって生成されます。ジオメトリが NULL の行 (たとえば MVTEncodeGeom によってクリップアウトされたもの) はスキップされます。省略可能な properties 引数は名前付きタプルで、その要素名がフィーチャの attribute キーとなり、要素の型がベクタータイルの値の型を決定します。
結果は単一レイヤーのタイルの生バイト列です。空のグループからは空のタイルが生成されます。これは PostGIS の ST_AsMVT に相当します。
構文
layer_name— ベクタータイルレイヤーの名前。String。extent— タイルの各辺のピクセル数で表した extent。範囲は[1, 2147483647]です。デフォルトは4096。UInt32。feature_id_name—propertiesタプル内の符号なし整数要素の名前を指定する省略可能なパラメータです。指定した要素は、タグではなく MVT Feature のid(UInt64) として出力されます。符号付き整数は受け付けられません。NULLのidはそのフィーチャでは省略されます。パラメータは位置指定のため、これを使うにはextentを指定する必要があります。String。stringify_unsupported— 省略可能なフラグ (0/1、デフォルトは0) 。1を指定すると、直接サポートされていないプロパティ型 (例: 大きな整数、UUID、Decimal) は、error を発生させる代わりにテキストのstring_valueとしてエンコードされます。UInt8。
geometry— タイル空間のジオメトリ。たとえばMVTEncodeGeomの出力です。Geometry。properties— フィーチャの属性を表す省略可能な named tuple。要素名は属性キーになります。Tuple。
String。
プロパティ型
Value バリアントとしてエンコードされます。
| ClickHouse 型 | ベクタータイルの値型 |
|---|---|
String / FixedString | string_value |
Float32 / BFloat16 | float_value |
Float64 | double_value |
Bool | bool_value |
Int8 / Int16 / Int32 / Int64 / Date32 | sint_value |
UInt8 / UInt16 / UInt32 / UInt64 / Date / DateTime | uint_value |
Nullable や LowCardinality でラップされることがあります。NULL 値の場合、そのフィーチャでは 해당 attribute は省略されます。これは、ベクタータイル形式では null を扱えないためです。その他のプロパティ型では例外が発生しますが、stringify_unsupported が設定されている場合は、テキストの string_value としてエンコードされます。
同じプロパティ値はレイヤーの共有値プールにインターンされるため、多数のフィーチャで現れる値でも
一度だけ格納されます。
プロパティ タプルへの命名
tuple(...) 内のカラムの別名はタプルの
要素名に引き継がれないため、キャストを使って要素に名前を付けてください:
クラスタリング
MVTEncodeGeom はピクセル単位の整数に丸めるため、ピクセルジオメトリでグループ化すると重なったジオメトリはマージされます。グループはサブクエリで集約し、クラスターごとに 1 行だけを MVTEncode に渡します。
Geometry 値でグループ化するには、allow_suspicious_types_in_group_by = 1 が必要です。これは、Variant ベースの
Geometry 型によるグループ化がデフォルトで制限されているためです。クラスタ化されたフィーチャではなく、入力の各行につき 1 つのフィーチャを出力するには、
内側の GROUP BY (および count()) を省略してください。
MVTBoundingBox
zoom、tile_x、tile_y で識別される slippy-map タイルの地理的なバウンディングボックスを、度単位のタプル
(min_lon, min_lat, max_lon, max_lat) として返します。
これを使うと、各行で Web Mercator 投影を再計算する代わりに、longitude/latitude カラムを直接フィルタしながら、対象の行をタイル内に絞り込めます。これにより、それらのカラムの主キーや
索引を利用できます。省略可能な margin は、タイルサイズに対するその割合だけボックスを各辺で拡張します。MVTEncodeGeom のクリップバッファをカバーするには、これを
buffer / extent に設定してください。
構文
zoom— Slippy-map のズームレベル。範囲は[0, 32]です。UInt8。tile_x— タイルの列インデックス。範囲は[0, 2^zoom - 1]です。UInt32。tile_y— タイルの行インデックス。範囲は[0, 2^zoom - 1]です。UInt32。margin— 各辺でボックスを拡張するための、タイルサイズに対するオプションの比率です。デフォルトは0です。Float64。
(min_lon, min_lat, max_lon, max_lat) として返します。Tuple(Float64, Float64, Float64, Float64)。
例
MVTBoundingBoxMercator
MVTBoundingBox の Web Mercator 版です。MVTEncodeGeom が内部で使用する full-UInt32 の Web Mercator 座標空間におけるタイルの
バウンディングボックスを、タプル
(min_x, min_y, max_x, max_y) として返します。y 軸は下向きに増加します (上が北です) 。longitude/latitude の代わりに、Mercator 座標のカラムをマテリアライズして
それらに索引を作成するテーブルを想定しています。
構文
MVTBoundingBox と同じです。
戻り値
タイルのバウンディングボックスを、Web Mercator 座標系でのタプル (min_x, min_y, max_x, max_y) として返します。Tuple(Float64, Float64, Float64, Float64)。
例
行をタイルに制限する
WHERE 句で低コストかつ索引を利用するバウンディングボックス条件 (性能) と、MVTEncodeGeom によるクリップ処理 (正確性) です。
このクリップ処理ではタイル外のジオメトリが除外されるため、バウンディングボックス条件が多少緩くても、タイル外のジオメトリが結果に入り込むことはありません。
MVTEncodeGeom のclipによって適用されます。クリッピングを無効にし、
WHERE predicateのみに依存するには、clip => false (7番目のargument) を MVTEncodeGeom に渡します。
HTTP 経由でタイルを配信する
/ でのみクエリを受け付けます。すっきりした
/tile/{z}/{x}/{y} URL は、サーバー設定の predefined query ハンドラー を使ってオペレーターが追加します。ハンドラーの url は regex: 形式を使ってパスセグメントを取り込み、それらをクエリ
パラメータにバインドし、FORMAT RawBLOB でバイト列を返します。
もっとも単純なケースでは、テーブルに Geometry カラムがあり、ハンドラーは 1 行につき 1 つの地物を返します。MVTEncodeGeom
は各ジオメトリを要求されたタイルに投影してクリップするため、タイル外の行は自動的に除外されます。
shapes は、geom Geometry カラム (points、lines、polygons を任意に混在できる) を持つテーブルです。GET /tile/10/550/335
は、エンコードされたタイルを返します。
ポイントデータの場合も、MVTEncodeGeom((lon, lat)::Point, …) を使ってポイントをインラインで構築すれば、通常の longitude/latitude カラムに対して同様に機能します。同一位置のフィーチャをクラスター化したり、大きなテーブルに対して索引を使用するバウンディングボックスの事前フィルタを追加したりするには、Clustering および
Restricting rows to a tile に示すように内部クエリを拡張してください。
制限事項
-
Web Mercator 投影では緯度は
±85.05112878°に制限され、反子午線をまたぐ入力は処理できません。 -
Polygon のクリッピングでは、MVT として有効な出力は保証されません。 クリッピングによってリングの向きと閉合は修正されますが、自己交差は修正されません。したがって、自己交差する (“bow-tie” 型の) リングは修復されず、タイルとの交わり方によっては、そのまま出力される (この場合も無効なまま) か、
NULLとして破棄されます。たとえば、タイル内に完全に収まる bow-tie は破棄されますが、同じ 4 つの頂点を単純なリングとして結んだものは保持されます。
- ジオメトリは、整数ピクセルグリッドに丸められる前にクリップされます。 PostGIS では、まずジオメトリを整数ピクセルグリッドにスナップし、その後でクリップします。一方、
MVTEncodeGeomでは、まずクリップし (浮動小数点の投影座標上で実行) 、その後で丸めます。タイルの端付近では、この違いにより、本来なら境界ピクセルに丸められるはずの座標が落とされることがあります。たとえば、buffer = 0の場合、タイル境界のすぐ東にある点はクリップされます。これは、先に丸める方式であれば保持される境界ピクセル4096に丸められるにもかかわらずです: