跳到主要内容

版本与错误

发布版本​

每个数据集的数据由不可变的发布版本提供。GET /v1/datasets 与 GET /v1/datasets/{datasetId} 的 release 给出当前版本：releaseId、releaseFingerprint、source、rowCount 与 coverage（该版本承诺的覆盖范围；以列名为键的映射保持列名原样）。

  • 查询省略 releaseId 时使用当前版本，响应的 meta.releaseId 是实际使用的版本。
  • 在请求体中传 releaseId 可固定一个已发布版本。对已完成当前版本切换的数据集只接受当前版本，指定旧版本返回 409 release-unavailable，而不是空数据；重新查询即可。尚未完成切换的数据集在过渡期继续接受其已发布版本。
  • GET /v1/datasets/{datasetId}?releaseId=<发布版本 ID> 返回该版本嵌入的契约。
  • 版本固定不代表 PIT：服务不支持按历史知识时间或修订选择版本。

指纹与校验和​

字段含义
releaseFingerprint对发布版本内容的规范化结构取的 SHA-256 指纹，用来判断版本内容是否变化。
contractFingerprint对数据集契约的规范化结构取的 SHA-256 指纹，用来判断字段定义是否变化。
objectSha256对一个 Parquet 文件字节取的 SHA-256，用来校验下载内容，见批量下载。

未发布、超出覆盖与无匹配​

这几种情形的响应各不相同，客户端不应把它们都当成空结果：

情形响应
数据集标识不在契约中404 dataset-not-found
契约中已定义但尚未发布409 dataset-unavailable；GET /v1/datasets 中该项的 release 为 null
请求范围超出该版本承诺的覆盖409 coverage-unavailable
范围合法但没有匹配记录200，data 为空数组，page.complete 为 true

错误信封​

所有错误响应使用同一结构：

{
  "error": {
    "code": "release-unavailable",
    "message": "This release is not the current version of the dataset.",
    "requestId": "<请求 ID>"
  }
}
  • 程序按 code 判断错误类型；message 供人阅读，措辞可能调整。
  • 向服务提供方反馈问题时附上 requestId。

常见错误码​

每个接口可能返回的完整状态码与错误码见接口参考中各接口的响应定义。鉴权与限流相关的错误见鉴权。

状态错误码含义与处理
404dataset-not-found数据集标识不在契约中。
404not-found服务未启用批量交付时，准备与下载接口返回该错误。
409dataset-unavailable数据集尚未发布，或指定的版本不可用。
409release-unavailable指定的版本，或游标、下载票据所属的版本，不再是当前版本。重新查询或重新准备。
409cursor-release-unavailable游标或下载票据所属的版本已不可用。重新查询或重新准备。
409coverage-unavailable请求范围超出该版本承诺的覆盖。
409delivery-unavailable该版本既不是分区发布也没有批准的交付证据。
413request-too-large请求体超过服务允许的大小。
422invalid-query请求体结构、成员、列名、运算符或取值无效；未知成员同样被拒绝。
422invalid-cursor游标或下载票据无效、过期，或与本次请求不匹配。
422adjustment-unsupported请求的复权口径不在该版本的覆盖中。
422result-too-large结果超出服务允许的规模。缩小查询范围。
503data-unavailable当前版本的查询数据暂时不可用。稍后重试。
503service-unavailable服务或其依赖暂时不可用。稍后重试。
504query-timeout执行超时。缩小查询范围后重试。

命名规则​

内容规则例子
协议字段：请求成员、响应信封、分页、元数据、错误信封、目录项、契约描述、覆盖信息、准备清单camelCasereleaseId、nextCursor、requestId、maxChunkBytes
数据集列名：select、where 的 field、结果行、契约字段名、Parquet 列保持契约原名（snake_case）close_price、trading_date
以列名为键的映射，例如覆盖信息中的 dimensions键保持列名原样adjustment
错误码与枚举值kebab-casedataset-not-found、not-ready
对规范化结构取的哈希以 Fingerprint 结尾releaseFingerprint、contractFingerprint
对字节内容取的哈希以 Sha256 结尾objectSha256