tilebox-datasets

Tilebox データセットの管理

ターゲット製品の要件に合った Tilebox データセットの選定や、データセットの確認、クエリ、スキーマ設計、作成・更新、ドキュメント作成、コレクション管理、データポイントの検索、生成される型など、データセットに関する運用・設計作業にこのスキルを使用します。ライブカタログの確認や操作には、CLI を優先してください。

新しい STAC カタログ、プロバイダーの XML/JSON ソース、オブジェクトストアのプレフィックス、または COG ファイルツリーを取り込み、そのコンバーターを実装する場合は、tilebox-ingesting-datasets に切り替えてください。このスキルでは、ソースの適合性、代表的なデータの探索、STAC 1.1 の正規化、Assets/Links/Storage/Authentication の標準マッピング、変換レシピ、Python/Go での実装、取り込みの検証を扱います。一般的なライブカタログの操作やソースの選定には、このスキルに戻ってください。

CLI メタデータの更新

記憶に頼る前に、インストール済みの正確なフラグとスキーマを確認してください。

tilebox agent-context dataset --output-schema

関連ドキュメントの概念：

• データセットは型が厳密に定義されたコンテナーです。データセット内のすべてのデータポイントは、そのデータセットのスキーマに従います。
• データセットの種類ごとに必須フィールドが自動的に追加されます。カスタムスキーマには必須フィールドを含めないでください。
• カスタムフィールドの説明と値の例は、スキーマのドキュメントの自動生成に利用されます。
• データが取り込まれた後は、既存のフィールドを削除または変更できません。フィールドは省略可能なため、新しいフィールドは追加できます。
• データが一度も含まれたことのないデータセットは、自由に編集できます。以前に取り込んだデータを削除すればこの制約がなくなると決めつけず、互換性を損なう更新を計画する前に、ライブバックエンドを確認してください。

対象プロダクトからデータセットを選択する

ユーザーが地球観測の成果について説明していても、データセット名を指定していない場合は、なじみのないスラッグから選ぶようユーザーに尋ねず、こちらで選択します。

1. 対象プロダクトを、観測モダリティ、プロダクトレベル、バンドまたは偏波、空間分解能、期間、再訪頻度、提供までの遅延、雲の許容度、品質保証（QA）、検証要件に分解します。
2. reference/earth-observation-product-selection.md を読み、既定の選択肢と有意義な代替案を特定します。
3. reference/open-data-dataset-catalog.md を読み、正確な Tilebox スラッグ、ペイロードの提供元、フォーマット、認証、制約を確認します。
4. tilebox dataset list --json と tilebox dataset get <slug> --json でライブカタログに照らして候補を確認します。
5. 要求された AOI と期間を対象に、少量のメタデータをクエリします。記憶しているスキーマを鵜呑みにせず、コレクション、フィールド、カバレッジ、アセットの場所、アクセスメタデータを確認します。
6. ソースへのアクセスを、認証なしの公開アクセス、提供元による認証、リクエスター支払い、制限付きのいずれかに分類します。データアクセスのコードを書く前に、リンク先の提供元ガイドを読みます。
7. 既定の選択肢を1つ選び、適合する理由を説明します。代替案は、トレードオフが有用な場合にのみ提示します。センサーや提供元を黙って組み合わせてはいけません。

一般的な光学マルチスペクトル地表反射率の処理では、ユーザーがソースを指定しておらず、Sentinel-2 の分解能、カバレッジ、再訪頻度、雲に関する制約が適切な場合、既定では open_data.aws_earth.sentinel2 を使用します。Element 84 の AWS Earth Search L2A ペイロードは公開 COG であり、ソース提供元の認証情報は不要です。過去にさかのぼる記録を長くするために Landsat 8/9 を追加する案は任意の選択肢として提案できますが、グリッド、分解能、スペクトル応答、放射量、スタイルの調整が大きな複雑さを伴うため、Sentinel-2 と Landsat を組み合わせたパイプラインを既定で作成してはいけません。

