Saltar al contenido

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

API de consulta (REST) — `/api/v1/query` y `/api/v1/tables`

En esta página (12)

La API de consulta REST está en acceso anticipado y todavía no está abierta para uso externo. Ejecuta procesamiento facturable en el datalake; la apertura llega junto con las protecciones finales de límite de solicitudes y de costo.

No construyas integraciones críticas sobre estas rutas todavía. Para el consumo externo de datos hoy, usa el feed OData (Power BI/Excel), que está disponible.

Esta página documenta el contrato de la API REST por transparencia y planificación. El comportamiento descrito es el del código actual; el contrato puede cambiar con aviso mientras la API esté en acceso anticipado.

Disponibilidad#

  • Estado: acceso anticipado. Motivo: son rutas que disparan consultas pagadas en el datalake y la protección de rate limit necesita operar en modo fail-closed comprobado (denegar cuando el limitador no esté disponible) antes de liberarse.
  • Alternativa disponible: OData v4 / Power BI / Excel (disponible) cubre la lectura de tablas de los marts publicados.
  • Región: Brasil (São Paulo).

Permisos#

  • Autenticación por clave de API (consulta Autenticación).
  • /api/v1/tables exige la acción de exportación de datos (rol member+ / clave de datos del dueño).
  • /api/v1/query (SQL libre) exige la acción de consulta de datos (admin+); la clave también necesita el alcance read/read_query.

Endpoints (contrato)#

GET /api/v1/tables

Lista las tablas de los marts publicados (gold + silver) del workspace.

json
[
  { "dataset": "prd_aurora_gold", "table": "vendas", "layer": "gold",
    "columns": [{ "name": "data", "type": "DATE" }, { "name": "total", "type": "NUMERIC" }] }
]

GET /api/v1/tables/{dataset}/{table}?limit=&offset=

Filas paginadas de una tabla publicada. dataset debe ser un mart del workspace (<prefixo>_gold o <prefixo>_silver) — cualquier otro responde 403.

  • limit: predeterminado 100, máximo 1000.
  • offset: desplazamiento inicial.
json
{ "table": "vendas", "rows": [ /*... */ ], "rowCount": 100, "nextOffset": 100 }

nextOffset es null cuando no hay más páginas.

POST /api/v1/query

SQL de solo lectura (SELECT/WITH … SELECT) con alcance en el workspace.

json
// cuerpo
{ "sql": "SELECT data, SUM(total) AS total FROM prd_aurora_gold.vendas GROUP BY data", "limit": 500 }
json
// respuesta
{ "rows": [ /*... */ ], "rowCount": 42 }

Si el resultado se corta por seguridad, la respuesta incluye "truncated": true y "totalRows" — para que la suma del otro lado no salga mal.

Defensas aplicadas antes de tocar el datalake (en capas):

  1. Solo SELECT — cualquier INSERT/UPDATE/DELETE/DDL/… → 403.
  2. Sin cruzar workspaces — una referencia a un dataset de otro cliente o a otro proyecto → 403.
  3. Sin construcciones peligrosas — EXTERNAL_QUERY, metadatos del proyecto (INFORMATION_SCHEMA/JOBS_*), etc. → 403.
  4. Solo marts publicados — solo *_gold/*_silver; una referencia a bronze o a cualquier otro dataset → 403.
  5. Protección de costo — tope de bytes facturados aplicado al job.

Validación (cuando se libere)#

  • GET /api/v1/tables responde 200 con la lista de tablas.
  • Una consulta a un dataset fuera del workspace responde 403 con un mensaje explícito.
  • Mientras esté en acceso anticipado, las integraciones deben tratar las respuestas de indisponibilidad (503) como un estado esperado.

Ejemplo#

bash
# Listar tabelas
curl -H "Authorization: Bearer ing_live_..." https://ingestia.io/api/v1/tables

# Puxar 100 linhas
curl -H "Authorization: Bearer ing_live_..." \
  "https://ingestia.io/api/v1/tables/prd_aurora_gold/vendas?limit=100&offset=0"

# SQL livre (read-only)
curl -X POST -H "Authorization: Bearer ing_live_..." -H "Content-Type: application/json" \
  -d '{"sql":"SELECT * FROM prd_aurora_gold.vendas LIMIT 10"}' \
  https://ingestia.io/api/v1/query

Costo#

  • Cobra por los bytes realmente procesados en el datalake — LIMIT/OFFSET no reducen los bytes leídos. Paginar una tabla grande es la forma más cara de extraer; prefiere un SELECT con filtro/agregación.
  • Las consultas idénticas (misma versión del workspace) se sirven desde la caché con costo R$ 0.
  • El valor en x-ingestia-cost-brl es una proyección, no un precio facturado garantizado hoy.

Seguridad#

  • Solo lectura + alcance por workspace (solo marts publicados).
  • Las columnas PII no se exponen por esta API.
  • Las consultas y cobros quedan registrados en la auditoría del workspace.

Límites#

  • limit máximo por página: 1000.
  • Clave a nivel de workspace (sin recorte por miembro).
  • Rate limit por clave y por workspace (consulta Errores y límites).
  • Sin escritura — no hay endpoint de INSERT/UPDATE/DELETE.

Troubleshooting#

SíntomaCausa probableQué hacer
503 recurrentecapacidad en acceso anticipado / datalake no aprovisionadousa el feed OData; haz seguimiento con soporte
403 Apenas consultas SELECT (solo SELECT)SQL de escritura/DDLusa solo SELECT/WITH … SELECT
403 fora do workspace (fuera del workspace)referencia a un dataset de otro cliente/proyectoconsulta solo *_gold/*_silver de tu workspace
403 só marts publicados (solo marts publicados)referencia a bronze/otro datasetapunta a gold/silver
Factura de costo altapaginación de una tabla grandefiltra/agrega en el SELECT en lugar de paginar todo

Próximos pasos: OData v4 / Power BI / Excel (alternativa disponible) · Errores y límites.

Enlaces relacionados