Funções

Cada função mapeia para uma fórmula sob o espaço de nomes CONNXL, endereçada pelo seu módulo e nome:

=CONNXL.SALES.TOP_CUSTOMERS(10)

Formas do resultado

A forma do resultado de uma função decide o aspeto que o resultado tem assim que chega à grelha — escolhe-la no construtor. (Separadamente, o tipo de uma função — a espécie de fonte de dados contra a qual corre — é definido quando escolhes uma ligação; a Referência de funções lista-os todos.)

• Valor único — um valor na célula que chama: um número, uma string, um booleano.
• Linha — um único registo disposto ao longo de uma linha de células.
• Tabela — linhas × colunas que derramam para um intervalo, com cabeçalhos por coluna e formatos numéricos mapeados a partir da resposta.
• JSON — a resposta JSON em bruto como texto, para quando queres analisá-la tu mesmo.
• Entidade — um tipo de dados ligado de Excel: um chip na célula cujas propriedades se tornam acessores de campo como =A2.Price. Apenas async.

Modelos de execução

• Sync — uma operação local de Excel, executada no suplemento sem chamada ao agent. Melhor para transformações leves.
• Async — o padrão. O Excel mostra #GETTING_DATA enquanto o agent obtém; o suplemento agrupa muitas chamadas de célula num só pedido de forma transparente.
• Streaming — a célula atualiza-se ao vivo à medida que chegam novos valores. O agent faz stream para o suplemento por Server-Sent Events no desktop, e recorre a polling no Excel para a web.

Constrói-a no dashboard

O construtor de funções guia-te pela escolha de uma ligação, a declaração dos parâmetros, a escrita da consulta ou do pedido, e o mapeamento da resposta para o tipo de saída que escolheste. Não há ficheiro JSON para escrever à mão — o dashboard é dono dos metadados, e o agent gera tudo o que o Excel precisa a partir da tua configuração.

Um exemplo prático

Imagina que tens uma ligação REST chamada Catalog API e queres os teus produtos principais como uma tabela derramada:

1. What it does — Fetch data. Basic info — nome TOP_PRODUCTS, módulo CATALOG.
2. Connection — Catalog API. Request — GET /products, parâmetro de consulta limit = 10.
3. Output — Table / Matrix. Caminho das linhas $.data[*]; colunas Name → $.name, SKU → $.sku, Price → $.price.
4. Guarda e depois publica o ambiente. No Excel: =CATALOG.TOP_PRODUCTS() derrama a tabela.

Um valor único funciona da mesma forma com a saída JSON path — por ex. GET /products/{'{{'}id{'}}'} com um parâmetro id numérico e o caminho data.name devolve o nome de um produto. Uma função de base de dados é idêntica, exceto que o passo do pedido é uma instrução SQL (SELECT name, total FROM orders ORDER BY total DESC) contra uma ligação Postgres/MySQL/SQL Server.

Um exemplo de fórmula sync

Para as funções de cálculo local (sync), o passo de "parâmetros" torna-se num editor de fórmulas: sem ligação, sem pedido, nada a que o agent precise de chamar. Escreve-a na sintaxe habitual do Excel, e o dashboard compila-a na árvore de expressão exata que o avaliador isolado do agent executa na célula, sem nunca tocar numa fonte de dados:

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

Cada referência entre [parênteses retos] torna-se num parâmetro da função, pela ordem em que aparece pela primeira vez — não há mais nada a declarar. O conjunto de funções suportadas é fechado e deliberadamente pequeno, para poder ser isolado com segurança: texto (CONCAT/CONCATENATE, UPPER, LOWER, TRIM, LEN, LEFT, RIGHT, MID, SUBSTITUTE), matemática (MOD, ROUND, ABS, MIN, MAX, além dos operadores habituais + - * /), comparações (= < > <= >= <>) e lógica (IF, AND, OR, NOT, COALESCE), e partes de data (YEAR, MONTH, DAY). & concatena, tal como no Excel.

Mapear uma resposta de tabela ou entidade

Quando o resultado é Tabela ou Entidade, o passo Output inclui um amostrador para não teres de adivinhar o JSONPath à mão:

1. Fetch a sample response — corre o teu pedido uma vez, ao vivo, contra a ligação real, e mostra-te o JSON real que chega.
2. Clica nos campos que queres — a amostra é analisada numa lista plana de campos candidatos; ao clicares num, adicionas-o como coluna (ou propriedade de entidade) e o caminho é preenchido por ti.
3. Se a resposta contiver mais do que uma lista plausível de linhas — um array aninhado, um envelope — um seletor de linha candidata deixa-te escolher qual é "a tabela"; a lista de campos atualiza-se para o candidato que escolheres.
4. Uma pré-visualização ao vivo apresenta as primeiras linhas como uma tabela real, para poderes verificar o mapeamento antes de guardares.

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

Obter uma amostra como esta deteta $.data[*] como o caminho das linhas e oferece name, sku e price como colunas de um clique.

Escrever dados de volta

A maioria das funções lê. Algumas ligações também sabem escrever, e o primeiro passo do construtor oferece a operação de escrita ao lado de Fetch data quando a ligação a admite — transformando o livro num cliente de carregamento em vez de um relatório.

• Bases de dados SQL — Inserir linhas. Escolhes a tabela de destino e o parâmetro que leva as linhas, e o agent monta por ti um INSERT parametrizado de várias linhas. Funciona em todos os motores com pool, Supabase incluído. Aqui não há SQL de texto livre: os nomes de tabela e de coluna têm de ser identificadores simples, e os valores viajam como parâmetros vinculados, por isso um cabeçalho do livro nunca se pode tornar uma instrução.
• MongoDB — insertOne, insertMany, updateMany e deleteMany sobre uma coleção.
• DynamoDB — put_item para um único objeto, put_items para um array inteiro.
• Cosmos DB — upsert escreve as linhas num contentor.

Os carregamentos são seguros de repetir. Cada clique cunha uma identidade de carregamento que todos os blocos levam, e os conetores usam-na para substituir em vez de acrescentar: o insert SQL carimba as linhas e troca o bloco numa única transação, o Cosmos deriva dela os seus ids de documento, o DynamoDB sobrescreve pela chave da tabela. Assim, voltar a clicar depois de uma falha parcial repara o carregamento em vez de o duplicar. Se em vez disso carregares para a tua própria API, as variáveis de modelo ${upload.*} dão-te essa mesma identidade para desduplicar — vê a Referência de funções.

Testar uma função

Versionamento e Promover

As funções são editadas apenas no ambiente fonte (Development). Quando estás pronto para levar uma alteração adiante, Promove-a para um ambiente a jusante — QA, staging, produção. Promover copia a estrutura preservando os valores próprios de ligação do ambiente-alvo, e os recursos novos chegam com credenciais em branco para tu preencheres. Podes promover a partir da configuração ao vivo de um ambiente irmão ou de uma versão nomeada guardada, por isso os lançamentos são repetíveis.