tilebox-ingesting-datasets

Tilebox へのデータセットの取り込み

Tilebox の時間または時空間カタログモデルに適合する、個別のシーン、観測、プロダクト、その他のレコード向けに、再現可能なコンバーターを設計・実装します。主な入力形式であり、最も詳しいドキュメントが整備されているのは STAC ですが、プロバイダーの XML／JSON、API、バケット、ファイルツリーも、同じ正規セマンティクスを裏付ける証拠があればサポートされます。

運用上の契約

新しいインジェスターごとに、次のルールに従ってください。

1. スキーマを設計する前に適合性を確認します。 Tilebox のカタログデータセットは、安定した識別情報、時刻、通常はジオメトリを持つ個別のレコードを表します。解析可能な多次元キューブのチャンクやスライスからシーンレコードを作り出してはいけません。
2. 作成する前に調査します。 フィールドや Tilebox コレクションを提案する前に、代表的なレコード、ソースコレクション、ファイルレイアウト、既知のバリエーションを調べます。
3. ソースをそのまま写すのではなく、クリーンで最新の STAC モデルを作成します。 Tilebox のフィールドを設計する前に、古い STAC と非 STAC の入力を正規の STAC 1.1 および現行の安定した拡張セマンティクスに正規化します。非推奨のプロパティは最新の同等のものに置き換え、セマンティクスが別の場所で保持される場合は冗長なレガシープロパティを省き、未加工のソースパスは変換レシピにのみ保持します。
4. 専用の STAC 構造のみを専用のまま保持します。 必須の空間フィールドには Geometry を使用します。STAC 固有の構造化データセットフィールドは、Assets、Links、Provider、ProcessingSoftware、Storage、Authentication のみです。Item レベルの SARProperties、SatelliteProperties、ProductProperties などの拡張プロパティグループは型付きフィールドにフラット化します。列挙型は列挙型のままにできます。Asset または Band スコープのメタデータは、関連付けが失われるためフラット化してはいけません。
5. 権威ある型付きの値を優先します。 標準的な STAC 拡張プロパティでは、観測された JSON のみや README の表ではなく、最新の正規拡張 JSON Schema からターゲットの型を決定します。レガシー入力の解析にはレガシースキーマのみを使用します。意味的に整数を表すソースの小数文字列は、適切な最小幅の Tilebox 整数型に変換します。正規フィールド自体が任意の JSON として指定されている場合を除き、不確かなソース型を回避するために JSON 文字列、google.protobuf.Value、Struct を使用してはいけません。
6. 曖昧さを推測で解決したり、メタデータを黙って破棄したりしてはいけません。 作業を止め、根拠を示し、選択肢を提案して、ユーザーの判断を変換レシピに記録します。
7. ソースの正規化はコンバーターで行います。 すべてのコンバーターはソースを検証し、プロバイダー固有の解析と STAC 1.1 への正規化を担います。これには、プロバイダーの処理レベルフィールドを正規の processing:level 値にマッピングすることも含まれます。
8. Tilebox CLI でスキーマを作成し、検査します。 スキーマの検出と作成は、取り込みプログラム内に組み込まず、ワークフローの明示的な手順として含めます。
9. 一括取り込みの前に検証します。 Tilebox から代表的なサンプルをクエリして取得し、一括実行を有効にする前に正規セマンティクスを比較します。

関連するリファレンスを選択する

ソースと実装言語に必要なリファレンスだけを読みます。デフォルトでは Python を使用します。Go を使用するのは、ユーザーが明示的に Go を要求した場合、または既存の Go コンバータープロジェクトで作業する場合に限ります。