一般的な Sentinel-1 の振幅／後方散乱処理では、ユーザーがソースを指定しておらず、GRD が目的に適合する場合、コレクション GRD の open_data.aws_earth.sentinel1 を既定で使用します。Element 84 の AWS Earth Search ペイロードは、署名なしの S3 および HTTPS ロケーションから利用できる公開 AWS アセットのため、ソース提供元の認証情報やリクエスター支払いの設定は不要です。GRD で十分な場合は、レガシーの open_data.copernicus.sentinel1_sar データセットよりこちらを優先します。AWS データセットに含まれるのは GRD のみです。SLC 位相データ、OCN、RAW、または利用できない別のプロダクトが必要な場合は、適切な Copernicus コレクションを使用します。

現在、認証情報なしで利用できる例には、open_data.capella.sar、open_data.iceye.sar、open_data.planet.tanager、open_data.satellogic.earth_view、open_data.umbra.sar、open_data.wyvern.dragonette があります。この一覧は網羅的ではありません。認証情報なしで利用できるデータセットは追加される可能性があるため、ライブカタログを確認してください。これらの商用ミッションのサンプルは、空間的・時間的なカバレッジが限られているか、厳選されています。ユーザーがその提供元、ミッション、プロダクトについて尋ねた場合は、候補として提示し、内容を確認してください。雲のないモザイク、定期的なモニタリング、任意の AOI など、対象範囲の広いアプリケーションの既定の選択肢にはしないでください。まずライブデータセットが要求された場所と期間をカバーしているか確認します。

成果物に雲を透過する SAR、変位、活発な火災または温度の測定、物体単位でより細かな分解能、Sentinel-2 より長い過去のアーカイブ、または明示的に指定された提供元／プロダクトのレイアウトが必要な場合は、光学の既定の選択肢を使用してはいけません。干渉測量、コヒーレンス、変位には、互換性のある SLC プロダクトと追加処理が必要なため、Sentinel-1 GRD の既定の選択肢を使用してはいけません。

Tilebox 外部の補助データを選択する

ワークフローでは、Tilebox がインデックス化していない補助データが必要になることがよくあります。たとえば、DEM、気象または気候の再解析データ、恒久水域マスクや土地マスク、人口データ、その他の全球グリッドなどです。これらは補助入力として扱い、Tilebox のデータセットスラッグを作り出さないでください。reference/auxiliary-data-sources.md を読み、最新のカタログを調査したうえで、変数の意味、空間・時間解像度、カバレッジ、更新頻度、鉛直方向や基準に関する規約、チャンク分割、ライセンス、アクセス要件に基づいて選択してください。

大規模な全球または多次元の補助グリッドでは、チャンク分割がワークフローに適合する場合、解析対応の Zarr または Icechunk ソースを強く推奨します。ストア全体をダウンロードするのではなく、タスクの AOI、時間、変数、レベルに合わせて遅延サブセットしてください。科学的に同等の選択肢がある場合は、認証情報なしでのアクセスを優先します。ただし、利便性を優先してプロダクトの正確性を損なわないでください。

外部の全球補助データと、プロダクトに付随するレイヤーを区別してください。Sentinel-2 の Scene Classification Layer、Landsat の QA バンド、SAR の入射角レイヤーなど、取得ごとに存在するデータは通常、選択したソースプロダクトに含まれるため、別の全球カタログを探すのではなく、そのプロダクトとともに読み込んでください。

作成に着手する前に、補助データプロバイダーのアカウントまたはサブスクリプションが必要な場合はユーザーに伝え、補助データのリファレンスに記載された直接リンクを使って設定方法を案内してください。ローカル環境またはランナーのシークレット環境でキーを設定し、範囲を限定した読み込みを1回検証してください。また、ローカルの認証情報がリモートランナーに自動的に引き継がれるわけではない点に留意してください。

データセットの選択とプロバイダーのリファレンス

