自定义 Analytics 查询

概览

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

请求

service_key

string

必填

具有 “Teams Read-only” 权限的服务密钥

group_name

string

将结果过滤为特定群组中的用户（可选）

query_requests

array

必填

用于定义要检索数据的查询请求对象数组

查询请求结构

每个查询请求对象包含：

data_source

string

必填

要查询的数据源。可选项：

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 数据

selections

array

必填

要检索的字段 selections 数组（参见 Selections 章节）

filters

array

要应用的过滤条件数组（参见 Filters 章节）

aggregations

array

用于分组的 aggregations 数组（参见 Aggregations 章节）

Selections

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

field

string

必填

要选择的字段名（参见 Available Fields 部分）

name

string

字段的别名。若未指定，默认为 {aggregation_function}_{field_name}（小写）

aggregation_function

string

要应用的聚合函数：

QUERY_AGGREGATION_UNSPECIFIED（默认）
QUERY_AGGREGATION_COUNT
QUERY_AGGREGATION_SUM
QUERY_AGGREGATION_AVG
QUERY_AGGREGATION_MAX
QUERY_AGGREGATION_MIN

选择示例

{
  "field": "num_acceptances",
  "name": "total_acceptances",
  "aggregation_function": "QUERY_AGGREGATION_SUM"
}

过滤器

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

name

string

必填

要过滤的字段名称

value

string

必填

用于比较的值

filter

string

必填

过滤操作：

QUERY_FILTER_EQUAL
QUERY_FILTER_NOT_EQUAL
QUERY_FILTER_GREATER_THAN
QUERY_FILTER_LESS_THAN
QUERY_FILTER_GE（大于等于）
QUERY_FILTER_LE（小于等于）

筛选示例

{
  "name": "language",
  "filter": "QUERY_FILTER_EQUAL",
  "value": "PYTHON"
}

Aggregations

Aggregations 可按指定条件对数据进行分组。

field

string

必填

用于分组的字段名

name

string

必填

该聚合字段的别名

聚合示例

{
  "field": "ide",
  "name": "ide_type"
}

可用字段

用户数据

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

字段名称	描述	可用聚合
`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

Chat 数据

所有 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

Chat 意图类型

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 - 函数单元测试代码镜头

Command 数据

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

Command 来源

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

提供方来源

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

PCW 数据

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

PCW 过滤器

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

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

示例请求

用户数据示例

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": "hour",
          "filter": "QUERY_FILTER_GE",
          "value": "2024-01-01"
        },
        {
          "name": "hour",
          "filter": "QUERY_FILTER_LE",
          "value": "2024-02-01"
        }
      ]
    }
  ]
}' \
https://server.codeium.com/api/v1/Analytics

Chat 数据示例

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

Command 数据示例

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

PCW 数据示例

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

响应

queryResults

array

查询结果数组，每个查询请求对应一个查询结果

responseItems

array

结果条目数组

item

object

包含所选字段及其值的对象

示例回复

用户数据响应

{
  "queryResults": [
    {
      "responseItems": [
        {
          "item": {
            "total_acceptances": "125",
            "total_lines": "863"
          }
        }
      ]
    }
  ]
}

Chat 数据响应

{
  "queryResults": [
    {
      "responseItems": [
        {
          "item": {
            "lines_used": "74",
            "ide_type": "jetbrains"
          }
        },
        {
          "item": {
            "lines_used": "41",
            "ide_type": "vscode"
          }
        }
      ]
    }
  ]
}

Command 数据响应

{
  "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"
          }
        }
      ]
    }
  ]
}

PCW 数据响应

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

重要说明

PCW（Percent Code Written）在单日或单个用户范围内波动较大——按周聚合可获得更可靠的洞察
所有 selection 字段要么全部使用聚合函数，要么全部不使用（不可混用）
符合 “distinct_*” 模式的字段不可用于 aggregations
字段别名在所有 selections 和 aggregations 中必须唯一
如果未指定聚合函数，将默认为 UNSPECIFIED

入门

功能

Cascade（JetBrains）

账户

上下文感知

最佳实践

故障排查

安全性

自定义 Analytics 查询

概览

请求

查询请求结构

Selections

选择示例

过滤器

筛选示例

Aggregations

聚合示例

可用字段

用户数据

Chat 数据

Chat 意图类型

Command 数据

Command 来源

提供方来源

PCW 数据

PCW 过滤器

示例请求

用户数据示例

Chat 数据示例

Command 数据示例

PCW 数据示例

响应

示例回复

用户数据响应

Chat 数据响应

Command 数据响应

PCW 数据响应

重要说明

入门

功能

Cascade（JetBrains）

账户

上下文感知

最佳实践

故障排查

安全性

​概览

​请求

​查询请求结构

​Selections

​选择示例

​过滤器

​筛选示例

​Aggregations

​聚合示例

​可用字段

​用户数据

​Chat 数据

​Chat 意图类型

​Command 数据

​Command 来源

​提供方来源

​PCW 数据

​PCW 过滤器

​示例请求

​用户数据示例

​Chat 数据示例

​Command 数据示例

​PCW 数据示例

​响应

​示例回复

​用户数据响应

​Chat 数据响应

​Command 数据响应

​PCW 数据响应

​重要说明

概览

请求

查询请求结构

Selections

选择示例

过滤器

筛选示例

Aggregations

聚合示例

可用字段

用户数据

Chat 数据

Chat 意图类型

Command 数据

Command 来源

提供方来源

PCW 数据

PCW 过滤器

示例请求

用户数据示例

Chat 数据示例

Command 数据示例

PCW 数据示例

响应

示例回复

用户数据响应

Chat 数据响应

Command 数据响应

PCW 数据响应

重要说明