Formato do card
O JSON (spec) que define um card de dashboard: tipos, gráficos, métricas, dimensões, filtros, períodos e limites.
A spec é o documento JSON que define um card. Ela é guardada em spec no card e enviada nas rotas de criar card, preview e gerar por texto. Cada nível é estrito: um campo que não existe aqui é recusado com unknown_field, em vez de ser ignorado.
Campos da spec
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
spec_version | inteiro | sim | Sempre 1. Outro valor é recusado com invalid_spec_version. |
kind | texto | sim | query, sql, component, service ou text. |
title | texto | sim | Título do card. |
subtitle | texto | não | Subtítulo. |
viz | objeto | sim | Como desenhar (abaixo). |
query | objeto | com kind=query | A consulta (abaixo). |
sql | objeto | com kind=sql | text (até 8000 caracteres), params, column_hints, vendor_scope. No painel do seller vendor_scope.mode precisa ser guc. |
component | objeto | com kind=component | component_id de uma lista fixa do painel. |
service | objeto | com kind=service | service_id de uma lista fixa e args (por exemplo limit). |
text | objeto | com kind=text | content (até 4000 caracteres), format (markdown ou plain), align (start ou center). |
viz: o desenho
| Campo | Descrição |
|---|---|
type | kpi, line, area, bar, hbar, stacked_bar, pie, donut, table, heatmap, gauge, sparkline, funnel, treemap, map_br, scatter, combo, pivot, text, vi_insight ou native. |
snippet_id | Obrigatório. Identificador estável do card: letras minúsculas, números e hífen, de 2 a 63 caracteres, começando por letra ou número. Não mude ao renomear o título. |
number_format | style (currency_cents, percent, integer, decimal, compact, duration_days, percent_of_total) e decimals. |
legend, palette, colors, data_labels, icon, accent, thresholds, compare_display | Apresentação. legend: top, bottom, left, right, hidden. palette: brand, categorical, sequential, diverging, custom. colors e accent são hexadecimais #RRGGBB. |
Gráficos pie, donut, bar, hbar, stacked_bar, line e area exigem ao menos uma dimensão na consulta; heatmap exige duas. Sem isso a spec é recusada, porque o gráfico sairia sempre vazio.
query: a consulta
| Campo | Descrição |
|---|---|
entity | Entidade do catálogo, como orders, order_items, products, return_requests. A lista vem de Catálogo. |
period | mode (inherit, preset, fixed, relative) com preset, from/to (YYYY-MM-DD), last_n_days (1 a 1095) e field (qual campo de data usar). |
compare | mode: none, previous_period ou previous_year. |
metrics | Até 8. Cada uma tem id e um kind: catalog (ref como orders.revenue), agg (agg de count, count_distinct, sum, avg, min, max sobre um field), ratio (num e den apontando métricas anteriores, scale raw ou percent) ou constant (value). |
dimensions | Até 3. id, field e, para datas, grain (hour, day, week, month, quarter, year) e fill_gaps. |
filter | Árvore de filtros: grupos {op, nodes} (com op igual a and ou or) e comparações {field, cmp} mais value, values ou right_field. Até 3 níveis e 40 nós. cmp: eq, ne, gt, gte, lt, lte, between (2 valores), in/not_in (1 a 20 valores), contains, not_contains, starts_with, ends_with, is_null, is_not_null, last_n_days, next_n_days, overdue. |
order | Até 2 itens {by, dir}; by é o id de uma métrica ou dimensão, dir é asc ou desc. |
limit | Até 1000 linhas. |
other_bucket | Agrupa o excedente do limit numa linha "outros". |
drill_down | detail_entity e path (ids de dimensões): o que abrir ao clicar num ponto. |
post | Até 6 pós-processamentos sobre uma métrica: cumulative, moving_avg (com window), percent_of_total, rank, cada um com output_id. |
Cada métrica de catálogo ligada a status de pedido (por exemplo orders.revenue) aceita status_scope: {"mode": "store_default" | "custom", "include": ["codigo-do-status", ...]}. Se você não enviar, a plataforma preenche com a regra atual da loja ao salvar.
Exemplo completo
json
{
"spec_version": 1,
"kind": "query",
"title": "Receita por dia",
"viz": {
"type": "line",
"snippet_id": "receita-por-dia",
"number_format": { "style": "currency_cents" }
},
"query": {
"entity": "orders",
"period": { "mode": "relative", "last_n_days": 7 },
"metrics": [{ "id": "receita", "kind": "catalog", "ref": "orders.revenue" }],
"dimensions": [{ "id": "dia", "field": "orders.created_at", "grain": "day" }],
"order": [{ "by": "dia", "dir": "asc" }],
"limit": 100
}
}