API de consultas guardadas

Una consulta guardada es una consulta PQL con un nombre, una descripción opcional y una visualización que indica cómo se dibuja su resultado. Pertenece a la organización, no a un proyecto. Cada una tiene un ULID asignado por el servidor, un creador y una visibilidad: public (todos los miembros) o private (su creador, los miembros y grupos de usuarios con acceso concedido, y los propietarios y administradores de la organización).

Las consultas guardadas están disponibles en los planes Pro y Enterprise, los mismos que las consultas y los dashboards. En cualquier otro plan, todos los endpoints de esta página responden 403 forbidden.

Método y ruta	Qué hace
`GET /api/v1/queries`	Lista las consultas guardadas que puedes ver, de la más recientemente modificada a la más antigua.
`POST /api/v1/queries`	Crea una consulta guardada.
`GET /api/v1/queries/{savedQueryUlid}`	Consulta una consulta guardada, con su texto y su visualización.
`PUT /api/v1/queries/{savedQueryUlid}`	Reemplaza todo el estado: texto, visualización, nombre, descripción, visibilidad y accesos.
`DELETE /api/v1/queries/{savedQueryUlid}`	Elimina la consulta guardada y sus accesos. Responde `204`.
`POST /api/v1/queries/{savedQueryUlid}/run`	Ejecuta el texto guardado con tu propio acceso a los proyectos.
`GET /api/v1/queries/{savedQueryUlid}/usage`	Lista los dashboards que dibujan la consulta, para confirmar su eliminación.

Quién ve y quién cambia una consulta guardada

Un miembro ve una consulta guardada cuando se cumple alguna de estas condiciones:

es public;
la creó;
él, o uno de sus grupos de usuarios, tiene acceso concedido a una consulta privada.

Los propietarios y administradores de la organización ven todas las consultas guardadas.

Crear una consulta requiere el permiso queries.write: los propietarios, los administradores y los miembros lo tienen, y los lectores pueden consultar las consultas guardadas, pero no crearlas. Solo el creador y los propietarios y administradores de la organización pueden modificar, eliminar o cambiar la visibilidad y los accesos de una consulta, sin importar qué otro acceso tenga el miembro. Si se elimina la cuenta del creador, la consulta permanece y solo los propietarios y administradores pueden modificarla.

Una consulta que no puedes ver responde 404 not_found en todas las llamadas, así que una consulta privada nunca confirma que existe. Una consulta que puedes ver pero no modificar responde 403 forbidden en PUT y DELETE.

El nombre

Un nombre es único en la organización, sin distinguir mayúsculas de minúsculas: Fallos de staging y fallos DE staging son el mismo nombre. La regla abarca todas las consultas guardadas de la organización, incluidas las privadas que no puedes ver, así que un 409 conflict al crear o al renombrar puede indicar que el nombre ya está en uso.

El nombre tiene de 1 a 120 caracteres, sin contar los espacios del principio y del final.

Crear y reemplazar

POST /api/v1/queries recibe:

Campo	Regla
`name`	Obligatorio, de 1 a 120 caracteres.
`description`	Opcional, hasta 2.000 caracteres.
`pql`	Obligatorio, de 1 a 4.000 caracteres de PQL.
`visualization`	Opcional. `{ "render": "table" }` por defecto. Ver más abajo.
`accessMode`	`public` (por defecto) o `private`.
`members`	Opcional. Los ULID de usuario de los miembros de la organización que pueden ver una consulta privada.
`groups`	Opcional. Los ULID de los grupos de usuarios que pueden ver una consulta privada.

members y groups admiten hasta 200 entradas cada uno, sin duplicados, y deben estar vacíos en una consulta pública. Una consulta privada puede empezar con sus primeros accesos, guardados en la misma petición.

PUT /api/v1/queries/{savedQueryUlid} recibe los mismos campos, y todos son obligatorios; envía description como null para borrarla. Si falta la lista members o groups, la petición se rechaza, de modo que nunca borra accesos por accidente. Una consulta pública recibe listas vacías, lo que elimina todos los accesos que tuviera.

El objeto visualization tiene un render y un series opcional:

