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

# Query di Custom Analytics

> Query di analisi flessibile con selezioni, filtri e aggregazioni personalizzate per i dati di autocomplete, chat, comando e PCW.

<div id="overview">
  ## Panoramica
</div>

L'API Custom Analytics offre funzionalità di interrogazione flessibili per i dati di completamento automatico, chat e comandi, con selezioni, filtri, aggregazioni e ordinamenti personalizzabili.

<div id="request">
  ## Richiesta
</div>

<ParamField body="service_key" type="string" required>
  La tua chiave di servizio con l'autorizzazione "Analytics Read"
</ParamField>

<ParamField body="group_name" type="string">
  Filtra i risultati agli utenti di un gruppo specifico (facoltativo)
</ParamField>

<ParamField body="query_requests" type="array" required>
  Array di oggetti di richiesta di query che definiscono i dati da recuperare

  <Expandable title="Oggetto richiesta di query">
    <ParamField body="data_source" type="string" required>
      Origine dati da interrogare. Opzioni:

      * `QUERY_DATA_SOURCE_USER_DATA` - Dati di completamento automatico
      * `QUERY_DATA_SOURCE_CHAT_DATA` - Dati della chat
      * `QUERY_DATA_SOURCE_COMMAND_DATA` - Dati dei comandi
      * `QUERY_DATA_SOURCE_PCW_DATA` - Dati della percentuale di codice scritto
    </ParamField>

    <ParamField body="selections" type="array" required>
      Array di selezioni di campi da recuperare

      <Expandable title="Oggetto selezione">
        <ParamField body="field" type="string" required>
          Nome del campo da selezionare (vedi la sezione Campi disponibili)
        </ParamField>

        <ParamField body="name" type="string">
          Alias del campo. Se non specificato, il valore predefinito è `{aggregation_function}_{field_name}` (in minuscolo)
        </ParamField>

        <ParamField body="aggregation_function" type="string">
          Funzione di aggregazione da applicare:

          * `QUERY_AGGREGATION_UNSPECIFIED` (predefinita)
          * `QUERY_AGGREGATION_COUNT`
          * `QUERY_AGGREGATION_SUM`
          * `QUERY_AGGREGATION_AVG`
          * `QUERY_AGGREGATION_MAX`
          * `QUERY_AGGREGATION_MIN`
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField body="filters" type="array">
      Array di filtri da applicare

      <Expandable title="Oggetto filtro">
        <ParamField body="name" type="string" required>
          Nome del campo su cui filtrare
        </ParamField>

        <ParamField body="filter" type="string" required>
          Operazione di filtro:

          * `QUERY_FILTER_EQUAL`
          * `QUERY_FILTER_NOT_EQUAL`
          * `QUERY_FILTER_GREATER_THAN`
          * `QUERY_FILTER_LESS_THAN`
          * `QUERY_FILTER_GE` (maggiore o uguale)
          * `QUERY_FILTER_LE` (minore o uguale)
        </ParamField>

        <ParamField body="value" type="string" required>
          Valore da confrontare
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField body="aggregations" type="array">
      Array di aggregazioni in base a cui raggruppare

      <Expandable title="Oggetto aggregazione">
        <ParamField body="field" type="string" required>
          Nome del campo in base a cui raggruppare
        </ParamField>

        <ParamField body="name" type="string" required>
          Alias del campo di aggregazione
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

<div id="query-request-structure">
  ## Struttura della richiesta di query
</div>

Ogni oggetto di richiesta di query contiene:

* **data\_source** (obbligatorio): Origine dati da interrogare
* **selections** (obbligatorio): Array di campi da recuperare
* **filters** (facoltativo): Array di filtri da applicare
* **aggregations** (facoltativo): Array di aggregazioni in base a cui raggruppare

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

Le selezioni definiscono quali campi recuperare e come aggregarli.

* **field** (obbligatorio): Nome del campo da includere
* **name** (facoltativo): Alias del campo
* **aggregation\_function** (facoltativo): Funzione di aggregazione da applicare

<div id="selection-example">
  ### Esempio di selezione
</div>

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

<div id="filters">
  ## Filtri
</div>

I filtri consentono di limitare i dati agli elementi che soddisfano criteri specifici.

* **name** (obbligatorio): Nome del campo su cui filtrare
* **filter** (obbligatorio): Operazione di filtro
* **value** (obbligatorio): Valore con cui confrontare

<div id="filter-example">
  ### Esempio di filtro
</div>

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

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

Le aggregazioni raggruppano i dati in base ai criteri specificati.

* **field** (obbligatorio): Nome del campo in base al quale raggruppare
* **name** (obbligatorio): Alias del campo di aggregazione

<div id="aggregation-example">
  ### Esempio di aggregazione
</div>

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

<div id="available-fields">
  ## Campi disponibili
</div>

<div id="user-data">
  ### Dati utente
</div>

Tutti i dati utente sono aggregati per utente e per ora.

