地理空間データ加工を作成する

Pipeline Builder では、地理空間データを読み込み、加工して活用できます。地理空間ワークフローが Pipeline Builder の現在の機能でまだサポートされていない場合は、Foundry のレガシーの地理空間ドキュメントを参照し、Code Repositories でデータを加工してください。

地理空間データをモデル化する

論理型

Pipeline Builder は、論理型という概念を使って地理空間データを内部的にモデル化します。論理型は、表されるデータに追加の制約を設けたベースタイプ（文字列、Integer、ブール値、配列、構造体）です。たとえば、ジオメトリ型は有効な GeoJSON でなければならない文字列として定義されます。一方、Geopoint は、経度が -180 以上 180 以下、緯度が -90 以上 90 以下の構造体でなければなりません。サポートされているデータ型の全リストは、以下を参照してください。

Pipeline Builder のすべての論理型は、そのベースタイプを継承しています。たとえば、ジオメトリは文字列型の入力を期待する式への入力として使用できますが、その逆はできません。ベースタイプから、そのベースタイプを拡張した特定の論理型にキャストするには、「論理型キャスト」式を使用できます。この式は、その論理型に関連する制約をデータに適用し、この検証に失敗した値を null にします。式で入力と出力に論理型を指定できるため、地理空間専用の式が GeoJSON 文字列を期待する場合には、確実に GeoJSON 文字列が渡されます。

サポートされている地理空間データ型

Pipeline Builder は現在、次の地理空間データ型をサポートしています。

• Geopoint： longitude と latitude の構造体です。longitude は -180 以上 180 以下の Double、latitude は -90 以上 90 以下の Double です。Geopoint は、WGS:84 または EPSG:4326 の座標参照系（CRS）に従った有効な (x, y) 座標でなければなりません。
• ジオメトリ： GeoJSON 仕様に準拠した、文字列化された JSON blob です。個々の座標は、Geopoint 型と同様に WGS:84/EPSG:4326 形式であることが期待されます。
• H3Index： 有効な H3 六角形インデックスを表す文字列です。
• LatLonBoundingBox： minLat、minLon、maxLat、maxLon の構造体で表される境界ボックスです。各エントリは有効な Geopoint であり、maxLat > minLat および maxLon > minLon を満たします。
• オントロジー 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 表現を構築します。すべての UTM ゾーンを含む、EPSG データベース内のほとんどの座標系からの変換をサポートしています。
• ジオメトリ：
  • Well-known text (WKT) をパース： Well-known text (WKT) 文字列をジオメトリ論理型に変換します。WKT がまだ WGS:84 でない場合は、任意でソースの座標系識別子を指定し、ソースの座標参照系から WGS:84 に変換できます。
  • ジオメトリを正規化： WGS:84 形式の GeoJSON 文字列を受け取り、正しい順序（右手の法則）、閉じたリング、重複の除去、ポイントの次元数の統一という属性を正規化します。
  • Shapefile から行を抽出： 生のシェープファイルのデータセットを受け取り、各シェープファイルを、各エントリのジオメトリとプロパティを含む行にパースします。出力データセットには、ジオメトリ列と、ユーザーが指定したプロパティごとの列が含まれます。WGS:84 以外のデータセットには、座標参照系を指定できます。
  • GeoJSON から行を抽出： 生の GeoJSON ファイルのデータセットを受け取り、各シェープファイルを、各エントリのジオメトリとプロパティを含む行にパースします。出力データセットには、ジオメトリ列と、ユーザーが指定したプロパティごとの列が含まれます。WGS:84 以外のデータセットには、座標参照系を指定できます。

上記の2つのデータ型を相互に変換する式や、H3 インデックス、MGRS、境界ボックス、オントロジー Geopoint 形式に変換する式もあります。

地理空間データ形式について、座標参照系と投影法のドキュメントで詳しくはこちら。

地理空間データを加工する

Pipeline Builder の地理空間データ型の列にデータを格納すると、地理空間データ専用のデータ加工を利用できます。ほとんどのデータ加工は、ストリーミングとバッチの両方のワークフローでサポートされています。主なものを以下に示します。

ジオメトリの比較

• 積集合
• 差集合
• 対称差集合
• 和集合（列単位および集計）

球面ジオメトリ

• 2点間のハバーサイン距離／大円距離
• 逆ハバーサイン距離（始点、距離、方位角から終点を計算）
• ジオメトリの面積／重心／長さ

H3

• 指定した解像度で H3 六角形の隣接セルを取得
• 指定した解像度の H3 六角形でポリゴンをカバー

複雑な形状の近似

• 楕円／円
• レンジファン（環状扇形）
• 指定したジオメトリの凸包

地理空間結合

Pipeline Builder は、以下の地理空間結合をサポートしています。

• ジオメトリ積集合結合
• ジオメトリ積集合アンチ結合
• ジオメトリ距離結合
• ジオメトリ最近傍結合
• 近似最近傍（ANN）結合

ジオメトリ積集合結合

