注: 以下の翻訳の正確性は検証されていません。AIPを利用して英語版の原文から機械的に翻訳されたものです。

ジオスペーシャルトランスフォームの作成

Pipeline Builder を使用すると、ジオスペーシャルデータをロード、トランスフォーム、および操作できます。ユーザーのジオスペーシャルワークフローがまだ Pipeline Builder の現在の機能でサポートされていない場合は、Foundry の従来のジオスペーシャルドキュメントを参照して、Code Repositories でデータをトランスフォームしてください。

ジオスペーシャルデータのモデリング

論理型

Pipeline Builder は、論理型の概念を使用して内部的にジオスペーシャルデータをモデル化します。これは、追加の制約を持つ基本型（文字列、整数、ブール値、配列、構造体）です。たとえば、Geometry 型は有効な GeoJSON である必要がある文字列として定義され、GeoPoint は経度が -180 から 180 の間で、緯度が -90 から 90 の間の構造体でなければなりません（両方とも含む）。サポートされている型の完全なリストは以下にあります。

Pipeline Builder のすべての論理型は基本型の継承者です。たとえば、ジオメトリは文字列型の入力を期待する式の入力として使用できますが、その逆はできません。基本型からその基本型を拡張する特定の論理型にキャストするには、「論理型キャスト」式を使用します。これにより、その論理型に関連付けられた制約がデータに適用され、この検証に失敗した値はすべてヌルになります。式が入力と出力として論理型を指定できる能力により、ジオスペーシャル固有の式が GeoJSON 文字列を期待する場合、GeoJSON 文字列が受け取られることが保証されます。

サポートされているジオスペーシャル型

Pipeline Builder は現在、以下のジオスペーシャル型をサポートしています：

GeoPoint: longitude と latitude の構造体で、longitude は -180 から 180 の間の倍精度浮動小数点数、latitude は -90 から 90 の間の倍精度浮動小数点数です（両方とも含む）。GeoPoint は WGS:84 または EPSG:4326 座標リファレンスシステム (CRS) に従った有効な (x, y) 座標でなければなりません。
Geometry: GeoJSON 仕様に準拠した文字列化された JSON ブロブ。個々の座標は GeoPoint 型と同様に WGS:84/EPSG:4326 形式であることが期待されます。
H3Index: 有効な H3 六角形インデックスを表す文字列。
LatLonBoundingBox: minLat, minLon, maxLat, maxLon の構造体で表されるバウンディングボックス。各エントリは有効な GeoPoint であり、maxLat > minLat および maxLon > minLon でなければなりません。
Ontology GeoPoint: オントロジーの GeoPoint プロパティ型と互換性のある文字列で、形式 {lat},{lon} を満たす必要があります。ここで、-90 <= lat <= 90 および -180 <= lon <= 180 です。
MGRS: 有効な MGRS（軍用グリッドリファレンスシステム）座標を表す文字列。

ジオスペーシャルデータのロード

Pipeline Builder は、さまざまなジオスペーシャルデータ用のトランスフォームと式をサポートしています。

GeoPoint:
- GeoPoint 列の作成: lat,lon ペアを取り、上記の境界を検証し、GeoPoint 表現に変換します。
- 座標系 (CRS) から GeoPoint の作成: x,y ペアと座標リファレンスシステムを取り、その (x,y) を WGS:84 に投影し、GeoPoint 表現を構築します。EPSG データベースのほとんどの座標系からの変換をサポートしています。UTM ゾーンを含みます。
Geometry:
- 既知のテキスト (WKT) の解析: 既知のテキスト (WKT) 文字列をジオメトリ論理型に変換します。オプションで、WKT がすでに WGS:84 でない場合、ソース CRS から WGS:84 への変換のためにソース座標システム識別子を指定することができます。
- Geometry の正規化: WGS:84 形式の GeoJSON 文字列を与えられた場合、次の属性を正規化します：適切な順序（右手の法則）、閉じたリング、重複削除、点の一定の次元。
- シェープファイルからの行の抽出: 生のシェープファイルのデータセットを与えられた場合、各シェープファイルを解析して各エントリのジオメトリとプロパティを含む行に変換します。出力データセットにはジオメトリ列と、ユーザーがリストした各プロパティの列が含まれます。非 WGS:84 データセットの場合、座標リファレンスシステムを指定できます。
- GeoJSON からの行の抽出: 生の GeoJSON ファイルのデータセットを与えられた場合、各シェープファイルを解析して各エントリのジオメトリとプロパティを含む行に変換します。出力データセットにはジオメトリ列と、ユーザーがリストした各プロパティの列が含まれます。非 WGS:84 データセットの場合、座標リファレンスシステムを指定できます。