リファレンス	使用する場面
reference/earth-observation-product-selection.md	対象プロダクトを観測要件、既定のデータセット、代替候補、反例に対応付ける場合。
reference/open-data-dataset-catalog.md	検証済みの Tilebox オープンデータのスラッグを調べ、プロバイダー、形式、認証、費用、制限事項を比較する場合。
reference/auxiliary-data-sources.md	Tilebox 外部の DEM、気象・気候データ、マスク、その他の補助グリッドを選択し、適した Zarr／Icechunk ソースを優先しながら、プロバイダーへのアクセス方法を案内する場合。
reference/providers/aws-earth-search.md	Element 84 AWS Earth Search の既定の公開 Sentinel-2 L2A および Sentinel-1 GRD ソースを使用する場合。
reference/providers/copernicus-data-space.md	Copernicus アカウントと S3 認証情報を使って open_data.copernicus.* のプロダクトデータにアクセスする場合。
reference/providers/usgs-landsat.md	AWS のリクエスター支払いバケット内の open_data.usgs.* Landsat データにアクセスする場合。
reference/providers/alaska-satellite-facility.md	NASA Earthdata Login の認証情報を使って open_data.asf.* SAR プロダクトデータにアクセスする場合。

メタデータとプロダクトデータを分ける

Tilebox のオープンデータデータセットは、構造化メタデータとアセットの場所をインデックス化します。通常、Tilebox はソース画像データをホストしていません。Tilebox API キーがあっても、Copernicus、USGS/AWS、ASF、商用プロバイダー、非公開のソースバケット、出力バケットへのアクセスが自動的に許可されるわけではありません。

次の3つのアクセス層を明確に分けてください。

1. Tilebox API： Tilebox API キーを使ったメタデータクエリおよびワークフロー／ジョブ操作。
2. ソースストレージ： プロバイダーがホストする画像データ。公開されている場合と、別途認証情報が必要な場合があります。
3. 出力ストレージ： ノートブック／ローカル作業に適したローカルディスク、またはリモート／分散作業用のユーザー管理下の共有ストレージ。Tilebox がホストする出力ストレージがあると想定しないでください。

選択した各ソースについて、Tilebox が提供するもの、データの保存場所、形式、ソースの認証情報やリクエスター支払いの料金が必要かどうか、実際に検証したアクセス内容をユーザーに伝えてください。シークレットをチャットに貼り付けたり、タスク入力、job_cache、ログ、ソース管理、リリース成果物に置いたりするようユーザーに求めないでください。

既存のデータセットを確認する

既存のデータセットを一覧表示して確認します。

tilebox dataset list --json
tilebox dataset get <dataset-slug> --json

選択やスキーマの変更を行う前に、dataset get を使用して現在のフィールド、フィールドの説明、コレクション数、時間範囲、各コレクションにデータが含まれているかどうかを確認します。

スキーマを設計する

データセットの種類を選択します。

• temporal（telemetry）：必須フィールドは time、id、ingestion_time です。
• spatiotemporal（catalog）：必須フィールドは time、id、ingestion_time、geometry です。

カスタムスキーマのルール：

• フィールド名は snake_case で、有効なコード識別子である必要があります。
• サポートされるフィールド型は string、bytes、bool、int32、int64、uint64、float64、Duration、Timestamp、UUID、Geometry です。
• ラスターの寸法、サンプルあたりのビット数、カウント、行／列インデックスなど、通常の範囲の整数には int32 を使用します。ソースの値が符号付き 32 ビットの範囲を超える可能性がある場合にのみ int64 を使用します。ProtoJSON では 64 ビット整数は文字列として出力されますが、int32 は JSON 数値として出力されます。
• サーバー側のフィルタリングをサポートする必要があるカスタムフィールドには "queryable": true を設定します。
• 配列フィールドには "repeated": true を設定します。
• 可能な限り、すべてのフィールドに description と example_value を含めます。これにより、生成されるデータセットのドキュメントが改善されます。
• データセットに一度でもデータが含まれた後は、フィールドの順序変更、名前変更、削除、型変更を破壊的変更として扱います。

schema.json の例：

