Modos de dados — Import, DirectQuery e cache

Selos usados: GA-candidato · Preview · NÃO MEDIDO · Roadmap. Legenda e template (selo + 9 campos) em README.

Como no Power BI, um dashboard tem um modo de dados. No ingestia.bi há dois: Import (extrato da tabela, custo zero na visualização) e DirectQuery (consulta ao vivo com cache). O teto de custo por consulta vale em toda consulta. Exemplos usam o workspace sintético Comércio Aurora Ltda.

Import (extrato da tabela)#

Selo: GA-candidato · ligado por cliente (um de cada vez, durante a transição)

1. O que é — o painel guarda um extrato de cada tabela que ele usa (uma cópia da tabela do datalake). Os visuais são recortados desse extrato, sem consultar o datalake de novo.
2. Quando usar — painéis do dia a dia que não precisam de tempo real; é o caso mais comum e o mais barato.
3. Como funciona —
   • Atualizar agora (ou a agenda do painel) refaz os extratos: uma leitura por tabela, por mais visuais que o painel tenha. É também o que traz para o painel uma coluna nova que entrou na tabela.
   • No editor, trocar ou acrescentar um campo num visual aparece na hora: o visual é recortado do extrato que já está guardado, sem nova consulta e sem esperar a próxima atualização.
   • Visual com consulta própria (SQL escrito à mão, de antes do extrato) continua consultando na atualização; migre-o para o extrato quando puder.
4. Pré-requisitos — datalake configurado e o modelo de extratos ligado para o cliente. Sem datalake, a plataforma roda em modo demonstração.
5. Como validar — clique em Atualizar agora, mexa num campo de um visual no editor e veja o número mudar sem esperar; o rodapé do painel mostra a data da última atualização.
6. Limites e ressalvas — o extrato é uma fotografia: o que mudou na tabela depois dela só aparece na próxima atualização. Contagem de distintos não se soma entre partes (ex.: usuários únicos por dia não dão os únicos do mês) — use a medida certa para o nível que o visual mostra.
7. Dados de exemplo (sintéticos) — "Receita por UF" (SP=250, RJ=90, MG=140) recortada do extrato de vendas.
8. Evidência — recorte do extrato, plano de extração por tabela e migração antes/depois cobertos por suíte determinística.
9. Estado & maturidade — motor GA-candidato; ligado cliente a cliente enquanto os painéis migram dos visuais com consulta própria.

DirectQuery (ao vivo)#

Selo: Preview · latência/throughput NÃO MEDIDO

1. O que é — o painel consulta a base ao vivo a cada visualização, com cache para reduzir custo.
2. Quando usar — quando o dado precisa refletir o estado atual, aceitando custo por consulta (no cache-miss).
3. Como funciona — o motor de DirectQuery consulta ao vivo com cache gerenciado de 10 min; a cobrança acontece no cache-miss. Falha de um widget vira card de erro e nunca derruba o painel.
4. Pré-requisitos — datalake configurado; cache gerenciado para o cache (sem ele, o cache é no-op).
5. Como validar — configure o modo rt, abra o painel duas vezes em menos de 10 min e confirme que a 2ª leitura vem do cache (sem novo custo).
6. Limites e ressalvas — latência, throughput e comportamento do cache quente em nuvem real são NÃO MEDIDO (não há teste de carga nem medição de latência nesta documentação). Não há timeout explícito nem cancelamento de consulta no datalake — a proteção é o maxDuration da função + reaper de runs presos.
7. Dados de exemplo (sintéticos) — 1ª leitura consulta (cache-miss, cobra); 2ª leitura em 5 min (cache-hit, custo zero).
8. Evidência — consulta ao vivo com cache (cobrança só no cache-miss) e isolamento de falha por widget cobertos por suíte determinística.
9. Estado & maturidade — Preview; números de desempenho NÃO MEDIDO.

Cache de consulta#

Selo: Preview · desempenho NÃO MEDIDO

