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

相关文档概念：

• 数据集是强类型容器；数据集中的每个数据点都遵循数据集架构。
• 数据集类型会自动添加必填字段。请勿在自定义架构中包含必填字段。
• 自定义字段的描述和示例值可用于自动生成架构文档。
• 数据摄取后，现有字段无法删除或更改。可以添加新字段，因为字段都是可选的。
• 从未包含数据的数据集可以自由编辑。请勿假设删除之前摄取的数据就能恢复这种自由；规划破坏性更新前，请先向实时后端确认。

从目标产品中选择数据集

当用户描述了地球观测结果，但没有指定数据集时，应主动选择，而不是让用户从陌生的 slug 中挑选：

1. 将目标产品转化为具体要求，包括模态、产品级别、波段或极化、空间分辨率、时间范围、重访周期、延迟、云量容忍度、QA 和验证要求。
2. 阅读 reference/earth-observation-product-selection.md，确定默认选项和有意义的替代方案。
3. 阅读 reference/open-data-dataset-catalog.md，了解准确的 Tilebox slug、负载提供方、格式、身份验证方式和限制。
4. 使用 tilebox dataset list --json 和 tilebox dataset get <slug> --json 对照实时目录验证候选项。
5. 针对用户要求的 AOI 和时间范围查询少量元数据样本。确认集合、字段、覆盖范围、资产位置和访问元数据，不要依赖记忆中的架构。
6. 将数据源访问方式归类为公开且无需签名、提供方身份验证、请求者付费或受限。编写数据访问代码前，先阅读链接的提供方指南。
7. 选择一个默认选项并说明其适用原因；只有当替代方案的权衡值得一提时才列出。不要悄悄合并传感器或提供方。

对于常规光学多光谱地表反射率工作，如果用户未指定数据源，且 Sentinel-2 的分辨率、覆盖范围、重访周期和云量限制均适用，则默认使用 open_data.aws_earth.sentinel2。其 Element 84 AWS Earth Search L2A 负载是公开 COG，无需数据源提供方凭据。可将 Landsat 8/9 作为延长历史记录的可选补充，但不要默认创建 Sentinel-2/Landsat 联合处理流水线，因为网格、分辨率、光谱响应、辐射度量和样式的协调会显著增加复杂度。

对于常规 Sentinel-1 振幅／后向散射工作，如果用户未指定数据源且 GRD 符合目标，则默认使用 open_data.aws_earth.sentinel1 中的 GRD 集合。其 Element 84 AWS Earth Search 负载是公开 AWS 资产，提供无需签名的 S3 和 HTTPS 位置，因此无需数据源提供方凭据或请求者付费配置。只要 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 数据集 slug。请阅读 reference/auxiliary-data-sources.md，调研当前目录，并根据变量语义、空间／时间分辨率、覆盖范围、更新频率、垂直／参考约定、分块方式、许可证和访问要求进行选择。

对于大型全球或多维辅助网格，如果分块方式适合工作流，应优先选择适合分析的 Zarr 或 Icechunk 数据源。应按需延迟读取任务的 AOI、时间、变量和层级子集，而不是下载整个存储库。若科学上等效，仍应优先选择无需凭据的访问方式，但不要为了方便而牺牲产品的正确性。

区分外部全球辅助数据与产品关联图层。Sentinel-2 场景分类图层、Landsat QA 波段、SAR 入射角图层或类似的单次采集数据，通常属于所选源产品，应随该产品一并读取，而不是从单独的全球目录中查找。

在编写内容之前，如果辅助数据提供商需要账号或订阅，请告知用户，并通过辅助数据参考文档中的直接链接引导其完成设置。通过本地或运行器的密钥环境配置密钥，验证一次有界读取，并注意本地凭据不会自动传递给远程运行器。

数据集选择与提供商参考

参考文档	使用场景
reference/earth-observation-product-selection.md	将目标产品映射到观测要求、默认数据集、备选项和反例。
reference/open-data-dataset-catalog.md	查找经过验证的 Tilebox 开放数据 slug，并比较提供商、格式、身份验证、费用和限制。
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、商业提供商、私有源存储桶或输出存储桶的访问权限。

明确区分以下三个访问层：

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 文档。
• 不要在同一条命令中同时从标准输入读取架构和说明。

添加 Markdown 文档

数据集的 description 用于存放较完整的 Markdown 文档，而不只是简短摘要。可用于说明应与架构一同保存的背景信息：

• 数据集的用途和所有权。
• 源系统和数据导入频率。
• 集合命名约定。
• 字段含义、单位、类似枚举的值以及可空性预期。
• 查询示例和已知注意事项。

从文件更新文档：

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。Agent 仍应始终传入 --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 进行相等 / 不等比较，以及空值检查。
• 数值字段支持 =、<>、<、<=、> 和 >=。
• 所有比较、NOT、AND 和 OR 均采用 SQL/CQL2 三值逻辑：与空值或缺失值进行比较时结果为未知，NOT unknown 仍为未知，只有结果为 true 时才会匹配。
• 如果用户意图要求包含空值，请明确将其纳入，例如 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

如果用户要求不受支持的字符串匹配（例如前缀或子串匹配），请说明此限制；只有在不违背用户意图时才使用精确匹配。如果空值处理方式存在歧义，且会显著影响结果，请确认是否应包含缺失值。

使用 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'

时间筛选：

• 使用 --last <duration> 设置相对时间范围，例如 7d、12h 或 1Y3M。
• 使用 --after 和 --before 指定明确的 RFC3339 时间戳或 YYYY-MM-DD 日期。
• 不要将 --last 与 --after 或 --before 组合使用。

空间筛选：

• 使用 --spatial-extent 指定内联 WKT 或 GeoJSON。
• 使用 --spatial-extent-file 指定 WKT 或 GeoJSON 文件。
• 查询几何必须为 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= 表达式。使用 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"),
)

使用 field("name").is_null() 和 .is_not_null() 检查空值。与空值或缺失字段进行比较时，结果为未知并会被排除，包括 != 和取反后的比较；如需包含此类字段，请显式使用 .is_null() 通过 OR 组合。Python API 构造的是类型化表达式，而不是解析 CQL2 文本，并且只公开一个 filter= 参数，因此请将多个条件组合成一个表达式。

Python SDK 查询会返回便于在 notebook 中使用的 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

如果应用代码会使用生成的文件，请将其纳入版本控制。