| Nome campo                 | Descrizione                                                        | Aggregazioni valide |
| -------------------------- | ------------------------------------------------------------------ | ------------------- |
| `api_key`                  | Hash dell'API key dell'utente                                      | UNSPECIFIED, COUNT  |
| `date`                     | Data UTC di Autocomplete                                           | UNSPECIFIED, COUNT  |
| `date UTC-x`               | Data con offset del fuso orario (ad es. "date UTC-8" per PST)      | UNSPECIFIED, COUNT  |
| `hour`                     | Ora UTC di Autocomplete                                            | UNSPECIFIED, COUNT  |
| `language`                 | Linguaggio di programmazione                                       | UNSPECIFIED, COUNT  |
| `ide`                      | IDE in uso                                                         | UNSPECIFIED, COUNT  |
| `version`                  | Versione dell'estensione/plugin (language-server), ad es. `1.48.x` | UNSPECIFIED, COUNT  |
| `num_acceptances`          | Numero di Autocomplete accettati                                   | SUM, MAX, MIN, AVG  |
| `num_lines_accepted`       | Righe di codice accettate                                          | SUM, MAX, MIN, AVG  |
| `num_bytes_accepted`       | Byte accettati                                                     | SUM, MAX, MIN, AVG  |
| `distinct_users`           | Utenti distinti                                                    | UNSPECIFIED, COUNT  |
| `distinct_developer_days`  | Tuple distinte (utente, giorno)                                    | UNSPECIFIED, COUNT  |
| `distinct_developer_hours` | Tuple distinte (utente, ora)                                       | UNSPECIFIED, COUNT  |

<div id="chat-data">
  ### Dati della chat
</div>

<Info>I dati della chat sono separati dai dati di Cascade e rappresentano l'utilizzo dei nostri plugin legacy non agentici</Info>

Tutti i dati della chat rappresentano le risposte del modello di chat, non le domande degli utenti.

| Nome del campo            | Descrizione                                                        | Aggregazioni valide |
| ------------------------- | ------------------------------------------------------------------ | ------------------- |
| `api_key`                 | Hash dell'API key dell'utente                                      | UNSPECIFIED, COUNT  |
| `model_id`                | ID del modello di chat                                             | UNSPECIFIED, COUNT  |
| `date`                    | Data UTC della risposta in chat                                    | UNSPECIFIED, COUNT  |
| `date UTC-x`              | Data con offset del fuso orario                                    | UNSPECIFIED, COUNT  |
| `ide`                     | IDE in uso                                                         | UNSPECIFIED, COUNT  |
| `version`                 | Versione dell'estensione/plugin (language-server), ad es. `1.48.x` | UNSPECIFIED, COUNT  |
| `latest_intent_type`      | Tipo di intento della chat (vedi Tipi di intento sotto)            | UNSPECIFIED, COUNT  |
| `num_chats_received`      | Numero di messaggi di chat ricevuti                                | SUM, MAX, MIN, AVG  |
| `chat_accepted`           | Indica se la chat è stata accettata (pollice in su)                | SUM, COUNT          |
| `chat_inserted_at_cursor` | Indica se è stato fatto clic sul pulsante "Insert"                 | SUM, COUNT          |
| `chat_applied`            | Indica se è stato fatto clic sul pulsante "Apply Diff"             | SUM, COUNT          |
| `chat_loc_used`           | Righe di codice utilizzate dalla chat                              | SUM, MAX, MIN, AVG  |

<div id="chat-intent-types">
  #### Tipi di intent della chat
</div>

* `CHAT_INTENT_GENERIC` - Chat standard
* `CHAT_INTENT_FUNCTION_EXPLAIN` - Code lens per la spiegazione della funzione
* `CHAT_INTENT_FUNCTION_DOCSTRING` - Code lens per la docstring della funzione
* `CHAT_INTENT_FUNCTION_REFACTOR` - Code lens per il refactor della funzione
* `CHAT_INTENT_CODE_BLOCK_EXPLAIN` - Code lens per la spiegazione del blocco di codice
* `CHAT_INTENT_CODE_BLOCK_REFACTOR` - Code lens per il refactor del blocco di codice
* `CHAT_INTENT_PROBLEM_EXPLAIN` - Code lens per la spiegazione del problema
* `CHAT_INTENT_FUNCTION_UNIT_TESTS` - Code lens per i test unitari della funzione

<div id="command-data">
  ### Dati del comando
</div>

I dati del comando includono tutti i comandi, compresi quelli rifiutati. Usa il campo `accepted` per filtrare solo i comandi accettati.

