docs(api): RUM query time range alignment and caching

api-reference/openapi.en.json

@@ -58437,7 +58437,7 @@
           "RUM/Data query"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Send 1 to 10 queries in one request; each query `id` becomes a key in the response object.\n- `start_time` and `end_time` are Unix epoch milliseconds, at most 31 days apart. The server adds the time-range and account filters itself; you do not need them in `sql`.\n- `FROM` names a RUM scope table: `sessions`, `views`, `actions`, `errors`, `resources`, `long_tasks`, `vitals`, `issues` or `sourcemaps` (the singular form is also accepted). Column names are the `field_key` values returned by `POST /rum/field/list`.\n- A query whose top-level `AND` conditions pin `application_id` (`=` or `IN`) must name applications the caller can read: a private application the caller's team does not own fails the whole request with `AccessDenied`, an unknown one with `ResourceNotFound`, and one request may name at most 50 distinct applications. A query that names no application silently skips the private applications the caller cannot read.\n- Malformed SQL, an invalid `time_zone` or an out-of-range time window fails the whole request with `InvalidParameter`. A query that fails later (unknown table or column, invalid `dql`, invalid `search_after_ctx`, database error) only sets `error` on its own entry, with code `InternalError`; the other queries still return `data`.\n- `values` is column-major: `values[i]` holds every row's value of column `fields[i]`.\n- `table` queries return at most 1,000 rows; a missing `LIMIT` or one above 1,000 is replaced with 1,000. A non-aggregate query with `ORDER BY` and no `OFFSET` returns `search_after_ctx` when the page is full — send it back with the same `sql` to get the next page.\n- `time_series` queries get a `ts` column prepended (bucket start, Unix milliseconds), grouped and ordered by it. The bucket width, returned as `interval` in milliseconds, is the smallest step from a fixed ladder (1, 2, 5, 10, 20, 50, 100, 200, 500 ms; 1, 2, 5, 10, 15, 30 s; 1, 2, 5, 10, 15, 30 min; 1, 2, 3, 6, 12 h; 1, 2, 3, 7 d; 30, 60, 90, 180 d) that is at least both `interval` and the window length divided by `max_points`.\n- On large time windows an aggregate query may run on sampled data; the response then carries `sampling`, and `COUNT`, `SUM` and `COUNT(DISTINCT)` columns are already multiplied by `scale_factor`. Set `disable_sampling: true` to always query the full data.",