上記の2つの型間の変換や、これらを H3 インデックス、MGRS、バウンディングボックス、および Ontology GeoPoint フォーマットに変換するための追加の式も存在します。

座標リファレンスシステムと投影に関するドキュメントでジオスペーシャルデータ形式について詳しく学ぶ

ジオスペーシャルデータのトランスフォーム

Pipeline Builder のジオスペーシャル型の列を作成したら、ジオスペーシャルデータに特化したトランスフォームを活用できます。ほとんどのトランスフォーム（ジオジョインを除く）は、現在ストリーミングおよびバッチワークフローの両方でサポートされています。以下にいくつかのハイライトを示します。

ジオメトリ比較

交差
差分
対称差分
結合（列単位および集約）

球面ジオメトリ

2点間のハバース/大円距離
逆ハバース距離（開始点、距離、および方位角を指定して終点を計算）
ジオメトリの面積/重心/長さ

H3

特定の解像度での H3 六角形の近隣を取得
特定の解像度で H3 六角形でポリゴンをカバー

複雑な形状の近似

楕円/円
範囲ファン（環状セクター）
与えられたジオメトリの凸包

ジオスペーシャルジョイン

Pipeline Builder は以下のジオスペーシャルジョインをサポートしています：

ジオメトリ交差ジョイン
ジオメトリ距離ジョイン
ジオメトリ最も近い隣接ジョイン

ジオメトリ交差ジョイン

Pipeline Builder のジオメトリ交差ジョインには、各データセットにジオメトリ型の列が必要です。ジオメトリ交差ジョインは、Ontology GeoPoint または GeoPoint を入力型として受け入れません。ジョインを適用する前に、ジオメトリ列を正規化し、出力に不要な null 値を明示的にフィルター処理することをお勧めします。パイプラインに非決定性や他のジョインがある場合は、ジオジョインの前にチェックポイントを追加することをお勧めします。

Pipeline Builder は中規模のジオメトリ（約34点まで）を持つデータセットを最大で両側に 100 万行までのスケールで結合できます。出力行数の2倍の増加を前提としています。歪んだデータの場合、ジョインは一方で 2 億 5000 万行、他方で 1.6 千行までサポートできます。ジオメトリのサイズが増加するにつれて、安定性が低下する可能性があります。ジョインは、最大で 4 万点の大規模ジオメトリを持つデータセットを最大で 50 万行まで一貫してサポートします。これ以上のスケールは断続的に成功する場合がありますが、公式にはサポートされていません。

ジオメトリ交差ジョインの出力行数がクロスジョインと同等の場合、ジョインの安定性が低下する可能性があります。

ジオメトリ交差ジョインの代替として、「ジオメトリが交差する」フィルターを設定したクロスジョインが、より安定したメモリ使用量を提供する場合があります。ただし、このアプローチはビルド時間の急激な増加を招く可能性があります。もう一つの代替案として、Code Repositories 内の geospatial-tools PySpark ライブラリを使用することもできます。詳細については、Palantir の担当者にお問い合わせください。

ジオメトリ距離ジョイン

Pipeline Builder のジオメトリ距離ジョインには、各データセットにジオメトリ型の列、ゼロより大きい距離の値、および距離の単位を決定する座標リファレンスシステム文字列が必要です。たとえば、座標リファレンスシステムに "epsg:4326" が指定されている場合、距離は度単位であると見なされます。交差ジョインと同様に、ジオメトリ列を正規化し、出力に不要な null 値を明示的にフィルター処理することをお勧めします。パイプラインに他のジョインや非決定性がある場合、ジョイン前にチェックポイントを追加します。

