数据集 · Cloudflare Analytics 文档

每个 SQL API 数据集都有带 schema 限定的名称。前缀标识一行代表什么，以及应如何解读数据：

前缀	行含义
`events.`	每一行是一个唯一事件。事件数据集通常经过采样。
`states.`	每一行表示记录观察时系统的当前状态。
`logs.`	每一行是一个唯一事件或日志条目。日志数据集通常未采样，但也可以采样。这包括 Log Explorer 数据集。

事件数据集

对 events. 数据集进行聚合分析，例如创建表、图表和仪表板。也可以检索单个事件。例如，以下查询按响应状态统计 HTTP 请求：

SELECT edgeResponseStatus AS status, COUNT(*) AS requests
FROM events.httpRequests
WHERE accountTag = '<ACCOUNT_TAG>'
  AND timestamp >= NOW() - INTERVAL '1' HOUR
GROUP BY edgeResponseStatus
ORDER BY requests DESC
LIMIT 10

事件数据集通常采用自适应采样。SQL API 会自动将采样权重应用于 COUNT、SUM 和 AVG。仅选择单个行的查询只会返回已采样的行，无法重建未被保留的事件。

状态数据集

使用 states. 数据集检查系统状态观察，例如 D1 数据库存储。每一行描述其 timestamp 字段所对应时间的状态。它不代表唯一操作或事务。

SELECT timestamp, databaseId, databaseSizeBytes
FROM states.d1Storage
WHERE accountTag = '<ACCOUNT_TAG>'
  AND timestamp >= NOW() - INTERVAL '1' HOUR
ORDER BY timestamp DESC
LIMIT 100

每个状态数据集定义哪些聚合函数对其值有意义。API 会拒绝所选状态数据集不支持的聚合函数。内省会将这些列在数据集 kind 的 valid_aggregations 中：

{
    "kind": {
        "states": {
            "sampling": "adaptive",
            "valid_aggregations": ["max"]
        }
    }
}

日志数据集

使用 logs. 数据集对单个事件和日志条目进行细粒度调查。也可以聚合日志数据以识别趋势。此类别包括由 Log Explorer 提供的数据集。

SELECT timestamp, scriptName, logType
FROM logs.workersLogs
WHERE accountTag = '<ACCOUNT_TAG>'
  AND timestamp >= NOW() - INTERVAL '15' MINUTE
ORDER BY timestamp DESC
LIMIT 100

日志数据集通常未采样，但有些使用自适应采样。与事件数据集一样，当日志数据集经过采样时，SQL API 会自动将采样权重应用于受支持的聚合函数。

Workers Analytics Engine 数据集

将 Workers Analytics Engine 数据集查询为 events.analyticsEngine.<DATASET_NAME>，将 <DATASET_NAME> 替换为绑定配置的名称。对于 myDataset 等名称使用未加引号的 SQL 标识符；对于包含连字符等字符的名称使用双引号标识符：events.analyticsEngine."example-dataset"。这些数据集需要 accountTag 或 scope.accountTag。不支持 zone 范围。

SELECT timestamp, index1, blob1, double1
FROM events.analyticsEngine."example-dataset"
WHERE accountTag = '<ACCOUNT_TAG>'
  AND timestamp >= NOW() - INTERVAL '1' HOUR
ORDER BY timestamp DESC
LIMIT 100

此接口使用 Analytics SQL API 端点和 SQL 方言。它独立于 Workers Analytics Engine SQL API。

Workers Analytics Engine 数据集采用自适应采样。SQL API 会将采样权重应用于受支持的聚合。为保持与现有 Workers Analytics Engine 查询的兼容性，这些数据集还支持聚合 DISTINCT、argMax 和 argMin。它们允许没有 LIMIT 的 ORDER BY，以及没有 LIMIT 的 OFFSET。这些兼容性例外不适用于其他自适应采样数据集。

自省会从账户自身的数据中发现 Workers Analytics Engine 数据集名称，默认最多返回 1,000 个不同的名称（超出部分会被静默截断，且不受时间范围限制：只要数据集中的任何数据仍被保留，该数据集就会继续列出）。这与 include_attributes 不同，后者只查看之前七天的数据。如果将不带 <DATASET_NAME> 后缀的纯 events.analyticsEngine namespace 作为 dataset_name 传入，则会返回该账户拥有的所有 Workers Analytics Engine 数据集，而不会因名称未知而被拒绝。

发现数据集

使用内省端点列出 SQL API 目录中的数据集。该目录不是固定列表：数据集可能因部署而出现或消失；对于 Workers Analytics Engine 和 Log Explorer 数据集，还会因账户而变化。请查询目录而不是硬编码数据集名称，也不要将某次响应中缺少某个数据集视为它永远不会出现的证据。

可以使用 Cloudflare CLI 检查目录：