{
  "kind": "spatiotemporal",
  "fields": [
    {
      "name": "scene_id",
      "type": "string",
      "description": "Provider scene identifier.",
      "example_value": "S2A_MSIL2A_20260521T104031_N0511_R008_T32TQM_20260521T132145"
    },
    {
      "name": "cloud_cover",
      "type": "float64",
      "queryable": true,
      "description": "Cloud cover percentage for the scene.",
      "example_value": "12.5"
    },
    {
      "name": "asset_urls",
      "type": "string",
      "repeated": true,
      "description": "URLs for assets associated with the scene.",
      "example_value": "[\"s3://bucket/path/B04.tif\"]"
    }
  ]
}

データセットを作成する

複雑なスキーマや Markdown ドキュメントにはファイルを使用します。

tilebox dataset create \
  --name "Processed Scenes" \
  --code-name processed_scenes \
  --summary "Processed Sentinel scenes" \
  --schema-file schema.json \
  --description-file README.md \
  --json

インラインスキーマは、小規模なテストに便利です。

tilebox dataset create \
  --name "Scenes" \
  --code-name scenes \
  --summary "Processed scenes" \
  --schema '{"kind":"temporal","fields":[{"name":"scene_id","type":"string","description":"Scene identifier","example_value":"S2A_001"}]}' \
  --json

入力ルール：

• --schema と --schema-file は同時に指定できません。どちらか一方が必須です。
• --description と --description-file は同時に指定できません。
• --schema-file - は標準入力からスキーマ JSON を読み込みます。
• --description-file - は標準入力から Markdown ドキュメントを読み込みます。
• 1 つのコマンドでスキーマと説明の両方を標準入力から読み込まないでください。

Markdown ドキュメントを追加する

データセットの description は、短い要約だけではなく、より詳細な Markdown ドキュメントです。スキーマと併せて管理する必要がある情報を記載します。

• データセットの目的と管理者。
• ソースシステムと取り込み頻度。
• コレクションの命名規則。
• フィールドの意味、単位、列挙値に相当する値、null 許容性に関する想定。
• クエリの例と既知の注意点。

ファイルからドキュメントを更新します。

tilebox dataset update <dataset-slug> --description-file README.md --json

短い概要のみを変更する場合は、概要を個別に更新します。

tilebox dataset update <dataset-slug> --summary "New short summary" --json

スキーマを安全に更新する

スキーマの更新では、カスタムスキーマ全体が置き換えられます。編集を始める前に、必ず現在のスキーマソースファイルを使用するか、tilebox dataset get から再構築してください。

データセットが空でない場合も安全な変更：

• 新しいカスタムフィールドの追加。
• 名前、概要、Markdown の説明などのメタデータの更新。

すべてのコレクションが空の場合にのみ安全な変更：

• カスタムフィールドの削除。
• フィールド名の変更。
• フィールド型または反復可能性の変更。
• データセットのコード名の変更。

ライブ環境での更新により安全性が確認されない限り、これらの変更は最初の取り込み後は永久に実施できないものとして扱ってください。デプロイ済みのバックエンドによっては取り込み履歴が保持され、すべてのデータポイントとコレクションを削除した後でも、スキーマやコード名の破壊的変更が拒否される場合があります。サンプルデータを取り込む前にフィールド幅を決めてください。空のデータセットでバックエンドに破壊的変更を拒否された場合は、修正したスキーマで代替データセットを作成してください。

破壊的変更の前にコレクション数を確認します。

tilebox dataset collection list --dataset <dataset-slug> --json | jq -r '.[] | [.name, .count] | @tsv'

スキーマを更新します。

tilebox dataset update <dataset-slug> --schema-file schema.json --json

同じ変更に関する更新の場合は、スキーマとドキュメントをまとめて更新します。

tilebox dataset update <dataset-slug> \
  --schema-file schema.json \
  --description-file README.md \
  --summary "Updated dataset summary" \
  --json

コレクションを管理する

コレクションは、データセット内のデータポイントを区分します。製品、ソース、処理レベル、テナント、論理ストリームなどに使用されます。

tilebox dataset collection list --dataset <dataset-slug> --json
tilebox dataset collection get <collection-name> --dataset <dataset-slug> --json
tilebox dataset collection create <collection-name> --dataset <dataset-slug> --if-not-exists --json
tilebox dataset collection delete <collection-name> --dataset <dataset-slug> --if-missing-ok --json

