选择分区列

通过让 Telemetry 跳过不能包含请求值的部分，分区列可以使选择性查询更快。它们对于在大型表中重复调查一个客户、服务、环境、跟踪或事件类型的代理和自动化工作流程特别有用。

它们与 SQL PARTITION BY 不同，它们不会更改查询结果。 Telemetry 在写入数据时对配置的值进行哈希处理，并记录每个部分的分区信息。在查询时，兼容的过滤器以相同的方式进行散列，因此可以在读取数据之前排除不相关的部分。

何时使用它们

当所有这些都成立时对表进行分区：

• 该表有足够的数据或部分，扫描它是一项实质性工作
• 重要查询在同一字段上重复过滤
• 这些过滤器通常选择表的一小部分
• 该字段是字符串、布尔值或数字标量

好的候选字段包括 account_id、workspace_id、service、environment、event 以及稳定的嵌套字段，例如 request.region。

对于逐个调查事件的代理来说，account_id 通常是强有力的第一列：

SELECT timestamp_utc, event, message
FROM app_events
WHERE account_id = 'acct_123'
  AND timestamp_utc >= now() - INTERVAL '24 hours'
ORDER BY timestamp_utc DESC

时间谓词仍然缩小了时间窗口；帐户谓词还允许 Telemetry 修剪该窗口内的分区部分。

将最有用的列放在前面

列顺序定义了前导前缀层次结构。鉴于：

{
  "partitionColumns": ["account_id", "event"]
}

Telemetry 可以对按以下条件过滤的查询使用分区修剪：

• account_id
• account_id 和 event

它无法将此布局用于仅按 event 筛选的查询，因为缺少第一列。为最广泛的重要查询集选择第一列，然后仅当查询通常按两者过滤时才添加另一列。

从一列开始。仅在您可以描述它改进的查询模式后才添加第二个。长列列表会创建越来越窄的写入和压缩组，而后面的列有助于减少查询。

启用修剪的过滤器

Telemetry 当前从字面相等、正 IN 以及与 AND 连接的 IS NULL 谓词派生分区修剪：

WHERE account_id = 'acct_123'

WHERE account_id IN ('acct_123', 'acct_456')

WHERE account_id = 'acct_123'
  AND event IN ('request_failed', 'request_retried')

WHERE account_id IS NULL

范围谓词、否定和不明确的 OR 表达式不会产生分区修剪。例如，在 duration_ms 上分区对 duration_ms > 1000 没有帮助。查询仍然正确；他们只是简单地扫描而没有进行优化。

嵌套标量路径也可以工作：

{
  "partitionColumns": ["request.region"]
}

SELECT count(*)
FROM app_events
WHERE request.region = 'us-west-2'

不支持列表、对象和时间戳作为分区列。时间戳过滤已经有自己的修剪路径，通常更好地表示为查询时间范围。

要避免什么

避免仅仅因为某个领域存在于每个事件中而选择它。有用的分区列反映了频繁的、选择性的查询。

谨慎对待：

• 几乎每个查询都会忽略的字段
• 主要使用范围、LIKE 或否定查询的字段
• 当查询很少重复时快速变化或无界的值
• 前导前缀与实际查询模式不匹配的多个列

低基数字段在删除表的大部分内容时仍然有用，例如 environment = 'production'。高基数标识符对于点调查非常有用，但它可能会导致写入和压缩碎片化。更喜欢在您真正关心的查询中删除最多数据的字段，而不仅仅是具有最多不同值的字段。

推出工作流程

1. 检查人员、仪表板、告警和代理运行的查询。识别由最昂贵的选择性查询共享的相等过滤器。
2. 确认该字段并输入 GET /tables/<table>/schema。
3. 通过表设置UI或表格 API配置一个分区列。
4. 保留重要查询的时间过滤器；分区剪枝是对时间剪枝的补充，而不是取代它。
5. 在现有数据有时间重写后重新运行代表性查询。比较扫描的工作和延迟，而不仅仅是一次热缓存执行。
6. 仅当常见查询同时筛选第一列和第二列时才添加第二列。

新数据立即使用更改后的分区规范。现有部分在后台重写，未重写的部分仍然可查询，因此结果在迁移过程中保持完整。随着更多表采用新布局，性能逐渐提高。

通过API配置

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

要更改顺序，请发送完整的所需列表。要关闭分区，请发送 null 或空数组：

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

API 根据表的当前架构验证字段。有关确切的请求和响应合同，请参阅 表 API 参考。