> ## Documentation Index
> Fetch the complete documentation index at: https://docs.windsurf.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 自定义 Analytics 查询

> 使用自定义 selections、过滤器和 aggregations 进行灵活的 Analytics 查询，用于 Autocomplete、Chat、Command 和 PCW 数据。

<div id="overview">
  ## 概览
</div>

Custom Analytics API 提供灵活的查询能力，可对 Autocomplete、Chat 和 Command 的数据进行可自定义的 selections、过滤、aggregations 和排序。

<div id="request">
  ## 请求
</div>

<ParamField body="service_key" type="string" required>
  具有“Analytics Read”权限的服务密钥
</ParamField>

<ParamField body="group_name" type="string">
  将结果筛选为特定用户组内的用户（可选）
</ParamField>

<ParamField body="query_requests" type="array" required>
  定义要检索的数据的查询请求对象数组

  <Expandable title="查询请求对象">
    <ParamField body="data_source" type="string" required>
      要查询的数据源。可选值：

      * `QUERY_DATA_SOURCE_USER_DATA` - Autocomplete 数据
      * `QUERY_DATA_SOURCE_CHAT_DATA` - Chat 数据
      * `QUERY_DATA_SOURCE_COMMAND_DATA` - Command 数据
      * `QUERY_DATA_SOURCE_PCW_DATA` - Percent Code Written 数据
    </ParamField>

    <ParamField body="selections" type="array" required>
      要检索的字段 selections 数组

      <Expandable title="Selection 对象">
        <ParamField body="field" type="string" required>
          要选择的字段名（参见 Available Fields 部分）
        </ParamField>

        <ParamField body="name" type="string">
          字段的别名。若未指定，默认为 `{aggregation_function}_{field_name}`（小写）
        </ParamField>

        <ParamField body="aggregation_function" type="string">
          要应用的聚合函数：

          * `QUERY_AGGREGATION_UNSPECIFIED`（默认）
          * `QUERY_AGGREGATION_COUNT`
          * `QUERY_AGGREGATION_SUM`
          * `QUERY_AGGREGATION_AVG`
          * `QUERY_AGGREGATION_MAX`
          * `QUERY_AGGREGATION_MIN`
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField body="filters" type="array">
      要应用的过滤条件数组

      <Expandable title="Filter 对象">
        <ParamField body="name" type="string" required>
          要进行过滤的字段名
        </ParamField>

        <ParamField body="filter" type="string" required>
          过滤操作：

          * `QUERY_FILTER_EQUAL`
          * `QUERY_FILTER_NOT_EQUAL`
          * `QUERY_FILTER_GREATER_THAN`
          * `QUERY_FILTER_LESS_THAN`
          * `QUERY_FILTER_GE`（大于或等于）
          * `QUERY_FILTER_LE`（小于或等于）
        </ParamField>

        <ParamField body="value" type="string" required>
          要用于比较的值
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField body="aggregations" type="array">
      用于分组的 aggregations 数组

      <Expandable title="Aggregation 对象">
        <ParamField body="field" type="string" required>
          用于分组的字段名
        </ParamField>

        <ParamField body="name" type="string" required>
          聚合字段的别名
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

<div id="query-request-structure">
  ## 查询请求结构
</div>

每个查询请求对象包含：

* **data\_source**（必需）：要查询的数据源
* **selections**（必需）：要检索的字段 selections 数组
* **filters**（可选）：要应用的过滤条件数组
* **aggregations**（可选）：用于分组的 aggregations 数组

<div id="selections">
  ## Selections
</div>

Selections 用于定义要检索的字段以及对其进行聚合的方式。

* **field**（必填）：要选择的字段名
* **name**（可选）：字段的别名
* **aggregation\_function**（可选）：要应用的聚合函数

<div id="selection-example">
  ### 选择示例
</div>

```json theme={null}
{
  "field": "num_acceptances",
  "name": "total_acceptances",
  "aggregation_function": "QUERY_AGGREGATION_SUM"
}
```

