Saltar al contenido

Traducción automática — la versión en portugués es la referencia. Ver en portugués

Actualizado el 2026-09-08

Endpoint: POST /api/v1/query

Referencia del endpoint de SQL libre de solo lectura (SELECT) con alcance al workspace, con defensas en capas y guarda de costo.

En esta página (8)

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 · rutaPOST /api/v1/query
Basehttps://ingestia.io
AuthClave de API + alcance read/read_query
Rol (RBAC)data.query.run (admin+); clave de datos = owner
Cuerpo{ "sql": string, "limit"?: number }
Costobytes reales procesados en el datalake; caché de consulta idéntica = R$ 0
Estados200 · 400 · 401 · 403 · 429 · 402 · 502 · 503

Defensas aplicadas (en capas, antes de tocar el datalake)#

  1. Solo SELECT — cualquier INSERT/UPDATE/DELETE/MERGE/DDL/… → 403.
  2. Sin cruzar workspaces — dataset de otro cliente u otro proyecto → 403.
  3. Sin construcciones peligrosas — EXTERNAL_QUERY, INFORMATION_SCHEMA, JOBS_*, etc. → 403.
  4. Solo marts publicados — únicamente *_gold/*_silver; una referencia a bronze u otro dataset → 403.
  5. 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}'

Respuesta 200#

json
{ "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ódigoMensaje típico
400cuerpo inválido / falta sql
401clave ausente/inválida
403Apenas consultas SELECT… · fuera del workspace · solo marts publicados · falta el alcance read_query
429 · 402rate limit (60/min por clave) / pago pendiente
502falla al ejecutar en el datalake
503datalake 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#


Última revisión: 2026-09-08.

Enlaces relacionados