1. O que é — cache do resultado de consulta (10 min), da verificação de acesso (60s) e do catálogo, com invalidação O(1) por versão.
2. Quando usar — automático no DirectQuery e em leituras repetidas.
3. Como funciona — chave por workspace + versão + hash do SQL; invalidação por bump de versão; fallback em memória quando não há cache gerenciado.
4. Pré-requisitos — cache gerenciado para o cache compartilhado; sem ele, cai no fallback local (no-op entre instâncias).
5. Como validar — repita a mesma consulta dentro de 10 min e confirme o cache-hit; publique uma nova versão e confirme a invalidação (miss no próximo acesso).
6. Limites e ressalvas — sem o cache gerenciado, o cache não é compartilhado entre instâncias; taxa de acerto e ganho de latência em produção são NÃO MEDIDO.
7. Dados de exemplo (sintéticos) — hash sql:a1b2 servido do cache por 10 min.
8. Evidência — cache por workspace + versão + hash do SQL, com invalidação O(1) por versão e fallback em memória, coberto por suíte determinística.
9. Estado & maturidade — Preview; desempenho NÃO MEDIDO.

Refresh incremental#

Selo: GA-candidato

1. O que é — recalcular só o período recente do snapshot em vez de refazer todo o histórico.
2. Quando usar — visuais com anos de histórico onde só os dias recentes mudam.
3. Como funciona — opt-in por visual; a elegibilidade é restritiva e garante que o resultado incremental seja idêntico ao completo (mesmas linhas, mesma ordem) — na menor dúvida, faz o refresh completo. A janela recentDays é calculada no fuso do painel.
4. Pré-requisitos — consulta particionável por período e ordenada ascendentemente pela coluna de período.
5. Como validar — ative incremental num visual de série temporal e confirme que o número do refresh incremental bate com o do refresh completo.
6. Limites e ressalvas — só aplica quando as condições de identidade são satisfeitas; caso contrário faz full (por segurança do número).
7. Dados de exemplo (sintéticos) — histórico 2024–2026 fixo + recálculo dos últimos 7 dias.
8. Evidência — elegibilidade restritiva e identidade incremental==completo cobertas por suíte determinística.
9. Estado & maturidade — GA-candidato.

Guarda de custo (FinOps)#

Selo: GA-candidato · efeito de cobrança em produção NÃO MEDIDO

1. O que é — teto de bytes por consulta e cobrança por bytes com mínimo por consulta, em reais.
2. Quando usar — automático em toda consulta e dry-run.
3. Como funciona — um teto de volume lido (1 GiB por padrão) em toda consulta; maxRows hard de 50.000 (nunca ilimitado); custo mínimo por consulta/tabela (10 MB) com conversão USD→BRL; débito atômico anti-corrida nos créditos.
4. Pré-requisitos — datalake configurado para a cobrança real; rótulo de workspace na cobrança export para o rateio por cliente.
5. Como validar — rode uma consulta e confirme, na auditoria, o costBrl e o bytesBilled registrados; tente estourar 1 GiB e confirme o bloqueio.
6. Limites e ressalvas — a conciliação por cliente depende do label workspace do billing export (pendência de produção); a cobrança efetiva em nuvem é NÃO MEDIDO aqui.
7. Dados de exemplo (sintéticos) — consulta de 12 MB → cobrada pelo mínimo; costBrl registrado na auditoria.
8. Evidência — teto de volume lido por consulta, maxRows hard, custo mínimo por consulta e débito atômico de crédito cobertos por suíte determinística.
9. Estado & maturidade — GA-candidato (guardas testadas); cobrança real NÃO MEDIDO.

Estado & evidência: motores de snapshot, cache e guarda de custo cobertos por suíte determinística; DirectQuery, latência, throughput e cobrança em nuvem real são NÃO MEDIDO (sem teste de carga/integração). Sem o datalake configurado, a plataforma roda em modo demonstração declarado. Estados derivados da matriz de estados do produto (teto Preview). Nenhum recurso é GA de produto.