Resultados, límites y errores de la API#
La API de consulta protege la base de datos del cliente con límites por usuario, por credencial y por consulta, y responde a cada problema con un código estable. Esta página reúne los formatos del resultado, los límites con su configuración y los errores con su solución.
Antes de empezar#
Lea el recorrido de la API de consulta. Los límites se configuran en ecenter.api.* (véase la referencia de configuración) y casi todos son por instancia del backend.
Formatos del resultado#
El formato se elige con la cabecera Accept de GET /queries/{id}/rows:
Accept |
Respuesta |
|---|---|
Ninguno, */* o application/json |
Una página en JSON, con nextCursor para la siguiente |
text/csv |
El resultado entero en CSV |
application/vnd.openxmlformats-officedocument.spreadsheetml.sheet |
La tabla pivotada en Excel |
application/vnd.apache.arrow.stream |
El resultado entero en Arrow |
| Otro | 406 NOT_ACCEPTABLE, con los admitidos en supported |
Con varios tipos en la cabecera gana el de más calidad (q). Los ficheros llevan Content-Disposition: attachment con el identificador de la consulta.
JSON#
Una página de la forma larga, de 1000 filas por defecto y hasta 10 000 (limit=). nextCursor es opaco, solo vale para esa consulta y es nulo en la última página. truncated es siempre false: por encima de un tope, la API responde 422 en lugar de recortar.
CSV#
RFC 4180, UTF-8 sin BOM, fin de línea CRLF, una cabecera con los nombres, números sin formato con punto decimal y los nulos vacíos. Con delimiter=; usa punto y coma, que es lo que espera Excel en español. Un texto que empieza por =, +, -, @, un tabulador o un retorno lleva un apóstrofo delante, para que una hoja de cálculo no lo tome por una fórmula; los números no se tocan.
Excel#
La tabla pivotada, como la enseña el visor del cubo: las dimensiones de rows en filas, las de columns en columnas, cabeceras fusionadas, totales sombreados, paneles inmovilizados y los números con los decimales de cada métrica. La primera fila lleva el título (la consulta en una frase) y el pie dice lo que el titular no ve, contado y sin nombres, y la fecha y hora del cálculo. Es para personas: los programas tienen la forma larga.
Una comparación de periodos o una consulta compuesta no tienen tabla pivotada: su Excel es la forma larga en una hoja, con el mismo título y pie.
Arrow#
La forma larga entera en el formato de flujo IPC de Apache Arrow, para leerla sin convertir tipos:
import pyarrow.ipc
tabla = pyarrow.ipc.open_stream(open("resultado.arrows", "rb").read()).read_all()
| Tipo de la columna | Tipo de Arrow |
|---|---|
NUMBER |
float64; int64 en una columna de código con todos los valores enteros |
TEXT |
utf8 |
DATE |
date32 |
DATETIME |
timestamp[us] |
BOOLEAN |
bool |
IDS (TOTAL_OF) |
list<int64> |
Cada campo lleva en sus metadatos lo mismo que el JSON (ecenter:name, ecenter:role, ecenter:metric…). Si dos columnas se llaman igual, la segunda lleva « (2)».
Cuánto dura un resultado#
- Un resultado se conserva 30 minutos desde que termina (
expiresAt). Paginar o descargar no vuelve a la base de datos. - Se conservan como mucho 20 resultados por titular y 10 000 000 de celdas por instancia. Al pasar uno de los topes se descarta el más antiguo, que desde entonces responde
404 RESULT_NOT_FOUNDcomo uno caducado. - Una consulta solo la ve la misma credencial que la envió: otra credencial del mismo usuario, la sesión de la aplicación o un administrador reciben
404 RESULT_NOT_FOUND. Tener el identificador no da acceso. - Revocar la credencial, o inhabilitar, bloquear o borrar al titular, cancela sus consultas en curso y las olvida.
Límites#
| Límite | Por defecto | Propiedad | Respuesta |
|---|---|---|---|
| Consultas en curso a la vez por titular | 2 | ecenter.api.max-running-per-user |
429 TOO_MANY_RUNNING con Retry-After |
| Peticiones por minuto y credencial | 60 | ecenter.api.rate |
429 RATE_LIMITED con Retry-After |
| Trabajos del titular esperando en su cola | 100 | ecenter.jobs.max-queued-per-user |
429 TOO_MANY_RUNNING |
| Espera de la petición | 10 s, como mucho 30 s | ecenter.api.wait, ecenter.api.max-wait |
202 con el identificador |
| Filas estimadas a partir de las que se avisa | 100 000 | ecenter.cube.warn-rows |
409 HEAVY_QUERY hasta repetir con confirmHeavy=true |
| Filas estimadas máximas | 2 000 000 | ecenter.api.max-estimated-rows |
422 TOO_HEAVY, ni confirmándolo |
| Filas del resultado | 50 000 | ecenter.api.max-rows |
422 TOO_HEAVY |
| Celdas del resultado | 2 000 000 | ecenter.api.max-cells |
422 TOO_HEAVY |
| Combinaciones que trae el cubo | 200 000 | ecenter.cube.max-rows |
422 TOO_HEAVY |
| Celdas de la tabla pivotada del Excel | 1 000 000 | ecenter.cube.max-export-cells |
422 TOO_HEAVY al pedir el Excel; la forma larga se sigue dando |
| Tiempo en la base de datos | 5 min | ecenter.querying.timeout |
La consulta falla |
| Tamaño de página | 1000, como mucho 10 000 | ecenter.api.page-size, ecenter.api.max-page-size |
El CSV y el Arrow van enteros |
Las consultas de la API son trabajos de su propia clase, que usa como mucho 2 sesiones del pool de cada conexión (ecenter.jobs.max-concurrent.API), para que la API no deje sin sesiones a la aplicación.
Nota
La estimación de filas se pide dentro del trabajo de la consulta: responde 409 HEAVY_QUERY con estimate.rows el envío, si la estimación llega dentro de su espera, o el seguimiento (GET /queries/{id}). Para calcularla de todos modos hay que repetir el envío con confirmHeavy=true. Un programa desatendido no debería confirmar sin más: lo prudente es segmentar la consulta o avisar a una persona.
Seguridad por columnas#
- El catálogo solo trae lo que el titular puede ver. Lo que no está no existe para él.
- Una consulta que nombra algo oculto (una dimensión de un eje o de una condición, una métrica, una métrica citada por una fórmula, una agrupación de una dimensión oculta) responde
403 COLUMNS_HIDDENcon los identificadores que envió, endimensionsymetrics, y nunca con sus nombres. La auditoría lo anota como una consulta denegada. - Un identificador que no existe no es lo mismo: responde
400 INVALID_QUERYconcandidates. - Un documento de partida que usa algo oculto se calcula sin ello y lo cuenta en
hidden.
{
"type": "about:blank", "title": "Forbidden", "status": 403,
"detail": "La consulta usa 1 métrica a la que usted no tiene acceso",
"code": "COLUMNS_HIDDEN", "metrics": [1203], "dimensions": [], "segmentation": false
}
segmentation es true cuando lo oculto está en una condición de la segmentación.
Errores#
Todos los errores son un ProblemDetail con code. El texto de detail está en español y explica qué corregir.
| HTTP | code |
Cuándo | Qué hacer |
|---|---|---|---|
| 400 | INVALID_QUERY |
La consulta no cumple las reglas del cubo o no encaja con el metadata; con problems y, si un identificador no existe, candidates. También un JSON mal formado. |
Corrija lo que dice problems. Valide antes de enviar. |
| 401 | CREDENTIAL_REQUIRED |
Falta la cabecera Authorization. |
Añádala. |
| 401 | INVALID_CREDENTIAL |
La credencial no vale. | Compruebe su estado en Credenciales de servicio. |
| 403 | NOT_ALLOWED |
Falta Acceso por API y MCP o Acceso a Empowerment Center; la credencial no incluye la conexión; una lista que el titular no puede usar; el SQL sin Administración del metadata. | Revise los privilegios del titular o las conexiones de la credencial. |
| 403 | COLUMNS_HIDDEN |
La consulta usa algo que el titular no ve. | Quítelo de la consulta. |
| 403 | LICENSE_INVALID |
Sin licencia válida. | Revise la licencia. |
| 404 | CONNECTION_NOT_FOUND |
La conexión no existe o el titular no puede usarla (no se dice cuál de las dos). | Use una de GET /connections. |
| 404 | RESULT_NOT_FOUND |
El resultado caducó, se descartó, es de otra credencial o está en otra instancia. | Vuelva a enviar la consulta. Con varias instancias, revise la afinidad del balanceador. |
| 404 | NOT_FOUND |
El libro, el documento o el marcador no existe o no se puede abrir. | Use los de GET /workbooks. |
| 404 | API_DISABLED |
La API está desactivada (ecenter.api.enabled: false). |
Actívela. |
| 400 | NOT_A_CUBE |
El documento pedido no es un cubo. | Elija un documento de cubo. |
| 406 | NOT_ACCEPTABLE |
El Accept no es ninguno de los admitidos. |
Use uno de supported. |
| 409 | HEAVY_QUERY |
La base de datos estima más filas que el aviso; con estimate.rows. |
Segmente, o repita con confirmHeavy=true. |
| 409 | CONNECTION_UNAVAILABLE |
La conexión está inactiva. | Actívela en Administración › Conexiones. |
| 422 | TOO_HEAVY |
Por encima de un tope. | Segmente o quite dimensiones. |
| 422 | DOCUMENT_NOT_QUERYABLE |
El documento no se puede convertir en una consulta. | Escriba la consulta. |
| 429 | RATE_LIMITED |
Más peticiones por minuto de las permitidas. | Espere lo que diga Retry-After. |
| 429 | TOO_MANY_RUNNING |
Ya hay 2 consultas del titular en curso, o la cola está llena. | Espere a que terminen; Retry-After dice cuánto. |
| 500 | QUERY_FAILED |
Un fallo interno. El detalle está en el registro del servidor. | Avise a quien administra el sistema. |
| 502 | CLIENT_DATABASE |
La base de datos del cliente ha fallado, con un texto clasificado («la BD rechaza la sentencia (SQLSTATE 42703)», «no se llega a la BD», «la BD no responde a tiempo»). | Revise la conexión y su base de datos. |
El texto de CLIENT_DATABASE nunca lleva el mensaje del controlador JDBC, que podría nombrar al usuario de la conexión o una columna de un universo.
Métricas de supervisión#
En /actuator/metrics y en el sistema de supervisión que se configure (véase Operación):
| Métrica | Qué cuenta |
|---|---|
ecenter.api.requests |
Las peticiones, por superficie (query, mcp) y resultado |
ecenter.api.rejections |
Lo que paran los límites, lo oculto y el origen, por motivo |
ecenter.api.queries |
Las consultas terminadas y cuánto tardan |
ecenter.api.runs.active |
Las consultas en cola o calculándose |
ecenter.credentials.active, ecenter.credentials.expiring |
Las credenciales que valen y las que caducan en 30 días, por ámbito |
Las etiquetas nunca llevan el titular, el cliente ni la consulta.