<div id="filters">
  ## 筛选器
</div>

筛选器用于将数据限定为满足特定条件的元素。

* **name**（必填）：要进行筛选的字段名称
* **filter**（必填）：筛选操作
* **value**（必填）：用于比较的值

<div id="filter-example">
  ### 筛选示例
</div>

```json theme={null}
{
  "name": "language",
  "filter": "QUERY_FILTER_EQUAL",
  "value": "PYTHON"
}
```

<div id="aggregations">
  ## Aggregations
</div>

aggregations 根据指定条件对数据进行分组。

* **field** (required): 用于分组的字段名
* **name** (required): 该聚合字段的别名

<div id="aggregation-example">
  ### 聚合示例
</div>

```json theme={null}
{
  "field": "ide",
  "name": "ide_type"
}
```

<div id="available-fields">
  ## 可用字段
</div>

<div id="user-data">
  ### 用户数据
</div>

所有用户数据按用户、按小时汇总。

| 字段名称                       | 描述                               | 可用聚合               |
| -------------------------- | -------------------------------- | ------------------ |
| `api_key`                  | 用户 API 密钥的哈希值                    | UNSPECIFIED, COUNT |
| `date`                     | 自动补全的 UTC 日期                     | UNSPECIFIED, COUNT |
| `date UTC-x`               | 带时区偏移的日期（例如，“date UTC-8” 表示 PST） | UNSPECIFIED, COUNT |
| `hour`                     | 自动补全的 UTC 小时                     | UNSPECIFIED, COUNT |
| `language`                 | 编程语言                             | UNSPECIFIED, COUNT |
| `ide`                      | 使用的 IDE                          | UNSPECIFIED, COUNT |
| `version`                  | Windsurf 版本                      | UNSPECIFIED, COUNT |
| `num_acceptances`          | Autocomplete 接受次数                | SUM, MAX, MIN, AVG |
| `num_lines_accepted`       | 接受的代码行数                          | SUM, MAX, MIN, AVG |
| `num_bytes_accepted`       | 接受的字节数                           | SUM, MAX, MIN, AVG |
| `distinct_users`           | 去重用户数                            | UNSPECIFIED, COUNT |
| `distinct_developer_days`  | 去重的（用户，日期）二元组                    | UNSPECIFIED, COUNT |
| `distinct_developer_hours` | 去重的（用户，小时）二元组                    | UNSPECIFIED, COUNT |

<div id="chat-data">
  ### Chat 数据
</div>

所有 Chat 数据均指 Chat 模型的回复，而非用户提问。

| 字段名称                      | 描述                          | 可用 aggregations    |
| ------------------------- | --------------------------- | ------------------ |
| `api_key`                 | 用户 API key 的哈希值             | UNSPECIFIED, COUNT |
| `model_id`                | Chat 模型 ID                  | UNSPECIFIED, COUNT |
| `date`                    | Chat 回复的 UTC 日期             | UNSPECIFIED, COUNT |
| `date UTC-x`              | 带时区偏移的日期                    | UNSPECIFIED, COUNT |
| `ide`                     | 使用的 IDE                     | UNSPECIFIED, COUNT |
| `version`                 | Windsurf 版本                 | UNSPECIFIED, COUNT |
| `latest_intent_type`      | Chat 意图类型（见下方 Intent Types） | UNSPECIFIED, COUNT |
| `num_chats_received`      | 接收到的 Chat 消息数量              | SUM, MAX, MIN, AVG |
| `chat_accepted`           | 是否接受该回复（点赞）                 | SUM, COUNT         |
| `chat_inserted_at_cursor` | 是否点击了“Insert”按钮             | SUM, COUNT         |
| `chat_applied`            | 是否点击了“Apply Diff”按钮         | SUM, COUNT         |
| `chat_loc_used`           | 来自 Chat 的已使用代码行数            | SUM, MAX, MIN, AVG |