+          "content": "## Time range alignment and caching\n\nSo that repeated queries can reuse cached results, the time range of aggregation queries is aligned to a grid:\n\n- `format=time_series`: the start is rounded down and the end rounded up to the `interval`. The number and positions of buckets do not change; the first and last buckets now cover their full interval instead of a partial one.\n- Aggregate (non-time-series) queries: the start is rounded down and the end rounded up to `max(1 minute, range ÷ 1226 rounded up to the next standard interval step)`, for example 24h aligns to 2 minutes, 7d to 10 minutes, and 30d to 1 hour. Ranges shorter than 100 grid steps are neither aligned nor cached. At most one grid step of extra data is included at the start; the end rounds into the future, which holds no data.\n- Detail/list queries (no aggregation, pagination), and queries whose SQL calls functions that depend on when they run, such as `now()`, are neither aligned nor cached.\n\nResults may be up to 60 seconds stale for the most recent data.\n\n## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Send 1 to 10 queries in one request; each query `id` becomes a key in the response object.\n- `start_time` and `end_time` are Unix epoch milliseconds, at most 31 days apart. The server adds the time-range and account filters itself; you do not need them in `sql`.\n- `FROM` names a RUM scope table: `sessions`, `views`, `actions`, `errors`, `resources`, `long_tasks`, `vitals`, `issues` or `sourcemaps` (the singular form is also accepted). Column names are the `field_key` values returned by `POST /rum/field/list`.\n- A query whose top-level `AND` conditions pin `application_id` (`=` or `IN`) must name applications the caller can read: a private application the caller's team does not own fails the whole request with `AccessDenied`, an unknown one with `ResourceNotFound`, and one request may name at most 50 distinct applications. A query that names no application silently skips the private applications the caller cannot read.\n- Malformed SQL, an invalid `time_zone` or an out-of-range time window fails the whole request with `InvalidParameter`. A query that fails later (unknown table or column, invalid `dql`, invalid `search_after_ctx`, database error) only sets `error` on its own entry, with code `InternalError`; the other queries still return `data`.\n- `values` is column-major: `values[i]` holds every row's value of column `fields[i]`.\n- `table` queries return at most 1,000 rows; a missing `LIMIT` or one above 1,000 is replaced with 1,000. A non-aggregate query with `ORDER BY` and no `OFFSET` returns `search_after_ctx` when the page is full — send it back with the same `sql` to get the next page.\n- `time_series` queries get a `ts` column prepended (bucket start, Unix milliseconds), grouped and ordered by it. The bucket width, returned as `interval` in milliseconds, is the smallest step from a fixed ladder (1, 2, 5, 10, 20, 50, 100, 200, 500 ms; 1, 2, 5, 10, 15, 30 s; 1, 2, 5, 10, 15, 30 min; 1, 2, 3, 6, 12 h; 1, 2, 3, 7 d; 30, 60, 90, 180 d) that is at least both `interval` and the window length divided by `max_points`.\n- On large time windows an aggregate query may run on sampled data; the response then carries `sampling`, and `COUNT`, `SUM` and `COUNT(DISTINCT)` columns are already multiplied by `scale_factor`. Set `disable_sampling: true` to always query the full data.",
           "href": "/en/api-reference/rum/data-query/rum-read-data-query",
           "metadata": {
             "sidebarTitle": "Query RUM data"
@@ -59236,7 +59236,7 @@
           "RUM/Facets"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **100 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Use `POST /rum/field/list` with `is_facet: true` to discover `facet_key` values for each scope.\n- `facet_key` must be a facet field (`is_facet: true`) of the requested `scope` with `show_type: list` and a non-array `value_type`; otherwise the call returns `InvalidParameter`.\n- Events where `facet_key` is `null` are not counted. Pass `facet_value` to count only events equal to that value; its JSON type must match the field's `value_type`.\n- Pass `dql` to filter events before counting. Pass `sql` as a bare `WHERE` condition; the word `SELECT` anywhere in it (case-insensitive) is rejected.\n- Events of private applications the caller cannot access are not counted, as in `POST /rum/data/query`.\n- `limit` defaults to 100; maximum is 100.\n- `start_time` / `end_time` are required Unix epoch **milliseconds**, at most 31 days apart.\n- For `scope: sourcemap`, `type` and `kind` choose which symbol store is counted.",
+          "content": "## Time range alignment and caching\n\nSo that repeated queries can reuse cached results, the start is rounded down and the end rounded up to `max(1 minute, range ÷ 1226 rounded up to the next standard interval step)`, for example 24h aligns to 2 minutes, 7d to 10 minutes, and 30d to 1 hour. Ranges shorter than 100 grid steps are neither aligned nor cached. At most one grid step of extra data is included at the start; the end rounds into the future, which holds no data. Results may be up to 60 seconds stale for the most recent data.\n\n## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **100 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Use `POST /rum/field/list` with `is_facet: true` to discover `facet_key` values for each scope.\n- `facet_key` must be a facet field (`is_facet: true`) of the requested `scope` with `show_type: list` and a non-array `value_type`; otherwise the call returns `InvalidParameter`.\n- Events where `facet_key` is `null` are not counted. Pass `facet_value` to count only events equal to that value; its JSON type must match the field's `value_type`.\n- Pass `dql` to filter events before counting. Pass `sql` as a bare `WHERE` condition; the word `SELECT` anywhere in it (case-insensitive) is rejected.\n- Events of private applications the caller cannot access are not counted, as in `POST /rum/data/query`.\n- `limit` defaults to 100; maximum is 100.\n- `start_time` / `end_time` are required Unix epoch **milliseconds**, at most 31 days apart.\n- For `scope: sourcemap`, `type` and `kind` choose which symbol store is counted.",
           "href": "/en/api-reference/rum/facets/rum-read-facet-count",
           "metadata": {
             "sidebarTitle": "Count facet value distribution"

api-reference/openapi.zh.json

@@ -58437,7 +58437,7 @@
           "RUM/RUM 数据查询"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 单次请求可提交 1 到 10 个查询；每个查询的 `id` 会成为响应对象中的 key。\n- `start_time`、`end_time` 为 Unix 毫秒时间戳，跨度不超过 31 天。服务端会自动追加时间范围与账户过滤条件，`sql` 中无需再写。\n- `FROM` 填写 RUM 数据表名：`sessions`、`views`、`actions`、`errors`、`resources`、`long_tasks`、`vitals`、`issues` 或 `sourcemaps`（也接受单数形式）。列名即 `POST /rum/field/list` 返回的 `field_key`。\n- 若查询在顶层 `AND` 条件中用 `=` 或 `IN` 限定了 `application_id`，调用者必须能读取这些应用：所属团队不包含调用者的私有应用会让整个请求返回 `AccessDenied`，不存在的应用返回 `ResourceNotFound`，单次请求最多涉及 50 个不同应用。未限定应用的查询会自动跳过调用者无权读取的私有应用。\n- SQL 语法错误、`time_zone` 无效或时间范围不合法时，整个请求返回 `InvalidParameter`。之后阶段才失败的查询（表或列不存在、`dql` 无效、`search_after_ctx` 无效、数据库报错）只在该查询自己的结果中返回 `error`，错误码为 `InternalError`，其他查询仍正常返回 `data`。\n- `values` 按列组织：`values[i]` 是列 `fields[i]` 在所有行上的取值。\n- `table` 查询最多返回 1,000 行；未写 `LIMIT` 或超过 1,000 时按 1,000 处理。不含聚合、带 `ORDER BY` 且没有 `OFFSET` 的查询在本页取满时会返回 `search_after_ctx`，用相同的 `sql` 带上它即可取下一页。\n- `time_series` 查询会在最前面插入 `ts` 列（时间桶起点，Unix 毫秒），并按它分组、排序。桶宽以毫秒在 `interval` 中返回，取值为固定档位（1、2、5、10、20、50、100、200、500 毫秒；1、2、5、10、15、30 秒；1、2、5、10、15、30 分钟；1、2、3、6、12 小时；1、2、3、7 天；30、60、90、180 天）中同时不小于 `interval` 和「时间跨度 ÷ `max_points`」的最小一档。\n- 时间跨度较大时，聚合查询可能基于抽样数据执行；此时响应带有 `sampling`，且 `COUNT`、`SUM`、`COUNT(DISTINCT)` 列已乘以 `scale_factor`。设置 `disable_sampling: true` 可始终查询全量数据。",
+          "content": "## 时间范围对齐与缓存\n\n为便于重复查询复用缓存结果，聚合查询的时间范围会被对齐到网格：\n\n- `format=time_series`：起始时间向下、结束时间向上取整到 `interval`。时间桶的数量和位置不变，首尾两个桶覆盖完整区间，而不是部分区间。\n- 聚合（非时序）查询：起始时间向下、结束时间向上取整到 `max(1 分钟, 时间范围 ÷ 1226 向上取到下一个标准间隔档)`，例如 24 小时对齐到 2 分钟，7 天对齐到 10 分钟，30 天对齐到 1 小时。时间范围短于 100 个网格步长时不对齐、不缓存。起始端最多多出一个网格步长的数据；结束端取整到未来，该部分没有数据。\n- 明细/列表查询（无聚合、分页），以及 SQL 中含有 `now()` 等随执行时间变化的函数的查询，不做对齐也不缓存。\n\n最近时间的数据结果最多可能滞后 60 秒。\n\n## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 单次请求可提交 1 到 10 个查询；每个查询的 `id` 会成为响应对象中的 key。\n- `start_time`、`end_time` 为 Unix 毫秒时间戳，跨度不超过 31 天。服务端会自动追加时间范围与账户过滤条件，`sql` 中无需再写。\n- `FROM` 填写 RUM 数据表名：`sessions`、`views`、`actions`、`errors`、`resources`、`long_tasks`、`vitals`、`issues` 或 `sourcemaps`（也接受单数形式）。列名即 `POST /rum/field/list` 返回的 `field_key`。\n- 若查询在顶层 `AND` 条件中用 `=` 或 `IN` 限定了 `application_id`，调用者必须能读取这些应用：所属团队不包含调用者的私有应用会让整个请求返回 `AccessDenied`，不存在的应用返回 `ResourceNotFound`，单次请求最多涉及 50 个不同应用。未限定应用的查询会自动跳过调用者无权读取的私有应用。\n- SQL 语法错误、`time_zone` 无效或时间范围不合法时，整个请求返回 `InvalidParameter`。之后阶段才失败的查询（表或列不存在、`dql` 无效、`search_after_ctx` 无效、数据库报错）只在该查询自己的结果中返回 `error`，错误码为 `InternalError`，其他查询仍正常返回 `data`。\n- `values` 按列组织：`values[i]` 是列 `fields[i]` 在所有行上的取值。\n- `table` 查询最多返回 1,000 行；未写 `LIMIT` 或超过 1,000 时按 1,000 处理。不含聚合、带 `ORDER BY` 且没有 `OFFSET` 的查询在本页取满时会返回 `search_after_ctx`，用相同的 `sql` 带上它即可取下一页。\n- `time_series` 查询会在最前面插入 `ts` 列（时间桶起点，Unix 毫秒），并按它分组、排序。桶宽以毫秒在 `interval` 中返回，取值为固定档位（1、2、5、10、20、50、100、200、500 毫秒；1、2、5、10、15、30 秒；1、2、5、10、15、30 分钟；1、2、3、6、12 小时；1、2、3、7 天；30、60、90、180 天）中同时不小于 `interval` 和「时间跨度 ÷ `max_points`」的最小一档。\n- 时间跨度较大时，聚合查询可能基于抽样数据执行；此时响应带有 `sampling`，且 `COUNT`、`SUM`、`COUNT(DISTINCT)` 列已乘以 `scale_factor`。设置 `disable_sampling: true` 可始终查询全量数据。",
           "href": "/zh/api-reference/rum/data-query/rum-read-data-query",
           "metadata": {
             "sidebarTitle": "查询 RUM 数据"
@@ -59236,7 +59236,7 @@
           "RUM/RUM 自定义字段"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**100 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 使用 `POST /rum/field/list`（传 `is_facet: true`）发现每个 scope 下可用的 `facet_key`。\n- `facet_key` 必须是所请求 `scope` 下的分面字段（`is_facet: true`），且 `show_type` 为 `list`、`value_type` 不是数组类型，否则返回 `InvalidParameter`。\n- `facet_key` 为 `null` 的事件不参与统计。传入 `facet_value` 时只统计取值等于它的事件，其 JSON 类型须与字段的 `value_type` 一致。\n- 传入 `dql` 可在统计前过滤事件。`sql` 只填 `WHERE` 条件本身；其中任意位置出现 `SELECT`（不区分大小写）都会被拒绝。\n- 调用者无权访问的私有应用的事件不参与统计，与 `POST /rum/data/query` 一致。\n- `limit` 默认 100，最大 100。\n- `start_time` / `end_time` 必填，为 Unix **毫秒**时间戳，跨度不超过 31 天。\n- `scope` 为 `sourcemap` 时，用 `type` 和 `kind` 选择统计哪个符号文件库。",
+          "content": "## 时间范围对齐与缓存\n\n为便于重复查询复用缓存结果，起始时间向下、结束时间向上取整到 `max(1 分钟, 时间范围 ÷ 1226 向上取到下一个标准间隔档)`，例如 24 小时对齐到 2 分钟，7 天对齐到 10 分钟，30 天对齐到 1 小时。时间范围短于 100 个网格步长时不对齐、不缓存。起始端最多多出一个网格步长的数据；结束端取整到未来，该部分没有数据。最近时间的数据结果最多可能滞后 60 秒。\n\n## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**100 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 使用 `POST /rum/field/list`（传 `is_facet: true`）发现每个 scope 下可用的 `facet_key`。\n- `facet_key` 必须是所请求 `scope` 下的分面字段（`is_facet: true`），且 `show_type` 为 `list`、`value_type` 不是数组类型，否则返回 `InvalidParameter`。\n- `facet_key` 为 `null` 的事件不参与统计。传入 `facet_value` 时只统计取值等于它的事件，其 JSON 类型须与字段的 `value_type` 一致。\n- 传入 `dql` 可在统计前过滤事件。`sql` 只填 `WHERE` 条件本身；其中任意位置出现 `SELECT`（不区分大小写）都会被拒绝。\n- 调用者无权访问的私有应用的事件不参与统计，与 `POST /rum/data/query` 一致。\n- `limit` 默认 100，最大 100。\n- `start_time` / `end_time` 必填，为 Unix **毫秒**时间戳，跨度不超过 31 天。\n- `scope` 为 `sourcemap` 时，用 `type` 和 `kind` 选择统计哪个符号文件库。",
           "href": "/zh/api-reference/rum/facets/rum-read-facet-count",
           "metadata": {
             "sidebarTitle": "查询分值分布"