render es uno de table, bar, line, donut o value.
series indica la columna del resultado que divide un gráfico en una serie por cada valor, o es null.

El texto de la consulta se valida al guardarlo, con las mismas comprobaciones de una ejecución y desde tu propia vista de la organización. Un texto que no se analiza o no valida responde 422 pql_invalid, con cada error y su span, como lo hace el endpoint de consultas. Una construcción que el motor aún no ejecuta responde 422 pql_unsupported. Una referencia a otra consulta guardada, in query("nombre"), se comprueba del mismo modo: un nombre que el autor no puede ver responde 422 pql_invalid, y un guardado que cerraría un ciclo de referencias se rechaza. En ambos casos no se guarda nada.

Quién puede ver los accesos

Una consulta devuelve sus accesos, members y groups, solo a quien puede modificarla. Los demás reciben null en ambos. Cada respuesta incluye canEdit, para que un cliente sepa si debe ofrecer cambios.

Listar

GET /api/v1/queries pagina las consultas que puedes ver, de la más recientemente modificada a la más antigua. Usa page (desde 1) y pageSize (hasta 200, 50 por defecto). q conserva las consultas cuyo nombre lo contiene, sin distinguir mayúsculas de minúsculas. Cada elemento de la lista incluye los campos de resumen: ulid, name, description, ownerUserUlid, accessMode, createdAt, updatedAt y canEdit. Consulta una sola para obtener su pql, su visualization y sus accesos.

Ejecutar

POST /api/v1/queries/{savedQueryUlid}/run recibe un offset opcional, de 0 a 10.000, en un cuerpo JSON; envía {} para ejecutar la primera página. Responde la página que el endpoint de consultas responde para el mismo texto: las mismas filas o grupos, calculados con tu propio acceso a los proyectos, y con scope.hiddenProjectCount contando los proyectos que no puedes abrir. Un texto que ya no pasa las comprobaciones, porque cambiaron los campos de la organización, responde 422 pql_invalid o 422 pql_unsupported.

Exportar

POST /api/v1/queries/{savedQueryUlid}/export responde las filas de la consulta guardada como CSV, para quien lo pide y con su propio acceso a proyectos. No recibe cuerpo. El CSV sigue las reglas de la exportación de consultas. Una consulta que quien pide no puede ver responde 404, y un texto que ya no pasa las comprobaciones responde 422.

Uso

GET /api/v1/queries/{savedQueryUlid}/usage responde los dashboards con un widget que dibuja la consulta, para ver qué dejaría una eliminación. dashboards nombra los que puedes abrir, por ULID y nombre; hiddenDashboardCount cuenta los demás, que nunca se nombran. Una consulta que no puedes ver responde 404. Al eliminar la consulta, esos widgets quedan en el estado de “consulta eliminada”.

Errores

Estado	Código	Cuándo
`403`	`forbidden`	El plan no incluye consultas, tu rol no incluye `queries.write` al crear, o puedes ver una consulta pero no modificarla.
`404`	`not_found`	No hay ninguna consulta guardada con este ULID que puedas ver.
`409`	`conflict`	Otra consulta guardada de la organización tiene este nombre, sin distinguir mayúsculas de minúsculas.
`422`	`validation_failed`	El cuerpo o un parámetro de la ruta está mal formado, o se supera un límite.
`422`	`pql_invalid`	El texto de la consulta no se analiza o no valida. `details.errors` lista cada error.
`422`	`pql_unsupported`	El texto de la consulta usa una construcción que añade una versión posterior. `details.construct` la nombra.

Auditoría

Cada cambio escribe un evento de auditoría, visible en el registro de auditoría:

saved_query.created cuando se crea una consulta, con su visibilidad.
saved_query.updated cuando cambian su nombre, descripción, texto o visualización. Indica los campos que cambiaron, nunca sus valores.
saved_query.access_changed por cada cambio de visibilidad y de acceso, con su motivo: mode_toggle, member_granted, member_cleared, group_granted o group_revoked.
saved_query.deleted cuando se elimina una consulta.

Una petición que no cambia nada no escribe ningún evento.