リファレンス	使用する場面
reference/source-discovery-and-recipe.md	常に使用します。ソースが Tilebox に適合するかを判断し、代表的なバリエーションを調べ、コレクションを設計し、決定事項を記録します。
reference/canonical-stac-1.1.md	常に使用します。STAC のコアフィールド、拡張機能、リンク、メディアタイプ、ロール、クラウド上の場所を正規化します。
reference/non-stac-and-file-tree-sources.md	ソースが XML、非 STAC API、オブジェクトストレージのプレフィックス、COG ディレクトリ、またはその他のファイルツリーの場合に使用します。
reference/stac-protobuf-mapping.md	Tilebox スキーマを設計し、正規化した値を既知のメッセージまたは生成フィールドにマッピングする場合に使用します。
reference/python-converter.md	デフォルトの実装手順です。tilebox-python と、その高水準セマンティック Assets API を使用します。
reference/go-converter.md	ユーザーが明示的に Go を要求した場合、または既存のコンバータープロジェクトが Go で記述されている場合に使用します。データセット型を生成し、tilebox-go で取り込みます。
reference/asset-profile-wire-format.md	Go のみを対象とした、低水準 Asset プロファイルの最適化とワイヤーエンコーディングに使用します。Python では読み込まないでください。AssetCollection がこれを自動的に処理します。
reference/validation.md	ソースの検証、正規化されたセマンティクス、コンパイル済みメッセージ、クエリによる再取得の動作、完全な取り込みをテストする場合に使用します。
reference/examples/earth-search-sentinel-2.md	レガシーの Band 配列、ソース優先の代替項目、便利なクエリ可能項目を扱う場合に使用します。
reference/examples/optical-and-hyperspectral.md	スコープ付きの修正、重複するコレクション、コンテナ内の Band など、光学／ハイパースペクトルの特殊なケースに対応する場合に使用します。
reference/examples/sar.md	空の href、ディレクトリをまたぐ Assets、Band スコープの周波数など、SAR／高度計測の特殊なケースに対応する場合に使用します。
reference/examples/authenticated-assets.md	Copernicus Data Space のパターンなど、認証が必要な場所、Storage、Authentication をモデル化する場合に使用します。

ワークフロー

フェーズ A — 発見と決定

reference/source-discovery-and-recipe.md と、該当するソースのリファレンスを読みます。代表的なバリエーション、正規化されたセマンティクス、スキーマフィールド、識別子、リビジョン、コレクションへの振り分け、未対応のメタデータを含む変換レシピを作成します。重要な決定事項が未解決の間は、データセットを作成しないでください。

フェーズ B — 設計と作成

reference/stac-protobuf-mapping.md を読み、tilebox dataset create のメタデータを更新してから、CLI を通じてレビュー済みのスキーマとコレクションを作成します。型やコンバーターコードを生成する前に、結果の契約を確認します。空でないデータセットには互換性のあるフィールドを追加できますが、既存のフィールドの型変更、名前変更、削除、並べ替え、番号変更は決して行わないでください。

フェーズ C — 変換の実装

Python または Go のリファレンスに従ってレシピを実装します。コンバーターはソースの形式を検証し、文書化されたソース／バージョンの正規化のみを適用し、正規化されたセマンティクスを構築して、データポイントを振り分けます。スキーマの発見や作成は行いません。すべてのオブジェクトにリクエストを送ることなく、相対 href をパスまたは URI として解決します。

フェーズ D — 検証と取り込み

reference/validation.md を読みます。冪等性があり、動作を可視化できる一括取り込みを有効にする前に、範囲を限定したフィクスチャでソース、正規化、SDK、Tilebox のクエリによる再取得の動作を確認します。COG では、ユーザーがウィンドウ読み込みを必要とする場合に備えて、代表的な配信経路でバイト範囲アクセスを検証します。Tilebox には STAC 出力インターフェースがないため、正式な STAC エクスポートを必須とするのではなく、再構築されたセマンティクスを比較してください。

公開ユーザー向けのドキュメントを作成する

データセットの説明は、取り込みレポートではなく、データを見つけて利用したい人向けの製品ドキュメントとして扱います。引き継ぎ前に作成し、tilebox dataset update --description-file で公開してください。

簡潔で実用的な内容にします。