<div id="chat-intent-types">
  #### Chat 意图类型
</div>

* `CHAT_INTENT_GENERIC` - 常规 Chat
* `CHAT_INTENT_FUNCTION_EXPLAIN` - 函数说明代码镜头
* `CHAT_INTENT_FUNCTION_DOCSTRING` - 函数文档字符串代码镜头
* `CHAT_INTENT_FUNCTION_REFACTOR` - 函数重构代码镜头
* `CHAT_INTENT_CODE_BLOCK_EXPLAIN` - 代码块说明代码镜头
* `CHAT_INTENT_CODE_BLOCK_REFACTOR` - 代码块重构代码镜头
* `CHAT_INTENT_PROBLEM_EXPLAIN` - 问题说明代码镜头
* `CHAT_INTENT_FUNCTION_UNIT_TESTS` - 函数单元测试代码镜头

<div id="command-data">
  ### Command 数据
</div>

Command 数据包含所有命令，包括被拒绝的命令。使用 `accepted` 字段可仅筛选已接受的命令。

| 字段名称              | 描述                                | 可用 aggregations    |
| ----------------- | --------------------------------- | ------------------ |
| `api_key`         | 用户 API key 的哈希                    | UNSPECIFIED, COUNT |
| `date`            | 命令的 UTC 日期                        | UNSPECIFIED, COUNT |
| `timestamp`       | 命令的 UTC 时间戳                       | UNSPECIFIED, COUNT |
| `language`        | 编程语言                              | UNSPECIFIED, COUNT |
| `ide`             | 使用的 IDE                           | UNSPECIFIED, COUNT |
| `version`         | Windsurf 版本                       | UNSPECIFIED, COUNT |
| `command_source`  | Command 触发来源（见下方 Command Sources） | UNSPECIFIED, COUNT |
| `provider_source` | 生成或编辑模式                           | UNSPECIFIED, COUNT |
| `lines_added`     | 新增代码行数                            | SUM, MAX, MIN, AVG |
| `lines_removed`   | 移除代码行数                            | SUM, MAX, MIN, AVG |
| `bytes_added`     | 新增字节数                             | SUM, MAX, MIN, AVG |
| `bytes_removed`   | 移除字节数                             | SUM, MAX, MIN, AVG |
| `selection_lines` | 选中行数（生成时为 0）                      | SUM, MAX, MIN, AVG |
| `selection_bytes` | 选中字节数（生成时为 0）                     | SUM, MAX, MIN, AVG |
| `accepted`        | 命令是否被接受                           | SUM, COUNT         |

<div id="command-sources">
  #### Command 来源
</div>

* `COMMAND_REQUEST_SOURCE_LINE_HINT_CODE_LENS`
* `COMMAND_REQUEST_SOURCE_DEFAULT` - 常规的 Command 用法
* `COMMAND_REQUEST_SOURCE_RIGHT_CLICK_REFACTOR`
* `COMMAND_REQUEST_SOURCE_FUNCTION_CODE_LENS`
* `COMMAND_REQUEST_SOURCE_FOLLOWUP`
* `COMMAND_REQUEST_SOURCE_CLASS_CODE_LENS`
* `COMMAND_REQUEST_SOURCE_PLAN`
* `COMMAND_REQUEST_SOURCE_SELECTION_HINT_CODE_LENS`

<div id="provider-sources">
  #### 提供方来源
</div>

* `PROVIDER_SOURCE_COMMAND_GENERATE` - 生成模式
* `PROVIDER_SOURCE_COMMAND_EDIT` - 编辑模式

<div id="pcw-data">
  ### PCW 数据
</div>

Percent Code Written 数据，分别统计 Autocomplete 和 Command 的贡献。

