Saltar al contenido principal

Guardar una consulta

Objetivo​

Guardar una pregunta («oportunidades abiertas por sector de la cuenta, este trimestre») con un nombre, para que un gráfico, un informe, un panel y una exportación puedan hacer la misma pregunta nombrándola, en lugar de llevar cada uno su propia copia.

Por qué existe​

Las copias de una pregunta divergen. Alguien ajusta el filtro del gráfico y no el del informe; seis meses después ambos discrepan en un cuatro por ciento y nadie sabe cuál es el correcto, porque cada uno parece perfectamente correcto donde está.

Una consulta guardada tiene una sola definición. Corríjala una vez y todo lo que la nombra queda corregido, también en Prueba y Producción la próxima vez que se importe la solución, porque una consulta guardada viaja en la solución como una tabla o un formulario.

Es una pregunta, no acceso a una respuesta. Quien ejecuta una consulta guardada ve exactamente lo que le permiten sus propios permisos, igual que en una lista de los mismos registros. Guardar una consulta no presta a nadie su acceso, y apuntar una consulta a una tabla que alguien no puede leer no le permite leerla.

Requisitos previos​

  • Ha iniciado sesión como creador, con una solución y un entorno seleccionados.
  • Las tablas que lee la consulta ya existen en ese entorno.

Pasos​

  1. Abra su solución y elija Consultas guardadas.

  2. Seleccione Nuevo. El diseñador de consultas se abre en su propia página.

  3. Asígnele un nombre para mostrar; el nombre lógico se rellena solo mientras escribe.

  4. Escriba una descripción breve. Quien apunte más adelante un panel a esta consulta a menudo no será usted, y un nombre rara vez dice qué registros deja fuera la consulta.

  5. Construya la consulta. Simple es una tabla, sus columnas, un filtro y una ordenación; Avanzada agrega tablas relacionadas, agrupación con medidas y las opciones; JSON es el propio documento. Las tres son vistas de una misma consulta, así que nunca pueden discrepar. Diseñar una consulta lo recorre todo.

    El documento útil más pequeño nombra una tabla y nada más:

    {
      "entity": "par_deal"
    }

    La forma completa es el esquema parsware-query@1, que también es lo que daría a un asistente de IA al que pidiera que le escribiera una.

  6. Seleccione Guardar. La plataforma comprueba tres cosas: que el artefacto está bien formado, que el documento es una consulta válida y que realmente se ejecutaría aquí, con cada campo, combinación, agrupación y medida resueltos contra las tablas reales de este entorno. Un campo mal escrito se rechaza ahora, ante usted, en lugar de descubrirlo más tarde quien abra el panel.

  7. Elija Vista previa para ejecutarla y ver lo que devuelve, ya sea desde el diseñador o desde la lista con la consulta seleccionada.

Dos formas: registros o grupos​

Que el documento tenga o no un bloque aggregate es toda la diferencia, y la lista indica de qué tipo es cada consulta en su columna Devuelve.

Registros: una página de filas coincidentes, que es lo que quiere una cuadrícula o una exportación:

{
  "entity": "par_deal",
  "select": ["par_name", "par_amount"],
  "filter": {
    "connector": "And",
    "conditions": [
      { "field": "par_status", "operator": "Equals", "value": "Open" }
    ]
  },
  "order": [{ "field": "par_amount", "descending": true }]
}

Grupos: totales, que es lo que quiere un gráfico o un mosaico de KPI. Esta además combina, que es lo que una consulta puede hacer y una vista no: lee una columna de la cuenta de la oportunidad. El diseñador construye todo esto; la combinación se elige a partir de una relación en lugar de escribirse.

{
  "entity": "par_deal",
  "links": [
    {
      "alias": "acct",
      "entity": "par_account",
      "from": "par_accountid",
      "to": "id",
      "kind": "outer"
    }
  ],
  "aggregate": {
    "groupBy": [{ "field": "acct.par_industry" }],
    "measures": [{ "alias": "revenue", "function": "Sum", "field": "par_amount" }]
  },
  "order": [{ "field": "revenue", "descending": true }],
  "top": 10
}

Una vez que una tabla se combina con un alias, sus columnas se llaman alias.column en todo el documento: en filtros, agrupaciones, medidas y ordenaciones por igual.

Cada tabla combinada se comprueba por separado. Si puede leer oportunidades pero no cuentas, esta consulta se rechaza en lugar de entregarle discretamente columnas de cuentas; si solo puede leer algunas cuentas, sigue viendo todas las oportunidades, simplemente sin adjuntar las que no puede ver.

Usar una consulta guardada​

Todo lo que ejecuta una consulta puede nombrar esta en lugar de tener la suya propia, y también puede hacerlo una aplicación o un control escritos a mano, mediante runtime.data.runSavedQuery("par_revenue_by_industry").

Lo que la ejecuta puede acotar la consulta (agregar un filtro, pedir una página concreta, elegir una zona horaria para agrupar fechas), pero no puede cambiar lo que la consulta lee, combina o mide. Un filtro agregado se combina con el suyo en lugar de reemplazarlo, de modo que una consulta que excluye los pedidos cancelados los sigue excluyendo se use como se use.

El nombre no se puede cambiar​

El nombre lógico es lo que almacenan todos los gráficos, informes y paneles, así que cambiarlo los rompería todos a la vez y sin avisar. Todo lo demás (el nombre para mostrar, la descripción, el documento entero, incluso la tabla que lee) puede cambiarlo cuando quiera.

Moverla entre entornos​

Una consulta guardada es un componente de solución, archivado bajo la tabla que lee. Agréguela a su solución desde la lista Administrar componentes de esa tabla (aparece en Consultas guardadas), y se exporta e importa con todo lo demás. Al importarla, se comprueba contra las tablas del entorno de destino igual que se comprobó aquí.

Desinstalar la solución se lleva sus consultas guardadas. Cualquier cosa de otro sitio que siga nombrando una falla entonces por nombre, que es el resultado honesto: la pregunta pertenecía a la solución que se fue.

Solución de problemas​

  • «The query document is not valid JSON.» — falta una coma o un corchete. El cuadro no reformatea lo que escribe, así que lo que ve es lo que se envió.
  • «A saved query must name the table it reads.» — agregue "entity": "your_table". Es opcional cuando una pantalla envía la consulta (la pantalla ya conoce la tabla) y obligatorio aquí, porque una consulta guardada se encuentra solo por su nombre.
  • «Unknown field …» — el nombre está mal escrito, o pertenece a una tabla combinada y necesita su alias delante (acct.par_industry, no par_industry).
  • «You did not join that table» — un campo está calificado con un alias que ningún vínculo declara. Compruebe la ortografía del alias contra la lista links.
  • La vista previa indica que no puede leer la tabla. — no puede guardar una consulta que no podría ejecutar; es deliberado, porque una consulta que no puede ejecutar es una consulta que no puede probar. Pida a un administrador permiso de lectura sobre las tablas implicadas.
  • Una consulta agrupada devuelve cifras demasiado grandes. — una combinación en el sentido de uno a varios repite la fila principal una vez por coincidencia, y los totales cuentan las repeticiones. Seguir una búsqueda (el caso habitual) no puede provocarlo; combinar hacia una tabla hija sí.

Escenarios relacionados​