Ir para o conteúdo

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

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

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 faz. Aceita as opções --database, --format e --restricted 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çãoSignifica
--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 SQLUma 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 NNo 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:

KindPor quê
metric_unknown_nameNenhuma métrica ou campo tem esse nome. O hint indica o mais próximo
metric_fanoutO 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_grainAs métricas contam conjuntos de dados diferentes. Peça cada uma em sua própria consulta
metric_ambiguous_path, metric_no_pathO modelo não indica exatamente um jeito de juntar os conjuntos de dados
metric_window_unsupported, metric_nested_aggregate, metric_not_aggregateA métrica é uma função de janela, aninha agregações ou não é uma agregação
metric_no_dialectA métrica não tem expressão em um dialeto que o DuckLocal lê
metric_bad_grainFoi pedida uma granularidade para um campo que não é de tempo
metric_filter_refusedUm --where tem mais de uma expressão
metric_missingNenhum --metric foi informado
metric_no_datasetNenhuma 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_invalidO 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.

Publicado sob a licença Apache-2.0.