| 字段名称                            | 描述                                                   | 可用聚合        |
| ------------------------------- | ---------------------------------------------------- | ----------- |
| `percent_code_written`          | 计算方式：codeium\_bytes / (codeium\_bytes + user\_bytes) | UNSPECIFIED |
| `codeium_bytes`                 | Codeium 生成的总字节数                                      | UNSPECIFIED |
| `user_bytes`                    | 用户编写的总字节数                                            | UNSPECIFIED |
| `total_bytes`                   | codeium\_bytes + user\_bytes                         | UNSPECIFIED |
| `codeium_bytes_by_autocomplete` | 来自 Autocomplete 的 Codeium 字节数                        | UNSPECIFIED |
| `codeium_bytes_by_command`      | 来自 Command 的 Codeium 字节数                             | UNSPECIFIED |

<div id="pcw-filters">
  #### PCW 过滤器
</div>

| 字段名        | 描述          | 示例                |
| ---------- | ----------- | ----------------- |
| `language` | 编程语言        | KOTLIN, GO, JAVA  |
| `ide`      | 所用 IDE      | jetbrains, vscode |
| `version`  | Windsurf 版本 | 1.28.0, 130.0     |

在 PCW 查询中进行日期筛选时，请在主请求体中使用 `start_timestamp` 和 `end_timestamp`。

<div id="example-requests">
  ## 示例请求
</div>

<div id="user-data-example">
  ### 用户数据示例
</div>

```bash theme={null}
curl -X POST --header "Content-Type: application/json" \
--data '{
  "service_key": "your_service_key_here",
  "query_requests": [
    {
      "data_source": "QUERY_DATA_SOURCE_USER_DATA",
      "selections": [
        {
          "field": "num_acceptances",
          "name": "total_acceptances",
          "aggregation_function": "QUERY_AGGREGATION_SUM"
        },
        {
          "field": "num_lines_accepted",
          "name": "total_lines",
          "aggregation_function": "QUERY_AGGREGATION_SUM"
        }
      ],
      "filters": [
        {
          "name": "date",
          "filter": "QUERY_FILTER_GE",
          "value": "2024-01-01"
        },
        {
          "name": "date",
          "filter": "QUERY_FILTER_LE",
          "value": "2024-02-01"
        }
      ]
    }
  ]
}' \
https://server.codeium.com/api/v1/Analytics
```

<div id="chat-data-example">
  ### Chat 数据示例
</div>

```bash theme={null}
curl -X POST --header "Content-Type: application/json" \
--data '{
  "service_key": "your_service_key_here",
  "query_requests": [
    {
      "data_source": "QUERY_DATA_SOURCE_CHAT_DATA",
      "selections": [
        {
          "field": "chat_loc_used",
          "name": "lines_used",
          "aggregation_function": "QUERY_AGGREGATION_SUM"
        }
      ],
      "filters": [
        {
          "name": "latest_intent_type",
          "filter": "QUERY_FILTER_EQUAL",
          "value": "CHAT_INTENT_FUNCTION_DOCSTRING"
        }
      ],
      "aggregations": [
        {
          "field": "ide",
          "name": "ide_type"
        }
      ]
    }
  ]
}' \
https://server.codeium.com/api/v1/Analytics
```

<div id="command-data-example">
  ### Command 数据示例
</div>

```bash theme={null}
curl -X POST --header "Content-Type: application/json" \
--data '{
  "service_key": "your_service_key_here", // 请在此处填写您的服务密钥
  "query_requests": [
    {
      "data_source": "QUERY_DATA_SOURCE_COMMAND_DATA",
      "selections": [
        {
          "field": "lines_added",
          "name": "total_lines_added",
          "aggregation_function": "QUERY_AGGREGATION_SUM"
        },
        {
          "field": "lines_removed",
          "name": "total_lines_removed",
          "aggregation_function": "QUERY_AGGREGATION_SUM"
        }
      ],
      "filters": [
        {
          "name": "provider_source",
          "filter": "QUERY_FILTER_EQUAL",
          "value": "PROVIDER_SOURCE_COMMAND_EDIT"
        },
        {
          "name": "accepted",
          "filter": "QUERY_FILTER_EQUAL",
          "value": "true"
        }
      ],
      "aggregations": [
        {
          "field": "language",
          "name": "programming_language"
        }
      ]
    }
  ]
}' \
https://server.codeium.com/api/v1/Analytics
```