Pipeline Builder は、小規模のジオメトリ（各約8点まで）を持つデータセットを最大で両側に 100 万行までのスケールで結合できます。ジョインの結果として行数が2倍になることを前提としています。出力行数がクロスジョインと同等の場合、安定性が低下する可能性があります。

ジオメトリ距離ジョインの代替として、ジオメトリバッファと「ジオメトリが交差する」フィルターを設定したクロスジョインが、大量の行数増加時により安定したメモリ使用量を提供する場合があります。ただし、このアプローチは多くの場合、ビルド時間の急激な増加を招く可能性があります。

ジオメトリ最も近い隣接 (KNN) ジョイン

Pipeline Builder のジオメトリ最も近い隣接ジョインには、ジオメトリの base データセットとポイントの neighbors データセットが必要です。k 整数パラメーターは、各ベースジオメトリに対して見つける最も近い隣接点の数を設定します。距離が計算および比較される方法を決定するために、座標リファレンスシステムが必要です。結果は、ベースジオメトリに最も近い k 個のポイントの1つを含む GeoPoint を含む結合された行のセットになります。タイは任意に解決され、結果は特定の順序で返されません。

このジョインには2つの要件があります：

neighbors データセット内のすべての GeoPoint は、エグゼキューターとドライバのメモリに収まる必要があります。これは現在の厳格な要件であり、ジョインのスケーラビリティを制限します。neighbors データセットの分散が必要なユースケースについては、Palantir の担当者にお問い合わせください。
Foundry は現在、メモリ消費を制限するために neighbors データセットに GeoPoint 論理型のみを受け入れています。ジョインの neighbors 側にポイント以外のジオメトリが必要な場合は、Palantir の担当者にお問い合わせください。

実際には、Pipeline Builder は k の控えめな値（< 5）をサポートし、neighbors データセットに数十万行、base データセットに 100 万ジオメトリまでをサポートします。両方のデータセットに数十万行ある場合、Pipeline Builder ははるかに大きな値の k をサポートできます。数百の最も近い隣接点を見つけることは、そのような場合には迅速に完了するはずです。このポイントを超える入力のスケールを増やすと、断続的に成功する場合がありますが、現在のところ一般的にはサポートされていません。

トラブルシューティング

ジョインの安定性に問題がある場合は、次の手順を使用して修正してください：

ジョイン前に不要な列を削除する。
入力ジオメトリを簡素化する（たとえば、大規模なジオメトリに対して粗い粒度を使用できますか？）。
垂直スケールを実行する。ドライバとエグゼキューターのメモリが多い計算プロファイルを手動で選択します。
最大の入力データセットを約 2500 万行のセットに分割し、別のビルドで結果を結合します。
出力行数を減らす（つまり、左と右のジオメトリ間の交差数）。

トランスフォーム結果のプレビュー

Pipeline Builder でデータのトランスフォームが完了したら、これらのトランスフォームの結果をマップ上で視覚的に検証できます。通常のプレビューペインで、マップ上でプレビューしたいセル（上記のジオスペーシャル型のいずれかの列のセルでなければなりません）を選択します。右クリックして Open Geo Preview を選択します。

新しいプレビュータブが表示され、選択したセルがマップ上にプロットされます。

オントロジーでジオスペーシャルデータを使用する

Pipeline Builder のジオスペーシャル機能は、プラットフォーム全体の下流データとシームレスに統合されるように設計されています。

オントロジー
- Builder のジオメトリ列型はオントロジーのジオシェイプ型と互換性がありますが、列を Builder 内のオブジェクトにマッピングする前に「ジオメトリの正規化」式を適用してください。これにより、ジオシェイプデータがオントロジーにデータをインデックス化する際に実行される検証に合格することが保証されます。
- 現在の GeoPoint 論理型はオントロジーで直接使用できませんが、ポイントはインデ