From 5b6e6419ca3633d23ef3cb78a554808fbba9b309 Mon Sep 17 00:00:00 2001
From: ysyneu <ysyneu@gmail.com>
Date: Sun, 25 Oct 2026 21:21:01 -0700
Subject: [PATCH 1/3] docs(api): document RUM query time range alignment and
 disable_cache

---
 api-reference/openapi.en.json     | 8 ++++++--
 api-reference/openapi.zh.json     | 8 ++++++--
 api-reference/rum.openapi.en.json | 8 ++++++--
 api-reference/rum.openapi.zh.json | 8 ++++++--
 4 files changed, 24 insertions(+), 8 deletions(-)

diff --git a/api-reference/openapi.en.json b/api-reference/openapi.en.json
index 982fa060..3266a3ce 100644
--- a/api-reference/openapi.en.json
+++ b/api-reference/openapi.en.json
@@ -20747,6 +20747,10 @@
       "RumDataQueryDefinition": {
         "description": "One RUM data query definition.",
         "properties": {
+          "disable_cache": {
+            "description": "When true, the query uses the exact `start_time`/`end_time` and the result is neither read from nor written to the cache. Defaults to false.",
+            "type": "boolean"
+          },
           "disable_sampling": {
             "description": "When `true`, the query always runs on the full data and the response never carries `sampling`. When `false` (default), the server may sample aggregate queries over large time windows.",
             "type": "boolean"
@@ -58339,7 +58343,7 @@
     },
     "/rum/data/query": {
       "post": {
-        "description": "Run one or more SQL-style RUM data queries over a bounded time range.",
+        "description": "Run one or more SQL-style RUM data queries over a bounded time range.\n\n**Time range alignment and caching**: so 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. 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) are not aligned.\n\nResults may be up to 60 seconds stale for the most recent data. Set `disable_cache=true` on a query entry to use the exact start and end and bypass the cache.",
         "operationId": "rum-read-data-query",
         "requestBody": {
           "content": {
@@ -59154,7 +59158,7 @@
     },
     "/rum/facet/count": {
       "post": {
-        "description": "Return the top N values for a facet field within a time range, sorted by occurrence count descending.",
+        "description": "Return the top N values for a facet field within a time range, sorted by occurrence count descending.\n\n**Time range alignment and caching**: so 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. 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.",
         "operationId": "rum-read-facet-count",
         "requestBody": {
           "content": {
diff --git a/api-reference/openapi.zh.json b/api-reference/openapi.zh.json
index 6c6f93fa..f213ab05 100644
--- a/api-reference/openapi.zh.json
+++ b/api-reference/openapi.zh.json
@@ -20747,6 +20747,10 @@
       "RumDataQueryDefinition": {
         "description": "单个 RUM 数据查询定义。",
         "properties": {
+          "disable_cache": {
+            "description": "为 true 时，使用精确的 `start_time`/`end_time` 查询，且结果既不读取也不写入缓存。默认 false。",
+            "type": "boolean"
+          },
           "disable_sampling": {
             "description": "为 `true` 时始终查询全量数据，响应不会出现 `sampling`。为 `false`（默认）时，服务端可能对大时间跨度的聚合查询进行抽样。",
             "type": "boolean"
@@ -58339,7 +58343,7 @@
     },
     "/rum/data/query": {
       "post": {
-        "description": "在指定时间范围内执行一个或多个 SQL 风格的 RUM 数据查询。",
+        "description": "在指定时间范围内执行一个或多个 SQL 风格的 RUM 数据查询。\n\n**时间范围对齐与缓存**：为便于重复查询复用缓存结果，聚合查询的时间范围会被对齐到网格：\n\n- `format=time_series`：起始时间向下、结束时间向上取整到 `interval`。时间桶的数量和位置不变，首尾两个桶覆盖完整区间，而不是部分区间。\n- 聚合（非时序）查询：起始时间向下、结束时间向上取整到 `max(1 分钟, 时间范围 ÷ 1226 向上取到下一个标准间隔档)`，例如 24 小时对齐到 2 分钟，7 天对齐到 10 分钟，30 天对齐到 1 小时。起始端最多多出一个网格步长的数据；结束端取整到未来，该部分没有数据。\n- 明细/列表查询（无聚合、分页）不做对齐。\n\n最近时间的数据结果最多可能滞后 60 秒。在查询项上设置 `disable_cache=true` 可使用精确的起止时间，并绕过缓存。",
         "operationId": "rum-read-data-query",
         "requestBody": {
           "content": {
@@ -59154,7 +59158,7 @@
     },
     "/rum/facet/count": {
       "post": {
-        "description": "按出现次数降序返回指定时间范围内某个分面字段的 Top N 值及其计数。",
+        "description": "按出现次数降序返回指定时间范围内某个分面字段的 Top N 值及其计数。\n\n**时间范围对齐与缓存**：为便于重复查询复用缓存结果，起始时间向下、结束时间向上取整到 `max(1 分钟, 时间范围 ÷ 1226 向上取到下一个标准间隔档)`，例如 24 小时对齐到 2 分钟，7 天对齐到 10 分钟，30 天对齐到 1 小时。起始端最多多出一个网格步长的数据；结束端取整到未来，该部分没有数据。最近时间的数据结果最多可能滞后 60 秒。",
         "operationId": "rum-read-facet-count",
         "requestBody": {
           "content": {
diff --git a/api-reference/rum.openapi.en.json b/api-reference/rum.openapi.en.json
index db596a30..280546cc 100644
--- a/api-reference/rum.openapi.en.json
+++ b/api-reference/rum.openapi.en.json
@@ -1223,6 +1223,10 @@
       "RumDataQueryDefinition": {
         "description": "One RUM data query definition.",
         "properties": {
+          "disable_cache": {
+            "description": "When true, the query uses the exact `start_time`/`end_time` and the result is neither read from nor written to the cache. Defaults to false.",
+            "type": "boolean"
+          },
           "disable_sampling": {
             "description": "When `true`, the query always runs on the full data and the response never carries `sampling`. When `false` (default), the server may sample aggregate queries over large time windows.",
             "type": "boolean"
@@ -9528,7 +9532,7 @@
     },
     "/rum/data/query": {
       "post": {
-        "description": "Run one or more SQL-style RUM data queries over a bounded time range.",
+        "description": "Run one or more SQL-style RUM data queries over a bounded time range.\n\n**Time range alignment and caching**: so 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. 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) are not aligned.\n\nResults may be up to 60 seconds stale for the most recent data. Set `disable_cache=true` on a query entry to use the exact start and end and bypass the cache.",
         "operationId": "rum-read-data-query",
         "requestBody": {
           "content": {
@@ -10343,7 +10347,7 @@
     },
     "/rum/facet/count": {
       "post": {
-        "description": "Return the top N values for a facet field within a time range, sorted by occurrence count descending.",
+        "description": "Return the top N values for a facet field within a time range, sorted by occurrence count descending.\n\n**Time range alignment and caching**: so 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. 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.",
         "operationId": "rum-read-facet-count",
         "requestBody": {
           "content": {
diff --git a/api-reference/rum.openapi.zh.json b/api-reference/rum.openapi.zh.json
index 2550aae9..d6367bf0 100644
--- a/api-reference/rum.openapi.zh.json
+++ b/api-reference/rum.openapi.zh.json
@@ -1223,6 +1223,10 @@
       "RumDataQueryDefinition": {
         "description": "单个 RUM 数据查询定义。",
         "properties": {
+          "disable_cache": {
+            "description": "为 true 时，使用精确的 `start_time`/`end_time` 查询，且结果既不读取也不写入缓存。默认 false。",
+            "type": "boolean"
+          },
           "disable_sampling": {
             "description": "为 `true` 时始终查询全量数据，响应不会出现 `sampling`。为 `false`（默认）时，服务端可能对大时间跨度的聚合查询进行抽样。",
             "type": "boolean"
@@ -9528,7 +9532,7 @@
     },
     "/rum/data/query": {
       "post": {
-        "description": "在指定时间范围内执行一个或多个 SQL 风格的 RUM 数据查询。",
+        "description": "在指定时间范围内执行一个或多个 SQL 风格的 RUM 数据查询。\n\n**时间范围对齐与缓存**：为便于重复查询复用缓存结果，聚合查询的时间范围会被对齐到网格：\n\n- `format=time_series`：起始时间向下、结束时间向上取整到 `interval`。时间桶的数量和位置不变，首尾两个桶覆盖完整区间，而不是部分区间。\n- 聚合（非时序）查询：起始时间向下、结束时间向上取整到 `max(1 分钟, 时间范围 ÷ 1226 向上取到下一个标准间隔档)`，例如 24 小时对齐到 2 分钟，7 天对齐到 10 分钟，30 天对齐到 1 小时。起始端最多多出一个网格步长的数据；结束端取整到未来，该部分没有数据。\n- 明细/列表查询（无聚合、分页）不做对齐。\n\n最近时间的数据结果最多可能滞后 60 秒。在查询项上设置 `disable_cache=true` 可使用精确的起止时间，并绕过缓存。",
         "operationId": "rum-read-data-query",
         "requestBody": {
           "content": {
@@ -10343,7 +10347,7 @@
     },
     "/rum/facet/count": {
       "post": {
-        "description": "按出现次数降序返回指定时间范围内某个分面字段的 Top N 值及其计数。",
+        "description": "按出现次数降序返回指定时间范围内某个分面字段的 Top N 值及其计数。\n\n**时间范围对齐与缓存**：为便于重复查询复用缓存结果，起始时间向下、结束时间向上取整到 `max(1 分钟, 时间范围 ÷ 1226 向上取到下一个标准间隔档)`，例如 24 小时对齐到 2 分钟，7 天对齐到 10 分钟，30 天对齐到 1 小时。起始端最多多出一个网格步长的数据；结束端取整到未来，该部分没有数据。最近时间的数据结果最多可能滞后 60 秒。",
         "operationId": "rum-read-facet-count",
         "requestBody": {
           "content": {

From c99ad018d037f808fe8ca16ce7427b77333364c8 Mon Sep 17 00:00:00 2001
From: ysyneu <ysyneu@gmail.com>
Date: Sun, 25 Oct 2026 22:22:04 -0700
Subject: [PATCH 2/3] docs(api): note that short-range and time-dependent RUM
 queries are not aligned or cached

---
 api-reference/openapi.en.json     | 4 ++--
 api-reference/openapi.zh.json     | 4 ++--
 api-reference/rum.openapi.en.json | 4 ++--
 api-reference/rum.openapi.zh.json | 4 ++--
 4 files changed, 8 insertions(+), 8 deletions(-)

diff --git a/api-reference/openapi.en.json b/api-reference/openapi.en.json
index 3266a3ce..2dfd7653 100644
--- a/api-reference/openapi.en.json
+++ b/api-reference/openapi.en.json
@@ -58343,7 +58343,7 @@
     },
     "/rum/data/query": {
       "post": {
-        "description": "Run one or more SQL-style RUM data queries over a bounded time range.\n\n**Time range alignment and caching**: so 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. 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) are not aligned.\n\nResults may be up to 60 seconds stale for the most recent data. Set `disable_cache=true` on a query entry to use the exact start and end and bypass the cache.",
+        "description": "Run one or more SQL-style RUM data queries over a bounded time range.\n\n**Time range alignment and caching**: so 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. Set `disable_cache=true` on a query entry to use the exact start and end and bypass the cache.",
         "operationId": "rum-read-data-query",
         "requestBody": {
           "content": {
@@ -59158,7 +59158,7 @@
     },
     "/rum/facet/count": {
       "post": {
-        "description": "Return the top N values for a facet field within a time range, sorted by occurrence count descending.\n\n**Time range alignment and caching**: so 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. 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.",
+        "description": "Return the top N values for a facet field within a time range, sorted by occurrence count descending.\n\n**Time range alignment and caching**: so 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.",
         "operationId": "rum-read-facet-count",
         "requestBody": {
           "content": {
diff --git a/api-reference/openapi.zh.json b/api-reference/openapi.zh.json
index f213ab05..51931494 100644
--- a/api-reference/openapi.zh.json
+++ b/api-reference/openapi.zh.json
@@ -58343,7 +58343,7 @@
     },
     "/rum/data/query": {
       "post": {
-        "description": "在指定时间范围内执行一个或多个 SQL 风格的 RUM 数据查询。\n\n**时间范围对齐与缓存**：为便于重复查询复用缓存结果，聚合查询的时间范围会被对齐到网格：\n\n- `format=time_series`：起始时间向下、结束时间向上取整到 `interval`。时间桶的数量和位置不变，首尾两个桶覆盖完整区间，而不是部分区间。\n- 聚合（非时序）查询：起始时间向下、结束时间向上取整到 `max(1 分钟, 时间范围 ÷ 1226 向上取到下一个标准间隔档)`，例如 24 小时对齐到 2 分钟，7 天对齐到 10 分钟，30 天对齐到 1 小时。起始端最多多出一个网格步长的数据；结束端取整到未来，该部分没有数据。\n- 明细/列表查询（无聚合、分页）不做对齐。\n\n最近时间的数据结果最多可能滞后 60 秒。在查询项上设置 `disable_cache=true` 可使用精确的起止时间，并绕过缓存。",
+        "description": "在指定时间范围内执行一个或多个 SQL 风格的 RUM 数据查询。\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 秒。在查询项上设置 `disable_cache=true` 可使用精确的起止时间，并绕过缓存。",
         "operationId": "rum-read-data-query",
         "requestBody": {
           "content": {
@@ -59158,7 +59158,7 @@
     },
     "/rum/facet/count": {
       "post": {
-        "description": "按出现次数降序返回指定时间范围内某个分面字段的 Top N 值及其计数。\n\n**时间范围对齐与缓存**：为便于重复查询复用缓存结果，起始时间向下、结束时间向上取整到 `max(1 分钟, 时间范围 ÷ 1226 向上取到下一个标准间隔档)`，例如 24 小时对齐到 2 分钟，7 天对齐到 10 分钟，30 天对齐到 1 小时。起始端最多多出一个网格步长的数据；结束端取整到未来，该部分没有数据。最近时间的数据结果最多可能滞后 60 秒。",
+        "description": "按出现次数降序返回指定时间范围内某个分面字段的 Top N 值及其计数。\n\n**时间范围对齐与缓存**：为便于重复查询复用缓存结果，起始时间向下、结束时间向上取整到 `max(1 分钟, 时间范围 ÷ 1226 向上取到下一个标准间隔档)`，例如 24 小时对齐到 2 分钟，7 天对齐到 10 分钟，30 天对齐到 1 小时。时间范围短于 100 个网格步长时不对齐、不缓存。起始端最多多出一个网格步长的数据；结束端取整到未来，该部分没有数据。最近时间的数据结果最多可能滞后 60 秒。",
         "operationId": "rum-read-facet-count",
         "requestBody": {
           "content": {
diff --git a/api-reference/rum.openapi.en.json b/api-reference/rum.openapi.en.json
index 280546cc..13b1e59b 100644
--- a/api-reference/rum.openapi.en.json
+++ b/api-reference/rum.openapi.en.json
@@ -9532,7 +9532,7 @@
     },
     "/rum/data/query": {
       "post": {
-        "description": "Run one or more SQL-style RUM data queries over a bounded time range.\n\n**Time range alignment and caching**: so 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. 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) are not aligned.\n\nResults may be up to 60 seconds stale for the most recent data. Set `disable_cache=true` on a query entry to use the exact start and end and bypass the cache.",
+        "description": "Run one or more SQL-style RUM data queries over a bounded time range.\n\n**Time range alignment and caching**: so 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. Set `disable_cache=true` on a query entry to use the exact start and end and bypass the cache.",
         "operationId": "rum-read-data-query",
         "requestBody": {
           "content": {
@@ -10347,7 +10347,7 @@
     },
     "/rum/facet/count": {
       "post": {
-        "description": "Return the top N values for a facet field within a time range, sorted by occurrence count descending.\n\n**Time range alignment and caching**: so 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. 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.",
+        "description": "Return the top N values for a facet field within a time range, sorted by occurrence count descending.\n\n**Time range alignment and caching**: so 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.",
         "operationId": "rum-read-facet-count",
         "requestBody": {
           "content": {
diff --git a/api-reference/rum.openapi.zh.json b/api-reference/rum.openapi.zh.json
index d6367bf0..fc18d06c 100644
--- a/api-reference/rum.openapi.zh.json
+++ b/api-reference/rum.openapi.zh.json
@@ -9532,7 +9532,7 @@
     },
     "/rum/data/query": {
       "post": {
-        "description": "在指定时间范围内执行一个或多个 SQL 风格的 RUM 数据查询。\n\n**时间范围对齐与缓存**：为便于重复查询复用缓存结果，聚合查询的时间范围会被对齐到网格：\n\n- `format=time_series`：起始时间向下、结束时间向上取整到 `interval`。时间桶的数量和位置不变，首尾两个桶覆盖完整区间，而不是部分区间。\n- 聚合（非时序）查询：起始时间向下、结束时间向上取整到 `max(1 分钟, 时间范围 ÷ 1226 向上取到下一个标准间隔档)`，例如 24 小时对齐到 2 分钟，7 天对齐到 10 分钟，30 天对齐到 1 小时。起始端最多多出一个网格步长的数据；结束端取整到未来，该部分没有数据。\n- 明细/列表查询（无聚合、分页）不做对齐。\n\n最近时间的数据结果最多可能滞后 60 秒。在查询项上设置 `disable_cache=true` 可使用精确的起止时间，并绕过缓存。",
+        "description": "在指定时间范围内执行一个或多个 SQL 风格的 RUM 数据查询。\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 秒。在查询项上设置 `disable_cache=true` 可使用精确的起止时间，并绕过缓存。",
         "operationId": "rum-read-data-query",
         "requestBody": {
           "content": {
@@ -10347,7 +10347,7 @@
     },
     "/rum/facet/count": {
       "post": {
-        "description": "按出现次数降序返回指定时间范围内某个分面字段的 Top N 值及其计数。\n\n**时间范围对齐与缓存**：为便于重复查询复用缓存结果，起始时间向下、结束时间向上取整到 `max(1 分钟, 时间范围 ÷ 1226 向上取到下一个标准间隔档)`，例如 24 小时对齐到 2 分钟，7 天对齐到 10 分钟，30 天对齐到 1 小时。起始端最多多出一个网格步长的数据；结束端取整到未来，该部分没有数据。最近时间的数据结果最多可能滞后 60 秒。",
+        "description": "按出现次数降序返回指定时间范围内某个分面字段的 Top N 值及其计数。\n\n**时间范围对齐与缓存**：为便于重复查询复用缓存结果，起始时间向下、结束时间向上取整到 `max(1 分钟, 时间范围 ÷ 1226 向上取到下一个标准间隔档)`，例如 24 小时对齐到 2 分钟，7 天对齐到 10 分钟，30 天对齐到 1 小时。时间范围短于 100 个网格步长时不对齐、不缓存。起始端最多多出一个网格步长的数据；结束端取整到未来，该部分没有数据。最近时间的数据结果最多可能滞后 60 秒。",
         "operationId": "rum-read-facet-count",
         "requestBody": {
           "content": {

From 621f6f3552ba9fedfc8d2c6108fff6e93dc64114 Mon Sep 17 00:00:00 2001
From: ysyneu <ysyneu@gmail.com>
Date: Mon, 26 Oct 2026 03:09:44 -0700
Subject: [PATCH 3/3] docs(api): keep RUM cache bypass out of public reference

---
 api-reference/openapi.en.json     | 12 ++++--------
 api-reference/openapi.zh.json     | 12 ++++--------
 api-reference/rum.openapi.en.json | 12 ++++--------
 api-reference/rum.openapi.zh.json | 12 ++++--------
 4 files changed, 16 insertions(+), 32 deletions(-)

diff --git a/api-reference/openapi.en.json b/api-reference/openapi.en.json
index 2dfd7653..f25ed087 100644
--- a/api-reference/openapi.en.json
+++ b/api-reference/openapi.en.json
@@ -20747,10 +20747,6 @@
       "RumDataQueryDefinition": {
         "description": "One RUM data query definition.",
         "properties": {
-          "disable_cache": {
-            "description": "When true, the query uses the exact `start_time`/`end_time` and the result is neither read from nor written to the cache. Defaults to false.",
-            "type": "boolean"
-          },
           "disable_sampling": {
             "description": "When `true`, the query always runs on the full data and the response never carries `sampling`. When `false` (default), the server may sample aggregate queries over large time windows.",
             "type": "boolean"
@@ -58343,7 +58339,7 @@
     },
     "/rum/data/query": {
       "post": {
-        "description": "Run one or more SQL-style RUM data queries over a bounded time range.\n\n**Time range alignment and caching**: so 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. Set `disable_cache=true` on a query entry to use the exact start and end and bypass the cache.",
+        "description": "Run one or more SQL-style RUM data queries over a bounded time range.",
         "operationId": "rum-read-data-query",
         "requestBody": {
           "content": {
@@ -58441,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"
@@ -59158,7 +59154,7 @@
     },
     "/rum/facet/count": {
       "post": {
-        "description": "Return the top N values for a facet field within a time range, sorted by occurrence count descending.\n\n**Time range alignment and caching**: so 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.",
+        "description": "Return the top N values for a facet field within a time range, sorted by occurrence count descending.",
         "operationId": "rum-read-facet-count",
         "requestBody": {
           "content": {
@@ -59240,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"
diff --git a/api-reference/openapi.zh.json b/api-reference/openapi.zh.json
index 51931494..fa3d6522 100644
--- a/api-reference/openapi.zh.json
+++ b/api-reference/openapi.zh.json
@@ -20747,10 +20747,6 @@
       "RumDataQueryDefinition": {
         "description": "单个 RUM 数据查询定义。",
         "properties": {
-          "disable_cache": {
-            "description": "为 true 时，使用精确的 `start_time`/`end_time` 查询，且结果既不读取也不写入缓存。默认 false。",
-            "type": "boolean"
-          },
           "disable_sampling": {
             "description": "为 `true` 时始终查询全量数据，响应不会出现 `sampling`。为 `false`（默认）时，服务端可能对大时间跨度的聚合查询进行抽样。",
             "type": "boolean"
@@ -58343,7 +58339,7 @@
     },
     "/rum/data/query": {
       "post": {
-        "description": "在指定时间范围内执行一个或多个 SQL 风格的 RUM 数据查询。\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 秒。在查询项上设置 `disable_cache=true` 可使用精确的起止时间，并绕过缓存。",
+        "description": "在指定时间范围内执行一个或多个 SQL 风格的 RUM 数据查询。",
         "operationId": "rum-read-data-query",
         "requestBody": {
           "content": {
@@ -58441,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 数据"
@@ -59158,7 +59154,7 @@
     },
     "/rum/facet/count": {
       "post": {
-        "description": "按出现次数降序返回指定时间范围内某个分面字段的 Top N 值及其计数。\n\n**时间范围对齐与缓存**：为便于重复查询复用缓存结果，起始时间向下、结束时间向上取整到 `max(1 分钟, 时间范围 ÷ 1226 向上取到下一个标准间隔档)`，例如 24 小时对齐到 2 分钟，7 天对齐到 10 分钟，30 天对齐到 1 小时。时间范围短于 100 个网格步长时不对齐、不缓存。起始端最多多出一个网格步长的数据；结束端取整到未来，该部分没有数据。最近时间的数据结果最多可能滞后 60 秒。",
+        "description": "按出现次数降序返回指定时间范围内某个分面字段的 Top N 值及其计数。",
         "operationId": "rum-read-facet-count",
         "requestBody": {
           "content": {
@@ -59240,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": "查询分值分布"
diff --git a/api-reference/rum.openapi.en.json b/api-reference/rum.openapi.en.json
index 13b1e59b..668f6550 100644
--- a/api-reference/rum.openapi.en.json
+++ b/api-reference/rum.openapi.en.json
@@ -1223,10 +1223,6 @@
       "RumDataQueryDefinition": {
         "description": "One RUM data query definition.",
         "properties": {
-          "disable_cache": {
-            "description": "When true, the query uses the exact `start_time`/`end_time` and the result is neither read from nor written to the cache. Defaults to false.",
-            "type": "boolean"
-          },
           "disable_sampling": {
             "description": "When `true`, the query always runs on the full data and the response never carries `sampling`. When `false` (default), the server may sample aggregate queries over large time windows.",
             "type": "boolean"
@@ -9532,7 +9528,7 @@
     },
     "/rum/data/query": {
       "post": {
-        "description": "Run one or more SQL-style RUM data queries over a bounded time range.\n\n**Time range alignment and caching**: so 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. Set `disable_cache=true` on a query entry to use the exact start and end and bypass the cache.",
+        "description": "Run one or more SQL-style RUM data queries over a bounded time range.",
         "operationId": "rum-read-data-query",
         "requestBody": {
           "content": {
@@ -9630,7 +9626,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"
@@ -10347,7 +10343,7 @@
     },
     "/rum/facet/count": {
       "post": {
-        "description": "Return the top N values for a facet field within a time range, sorted by occurrence count descending.\n\n**Time range alignment and caching**: so 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.",
+        "description": "Return the top N values for a facet field within a time range, sorted by occurrence count descending.",
         "operationId": "rum-read-facet-count",
         "requestBody": {
           "content": {
@@ -10429,7 +10425,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"
diff --git a/api-reference/rum.openapi.zh.json b/api-reference/rum.openapi.zh.json
index fc18d06c..3207a7cb 100644
--- a/api-reference/rum.openapi.zh.json
+++ b/api-reference/rum.openapi.zh.json
@@ -1223,10 +1223,6 @@
       "RumDataQueryDefinition": {
         "description": "单个 RUM 数据查询定义。",
         "properties": {
-          "disable_cache": {
-            "description": "为 true 时，使用精确的 `start_time`/`end_time` 查询，且结果既不读取也不写入缓存。默认 false。",
-            "type": "boolean"
-          },
           "disable_sampling": {
             "description": "为 `true` 时始终查询全量数据，响应不会出现 `sampling`。为 `false`（默认）时，服务端可能对大时间跨度的聚合查询进行抽样。",
             "type": "boolean"
@@ -9532,7 +9528,7 @@
     },
     "/rum/data/query": {
       "post": {
-        "description": "在指定时间范围内执行一个或多个 SQL 风格的 RUM 数据查询。\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 秒。在查询项上设置 `disable_cache=true` 可使用精确的起止时间，并绕过缓存。",
+        "description": "在指定时间范围内执行一个或多个 SQL 风格的 RUM 数据查询。",
         "operationId": "rum-read-data-query",
         "requestBody": {
           "content": {
@@ -9630,7 +9626,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 数据"
@@ -10347,7 +10343,7 @@
     },
     "/rum/facet/count": {
       "post": {
-        "description": "按出现次数降序返回指定时间范围内某个分面字段的 Top N 值及其计数。\n\n**时间范围对齐与缓存**：为便于重复查询复用缓存结果，起始时间向下、结束时间向上取整到 `max(1 分钟, 时间范围 ÷ 1226 向上取到下一个标准间隔档)`，例如 24 小时对齐到 2 分钟，7 天对齐到 10 分钟，30 天对齐到 1 小时。时间范围短于 100 个网格步长时不对齐、不缓存。起始端最多多出一个网格步长的数据；结束端取整到未来，该部分没有数据。最近时间的数据结果最多可能滞后 60 秒。",
+        "description": "按出现次数降序返回指定时间范围内某个分面字段的 Top N 值及其计数。",
         "operationId": "rum-read-facet-count",
         "requestBody": {
           "content": {
@@ -10429,7 +10425,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": "查询分值分布"