| Nome campo        | Descrizione                                                         | Aggregazioni valide |
| ----------------- | ------------------------------------------------------------------- | ------------------- |
| `api_key`         | Hash della chiave API dell'utente                                   | UNSPECIFIED, COUNT  |
| `date`            | Data UTC del comando                                                | UNSPECIFIED, COUNT  |
| `timestamp`       | Timestamp UTC del comando                                           | UNSPECIFIED, COUNT  |
| `language`        | Linguaggio di programmazione                                        | UNSPECIFIED, COUNT  |
| `ide`             | IDE in uso                                                          | UNSPECIFIED, COUNT  |
| `version`         | Versione dell'estensione/plugin (language-server), ad es. `1.48.x`  | UNSPECIFIED, COUNT  |
| `command_source`  | Origine dell'attivazione del comando (vedi fonte dei comandi sotto) | UNSPECIFIED, COUNT  |
| `provider_source` | Modalità di generazione o modifica                                  | UNSPECIFIED, COUNT  |
| `lines_added`     | Righe di codice aggiunte                                            | SUM, MAX, MIN, AVG  |
| `lines_removed`   | Righe di codice rimosse                                             | SUM, MAX, MIN, AVG  |
| `bytes_added`     | Byte aggiunti                                                       | SUM, MAX, MIN, AVG  |
| `bytes_removed`   | Byte rimossi                                                        | SUM, MAX, MIN, AVG  |
| `selection_lines` | Righe selezionate (zero per le generazioni)                         | SUM, MAX, MIN, AVG  |
| `selection_bytes` | Byte selezionati (zero per le generazioni)                          | SUM, MAX, MIN, AVG  |
| `accepted`        | Indica se il comando è stato accettato                              | SUM, COUNT          |

<div id="command-sources">
  #### Fonti dei comandi
</div>

* `COMMAND_REQUEST_SOURCE_LINE_HINT_CODE_LENS`
* `COMMAND_REQUEST_SOURCE_DEFAULT` - Uso tipico del comando
* `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">
  #### Sorgenti del provider
</div>

* `PROVIDER_SOURCE_COMMAND_GENERATE` - Modalità di generazione
* `PROVIDER_SOURCE_COMMAND_EDIT` - Modalità di modifica

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

Dati relativi alla Percentuale di Codice Scritto, con monitoraggio separato dei contributi di completamento automatico e dei comandi.

| Nome campo                      | Descrizione                                                    | Aggregazioni valide |
| ------------------------------- | -------------------------------------------------------------- | ------------------- |
| `percent_code_written`          | Calcolato come codeium\_bytes / (codeium\_bytes + user\_bytes) | UNSPECIFIED         |
| `codeium_bytes`                 | Byte totali generati da Codeium                                | UNSPECIFIED         |
| `user_bytes`                    | Byte totali scritti dall'utente                                | UNSPECIFIED         |
| `total_bytes`                   | codeium\_bytes + user\_bytes                                   | UNSPECIFIED         |
| `codeium_bytes_by_autocomplete` | Byte di Codeium generati dal completamento automatico          | UNSPECIFIED         |
| `codeium_bytes_by_command`      | Byte di Codeium generati dai comandi                           | UNSPECIFIED         |

<div id="pcw-filters">
  #### Filtri PCW
</div>

| Nome del campo | Descrizione                                                            | Esempi            |
| -------------- | ---------------------------------------------------------------------- | ----------------- |
| `language`     | Linguaggio di programmazione                                           | KOTLIN, GO, JAVA  |
| `ide`          | IDE utilizzato                                                         | jetbrains, vscode |
| `version`      | Versione dell'estensione/del plugin (language-server), ad es. `1.48.x` | 1.28.0, 130.0     |

Per filtrare per data nelle query PCW, usa `start_timestamp` e `end_timestamp` nel corpo principale della richiesta.

<div id="example-requests">
  ## Esempi di richieste
</div>

<div id="user-data-example">
  ### Esempio di dati utente
</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">
  ### Esempio di dati della 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">
  ### Esempio di dati del comando
</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">
  ### Esempio di dati 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">
  ## Risposta
</div>

<ResponseField name="queryResults" type="array">
  Array dei risultati delle query, uno per ogni richiesta di query

  <ResponseField name="responseItems" type="array">
    Array di elementi di risultato

    <ResponseField name="item" type="object">
      Oggetto contenente i campi selezionati e i relativi valori
    </ResponseField>
  </ResponseField>
</ResponseField>

<div id="example-responses">
  ### Esempi di risposta
</div>

<div id="user-data-response">
  #### Risposta con i dati dell'utente
</div>

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

<div id="chat-data-response">
  #### Risposta con i dati della 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">
  #### Risposta con i dati del comando
</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">
  #### Risposta dati 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">
  ## Note importanti
</div>

* Il PCW (Percentuale di Codice Scritto) presenta un'elevata variabilità su singole giornate o singoli utenti: aggrega i dati su base settimanale per ottenere migliori approfondimenti
* Tutti i campi di selezione devono avere funzioni di aggregazione, oppure nessuno deve averle (non è possibile mescolarli)
* I campi con pattern "distinct\_\*" non possono essere usati nelle aggregazioni
* Gli alias dei campi devono essere univoci in tutte le selezioni e aggregazioni
* Se non viene specificata alcuna funzione di aggregazione, il valore predefinito è UNSPECIFIED