<div id="pcw-data-example">
  ### PCW 数据示例
</div>

```bash theme={null}
curl -X POST --header "Content-Type: application/json" \
--data '{
  "service_key": "your_service_key_here",
  "start_timestamp": "2024-01-01T00:00:00Z",
  "end_timestamp": "2024-12-22T00:00:00Z",
  "query_requests": [
    {
      "data_source": "QUERY_DATA_SOURCE_PCW_DATA",
      "selections": [
        {
          "field": "percent_code_written",
          "name": "pcw"
        },
        {
          "field": "codeium_bytes",
          "name": "ai_bytes"
        },
        {
          "field": "total_bytes",
          "name": "total"
        },
        {
          "field": "codeium_bytes_by_autocomplete",
          "name": "autocomplete_bytes"
        },
        {
          "field": "codeium_bytes_by_command",
          "name": "command_bytes"
        }
      ],
      "filters": [
        {
          "filter": "QUERY_FILTER_EQUAL",
          "name": "language",
          "value": "GO"
        }
      ]
    }
  ]
}' \
https://server.codeium.com/api/v1/Analytics
```

<div id="response">
  ## 响应
</div>

<ResponseField name="queryResults" type="array">
  查询结果数组，其中每个元素对应一个查询请求

  <ResponseField name="responseItems" type="array">
    结果条目数组

    <ResponseField name="item" type="object">
      包含所选字段及其值的对象
    </ResponseField>
  </ResponseField>
</ResponseField>

<div id="example-responses">
  ### 示例回复
</div>

<div id="user-data-response">
  #### 用户数据响应
</div>

```json theme={null}
{
  "queryResults": [
    {
      "responseItems": [
        {
          "item": {
            "total_acceptances": "125",
            "total_lines": "863"
          }
        }
      ]
    }
  ]
}
```

<div id="chat-data-response">
  #### Chat 数据响应
</div>

```json theme={null}
{
  "queryResults": [
    {
      "responseItems": [
        {
          "item": {
            "lines_used": "74",
            "ide_type": "jetbrains"
          }
        },
        {
          "item": {
            "lines_used": "41",
            "ide_type": "vscode"
          }
        }
      ]
    }
  ]
}
```

<div id="command-data-response">
  #### Command 数据响应
</div>

```json theme={null}
{
  "queryResults": [
    {
      "responseItems": [
        {
          "item": {
            "programming_language": "PYTHON",
            "total_lines_added": "21",
            "total_lines_removed": "5"
          }
        },
        {
          "item": {
            "programming_language": "GO",
            "total_lines_added": "31",
            "total_lines_removed": "27"
          }
        }
      ]
    }
  ]
}
```

<div id="pcw-data-response">
  #### PCW 数据返回
</div>

```json theme={null}
{
  "queryResults": [
    {
      "responseItems": [
        {
          "item": {
            "ai_bytes": "6018",
            "autocomplete_bytes": "4593",
            "command_bytes": "1425",
            "pcw": "0.61",
            "total": "9900"
          }
        }
      ]
    }
  ]
}
```

<div id="important-notes">
  ## 重要说明
</div>

* PCW（Percent Code Written，代码编写百分比）在单个自然日内或不同用户之间波动较大——建议按周聚合以获得更可靠的分析结果
* 所有 selection 字段要么全部使用聚合函数，要么全部不使用（不能混用）
* 名称符合 "distinct\_\*" 模式的字段不能用于 aggregations
* 字段别名在所有 selections 和 aggregations 中必须唯一
* 如果未指定聚合函数，则默认为 UNSPECIFIED