Pipeline Builder のジオメトリ積集合結合には2個のデータセットが必要で、それぞれにジオメトリ型の列が必要です。ジオメトリ積集合結合は、入力データ型としてオントロジー Geopoint または Geopoint を受け付けません。結合を適用する前に、ジオメトリ列を正規化し、出力に null 値が不要な場合は明示的に除外することを推奨します。パイプラインに非決定性または別の結合がある場合は、地理空間結合の前に Checkpoint を追加することを推奨します。

ジオメトリ積集合結合の代わりに、「ジオメトリに交差あり」フィルターを設定したクロス結合を使用すると、メモリー使用量がより安定する場合があります。ただし、この方法ではビルド時間が大幅に増加する可能性があります。

ジオメトリ積集合アンチ結合

Pipeline Builder のジオメトリ積集合アンチ結合は、右側のデータセットのどのジオメトリとも交差しないジオメトリを持つ行を、左側のデータセットから返します。この結合は、バッチとストリーミングの両方のパイプラインでサポートされています。

ジオメトリ積集合アンチ結合には2個のデータセットが必要で、それぞれにジオメトリ型の列が必要です。積集合結合と同様に、ジオメトリ列を正規化し、出力に null 値が不要な場合は明示的に除外することを推奨します。

ジオメトリ距離結合

Pipeline Builder のジオメトリ距離結合には、それぞれにジオメトリ型の列がある2個のデータセット、0より大きい距離の値、および指定した距離の単位を決める座標参照系の文字列が必要です。たとえば、座標参照系に「epsg:4326」を指定した場合、距離の単位は度とみなされます。積集合結合と同様に、ジオメトリ列を正規化し、出力に null 値が不要な場合は明示的に除外することを推奨します。パイプラインに別の結合または非決定性がある場合は、結合の前に Checkpoint を追加します。

ジオメトリ k 近傍（KNN）結合

Pipeline Builder のジオメトリ最近傍結合には、ジオメトリの base データセットと点の neighbors データセットの2個が必要です。整数パラメーター k は、各ベースジオメトリについて検索する最近傍の数を設定します。ベースジオメトリと近傍点の間の距離を計算して比較する方法を決めるために、座標参照系が必要です。結果は結合された行で、各行にはベースジオメトリに最も近い k 個の点のうち1個の Geopoint が含まれます。同距離の場合は任意に選択され、結果は特定の順序では返されません。

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

近似最近傍（ANN）結合

Pipeline Builder の近似最近傍（ANN）結合は、厳密な精度よりも処理速度を優先する、KNN 結合の代替手段です。各行について厳密に K 個の最近傍を検索する KNN 結合とは異なり、ANN 結合は推定した近い候補を使用することで、精度の低下をわずかに抑えながら処理速度を大幅に向上させます。

厳密な精度よりも処理速度を優先する場合、または厳密な KNN 結合では遅すぎる大規模なデータセットを扱う場合は、ANN 結合の使用を検討してください。厳密な最近傍の結果が必要なユースケースでは、代わりにジオメトリ KNN 結合を使用します。

トラブルシューティング

結合で安定性の問題が発生している場合は、以下の手順で対処します。

1. 結合の前に不要な列を削除します。
2. 入力ジオメトリを簡素化します（たとえば、大きなジオメトリに対して粒度を粗くできますか？）
3. 垂直方向にスケールします。ドライバーとエグゼキューターのメモリーが多いコンピューティングプロファイルを手動で選択します。
4. 最大の入力データセットを約2,500万行ずつに分割し、別のビルドで結果を和集合としてまとめます。
5. 出力行数（つまり、左右のジオメトリ間の交差数）を減らします。

データ加工の結果をプレビューする

Pipeline Builder でデータの加工が完了したら、その結果を地図上で視覚的に検証できます。通常のプレビューペインで、地図上でプレビューするセルを選択します（セルは、上記の地理空間データ型のいずれかの列に含まれている必要があります）。右クリックして、ジオプレビューを開くを選択します。

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

地理空間データをオントロジーで使用する

Pipeline Builder の地理空間機能は、プラットフォーム全体の下流データとシームレスに統合できるように設計されています。

• オントロジー
  • Builder のジオメトリ列のデータ型は、オントロジーの Geoshape データ型に対応していますが、Builder で列をオブジェクトにマッピングする前に、必ず「ジオメトリを正規化」式を適用してください。これにより、オントロジーにデータをインデックス化する際に実行される検証に Geoshape データが合格することが保証されます。
  • 現在の Geopoint 論理データ型はオントロジーで直接使用できませんが、インデックス化する前に、ポイントを「オントロジー Geopoint」データ型（'{lat},{lon}' 形式の文字列）に簡単に変換できます。
• データセット
  • 地理空間データ型のデータは、Builder パイプラインの出力データセットに保存されます。そのため、そのデータセットから下流の Builder パイプラインを作成しても、データの正しい論理データ型および地理空間データ型は保持されます。
• 地理時系列の同期
  • Geopoint 列とジオメトリ列を地理時系列の同期出力にマッピングして、Map アプリケーションなどの下流のアプリケーションでポイントとジオメトリを描画できます。すべての地理時系列の同期出力には、各行に対応する観測の位置を示す Geopoint 列が必要です。統合で地理空間プロパティを設定する方法の詳細については、地理時系列出力のドキュメントを参照してください。