> ## 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.

# カスタム分析クエリ

> オートコンプリート、チャット、Command、PCW のデータに対して、カスタムの選択、フィルター、集計を使った柔軟な分析クエリを実行できます。

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

Custom Analytics API では、オートコンプリート、チャット、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` - オートコンプリートデータ
      * `QUERY_DATA_SOURCE_CHAT_DATA` - チャットデータ
      * `QUERY_DATA_SOURCE_COMMAND_DATA` - Command データ
      * `QUERY_DATA_SOURCE_PCW_DATA` - Percent Code Written データ
    </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">
  ## 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">
  ## 集計
</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キーのhash                                 | UNSPECIFIED, COUNT |
| `date`                     | オートコンプリートのUTC日付                                 | UNSPECIFIED, COUNT |
| `date UTC-x`               | タイムゾーンオフセット付きの日付 (例: PST の場合は "date UTC-8")     | UNSPECIFIED, COUNT |
| `hour`                     | オートコンプリートのUTC時刻                                 | UNSPECIFIED, COUNT |
| `language`                 | プログラミング言語                                       | UNSPECIFIED, COUNT |
| `ide`                      | 使用中のIDE                                         | UNSPECIFIED, COUNT |
| `version`                  | 拡張機能/プラグイン (language-server) のバージョン、例: `1.48.x` | UNSPECIFIED, COUNT |
| `num_acceptances`          | オートコンプリートの受け入れ回数                                | 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`  | 一意の (user, day) タプル数                            | UNSPECIFIED, COUNT |
| `distinct_developer_hours` | 一意の (user, hour) タプル数                           | UNSPECIFIED, COUNT |

<div id="chat-data">
  ### チャットデータ
</div>

<Info>チャットデータはCascade dataとは別で、レガシーな非エージェント型プラグインの使用量を表します</Info>

チャットデータ はすべて、ユーザーの質問ではなく、チャットモデルの応答を表します。

| フィールド名                    | 説明                                              | 有効な集計              |
| ------------------------- | ----------------------------------------------- | ------------------ |
| `api_key`                 | ユーザーのAPIキーのhash                                 | 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` - 関数の説明用コードレンズ
* `CHAT_INTENT_FUNCTION_DOCSTRING` - 関数の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` フィールドを利用してください。

| Field Name        | Description                                       | Valid Aggregations |
| ----------------- | ------------------------------------------------- | ------------------ |
| `api_key`         | ユーザーのAPIキーのhash値                                  | 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` | 選択された行数 (生成時はゼロ)                                  | SUM, MAX, MIN, AVG |
| `selection_bytes` | 選択されたバイト数 (生成時はゼロ)                                | 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>

オートコンプリートと 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` | オートコンプリートによる 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">
  クエリ結果の配列。各クエリリクエストに対応する結果が1つずつ含まれます

  <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 (Percent Code Written) は日単位やユーザー単位ではばらつきが大きいため、より有用な分析結果を得るには週単位で集計してください
* すべての選択フィールドで集計関数を指定するか、どのフィールドでも指定しないようにする必要があります (混在は不可)
* "distinct\_\*" パターンのフィールドは集計に利用できません
* フィールドエイリアスは、すべての選択項目および集計全体で一意である必要があります
* 集計関数が指定されていない場合、デフォルト値はUNSPECIFIEDになります