Funciones

Cada función se corresponde con una fórmula bajo el espacio de nombres CONNXL, direccionada por su módulo y su nombre:

=CONNXL.SALES.TOP_CUSTOMERS(10)

Formas de salida

La forma de salida de una función decide cómo se ve el resultado una vez que aterriza en la cuadrícula — la eliges en el constructor. (Por separado, el tipo de una función — la clase de fuente de datos contra la que se ejecuta — se define cuando eliges una conexión; la Referencia de funciones los enumera todos.)

• Único valor — un valor en la celda que llama: un número, una cadena, un booleano.
• Fila — un solo registro distribuido a lo largo de una fila de celdas.
• Tabla — filas × columnas que se desbordan en un rango, con encabezados por columna y formatos de número mapeados desde la respuesta.
• JSON — la respuesta JSON en crudo como texto, para cuando quieres analizarla tú mismo.
• Entidad — un tipo de datos vinculado de Excel: un chip en la celda cuyas propiedades se convierten en accesores de campo como =A2.Price. Solo async.

Modelos de ejecución

• Sync — una operación local de Excel, ejecutada en el complemento sin llamada al agent. Ideal para transformaciones ligeras.
• Async — el predeterminado. Excel muestra #GETTING_DATA mientras el agent obtiene los datos; el complemento agrupa muchas llamadas de celda en una sola petición de forma transparente.
• Streaming — la celda se actualiza en vivo a medida que llegan nuevos valores. El agent transmite al complemento por Server-Sent Events en el escritorio, y recurre a polling en Excel para la web.

Constrúyela en el panel

El constructor de funciones te guía por la elección de una conexión, la declaración de parámetros, la escritura de la consulta o la petición, y el mapeo de la respuesta a tu tipo de salida elegido. No hay archivo JSON que escribir a mano — el panel es el dueño de los metadatos, y el agent genera todo lo que Excel necesita a partir de tu configuración.

Un ejemplo práctico

Supón que tienes una conexión REST llamada Catalog API y quieres tus productos principales como una tabla desbordada:

1. What it does — Fetch data. Basic info — nombre TOP_PRODUCTS, módulo CATALOG.
2. Connection — Catalog API. Request — GET /products, parámetro de consulta limit = 10.
3. Output — Table / Matrix. Ruta de filas $.data[*]; columnas Name → $.name, SKU → $.sku, Price → $.price.
4. Guarda y luego publica el entorno. En Excel: =CATALOG.TOP_PRODUCTS() desborda la tabla.

Un único valor funciona igual con la salida JSON path — p. ej. GET /products/{'{{'}id{'}}'} con un parámetro id numérico y la ruta data.name devuelve el nombre de un producto. Una función de base de datos es idéntica salvo que el paso de la petición es una sentencia SQL (SELECT name, total FROM orders ORDER BY total DESC) contra una conexión Postgres/MySQL/SQL Server.

Un ejemplo de fórmula sync

Para las funciones de cálculo local (sync), el paso de "parámetros" se convierte en un editor de fórmulas: sin conexión, sin petición, nada a lo que el agent tenga que llamar. Escríbela en la sintaxis habitual de Excel, y el panel la compila en el árbol de expresión exacto que el evaluador aislado del agent ejecuta en la celda, sin tocar nunca una fuente de datos:

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

Cada referencia entre [corchetes] se convierte en un parámetro de la función, en el orden en que aparece por primera vez — no hay nada más que declarar. El conjunto de funciones admitidas es cerrado y deliberadamente pequeño, para poder aislarlo con seguridad: texto (CONCAT/CONCATENATE, UPPER, LOWER, TRIM, LEN, LEFT, RIGHT, MID, SUBSTITUTE), matemáticas (MOD, ROUND, ABS, MIN, MAX, además de los operadores habituales + - * /), comparaciones (= < > <= >= <>) y lógica (IF, AND, OR, NOT, COALESCE), y partes de fecha (YEAR, MONTH, DAY). & concatena, igual que en Excel.

Mapear una respuesta de tabla o entidad

Cuando la salida es Tabla o Entidad, el paso Output incluye un muestreador para que no tengas que adivinar el JSONPath a mano:

1. Fetch a sample response — ejecuta tu petición una vez, en vivo, contra la conexión real, y te muestra el JSON real que llega.
2. Haz clic en los campos que quieras — la muestra se analiza en una lista plana de campos candidatos; al hacer clic en uno lo añades como columna (o propiedad de entidad) y se rellena su ruta por ti.
3. Si la respuesta contiene más de una lista plausible de filas — un array anidado, un sobre envolvente — un selector de fila candidata te deja elegir cuál es "la tabla"; la lista de campos se actualiza para el candidato que elijas.
4. Una vista previa en vivo renderiza las primeras filas como una tabla real, para que puedas comprobar el mapeo antes de guardar.

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

Obtener una muestra como esta detecta $.data[*] como la ruta de filas y ofrece name, sku y price como columnas de un clic.

Escribir datos de vuelta

La mayoría de las funciones leen. Algunas conexiones también pueden escribir, y el primer paso del constructor ofrece la operación de escritura junto a Fetch data cuando la conexión lo admite — convirtiendo el libro en un cliente de subida en lugar de un informe.

• Bases de datos SQL — Insertar filas. Eliges la tabla destino y el parámetro que lleva las filas, y el agent ensambla por ti un INSERT parametrizado de varias filas. Funciona en todos los motores con pool, Supabase incluido. Aquí no hay SQL de texto libre: los nombres de tabla y de columna deben ser identificadores simples, y los valores viajan como parámetros vinculados, así que un encabezado del libro nunca puede convertirse en una sentencia.
• MongoDB — insertOne, insertMany, updateMany y deleteMany sobre una colección.
• DynamoDB — put_item para un solo objeto, put_items para un array entero.
• Cosmos DB — upsert escribe las filas en un contenedor.

Las subidas son seguras de reintentar. Cada clic acuña una identidad de subida que llevan todos los trozos, y los conectores la usan para reemplazar en vez de añadir: el insert SQL estampa las filas e intercambia el trozo en una única transacción, Cosmos deriva de ella sus ids de documento, DynamoDB sobrescribe por la clave de la tabla. Así, volver a hacer clic tras un fallo parcial arregla la subida en lugar de duplicarla. Si en cambio subes a tu propia API, las variables de plantilla ${upload.*} te dan esa misma identidad para deduplicar — consulta la Referencia de funciones.

Probar una función

Versionado y Promote

Las funciones se editan solo en el entorno fuente (Development). Cuando estés listo para hacer avanzar un cambio, hazle Promote a un entorno posterior — QA, staging, producción. Promote copia la estructura conservando los valores de conexión propios del entorno destino, y los recursos nuevos llegan con credenciales en blanco para que las rellenes. Puedes promover desde la configuración en vivo de un entorno hermano o desde una versión con nombre guardada, así que las publicaciones son repetibles.