• ミッションやソースプログラム、データセットに含まれる内容、カバレッジや更新頻度に関する注意点、ライセンスを説明し、信頼できるソースへのリンクを示します。
• 利用できるアセットファミリー、それぞれに含まれる内容、一般的なワークフローでユーザーが選ぶべきプロダクトを列挙します。
• バイトデータの保存場所、認証情報やリクエスター・ペイズのアクセスが必要かどうか、利用できる HTTPS、S3、その他の場所を明記します。
• データセットが標準 Assets API に対応している場合は、1 つのデータポイントをクエリし、AssetCollection.from_datapoint(...) でデコードして、tilebox.storage.aio を通じてアセットを読み取るかダウンロードする小さな例を含めます。

コンバーターの仕組み、フィールドマッピングの判断、重複排除のルール、スキップされた補助レコード、正規化の詳細、検証に関する注意事項、その他実装にのみ関係する情報は公開しないでください。ソース固有のサブセットや場所については、科学的な内容やカバレッジの理解に役立つ場合にのみ言及します。リンク、アセット名、アクセス要件、定量的なミッションの主張は、最新のデータと信頼できるドキュメントに照らして確認してください。

適合性と中止条件

ソースの自然なレコードが、安定した識別情報、信頼できる時刻、意味のある境界、有用なカタログメタデータを持つ個別のシーン、取得データ、観測、またはプロダクトである場合、そのソースは適しています。解析済みの Zarr または Icechunk キューブは通常そのまま利用します。具体的なニーズに応える場合に限り、上流の取得データインベントリや実際のプロダクトレコードをカタログ化してください。

証拠により明確な方法が 1 つ定まる場合は、不要な選択肢を提示せずに進めてください。信頼できる証拠から次の事項を特定できない場合に限り、中止して確認を求めてください。

• 識別情報、時刻、ジオメトリ、レコード境界、重複排除、またはコレクションの振り分け
• 安定したフィールドの型や名前、または旧形式の Band 配列の対応関係
• 未知の閉じた値や曖昧なソース値の意味
• 入れ子のメタデータやソース認証の有効な表現
• 相対または空の href に対する正確なベースまたはリゾルバー
• 損失のないクラウド側の代替手段またはファイルツリーの推論ルール

代表的なレコード、ソースと標準形式のパス、観測された値と型、提案する判断、代替案、およびその影響を提示してください。サポートされていない認証については、標準形式では表現できないことを明確に警告してください。回答はレシピに保存してください。

責務の境界

ソースコンバーターの責務は次のとおりです。

• 検出に関するアサーションとソースの検証
• プロバイダー固有の解析と正規化
• 標準 STAC 1.1 のセマンティクス
• セマンティックな Asset、Band、Link、Storage、Authentication の値
• 生成されるデータセットプロパティの値
• 重複排除とコレクションの振り分け
• 可観測性と取り込みの制御

Python のセマンティック Assets API は、STAC Asset／Band の継承の適用、セマンティックな Assets 全体とその場所の検証、およびデータセットフィールド Assets、Storage、Authentication の生成を担当します。Python コンバーターはセマンティックな値を提供し、生成されるメッセージを手作業で再構築しません。

Go にはまだ同等の高水準 API がありません。ワイヤ形式の直接構築は分離し、高度なリファレンスに従い、ゴールデン往復テストで網羅してください。

想定されるプロジェクト成果物

完成した取り込みプロジェクトには、次のものが含まれます。

• 根拠とポリシー上の決定事項を記載した、文書化済みの変換手順。
• Tilebox のスキーマソースとデータセットのドキュメント。
• 繰り返し実行可能なソース変換ツールと取り込みコマンド。
• 不正なケースや正規化済みのケースを含む、代表的なソースフィクスチャ。
• 正規化されたセマンティクス、冪等性、コレクションへのルーティング、クエリによる再取得を検証するテスト。
• 認証情報、リビジョン、再試行、全件取り込みに関する運用ガイダンス。

汎用的なスキーマジェネレーターのスクリプトは作成しないでください。エージェントはユーザーとともに調査とスキーマ設計を行います。コミットするプログラムは、その文書化された契約に従ってレコードを変換し、取り込みます。