Enregistrer une requête

Objectif

Enregistrer une question — « affaires ouvertes par secteur d’activité du compte, ce trimestre » — sous un nom, afin qu’un graphique, un rapport, un tableau de bord et une exportation puissent tous poser la même question en la nommant, au lieu de porter chacun leur propre copie.

Pourquoi cela existe

Les copies d’une question dérivent. Quelqu’un resserre le filtre du graphique mais pas celui du rapport ; six mois plus tard, les deux divergent de quatre pour cent et personne ne peut dire lequel a raison, car chacun paraît parfaitement correct là où il se trouve.

Une requête enregistrée a une seule définition. Corrigez-la une fois et tout ce qui la nomme est corrigé — y compris en test et en production à la prochaine importation de la solution, car une requête enregistrée voyage dans la solution comme une table ou un formulaire.

C’est une question, pas un accès à une réponse. Quiconque exécute une requête enregistrée voit exactement ce que ses propres autorisations lui permettent, exactement comme dans une liste des mêmes enregistrements. Enregistrer une requête ne prête votre accès à personne, et faire pointer une requête vers une table que quelqu’un ne peut pas lire ne lui permet pas de la lire.

Prérequis

Vous êtes connecté en tant que créateur, avec une solution et un environnement sélectionnés.
Les tables que lit la requête existent déjà dans cet environnement.

Étapes

Ouvrez votre solution et choisissez Requêtes enregistrées.
Sélectionnez Nouveau. Le concepteur de requêtes s’ouvre sur sa propre page.
Donnez-lui un nom d’affichage — le nom logique se remplit au fur et à mesure de la saisie.
Rédigez une courte description. La personne qui fera plus tard pointer un tableau de bord vers cette requête n’est souvent pas vous, et un nom dit rarement quels enregistrements la requête laisse de côté.
Construisez la requête. Simple comprend une table, ses colonnes, un filtre et un tri ; Avancé ajoute des tables associées, le regroupement avec des mesures, et les options ; JSON est le document lui-même. Les trois sont des vues d’une même requête : elles ne peuvent donc jamais diverger. Concevoir une requête détaille tout cela.

Le plus petit document utile nomme une table et rien d’autre :
```
{
  "entity": "par_deal"
}
```
La forme complète est le schéma parsware-query@1, que vous remettriez aussi à un assistant d’IA chargé d’en écrire une pour vous.
Sélectionnez Enregistrer. La plateforme vérifie trois choses : que l’artefact est bien formé, que le document est une requête valide, et qu’elle s’exécuterait réellement ici — chaque champ, jointure, regroupement et mesure étant résolu par rapport aux vraies tables de cet environnement. Un champ mal orthographié est refusé maintenant, par vous, plutôt que découvert plus tard par la personne qui ouvre le tableau de bord.
Choisissez Aperçu pour l’exécuter et voir ce qu’elle renvoie — depuis le concepteur, ou depuis la liste avec la requête sélectionnée.

Deux formes : des enregistrements ou des groupes

La présence d’un bloc aggregate dans le document fait toute la différence, et la liste indique la forme de chaque requête dans sa colonne Renvoie.

Enregistrements — une page de lignes correspondantes, ce qu’attend une grille ou une exportation :

{
  "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 }]
}

Groupes — des totaux, ce qu’attend un graphique ou une vignette d’indicateur. Celle-ci effectue aussi une jointure, ce qu’une requête sait faire et qu’une vue ne sait pas : elle lit une colonne du compte de l’affaire. Le concepteur construit tout cela — la jointure est choisie à partir d’une relation plutôt que saisie.

{
  "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
}

Une fois qu’une table est jointe sous un alias, ses colonnes se nomment alias.column partout dans le document — dans les filtres, les regroupements, les mesures et les tris.

Chaque table jointe est vérifiée pour elle-même. Si vous pouvez lire les affaires mais pas les comptes, cette requête est refusée plutôt que de vous remettre discrètement des colonnes de comptes ; si vous ne pouvez lire que certains comptes, vous voyez quand même toutes les affaires, celles dont vous ne pouvez pas voir le compte n’y étant simplement pas rattachées.

Utiliser une requête enregistrée

Tout ce qui exécute une requête peut nommer celle-ci au lieu de détenir la sienne — y compris une application ou un contrôle écrit à la main, via runtime.data.runSavedQuery("par_revenue_by_industry").

Ce qui l’exécute peut restreindre la requête — ajouter un filtre, demander une page précise, choisir un fuseau horaire pour le regroupement par date —, mais ne peut pas changer ce qu’elle lit, joint ou mesure. Un filtre ajouté se combine au vôtre au lieu de le remplacer : une requête qui exclut les commandes annulées continue donc de les exclure, quelle que soit la façon dont elle est utilisée.

Le nom ne peut pas être changé

Le nom logique est ce que stockent chaque graphique, rapport et tableau de bord : le renommer les casserait tous d’un coup, en silence. Tout le reste — le nom d’affichage, la description, le document entier, et même la table qu’elle lit — peut être modifié quand vous le souhaitez.

La déplacer entre environnements

Une requête enregistrée est un composant de solution, classé sous la table qu’elle lit. Ajoutez-la à votre solution depuis la liste Gérer les composants de cette table (elle apparaît sous Requêtes enregistrées), et elle est exportée et importée avec tout le reste. À l’importation, elle est vérifiée par rapport aux tables de l’environnement cible, de la même façon qu’ici.

Désinstaller la solution emporte ses requêtes enregistrées. Tout ce qui, ailleurs, en nomme encore une échoue alors en la nommant, ce qui est l’issue honnête — la question appartenait à la solution qui est partie.

Dépannage

« The query document is not valid JSON. » — une virgule ou un crochet manquant. La zone ne reformate pas ce que vous saisissez : ce que vous voyez est ce qui a été envoyé.
« A saved query must name the table it reads. » — ajoutez "entity": "your_table". C’est facultatif lorsqu’une requête est envoyée par un écran (l’écran connaît déjà la table) et obligatoire ici, car une requête enregistrée n’est retrouvée que par son nom.
« Unknown field … » — le nom est mal orthographié, ou il appartient à une table jointe et doit être précédé de son alias (acct.par_industry, et non par_industry).
« You did not join that table » — un champ est qualifié par un alias qu’aucun lien ne déclare. Vérifiez l’orthographe de l’alias par rapport à la liste links.
L’aperçu indique que vous ne pouvez pas lire la table. — vous ne pouvez pas enregistrer une requête que vous ne pourriez pas exécuter ; c’est délibéré, car une requête que vous ne pouvez pas exécuter est une requête que vous ne pouvez pas tester. Demandez à un administrateur l’autorisation de lecture sur les tables concernées.
Une requête groupée renvoie des nombres trop élevés. — une jointure dans le sens un-à-plusieurs répète la ligne parente une fois par correspondance, et les totaux comptent les répétitions. Suivre un champ de recherche (le cas habituel) ne peut pas produire cela ; joindre vers une table enfant, si.

Objectif​

Pourquoi cela existe​

Prérequis​

Étapes​

Deux formes : des enregistrements ou des groupes​

Utiliser une requête enregistrée​

Le nom ne peut pas être changé​

La déplacer entre environnements​

Dépannage​

Scénarios associés​