Créer une requête personnalisée

Quand l'assistant ne convient pas — analytique, rapports, jointures multi-tables, appels de procédures stockées, tout ce qui ne se projette pas 1 pour 1 sur une seule table — écrivez la requête à la main sous l'onglet Non classées.

Cette page parcourt le formulaire d'éditeur champ par champ, en s'appuyant sur la forme vérifiée du schéma QueryDef.

---

Où le trouver

Paramètres → Connecteurs → sélectionnez un connecteur → barre de modes : Non classées → ＋ Ajouter une requête.

La page demande un nom, crée une requête custom vide et ouvre son éditeur.

---

Le formulaire d'éditeur

---

Champ par champ

name

En lecture seule dans l'éditeur. Le nom est fixé au clic sur ＋ Ajouter une requête et constitue la clé de permission de la requête — sql:<connector>:<name>. Renommez via le bouton Renommer en haut (multi-fichiers — chaque référence d'écran/menu/dictionnaire est mise à jour en une seule passe ; refuse de s'exécuter sur des modifications locales non enregistrées).

Règles de nommage :

Règle	Pourquoi
Lettres, chiffres, tirets bas.	Clé TOML, segment d'URL et chaîne de permission d'un seul coup.
Commence par une lettre ou un tiret bas.	Idem.
Évitez les suffixes _get / _put / _post / _delete.	L'onglet Tables le ramasserait et tenterait de le regrouper dans un jeu CRUD.

Conventions de nommage qui passent à l'échelle :

Motif	Exemple
<entité>_<action>	customer_balance, invoice_send
<verbe>_<nom>	get_top_clients, mark_paid
report_<sujet>	report_monthly_revenue, report_overdue_invoices

type

Liste déroulante — détermine le classement par onglet. Pour une requête isolée écrite à la main, conservez custom. Les autres valeurs déplacent la requête ailleurs sur la page :

Valeur	Onglet
custom	Non classées (cette page).
table	Tables (utile uniquement quand le nom respecte la convention <base>_<crud>).
sequence	Séquences.
lookup	Recherches.

Changer type ne réécrit pas la requête — seulement la page qui la classe. Pour les séquences et recherches, préférez la fenêtre Scaffold, qui écrit l'entrée du dictionnaire en parallèle.

writable

Bascule booléenne.

État	Autorisé
Inactif (défaut)	Instructions SELECT et CTE-seules.
Actif	INSERT / UPDATE / DELETE / CALL / MERGE / DDL — tout ce qui modifie la base.

Laissez-le inactif pour les requêtes de lecture — le garde-fou refuse sinon toute exécution non-SELECT. L'Assistant CRUD la positionne déjà pour _put / _post / _delete ; sur une requête écrite à la main, activez-la vous-même au besoin.

sql

L'éditeur SQL accepte une instruction unique (cas courant) ou une map par dialecte — voir Variantes SQL par dialecte.

Trois fonctions offertes par l'éditeur :

Fonction	Rôle
Coloration syntaxique	Mots-clés colorés ; parenthèses non appariées signalées.
Autocomplétion	Tables et colonnes provenant du pool du connecteur. Appuyez sur Ctrl+Espace pour l'invoquer.
Placeholders :name	Tout :identifier du SQL est reconnu comme paramètre lié — déclarez-le dans le bloc params ci-dessous.

Quelques règles tirées de la façon dont le moteur lie les paramètres :

• Utilisez :name pour les paramètres, jamais l'interpolation littérale de chaîne. Le moteur les lie via le pilote SQLAlchemy — '%' || :search || '%' est bien le motif LIKE attendu, pas '%' + search + '%'.
• Le suffixe réservé _ORIGINAL est utilisé par l'Enregistrer du dialogue pour le filtrage WHERE de l'UPDATE (voir Créer depuis une table de base pour la convention).
• Une seule instruction par requête. Pour des instructions chaînées, utilisez un CALL vers une procédure stockée ou découpez en plusieurs requêtes Liberty.

params

La liste des paramètres déclarés — chaque :placeholder du SQL obtient une ligne. Chaque entrée porte :