自動化では冪等性を保つフラグを使用します。

• 作成には --if-not-exists を使用します。
• 削除には --if-missing-ok を使用します。

コレクションを削除する前に、ユーザーが削除を明示的に依頼した場合を除き、削除の意図を確認してください。コレクションを削除すると、その論理コレクションがデータセットから削除されます。削除するコレクションは空である必要があります。

CLI でデータポイントをクエリする

tilebox dataset query は常に JSON を出力します。エージェントは一貫して --json も渡すようにしてください。手早い確認やスクリプトで使用します。

# Query all collections in the last 7 days
tilebox dataset query <dataset-slug> --last 7d --limit 100 --json

# Query specific collections over a time range
tilebox dataset query <dataset-slug> \
  --collections raw,processed \
  --after 2026-05-01 \
  --before 2026-06-01 \
  --limit 100 \
  --json

# Query datapoints intersecting a WKT polygon
tilebox dataset query <dataset-slug> \
  --last 7d \
  --spatial-extent 'POLYGON((-109.05 41,-109.05 37,-102.05 37,-102.05 41,-109.05 41))' \
  --limit 100 \
  --json

# Query datapoints intersecting a GeoJSON polygon or multipolygon file
tilebox dataset query <dataset-slug> \
  --after 2026-05-01 \
  --before 2026-06-01 \
  --spatial-extent-file colorado.geojson \
  --limit 100 \
  --json

# Continue pagination
tilebox dataset query <dataset-slug> --last 7d --limit 100 --cursor <next_cursor> --json

クエリ可能なフィールドでフィルターする

--filter は、クエリ可能なデータセットフィールドに対する CQL2 Text 式を受け付けます。式を作成する前に、データセットが公開しているフィールドを確認してください。

tilebox dataset get <dataset-slug> --json \
  | jq '[.fields[] | select(.queryable == true) | {name, type, description, exampleValue}]'

ユーザーの意図を正確なクエリ可能フィールドに対応付け、その型に応じた演算子を選択してください。フィールド名を作り出したり、スキーマのすべてのフィールドがクエリ可能だと想定したりしないでください。

• 文字列でサポートされるのは、完全一致と IS NULL／IS NOT NULL です。前方一致、部分一致、パターン照合、順序比較はサポートされません。
• ブール型フィールドでは、TRUE または FALSE との等価／不等価比較と、NULL チェックがサポートされます。
• 数値フィールドでは、=、<>、<、<=、>、>= がサポートされます。
• すべての比較、NOT、AND、OR では、SQL／CQL2 の三値論理が使われます。NULL または欠損値との比較結果は不明となり、NOT unknown も不明のままで、true の結果のみが一致します。
• ユーザーの意図に必要な場合は、NULL 値を明示的に含めてください。たとえば cloud_cover < 5 OR cloud_cover IS NULL のようにします。
• 括弧、ネストされた AND／OR 式、および NOT がサポートされます。
• --filter を繰り返し指定すると、各フィルターが明示的な AND で結合されます。

例：

# Exact string and numeric comparison
tilebox dataset query open_data.aws_earth.sentinel2 --last 5d \
  --filter "cloud_cover < 5 AND platform = 'sentinel-2c'" \
  --json

# Nested logic that deliberately includes missing cloud cover
tilebox dataset query open_data.aws_earth.sentinel2 --last 5d \
  --filter "(cloud_cover < 5 OR cloud_cover IS NULL) AND platform = 'sentinel-2c'" \
  --json

# Equivalent explicit AND across repeated flags
tilebox dataset query open_data.aws_earth.sentinel2 --last 5d \
  --filter "cloud_cover < 5" \
  --filter "platform = 'sentinel-2c'" \
  --json

ユーザーが前方一致や部分一致など、サポートされていない文字列照合を求めた場合は、その制限を説明し、意図を損なわない場合に限り完全一致を使用してください。NULL の扱いが曖昧で、結果に大きく影響する場合は、欠損値を含めるかどうかを確認してください。

