Fonctions

Chaque fonction correspond à une formule sous l'espace de noms CONNXL, adressée par son module et son nom :

=CONNXL.SALES.TOP_CUSTOMERS(10)

Formes de sortie

La forme de sortie d'une fonction décide de ce à quoi ressemble le résultat une fois arrivé dans la grille — vous la choisissez dans le générateur. (Séparément, le genre d'une fonction — le type de source de données sur lequel elle s'exécute — est défini lorsque vous choisissez une connexion ; la Référence des fonctions les répertorie tous.)

• Valeur unique — une valeur dans la cellule appelante : un nombre, une chaîne, un booléen.
• Ligne — un seul enregistrement disposé sur une ligne de cellules.
• Table — lignes × colonnes qui se répandent dans une plage, avec des en-têtes par colonne et des formats de nombre mappés depuis la réponse.
• JSON — la réponse JSON brute sous forme de texte, pour quand vous voulez l'analyser vous-même.
• Entité — un type de données lié Excel : une puce dans la cellule dont les propriétés deviennent des accesseurs de champ comme =A2.Price. Async uniquement.

Modèles d'exécution

• Sync — une opération Excel locale, exécutée dans le complément sans appel à l'agent. Idéal pour les transformations légères.
• Async — par défaut. Excel affiche #GETTING_DATA pendant que l'agent récupère les données ; le complément regroupe de manière transparente de nombreux appels de cellules en une seule requête.
• Streaming — la cellule se met à jour en direct à mesure que de nouvelles valeurs arrivent. L'agent diffuse vers le complément via Server-Sent Events sur le bureau, et bascule vers l'interrogation sur Excel pour le web.

Le construire dans le tableau de bord

Le générateur de fonctions vous guide dans le choix d'une connexion, la déclaration des paramètres, l'écriture de la requête et le mappage de la réponse au genre de sortie choisi. Il n'y a pas de fichier JSON à rédiger à la main — le tableau de bord possède les métadonnées, et l'agent génère tout ce dont Excel a besoin à partir de votre configuration.

Un exemple concret

Supposons que vous ayez une connexion REST nommée Catalog API et que vous vouliez vos meilleurs produits sous forme de table répandue :

1. What it does — Fetch data. Basic info — nom TOP_PRODUCTS, module CATALOG.
2. Connection — Catalog API. Request — GET /products, paramètre de requête limit = 10.
3. Output — Table / Matrix. Chemin des lignes $.data[*] ; colonnes Name → $.name, SKU → $.sku, Price → $.price.
4. Enregistrez, puis publiez l'environnement. Dans Excel : =CATALOG.TOP_PRODUCTS() répand la table.

Une valeur unique fonctionne de la même façon avec la sortie JSON path — par ex. GET /products/{'{{'}id{'}}'} avec un paramètre id numérique et le chemin data.name renvoie le nom d'un produit. Une fonction de base de données est identique, si ce n'est que l'étape de la requête est une instruction SQL (SELECT name, total FROM orders ORDER BY total DESC) sur une connexion Postgres/MySQL/SQL Server.

Un exemple de formule sync

Pour les fonctions de calcul local (sync), l'étape « paramètres » devient un éditeur de formule : pas de connexion, pas de requête, rien que l'agent ait à appeler. Écrivez-la dans la syntaxe Excel habituelle, et le tableau de bord la compile dans l'arbre d'expression exact que l'évaluateur isolé de l'agent exécute dans la cellule, sans jamais toucher à une source de données :

=CONCAT(UPPER([name]), " — ", [id])

Chaque référence entre [crochets] devient un paramètre de la fonction, dans l'ordre de sa première apparition — rien d'autre à déclarer. L'ensemble des fonctions prises en charge est fermé et volontairement restreint, pour pouvoir être isolé en toute sécurité : texte (CONCAT/CONCATENATE, UPPER, LOWER, TRIM, LEN, LEFT, RIGHT, MID, SUBSTITUTE), calcul (MOD, ROUND, ABS, MIN, MAX, plus les opérateurs habituels + - * /), comparaisons (= < > <= >= <>) et logique (IF, AND, OR, NOT, COALESCE), et parties de date (YEAR, MONTH, DAY). & concatène, comme dans Excel.

Mapper une réponse de type table ou entité

Quand la sortie est Table ou Entité, l'étape Output inclut un échantillonneur pour que vous n'ayez pas à deviner le JSONPath à la main :

1. Fetch a sample response — exécute votre requête une fois, en direct, contre la vraie connexion, et vous montre le vrai JSON qui revient.
2. Cliquez sur les champs que vous voulez — l'échantillon est analysé en une liste plate de champs candidats ; cliquer sur l'un l'ajoute comme colonne (ou propriété d'entité) et remplit son chemin pour vous.
3. Si la réponse contient plus d'une liste de lignes plausible — un tableau imbriqué, une enveloppe — un sélecteur de ligne candidate vous laisse choisir laquelle est « la table » ; la liste de champs se met à jour pour le candidat choisi.
4. Un aperçu en direct affiche les premières lignes sous forme de vraie table, pour que vous puissiez vérifier le mappage avant d'enregistrer.

{
"data": [
  { "name": "Widget", "sku": "W-100", "price": 19.99 },
  { "name": "Gadget", "sku": "G-200", "price": 34.5 }
]
}

Récupérer un échantillon comme celui-ci détecte $.data[*] comme chemin de lignes et propose name, sku et price comme colonnes en un clic.

Réécrire des données à la source

La plupart des fonctions lisent. Certaines connexions savent aussi écrire, et la première étape du générateur propose l'opération d'écriture à côté de Fetch data quand la connexion l'accepte — le classeur devient alors un client de téléversement plutôt qu'un rapport.

• Bases de données SQL — Insérer des lignes. Vous choisissez la table cible et le paramètre qui porte les lignes, et l'agent assemble pour vous un INSERT paramétré multi-lignes. Fonctionne sur tous les moteurs à pool, Supabase compris. Pas de SQL en texte libre ici : les noms de table et de colonne doivent être des identifiants simples, et les valeurs voyagent en paramètres liés — un en-tête de classeur ne peut donc jamais devenir une instruction.
• MongoDB — insertOne, insertMany, updateMany et deleteMany sur une collection.
• DynamoDB — put_item pour un seul objet, put_items pour un tableau entier.
• Cosmos DB — upsert écrit les lignes dans un conteneur.

Les téléversements sont sûrs à réessayer. Chaque clic frappe une identité de téléversement que portent tous les blocs, et les connecteurs s'en servent pour remplacer au lieu d'ajouter : l'insert SQL estampille les lignes et échange le bloc dans une seule transaction, Cosmos en dérive ses ids de document, DynamoDB écrase par clé de table. Recliquer après un échec partiel répare donc le téléversement au lieu de le doubler. Si vous téléversez plutôt vers votre propre API, les variables de modèle ${upload.*} vous donnent cette même identité pour dédupliquer — voir la Référence des fonctions.

Tester une fonction

Gestion des versions et Promouvoir

Les fonctions ne sont modifiées que dans l'environnement source (Development). Lorsque vous êtes prêt à faire avancer une modification, Promouvoir-la vers un environnement en aval — QA, préproduction, production. Promouvoir copie la structure tout en préservant les propres valeurs de connexion de l'environnement cible, et les ressources entièrement nouvelles arrivent avec des identifiants vierges à remplir. Vous pouvez promouvoir depuis la configuration en direct d'un environnement voisin ou depuis une version nommée enregistrée, de sorte que les publications soient reproductibles.