# Métricas semânticas

> Defina suas métricas uma vez em um modelo do Apache Ossie e execute-as pela barra lateral do DuckLocal ou pela CLI ducklocal metrics, compiladas em um único SELECT do DuckDB.

Source: https://ducklocal.app/docs/pt/metrics

Um modelo semântico define uma única vez o que um número significa: o que
conta como erro, quais chamadas são mudanças de acesso, como duas tabelas se
juntam. O DuckLocal lê o modelo de um arquivo do
[Apache Ossie](https://ossie.apache.org/), `model.ossie.yaml`, e transforma
cada pedido (estas métricas, por estes campos, sob estas condições) em um
único `SELECT` do DuckDB. O mesmo pedido sobre o mesmo modelo sempre compila
para o mesmo SQL, então todo gráfico, resposta e agente que usa `error_rate`
fala da mesma coisa.

Você pode executar uma métrica pela barra lateral da janela ou com
`ducklocal metrics` na linha de comando. Um agente com a
[skill oficial](cli.md#install-the-official-skill) pergunta por métrica em vez
de escrever o SQL por conta própria.

::: info Mais novo que a 0.4.1
As métricas semânticas estão no branch `main` do DuckLocal e chegam na próxima
versão. A 0.4.1 não as tem.
:::

## Escreva um modelo {#write-a-model}

Coloque `model.ossie.yaml` na raiz de um projeto, ao lado dos painéis ou acima
deles. O DuckLocal lê a forma plana do Ossie 0.2:

- `datasets`: cada um tem uma `source` (o nome de uma tabela ou view), um
  `primary_key` opcional e `fields`. Um campo marcado com
  `dimension: {is_time: true}` é um campo de tempo.
- `relationships`: `from`, `to`, `from_columns` e `to_columns`.
- `metrics`: na raiz do modelo ou sob um conjunto de dados, onde se chamam
  `dataset.metric`.

Cada expressão é escrita por dialeto SQL. O DuckLocal usa o primeiro entre
`DUCKDB`, `OSSIE_SQL_2026` e `ANSI_SQL` que a expressão tiver, e o próprio
parser do DuckDB a lê. Este modelo resumido, do
[exemplo do CloudTrail](example-cloudtrail.md), conta a view `events` que o
painel do exemplo define:

```yaml
version: 0.2.0.dev0
name: cloudtrail
ai_context:
  instructions: >
    event_time is UTC. A NULL error_code means the call succeeded.
datasets:
- name: events
  source: events
  fields:
  - name: event_time
    expression: {dialects: [{dialect: ANSI_SQL, expression: event_time}]}
    dimension: {is_time: true}
  - name: ip
    expression: {dialects: [{dialect: ANSI_SQL, expression: ip}]}
    dimension: {is_time: false}
    ai_context: {synonyms: [source_ip, address]}
metrics:
- name: event_count
  description: API calls.
  expression: {dialects: [{dialect: ANSI_SQL, expression: COUNT(events.event_time)}]}
- name: error_count
  description: Calls that were refused or failed.
  expression: {dialects: [{dialect: ANSI_SQL, expression: COUNT(events.error_code)}]}
- name: error_rate
  description: The share of calls that were refused or failed.
  expression: {dialects: [{dialect: ANSI_SQL, expression: "error_count * 1.0 / NULLIF(event_count, 0)"}]}
```

Uma métrica pode ser construída a partir de outras, como `error_rate`. Um
campo ou métrica sem dialeto utilizável, ou que o DuckDB não consegue
analisar, aparece com o problema, e o resto do modelo continua funcionando. Um
modelo com nome duplicado, uma relação com um conjunto de dados que não existe
ou uma `source` que não é nome de tabela é recusado por inteiro.

## Execute uma métrica pela barra lateral {#sidebar}

A aba Esquema da barra lateral tem uma seção **Métricas**, abaixo de
**Painéis**. Ela lista os modelos encontrados ao lado dos painéis que você
abriu recentemente:

- Para cada painel, o DuckLocal procura `model.ossie.yaml` na pasta dele e em
  até três pastas acima. Ele para numa pasta que contenha
  `ducklocal-project.json`, a marca de um
  [projeto portátil](agent-workflows.md). Um modelo encontrado a partir de
  vários painéis aparece uma vez só.
- Sob cada modelo há uma linha por métrica. Passe o mouse sobre o modelo para
  ver o caminho e o painel de onde vêm seus conjuntos de dados. Passe sobre uma
  métrica para ver a descrição e os sinônimos.
- Uma métrica que não pode ser consultada aparece marcada como **não
  consultável**. Passe o mouse sobre ela para ver por quê.

Clique numa métrica, ou no botão ▶ dela, e o DuckLocal a compila, coloca o SQL
no editor de consultas ativo e o executa. O botão 📈 a executa dividida por
dia, sobre o primeiro campo de tempo do conjunto de dados que ela conta.

O SQL começa com uma linha dizendo de onde vem o número, por exemplo
`-- Metric error_count, from model cloudtrail (model.ossie.yaml, sha256 …)`.
Quando os conjuntos de dados do modelo vêm dos blocos `source` e `view` de um
painel, esses blocos vão à frente da consulta como CTEs. A consulta roda então
na própria conexão da janela, com o painel aberto ou não, e você pode editá-la
como qualquer outra.

## Execute uma métrica pela linha de comando {#cli}

```bash
ducklocal metrics                       # o modelo da pasta atual
ducklocal metrics compile --metric error_count,event_count --by events.ip \
  --where "events.user_name = 'ci-deploy'"
ducklocal metrics query --metric event_count --by events.event_time:day \
  --views reports/investigation.dash --restricted --allow-read data
```

O primeiro argumento é um arquivo de modelo ou uma pasta que contém
`model.ossie.yaml`. Sem ele, a pasta atual é usada.

- `ducklocal metrics` imprime o vocabulário do modelo em JSON:
  - `model`, com seu `sha256` e `ai_context`.
  - Cada métrica, com `description`, `synonyms` e `queryable`. Uma métrica
    consultável indica sua `base`, o conjunto de dados que conta; a que não é
    tem um `problem` dizendo por quê.
  - Cada campo como `dataset.field`, com `is_time`.
  - As relações, cada uma com sua `cardinality`: `many_to_one` quando as
    `to_columns` são uma chave de `to`, `unknown` caso contrário.
- `metrics compile` imprime o SQL de um pedido, com suas colunas, conjunto de
  dados base, junções e o `sql_sha256` do SQL. Não lê dados.
- `metrics query` compila o pedido e executa o SQL como
  [`ducklocal query`](cli.md#query-options) faz. Aceita as opções `--database`,
  `--format` e [`--restricted`](agent-workflows.md) de `query` e acrescenta um
  objeto `semantic` com o SQL compilado, o pedido e o `sha256` do modelo, que é
  o que deve ser citado. `--views FILE.dash` coloca os blocos `source` e `view`
  desse painel à frente do SQL, para modelos cujos conjuntos de dados estão
  definidos ali.

Um pedido é composto de:

| Opção | Significa |
| --- | --- |
| `--metric NAME[,NAME]` | As métricas a calcular. Repetível |
| `--by REF[,REF]` | Campos pelos quais dividir, como `dataset.field`. O nome do campo sozinho basta quando só um conjunto de dados o tem. `dataset.field:GRAIN` trunca um campo de tempo para `second`, `minute`, `hour`, `day`, `week`, `month`, `quarter` ou `year`. Repetível |
| `--where SQL` | Uma condição. Uma condição sobre campos filtra linhas (`WHERE`); uma sobre nomes de métricas, como `"error_count > 5"`, filtra grupos (`HAVING`). Repetível; todas se aplicam |
| `--order-by NAME[:desc]` | Uma coluna de saída, ou o `dataset.field` de onde ela veio. O padrão são as colunas de `--by`, em ordem crescente |
| `--limit N` | No máximo N linhas |

## Como um pedido vira SQL {#compiled-sql}

O SQL compilado é um único `SELECT` sobre o conjunto de dados que as métricas
contam. Ele é ligado por `LEFT JOIN`, ao longo de relações muitos-para-um, a
cada conjunto de dados que o pedido menciona, então uma linha sem
correspondência ainda conta, sob `NULL`. As colunas de saída recebem o nome do
campo (`ip`, ou `event_time_day` com uma granularidade) ou da métrica. Quando
dois nomes colidem, são qualificados (`events.user_name`). Uma condição sobre
campo vai para `WHERE`, e uma sobre métrica para `HAVING`. Cada `--where` é uma
única expressão: uma subconsulta, uma segunda instrução ou qualquer coisa em
volta da expressão é recusada.

## Quando um pedido é recusado {#refusals}

O DuckLocal recusa um pedido que não consegue responder com exatidão, em vez
de devolver um número que pode estar errado. Uma recusa sai com código 2, e o
erro indica um `kind`:

| Kind | Por quê |
| --- | --- |
| `metric_unknown_name` | Nenhuma métrica ou campo tem esse nome. O `hint` indica o mais próximo |
| `metric_fanout` | O campo está no lado "muitos" de uma relação, e a junção contaria linhas mais de uma vez. Divida por um campo do próprio conjunto de dados da métrica |
| `metric_multi_grain` | As métricas contam conjuntos de dados diferentes. Peça cada uma em sua própria consulta |
| `metric_ambiguous_path`, `metric_no_path` | O modelo não indica exatamente um jeito de juntar os conjuntos de dados |
| `metric_window_unsupported`, `metric_nested_aggregate`, `metric_not_aggregate` | A métrica é uma função de janela, aninha agregações ou não é uma agregação |
| `metric_no_dialect` | A métrica não tem expressão em um dialeto que o DuckLocal lê |
| `metric_bad_grain` | Foi pedida uma granularidade para um campo que não é de tempo |
| `metric_filter_refused` | Um `--where` tem mais de uma expressão |
| `metric_missing` | Nenhum `--metric` foi informado |
| `metric_no_dataset` | Nenhuma métrica do pedido lê uma coluna, então não há conjunto de dados para contar. Qualifique a agregação no modelo: `COUNT(events.event_id)`, não `COUNT(*)` |
| `model_invalid` | O próprio modelo está errado, como descrito em [Escreva um modelo](#write-a-model) |

Um arquivo de modelo que não pode ser lido sai com código 1 e kind
`model_not_found`. Quando uma pergunta precisa de SQL que o modelo não
consegue expressar, escreva-o com `ducklocal query` e diga que esse número não
é uma das métricas do modelo.
