浏览文档

API 参考更新于 2026年7月25日由 Telemetry 编辑团队和产品团队审核阅读约需 4 分钟

让编程智能体使用这篇文档

打开 Claude Code、Codex、Cursor 或其他编码代理的集中提示包，然后将其适应此处介绍的工作流程。

打开提示词包连接真实遥测

本页内容

表路径契约
列表表
示例
获取表架构
示例
设置表保留
示例
清晰的保留
设置分区列
示例
禁用分区
删除表
示例
相关端点
常见错误

表

表 API 允许您以编程方式检查和管理表。

支持的操作：

列出表格. GET https://api.telemetry.sh/tables
获取架构. GET https://api.telemetry.sh/tables/<table>/schema
设置保留. PATCH https://api.telemetry.sh/tables/<table>/retention
设置分区列. PATCH https://api.telemetry.sh/tables/<table>/partition-columns
删除表. DELETE https://api.telemetry.sh/tables/<table>

标题

名称	类型	描述
`Content-Type`	字符串	将 `application/json` 用于 `PATCH`。
`Authorization`	字符串	您的 API 密钥，作为原始密钥或 `Bearer <key>`。

范围规则：

GET /tables 和 GET /tables/<table>/schema 需要 read、write 或 read-and-write
PATCH /tables/<table>/retention、PATCH /tables/<table>/partition-columns 和 DELETE /tables/<table> 需要 write 或 read-and-write

表路径契约

<table>路径段在转发之前由API进行归一化：

空格转换为下划线
字母是小写的
标准化后，仅允许小写 ASCII 字母、数字和 _

示例：

Uber Rides 变为 uber_rides
graphjson_egress 保持 graphjson_egress
my-table 被拒绝，因为 - 不允许

如果您想要可预测的行为，请使用仅包含小写字母、数字和下划线的规范表名称。

列表表

获取 https://api.telemetry.sh/tables

支持的查询参数：

领域	类型	必填	精确合约	默认
`page`	整数	否	正整数页码。小于 `1` 的值将被拒绝。	`1`
`pageSize`	整数	否	正整数页面大小。大于 `100` 的值将被限制为 `100`。 API 还接受旧别名 `page_size`。	`50`

成功请求返回200 OK：

{
  "status": "success",
  "pagination": {
    "page": 1,
    "pageSize": 50,
    "total": 3,
    "totalPages": 1,
    "hasNextPage": false,
    "hasPreviousPage": false
  },
  "tables": [
    "heartbeat",
    "telemetry_user_events",
    "graphjson_egress"
  ]
}

示例

curl "https://api.telemetry.sh/tables?page=1&pageSize=25" \
  -H "Authorization: $API_KEY"

获取表架构

获取 https://api.telemetry.sh/tables/<table>/schema

这将返回：

表的解析模式对象
当前的保留政策（如果有）
分区元数据（如果有）

成功请求返回200 OK：

{
  "status": "success",
  "table": "graphjson_egress",
  "schema": {
    "fields": [
      {
        "name": "timestamp_utc",
        "data_type": {
          "Timestamp": ["Millisecond", "UTC"]
        },
        "nullable": true,
        "dict_id": 0,
        "dict_is_ordered": false,
        "metadata": {}
      }
    ],
    "metadata": {}
  },
  "retention_days": null,
  "partition_columns": null,
  "partition_spec_version": null
}

示例

curl https://api.telemetry.sh/tables/graphjson_egress/schema \
  -H "Authorization: $API_KEY"

设置表保留

补丁 https://api.telemetry.sh/tables/<table>/retention

身体

领域	类型	必填	精确合约	示例
`retentionDays`	整数或 `null`	否	保留数据的正整数天数。使用`null`清除保留并无限期保留数据。 API 还接受旧别名 `retention_days`。	`30`

注意事项：

小于 1 的值将被拒绝。
如果发送 {} 或 {"retentionDays": null}，保留将被清除。

成功请求返回200 OK：

{
  "status": "success",
  "table": "graphjson_egress",
  "retention_days": 30,
  "partition_columns": null,
  "partition_spec_version": null
}

示例

curl -X PATCH https://api.telemetry.sh/tables/graphjson_egress/retention \
  -H "Content-Type: application/json" \
  -H "Authorization: $API_KEY" \
  -d '{
    "retentionDays": 30
  }'

清晰的保留

curl -X PATCH https://api.telemetry.sh/tables/graphjson_egress/retention \
  -H "Content-Type: application/json" \
  -H "Authorization: $API_KEY" \
  -d '{
    "retentionDays": null
  }'

设置分区列

补丁 https://api.telemetry.sh/tables/<table>/partition-columns

分区列组织表的各个部分，以便相等过滤器可以在查询读取不相关的数据之前跳过它。顺序很重要：将最多查询使用的字段放在前面。请参阅选择分区列了解选型建议和查询示例。

该表必须已有架构。您可以使用顶级或嵌套标量字段，例如 account_id 或 request.region。支持字符串、布尔值和数字字段。

身体

领域	类型	必填	精确合约	示例
`partitionColumns`	字符串数组或 `null`	否	有序字段名称。名称被修剪并小写。使用 `null`、`[]` 或 `{}` 禁用分区。 API 还接受 Snake_case 别名 `partition_columns`。	`["account_id", "event"]`

如果某个字段在当前模式中不存在、具有不受支持的类型、重复、为空或包含空的嵌套路径段，则请求将被拒绝。

更改列会创建新的分区规范。新摄取的数据会立即使用它，而现有部分会在后台重写。查询在该转换期间保持完整，但随着重写的进行，性能优势将显现出来。

成功的请求返回 200 OK 以及有效设置：

{
  "status": "success",
  "table": "graphjson_egress",
  "retention_days": 30,
  "partition_columns": ["account_id", "event"],
  "partition_spec_version": 2
}

示例

curl -X PATCH https://api.telemetry.sh/tables/graphjson_egress/partition-columns \
  -H "Content-Type: application/json" \
  -H "Authorization: $API_KEY" \
  -d '{
    "partitionColumns": ["account_id", "event"]
  }'

禁用分区

curl -X PATCH https://api.telemetry.sh/tables/graphjson_egress/partition-columns \
  -H "Content-Type: application/json" \
  -H "Authorization: $API_KEY" \
  -d '{
    "partitionColumns": null
  }'

删除表

删除 https://api.telemetry.sh/tables/<table>

这将永久删除该表及其所有数据。

成功请求返回200 OK：

{
  "status": "success",
  "deleted_table": {
    "name": "graphjson_egress"
  }
}

示例

curl -X DELETE https://api.telemetry.sh/tables/graphjson_egress \
  -H "Authorization: $API_KEY"

Telemetry 还仍然支持旧版 DELETE /delete 端点，用于删除带有 where 子句的行。当您需要整个表生命周期操作时，请使用表 API。

常见错误

400 Bad Request 如果表名规范化后包含无效字符
400 Bad Request 如果 retentionDays 不是正整数或 null
400 Bad Request 如果分区列无效或者不是当前架构中受支持的字段
403 Forbidden 如果 API 密钥没有请求操作的权限
401 Unauthorized（如果 API 密钥丢失或无效）
404 Not Found 如果表不存在

页面作者和参考资料

Telemetry 编辑团队负责维护本文；产品团队审核功能行为、示例和适用范围。

我们如何审核文档

让编程智能体使用这篇文档

表

表路径契约

列表表

示例

获取表架构

示例

设置表保留

示例

清晰的保留

设置分区列

示例

禁用分区

删除表

示例

相关端点

常见错误

相关功能

页面作者和参考资料