cf sql datasets --account-tag "<ACCOUNT_TAG>"

curl --get "https://api.cloudflare.com/client/v4/analytics/sql/introspection" \
  --header "Authorization: Bearer <API_TOKEN>" \
  --data-urlencode "account_tag=<ACCOUNT_TAG>"

响应包含按名称排序的数据集名称、标题、类别、描述和种类。默认省略列。kind 的 sampling 为 unsampled 或 adaptive。

{
    "datasets": [
        {
            "name": "events.httpRequests",
            "title": "HTTP Requests",
            "category": "HTTP Traffic",
            "description": "Aggregated HTTP requests data with adaptive sampling",
            "kind": {
                "events": {
                    "sampling": "adaptive"
                }
            }
        }
    ]
}

查询参数

该端点接受以下查询参数：

参数	类型	必填	描述
`account_tag`	字符串	是	账户标识符。需要 Account Analytics Read 权限。
`dataset_name`	字符串	否	要返回的精确、区分大小写的带 schema 限定的数据集名称。
`include_columns`	boolean	否	设为 `true` 以包含列名、描述和数据类型。默认为 `false`。
`include_attributes`	boolean	否	设置为 `true`，可从账户数据中发现数据集 `attributes` 字段的键及其类型。要求 `dataset_name` 非空。
`include_custom_attributes`	boolean	否	已弃用。请改用 `include_attributes`。
`include_wae`	boolean	否	设为 `false` 以省略 Workers Analytics Engine 数据集（从账户自身数据发现）。默认为 `true`。
`include_lex`	boolean	否	设为 `false` 以省略 Log Explorer 数据集（仅对拥有它们的账户列出）。默认为 `true`。

列

要检查一个数据集及其列，请同时提供这两个可选参数：

curl --get "https://api.cloudflare.com/client/v4/analytics/sql/introspection" \
  --header "Authorization: Bearer <API_TOKEN>" \
  --data-urlencode "account_tag=<ACCOUNT_TAG>" \
  --data-urlencode "dataset_name=events.httpRequests" \
  --data-urlencode "include_columns=true"

{
    "datasets": [
        {
            "name": "events.httpRequests",
            "title": "HTTP Requests",
            "category": "HTTP Traffic",
            "description": "Aggregated HTTP requests data with adaptive sampling",
            "kind": {
                "events": {
                    "sampling": "adaptive"
                }
            },
            "columns": [
                {
                    "name": "accountTag",
                    "description": "Account tag (hex identifier)",
                    "data_type": "String"
                },
                {
                    "name": "timestamp",
                    "description": "The date and time the event occurred at the edge",
                    "data_type": "DateTime"
                }
            ]
        }
    ]
}

列的 data_type 为 String、UInt8、UInt16、UInt32、UInt64、Int64、Float64、Date、DateTime、DateTime64(3)、Array(<scalar type>)（例如 Array(String)）或 Json 之一。

属性

某些数据集会将额外的键值数据存储在名为 attributes 的 JSON 列中。你可以通过精确键查找来查询此列中的键，例如 attributes['http.method']。有关详细信息，请参阅 JSON 字段。

自省通常返回静态 catalog 元数据，而不会查询底层数据存储。设置 include_attributes=true 后，会查询指定账户中所选数据集之前七天的数据，并在数据集响应的 attributes 字段中返回发现的键：

每种属性类型都受服务所配置属性上限的限制（默认为 1,000 个），因此响应可能不会包含所有历史属性。
截断是静默的：响应不会指示已达到上限。
属性的 data_type 为 String、Float64 或 Bool 之一，其可选值比列的 data_type 值更少。
如果数据集没有可发现的属性，则会省略 attributes，而不是返回空数组。

Log Explorer 可用性

Log Explorer 数据集在 kind 旁包含 availability 字段，列出账户已启用该数据集的范围：

{
    "availability": [
        { "scope": "account" },
        { "scope": "zone", "zone": "<ZONE_TAG>" }
    ]
}

非 Log Explorer 支持的数据集会省略 availability。

错误

内省使用与 SQL API 其余部分相同的 HTTP 状态码。以下 422 原因特定于内省：

account_tag 无效或未知。
设置了 include_attributes=true（或已弃用的 include_custom_attributes=true），但未提供非空的 dataset_name。
dataset_name 标识 Workers Analytics Engine 数据集，同时 include_wae=false。
用于直接查找的 Workers Analytics Engine 数据集名称格式错误或包含不支持的字符。
所提供的条件（例如 dataset_name）不匹配任何数据集。存在但在此部署中无法描述的数据集会返回相同错误，消息会指出未匹配任何内容的条件，因此这两种情况无法区分。

响应中出现数据集或列并不保证你的套餐和权限允许查询它。提交查询时，SQL API 会应用数据集和字段授权。