jq でフィールドを抽出します。

tilebox dataset query <dataset-slug> --last 7d --limit 10 --json | jq '.datapoints'
tilebox dataset query <dataset-slug> --last 7d --limit 10 --json | jq -r '.next_cursor'
tilebox dataset query <dataset-slug> --last 7d --limit 10 --json | jq -r '.datapoints[] | [.id, .time] | @tsv'

時間フィルター：

• 7d、12h、1Y3M などの相対期間には、--last <duration> を使用します。
• 明示的な RFC3339 タイムスタンプまたは YYYY-MM-DD 形式の日付には、--after と --before を使用します。
• --last を --after または --before と組み合わせないでください。

空間フィルター：

• インラインの WKT または GeoJSON には、--spatial-extent を使用します。
• WKT または GeoJSON ファイルには、--spatial-extent-file を使用します。
• クエリジオメトリは Polygon または MultiPolygon である必要があります。ジオメトリがポリゴンまたはマルチポリゴンであれば、GeoJSON の Feature ラッパーも受け付けます。
• --spatial-extent と --spatial-extent-file を組み合わせないでください。
• 地理データセットでは座標に経度／緯度を使用し、ポリゴンのリングを閉じてください。
• 空間フィルターは --collections、--last、--after、--before、--limit、--cursor と組み合わせられます。

インライン GeoJSON クエリの例：

tilebox dataset query open_data.aws_earth.sentinel2 \
  --collections L2A \
  --last 14d \
  --spatial-extent '{"type":"Polygon","coordinates":[[[-109.05,41],[-109.05,37],[-102.05,37],[-102.05,41],[-109.05,41]]]}' \
  --limit 50 \
  --json

WKT ファイルクエリの例：

cat > area.wkt <<'EOF'
MULTIPOLYGON(((-109.05 41,-109.05 37,-102.05 37,-102.05 41,-109.05 41)))
EOF

tilebox dataset query <dataset-slug> \
  --after 2026-05-01T00:00:00Z \
  --before 2026-06-01T00:00:00Z \
  --spatial-extent-file area.wkt \
  --limit 100 \
  --json

Python SDK でフィルターする

Python SDK は、データセットレベルおよびコレクションレベルのクエリで、型付きの filter= 式を1つ受け付けます。field() で式を作成し、Python の and、or、not ではなく、&、|、~ で式を結合してください。比較式を結合するときは括弧で囲んでください。

from tilebox.datasets import field

data = dataset.query(
    temporal_extent=(start, end),
    filter=(field("cloud_cover") < 5) & (field("platform") == "sentinel-2c"),
)

data_including_missing = dataset.query(
    temporal_extent=(start, end),
    filter=((field("cloud_cover") < 5) | field("cloud_cover").is_null())
    & (field("platform") == "sentinel-2c"),
)

NULL チェックには field("name").is_null() と .is_not_null() を使用します。NULL または欠損フィールドとの比較は不明と評価され、!= や否定した比較も含めて除外されます。NULL を含めるには、明示的に .is_null() と OR で結合してください。Python API は CQL2 テキストを解析するのではなく、型付きの式を構築します。また、引数として filter= を1つだけ公開しているため、複数の条件は1つの式にまとめてください。

Python SDK のクエリは、ノートブックで扱いやすい xarray の結果を返します。また、時間範囲、時空間ジオメトリフィルター、自動ページネーション、プログレスバー、および高速な存在確認／件数確認に使える skip_data=True もサポートしています。

ID でデータポイントを検索する

データポイントの UUID がわかっていて、データセット内の任意のコレクションからデコード済みのデータポイントを取得したい場合は、find を使用します。

tilebox dataset find <dataset-slug> <datapoint-id> | jq '.'

Go 型を生成する

Go コードから型安全なデータポイントをクエリする場合は、Go の protobuf 型を生成します。

tilebox dataset generate --slug <dataset-slug> --out ./protogen --package tilebox.v1 --json

生成されたファイルをアプリケーションコードで使用する場合は、バージョン管理に追加してください。