カスタム Analytics クエリ

概要

Custom Analytics API は、Autocomplete、Chat、Command のデータに対して、selections、フィルター、集計、並び順を自在に指定できる柔軟なクエリ機能を提供します。

リクエスト

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 セクションを参照）

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

集計

集計は、指定した条件でデータをグループ化します。

field

string

必須

グループ化の基準となるフィールド名

name

string

必須

集計フィールドの別名（エイリアス）

集計の例

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

利用できるフィールド

ユーザーデータ

すべてのユーザーデータは、ユーザー単位・時間単位で集計されます。

フィールド名	説明	有効な集計
`api_key`	ユーザーAPIキーのハッシュ	UNSPECIFIED, COUNT
`date`	AutocompleteのUTC日付	UNSPECIFIED, COUNT
`date UTC-x`	タイムゾーンオフセット付きの日付（例：「date UTC-8」はPST）	UNSPECIFIED, COUNT
`hour`	Autocompleteの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 の AI モデルの応答を表します。

Field Name	Description	Valid Aggregations
`api_key`	ユーザーの API キーのハッシュ	UNSPECIFIED, COUNT
`model_id`	Chat の AI モデル 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`	受信したチャットメッセージ数	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 フィールドを使用して、受け入れられたコマンドのみに絞り込んでください。

フィールド名	説明	有効な集計
`api_key`	ユーザー API キーのハッシュ	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 データ

Autocomplete と Command の寄与を個別にトラッキングした Percent Code Written のデータ。

Field Name	Description	Valid Aggregations
`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"
        }
      ],
      "集計": [
        {
          "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）は、同一日や同一ユーザー内でもばらつきが大きいため、より有用なインサイトを得るには週単位での集計を推奨します
すべての選択フィールドは、集計関数をすべてに適用するか、いずれにも適用しないかのいずれかである必要があります（混在不可）
“distinct_*” パターンのフィールドは集計には使用できません
フィールドのエイリアスは、すべての selections と集計を通じて一意でなければなりません
集計関数が指定されていない場合、既定値は UNSPECIFIED です

はじめに

機能

Cascade（JetBrains）

アカウント

コンテキスト認識

ベストプラクティス

トラブルシューティング

セキュリティ

カスタム Analytics クエリ

概要

リクエスト

クエリリクエストの構造

Selections

選択例

フィルター

フィルター例

集計

集計の例

利用できるフィールド

ユーザーデータ

Chat データ

Chat のインテントタイプ

Command データ

Command のソース

プロバイダーのソース

PCW データ

PCW フィルター

例示リクエスト

ユーザーデータの例

Chat のデータ例

Command データ例

PCW のデータ例

レスポンス

応答例

ユーザーデータの応答

Chat データのレスポンス

Command データレスポンス

PCW データレスポンス

重要な注意事項

はじめに

機能

Cascade（JetBrains）

アカウント

コンテキスト認識

ベストプラクティス

トラブルシューティング

セキュリティ

​概要

​リクエスト

​クエリリクエストの構造

​Selections

​選択例

​フィルター

​フィルター例

​集計

​集計の例

​利用できるフィールド

​ユーザーデータ

​Chat データ

​Chat のインテントタイプ

​Command データ

​Command のソース

​プロバイダーのソース

​PCW データ

​PCW フィルター

​例示リクエスト

​ユーザー データの例

​Chat のデータ例

​Command データ例

​PCW のデータ例

​レスポンス

​応答例

​ユーザーデータの応答

​Chat データのレスポンス

​Command データレスポンス

​PCW データレスポンス

​重要な注意事項

概要

リクエスト

クエリリクエストの構造

Selections

選択例

フィルター

フィルター例

集計

集計の例

利用できるフィールド

ユーザーデータ

Chat データ

Chat のインテントタイプ

Command データ

Command のソース

プロバイダーのソース

PCW データ

PCW フィルター

例示リクエスト

ユーザーデータの例

Chat のデータ例

Command データ例

PCW のデータ例

レスポンス

応答例

ユーザーデータの応答

Chat データのレスポンス

Command データレスポンス

PCW データレスポンス

重要な注意事項