OData v4 · Power BI · Excel

Selo de estado: Preview — funciona e é documentado, sem SLA. A conexão real fim-a-fim com Power BI/Excel (folding/refresh incremental) é validada continuamente; use com acompanhamento do suporte. Atualizado em 2026-09-06.

O ingestia.io expõe os marts publicados do seu datalake (datasets *_gold e *_silver) como um feed OData v4 — o formato que Power BI e Excel consomem nativamente, sem conector custom.

Esta página é o kit oficial Power BI/Excel — com as receitas prontas de conexão, query folding e refresh incremental.

Disponibilidade#

• Estado operacional: Preview — sem SLA.
• Clientes: Power BI (Desktop e Serviço), Excel (Windows e Mac 365), e qualquer cliente OData v4.
• Região: Brasil (São Paulo).

Permissões#

• Autenticação por chave de API (ver Autenticação); só o dono do workspace cria/revoga.
• Exige a ação de exportação de dados (chave de dados do dono passa).
• A chave enxerga todos os marts publicados do workspace; colunas PII nunca saem pela API (nem no $metadata).

Configuração (Power BI — caminho recomendado)#

Página Inicial → Obter Dados → Consulta em Branco → Editor Avançado:

let
    Chave = "SUA_CHAVE",
    Fonte = OData.Feed("https://ingestia.io/api/v1/odata", null, [
        Headers = [ #"Authorization" = "Bearer " & Chave ],
        Implementation = "2.0"
    ]),
    Tabela = Fonte{[Name = "sua_tabela"]}[Data]
in
    Tabela

Implementation = "2.0" é obrigatório: fala OData v4 e dobra (query folding) filtros/projeções para o servidor. Caminho simples (Excel/PBI): Obter Dados → Feed OData com …/api/v1/odata?api_key=SUA_CHAVE e autenticação Anônima — lembrando que a chave na URL vira segredo.

Query folding — o que roda no servidor (pushdown)

Filtro que o feed não sabe traduzir devolve HTTP 501 com a lista do que é suportado — nunca ignoramos um filtro em silêncio (resultado errado é pior que erro). Simplifique o filtro ou aplique-o localmente depois.

Refresh incremental (resumo)

Crie os parâmetros RangeStart/RangeEnd (tipo Data/Hora), filtre a tabela por each [data] >= RangeStart and [data] < RangeEnd, e configure a política. O filtro por data dobra para o servidor e só a janela é lida (menos bytes = menos custo). Receita completa no kit Power BI/Excel.

Validação (como confirmar que funcionou)#

• GET /api/v1/odata responde 200 com value: [{ name, kind, url }].
• GET /api/v1/odata/$metadata responde XML EDMX com os tipos das colunas.
• No Power BI, a etapa de fonte carrega e o "Editor" mostra as etapas dobradas (clique direito → Exibir consulta nativa, quando disponível).

Exemplo#

# Service document
curl -H "Authorization: Bearer ing_live_..." https://ingestia.io/api/v1/odata

# Página de uma tabela, com projeção, filtro, contagem e ordenação
curl -H "Authorization: Bearer ing_live_..." \
  "https://ingestia.io/api/v1/odata/silver_vendas?\$select=data,total&\$filter=data ge 2026-01-01&\$orderby=data&\$count=true"

Resposta paginada:

{
  "@odata.context": "https://ingestia.io/api/v1/odata/$metadata#silver_vendas",
  "@odata.count": 12345,
  "value": [ /*... */ ],
  "@odata.nextLink": "https://ingestia.io/api/v1/odata/silver_vendas?...$skiptoken=..."
}

Paginação (server-driven)#

• Páginas de até 1.000 linhas com @odata.nextLink — Power BI/Excel seguem o link automaticamente até o fim.
• Prefer: odata.maxpagesize=N reduz a página (teto 1.000); responde Preference-Applied.
• Sempre siga o @odata.nextLink exatamente como recebido (ele carrega o $skiptoken opaco). Um $skiptoken adulterado responde 400.
• Profundidade máxima: 1.000.000 de linhas por consulta; acima disso, 400 orientando a filtrar (cada página varre a tabela inteira no datalake).

Custo#

• Cobra pelos bytes realmente processados; x-ingestia-cost-brl mostra o valor (uma projeção hoje). Cada chamada fica na auditoria (api.odata.read, com bytes, página e chave) — separável do BI nativo.
• $count=true roda um COUNT(*) adicional, também contado.
• Dica: aponte o refresh incremental para uma coluna de partição — o o datalake poda partições e o byte lido cai de verdade.

Segurança#

• Somente leitura, escopado ao workspace (marts publicados apenas).
• Colunas PII não aparecem no feed nem no $metadata.
• Se a nuvem própria do cliente cair, o feed responde 503 — nunca uma coleção vazia (que faria o Excel ler "a tabela esvaziou").

Limites#

• Subset OData: sem $expand, $apply, $search, $compute, lambdas (any/all) e aritmética em filtro; texto só contains/startswith/endswith. Fora do subset = 501 explícito. $format: apenas JSON.
• Colunas STRUCT/RECORD não são publicadas; publique colunas planas.
• Chave de nível workspace (sem recorte por membro).
• Quota: 120 req/min por chave (240/min por workspace), separada do resto da plataforma — o consumo via Power BI não degrada o BI nativo. Estouro → 429 com Retry-After.
• Sem datalake provisionado (demo), o feed serve dados claramente simulados e $filter/$orderby/$count respondem 503 — nunca finge que filtrou.

Troubleshooting#

Próximos passos: Autenticação · Erros e limites · Troubleshooting.

Estado & evidência: OData v4 + kit Power BI/Excel = Preview; conexão real Power BI/Excel sob validação humana contínua. Fonte: matriz de estados do produto.