Métricas semânticas
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, 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 pergunta por métrica em vez de escrever o SQL por conta própria.
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
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 umasource(o nome de uma tabela ou view), umprimary_keyopcional efields. Um campo marcado comdimension: {is_time: true}é um campo de tempo.relationships:from,to,from_columnseto_columns.metrics: na raiz do modelo ou sob um conjunto de dados, onde se chamamdataset.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, conta a view events que o painel do exemplo define:
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
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.yamlna pasta dele e em até três pastas acima. Ele para numa pasta que contenhaducklocal-project.json, a marca de um projeto portátil. 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
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 dataO primeiro argumento é um arquivo de modelo ou uma pasta que contém model.ossie.yaml. Sem ele, a pasta atual é usada.
ducklocal metricsimprime o vocabulário do modelo em JSON:model, com seusha256eai_context.- Cada métrica, com
description,synonymsequeryable. Uma métrica consultável indica suabase, o conjunto de dados que conta; a que não é tem umproblemdizendo por quê. - Cada campo como
dataset.field, comis_time. - As relações, cada uma com sua
cardinality:many_to_onequando asto_columnssão uma chave deto,unknowncaso contrário.
metrics compileimprime o SQL de um pedido, com suas colunas, conjunto de dados base, junções e osql_sha256do SQL. Não lê dados.metrics querycompila o pedido e executa o SQL comoducklocal queryfaz. Aceita as opções--database,--formate--restricteddequerye acrescenta um objetosemanticcom o SQL compilado, o pedido e osha256do modelo, que é o que deve ser citado.--views FILE.dashcoloca os blocossourceeviewdesse 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
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
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 |
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.
