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

# 自定义分析查询

> 可针对 Autocomplete、聊天、Command 和 PCW 数据自定义选择、筛选和聚合，灵活执行分析查询。

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

自定义分析 API 支持对 Autocomplete、聊天和 Command 数据进行灵活查询，并可自定义选择、筛选、聚合和排序。

<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` - 代码编写占比数据
    </ParamField>

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

      <Expandable title="选择对象">
        <ParamField body="field" type="string" required>
          要选择的字段名称 (参见“可用字段”部分)
        </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="筛选器对象">
        <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">
      用于分组的聚合数组

      <Expandable title="聚合对象">
        <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** (必填) ：要获取的字段数组
* **filters** (可选) ：要应用的筛选条件数组
* **aggregations** (可选) ：用于分组的聚合数组

<div id="selections">
  ## 选择项
</div>

选择项用于定义要检索哪些字段，以及如何对这些字段进行聚合。

* **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">
  ## 聚合
</div>

聚合按指定条件对数据进行分组。

* **field** (必填): 用于分组的字段名称
* **name** (必填): 聚合字段的别名

<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 key 的哈希值                        | UNSPECIFIED, COUNT |
| `date`                     | Autocomplete 的 UTC 日期                  | UNSPECIFIED, COUNT |
| `date UTC-x`               | 带时区偏移的日期 (例如，PST 使用 `date UTC-8`)      | UNSPECIFIED, COUNT |
| `hour`                     | Autocomplete 的 UTC 小时                  | UNSPECIFIED, COUNT |
| `language`                 | 编程语言                                   | UNSPECIFIED, COUNT |
| `ide`                      | 正在使用的 IDE                              | UNSPECIFIED, COUNT |
| `version`                  | 扩展/插件 (language-server) 版本，例如 `1.48.x` | 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">
  ### 聊天数据
</div>

<Info>聊天数据与 Cascade 数据分开统计，对应我们旧版非 Agent 插件的用量</Info>

所有聊天数据反映的都是聊天模型的响应，而非用户提出的问题。

| 字段名称                      | 说明                                     | 支持的聚合方式            |
| ------------------------- | -------------------------------------- | ------------------ |
| `api_key`                 | 用户 API key 的哈希值                        | UNSPECIFIED, COUNT |
| `model_id`                | 聊天模型 ID                                | UNSPECIFIED, COUNT |
| `date`                    | 聊天响应的 UTC 日期                           | UNSPECIFIED, COUNT |
| `date UTC-x`              | 带时区偏移的日期                               | UNSPECIFIED, COUNT |
| `ide`                     | 正在使用的 IDE                              | UNSPECIFIED, COUNT |
| `version`                 | 扩展/插件 (language-server) 版本，例如 `1.48.x` | UNSPECIFIED, COUNT |
| `latest_intent_type`      | 聊天意图类型 (见下方“意图类型”)                     | UNSPECIFIED, COUNT |
| `num_chats_received`      | 收到的聊天消息数量                              | SUM, MAX, MIN, AVG |
| `chat_accepted`           | 聊天是否被接受 (点赞)                           | SUM, COUNT         |
| `chat_inserted_at_cursor` | 是否点击了“Insert”按钮                        | SUM, COUNT         |
| `chat_applied`            | 是否点击了“Apply Diff”按钮                    | SUM, COUNT         |
| `chat_loc_used`           | 从聊天中使用的代码行数                            | SUM, MAX, MIN, AVG |

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

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

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

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

| Field Name        | Description                            | Valid Aggregations |
| ----------------- | -------------------------------------- | ------------------ |
| `api_key`         | 用户 API key 的哈希值                        | UNSPECIFIED, COUNT |
| `date`            | 命令的 UTC 日期                             | UNSPECIFIED, COUNT |
| `timestamp`       | 命令的 UTC 时间戳                            | UNSPECIFIED, COUNT |
| `language`        | 编程语言                                   | UNSPECIFIED, COUNT |
| `ide`             | 当前使用的 IDE                              | UNSPECIFIED, COUNT |
| `version`         | 扩展/插件 (language-server) 版本，例如 `1.48.x` | UNSPECIFIED, COUNT |
| `command_source`  | Command 的触发来源 (请参见下方的 Command 来源)      | 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`  | 扩展/插件 (language-server) 版本，例如 `1.48.x` | 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">
  ### 聊天数据示例
</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">
  #### 聊天数据响应
</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 (代码编写百分比) 在单日或单个用户层面的波动较大，建议按周汇总，以获得更有意义的洞察
* 所有选取字段必须要么都使用聚合函数，要么都不使用 (不能混用)
* 名称匹配 "distinct\_\*" 模式的字段不能用于聚合
* 在所有选取字段和聚合中，字段别名都必须唯一
* 如果未指定聚合函数，则默认为 UNSPECIFIED