La API de consulta REST (
/api/v1) está en acceso anticipado y todavía no está abierta para uso externo. El código existe y el contrato de abajo es el del comportamiento actual. SQL libre vía API dispara procesamiento facturable en el datalake. Para consumo externo ahora, usa el feed OData.
Acceso anticipado
Contrato documentado para planificación. No construyas integraciones críticas sobre SQL libre vía API mientras no se libere. Para lectura externa hoy, usa el feed OData.
Ejecuta SQL de solo lectura (SELECT/WITH … SELECT) con alcance al workspace,
sobre los marts publicados. No hay API de escritura.
Resumen#
| Método · ruta | POST /api/v1/query |
| Base | https://ingestia.io |
| Auth | Clave de API + alcance read/read_query |
| Rol (RBAC) | data.query.run (admin+); clave de datos = owner |
| Cuerpo | { "sql": string, "limit"?: number } |
| Costo | bytes reales procesados en el datalake; caché de consulta idéntica = R$ 0 |
| Estados | 200 · 400 · 401 · 403 · 429 · 402 · 502 · 503 |
Defensas aplicadas (en capas, antes de tocar el datalake)#
- Solo
SELECT— cualquierINSERT/UPDATE/DELETE/MERGE/DDL/…→403. - Sin cruzar workspaces — dataset de otro cliente u otro proyecto →
403. - Sin construcciones peligrosas —
EXTERNAL_QUERY,INFORMATION_SCHEMA,JOBS_*, etc. →403. - Solo marts publicados — únicamente
*_gold/*_silver; una referencia abronzeu otro dataset →403. - Guarda de costo — tope de bytes facturados por job.
Ejemplo#
curl -X POST https://ingestia.io/api/v1/query \
-H "Authorization: Bearer ing_live_EXEMPLO" \
-H "Content-Type: application/json" \
-d '{"sql":"SELECT data, SUM(total) AS total FROM prd_aurora_gold.vendas GROUP BY data","limit":500}'const res = await fetch("https://ingestia.io/api/v1/query", {
method: "POST",
headers: {
Authorization: "Bearer ing_live_EXEMPLO",
"Content-Type": "application/json",
},
body: JSON.stringify({
sql: "SELECT data, SUM(total) AS total FROM prd_aurora_gold.vendas GROUP BY data",
limit: 500,
}),
});
const dados = await res.json();import requests
res = requests.post(
"https://ingestia.io/api/v1/query",
headers={
"Authorization": "Bearer ing_live_EXEMPLO",
"Content-Type": "application/json",
},
json={
"sql": "SELECT data, SUM(total) AS total FROM prd_aurora_gold.vendas GROUP BY data",
"limit": 500,
},
)
dados = res.json()Respuesta 200#
{ "rows": [ { "data": "2026-09-01", "total": 1234.56 } ], "rowCount": 42 }Si el resultado se recorta por seguridad, la respuesta incluye "truncated": true y
"totalRows" — para que la suma del otro lado no salga equivocada. Encabezados:
x-ingestia-cost-brl (costo proyectado) y x-ingestia-cache (hit/miss).
Caché#
Las consultas idénticas (misma versión del workspace) se sirven desde la caché con costo
R$ 0 (x-ingestia-cache: hit). La invalidación por pipeline/DML garantiza que
nunca se sirvan datos desactualizados.
Errores#
| Código | Mensaje típico |
|---|---|
400 | cuerpo inválido / falta sql |
401 | clave ausente/inválida |
403 | Apenas consultas SELECT… · fuera del workspace · solo marts publicados · falta el alcance read_query |
429 · 402 | rate limit (60/min por clave) / pago pendiente |
502 | falla al ejecutar en el datalake |
503 | datalake no aprovisionado / limitador no disponible |
Seguridad#
- Solo lectura + alcance por workspace (solo marts publicados).
- Las columnas PII no se exponen.
- La consulta y su costo quedan registrados en la auditoría.
Relacionados#
- API de consulta (guía)
- Endpoint: filas de una tabla
- Endpoint: OData de una entidad
- Errores y límites
Última revisión: 2026-09-08.