Champ	Rôle
name	Le nom du placeholder (sans les deux-points). Mis en correspondance sans tenir compte de la casse.
label	Ce que l'entrée de formulaire affiche au-dessus du champ. Retombe sur name quand vide.
default	Valeur pré-remplie. Vide signifie que l'appelant peut l'omettre (le moteur lie un NULL SQL).

Ajouter des lignes ici ne modifie pas le SQL — cela indique simplement aux écrans et à l'assistant IA comment rendre une entrée pour chaque placeholder. Sautez ce bloc quand la requête n'a pas de :placeholders ; le moteur accepte des paramètres non déclarés à l'exécution (un dialogue de colonne peut lier n'importe quel :column_name qu'il rencontre).

Pour lier des valeurs depuis d'autres écrans/sources (un clic sur une ligne, un filtre parent, une action chaînée), voir Liaison de paramètres.

label (Avancé)

Nom court affiché dans les listes déroulantes ailleurs — le concepteur d'écran, le sélecteur de cible de menu, l'éditeur d'actions. Vaut par défaut le nom de la requête.

description (Avancé)

Texte plus long. Apparaît dans la liste Tables sous le nom de base, et comme infobulle quand l'opérateur survole la requête dans le sélecteur de requête-lecture du concepteur d'écran.

---

Actions de la barre haute

Les boutons en haut de l'éditeur de requête unique :

Action	Rôle	Notes
← Retour	Renvoie à la liste Non classées (sans enregistrement).	Les modifications non enregistrées restent dans l'état modifié de la page — Enregistrer sur la barre d'outils du haut les persiste.
✎ Renommer	Renommage multi-fichiers.	Refuse sur des modifications locales non enregistrées ; met à jour chaque référence.
⎘ Dupliquer	Duplication d'une seule requête — demande un nouveau nom.	Suggestion par défaut <name>_copy. Voir Dupliquer une requête ou un connecteur.
🗑 Supprimer	Retire la requête du connecteur.	Avec une fenêtre de confirmation.

---

Enregistrement et rechargement

L'Enregistrer au niveau page, en haut de la page Connecteurs, valide le fichier connecteur et déclenche un rechargement à chaud. La nouvelle requête est appelable immédiatement à /api/sql/<connector>/<name> (avec les paramètres liés en valeurs de query-string pour GET, en corps JSON pour les POST writable).

---

Vérifier que la requête fonctionne

Le connecteur SQL ne propose pas d'onglet Test de requête dédié — la voie de test est l'une de ces trois :

Voie	Quand
L'utiliser depuis un écran.	Quand l'étape suivante est de toute façon la construction de l'écran.
Appeler l'endpoint REST directement.	Pour un test rapide — GET /api/sql/<connector>/<query>?from_date=2026-01-01&to_date=2026-01-31.
Demander à l'assistant IA.	« Montre-moi le résultat de monthly_revenue pour le mois dernier » — l'assistant exécute la requête et retourne les lignes. Nécessite les permissions ai:chat et sql:<connector>:<query>.

La voie REST est la plus rapide pour déboguer — les messages d'erreur reviennent tels quels et les paramètres passent par l'URL.

---

Quand préférer cet outil à l'assistant

Utiliser l'assistant	Utiliser l'éditeur personnalisé
La table existe en base et vous voulez les formes CRUD standard.	La requête joint plusieurs tables.
Vous voulez le câblage :NAME_ORIGINAL cohérent sur UPDATE.	La requête est un agrégat GROUP BY.
Vous voulez un _delete filtré sur la clé primaire.	La requête retourne une colonne dérivée que la table n'a pas.
	La requête est un appel de procédure stockée.
	La requête est une écriture qui n'est pas un simple UPDATE / INSERT / DELETE (un MERGE, un TRUNCATE).

---

Et ensuite

• Dupliquer une requête ou un connecteur — partir d'une requête existante plutôt que de zéro.
• Liaison de paramètres — donner aux paramètres :placeholder libellés, valeurs par défaut et sources liées.
• Variantes SQL par dialecte — livrer une requête unique avec des SQL différents sur Postgres et Oracle.