Feed OData v4 disponible para Power BI, Excel y cualquier cliente OData v4.
ingestia.io expone los marts publicados de tu datalake (datasets *_gold y
*_silver) como un feed OData v4 — el formato que Power BI y Excel consumen
de forma nativa, sin conector personalizado.
| URL | Qué |
|---|---|
https://ingestia.io/api/v1/odata | Service document (lista las tablas) |
https://ingestia.io/api/v1/odata/$metadata | Esquema EDMX (tipos de las columnas) |
https://ingestia.io/api/v1/odata/<tabela> | Filas de una tabla (paginadas) |
Esta página es el kit oficial Power BI/Excel — con las recetas listas de conexión, query folding y refresh incremental.
Disponibilidad#
- Estado: disponible. La disponibilidad sigue el SLA de su plan (99,5% mensual a partir de Growth).
- Clientes: Power BI (Desktop y Servicio), Excel (Windows y Mac 365), y cualquier cliente OData v4.
- Región: Brasil (São Paulo).
Permisos#
- Autenticación por clave de API (consulta Autenticación); solo el dueño del workspace crea/revoca.
- Exige la acción de exportación de datos (la clave de datos del dueño pasa).
- La clave ve todos los marts publicados del workspace; las columnas PII
nunca salen por la API (ni en el
$metadata).
Configuración (Power BI — camino recomendado)#
Inicio → Obtener datos → Consulta en blanco → Editor avanzado:
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
TabelaImplementation = "2.0" es obligatorio: habla OData v4 y pliega (query folding)
filtros/proyecciones hacia el servidor. Camino simple (Excel/PBI):
Obtener datos → Fuente OData con …/api/v1/odata?api_key=SUA_CHAVE y autenticación
Anónima — recuerda que la clave en la URL se vuelve un secreto.
Query folding — lo que corre en el servidor (pushdown)
| Operación en Power Query | Se convierte en |
|---|---|
| Elegir/quitar columnas | $select |
Filtrar con = <> > >= < <= | $filter (eq/ne/gt/ge/lt/le) |
| Combinar filtros (Y/O/NO) | and/or/not |
| Contiene / Comienza por / Termina con | contains/startswith/endswith |
| Conservar las primeras N filas | $top |
| Ordenar | $orderby |
| Recuento | $count=true |
Un filtro que el feed no sabe traducir devuelve HTTP 501 con la lista de lo
que se soporta — nunca ignoramos un filtro en silencio (un resultado incorrecto es peor
que un error). Simplifica el filtro o aplícalo localmente después.
Refresh incremental (resumen)
Crea los parámetros RangeStart/RangeEnd (tipo Fecha/Hora), filtra la tabla con
each [data] >= RangeStart and [data] < RangeEnd y configura la política. El
filtro por fecha se pliega hacia el servidor y solo se lee la ventana (menos bytes = menos
costo). Receta completa en el kit Power BI/Excel.
Validación (cómo confirmar que funcionó)#
GET /api/v1/odataresponde200convalue: [{ name, kind, url }].GET /api/v1/odata/$metadataresponde XML EDMX con los tipos de las columnas.- En Power BI, el paso de origen carga y el "Editor" muestra los pasos plegados (clic derecho → Ver consulta nativa, cuando esté disponible).
Ejemplo#
# 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"Respuesta 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=..."
}Paginación (server-driven)#
- Páginas de hasta 1.000 filas con
@odata.nextLink— Power BI/Excel siguen el enlace automáticamente hasta el final. Prefer: odata.maxpagesize=Nreduce la página (tope 1.000); respondePreference-Applied.- Siempre sigue el
@odata.nextLinkexactamente como lo recibiste (lleva el$skiptokenopaco). Un$skiptokenadulterado responde400. - Profundidad máxima: 1.000.000 de filas por consulta; por encima de eso,
400indicando filtrar (cada página recorre la tabla completa en el datalake).
Costo#
- Cobra por los bytes realmente procesados;
x-ingestia-cost-brlmuestra el valor (una proyección hoy). Cada llamada queda en la auditoría (api.odata.read, con bytes, página y clave) — separable del BI nativo. $count=trueejecuta unCOUNT(*)adicional, que también se cuenta.- Consejo: apunta el refresh incremental a una columna de partición — el datalake poda particiones y los bytes leídos bajan de verdad.
Seguridad#
- Solo lectura, con alcance en el workspace (solo marts publicados).
- Las columnas PII no aparecen en el feed ni en el
$metadata. - Si la nube propia del cliente se cae, el feed responde
503— nunca una colección vacía (que haría que Excel leyera "la tabla se vació").
Límites#
- Subconjunto OData: sin
$expand,$apply,$search,$compute, lambdas (any/all) ni aritmética en filtros; texto solocontains/startswith/endswith. Fuera del subconjunto =501explícito.$format: solo JSON. - Las columnas
STRUCT/RECORDno se publican; publica columnas planas. - Clave a nivel de workspace (sin recorte por miembro).
- Cuota: 120 req/min por clave (240/min por workspace), separada del resto de la
plataforma — el consumo vía Power BI no degrada el BI nativo. Exceso →
429conRetry-After. - Sin datalake aprovisionado (demo), el feed sirve datos claramente simulados y
$filter/$orderby/$countresponden503— nunca finge que filtró.
Troubleshooting#
| Síntoma | Causa probable | Qué hacer |
|---|---|---|
501 en un filtro | operación fuera del subconjunto | simplifica el $filter o filtra localmente |
400 $skiptoken inválido | enlace de paginación alterado | sigue el @odata.nextLink exactamente |
429 | cuota excedida | respeta el Retry-After; reduce el paralelismo |
503 en el feed | nube propia caída / datalake no aprovisionado | inténtalo de nuevo; confirma el aprovisionamiento |
| Falta una columna | es PII o STRUCT | PII no sale por la API; publica columnas planas |
| Costo alto | paginar una tabla grande sin filtro | usa refresh incremental en una columna de partición |
Próximos pasos: Autenticación · Errores y límites · Troubleshooting.