> ## Documentation Index
> Fetch the complete documentation index at: https://docs.brainchat.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Fórmulas e valor inicial

> Preencha campos das tabelas com cálculos automáticos, sugestões na criação do registro e dados de outras tabelas da organização.

Todo campo de uma tabela (texto, número, moeda, data, seleção, etiqueta e os demais tipos) pode ser preenchido por uma pessoa ou pelo próprio Brainchat. Você escolhe isso no editor da coluna, em **Comportamento → Como o campo é preenchido**.

***

## As três formas de preencher um campo

| Forma | Como funciona | Quando usar |
| - | - | - |
| **Manual** | A pessoa preenche o campo. | Dados que só quem cadastra sabe (nome, observação, telefone) |
| **Valor inicial** | Uma expressão sugere o valor **uma vez**, quando o registro é criado. Depois disso, a pessoa pode alterar à vontade. | Padrões que às vezes mudam: prazo de 30 dias, status "Novo", responsável = quem criou |
| **Fórmula** | O sistema calcula o valor e ninguém edita à mão (nem pela tela, nem pela API, importação ou Flow). | Totais, prazos calculados, classificações, dados trazidos de outra tabela |

Exemplos:

```text theme={null}
Valor inicial do campo "Prazo":   ADD_DAYS(TODAY(), 30)
Fórmula do campo "Total":         [Quantidade] * [Preço unitário]
Fórmula do campo "Faixa":         IF([Total] > 1000, "Alto", "Normal")
```

> [!NOTE]
>
> Um campo com fórmula **nunca é obrigatório**: como ninguém o preenche, a opção de obrigatoriedade deixa de valer para ele.

***

## Como escrever uma fórmula

* **Campos** vão entre colchetes, pelo nome da coluna: `[Valor]`, `[Data de entrega]`.
* **Textos** vão entre aspas: `"Pago"`.
* **Funções** têm nomes em inglês, no estilo do AppSheet: `IF`, `SUM`, `LOOKUP`, `TODAY`. Veja todas na [Referência de funções](https://docs.brainchat.app/insights/tabelas/funcoes.md).
* **Argumentos** são separados por vírgula. Ponto e vírgula também é aceito.
* **Verdadeiro e falso** são `TRUE` e `FALSE`.
* **Operadores:** `+ - * /` para contas, `&` para juntar textos, `= <> < > <= >=` para comparar.
* `[_THISROW].[Coluna]` volta ao registro atual dentro de uma condição que percorre outra tabela (por exemplo, em `SELECT`).

O editor da fórmula sugere campos e funções enquanto você digita e aponta erros antes de salvar.

***

## Fórmula gravada e fórmula calculada na hora

**Gravada (padrão).** O Brainchat calcula o valor em segundo plano sempre que o registro muda ou que muda algo em uma tabela que a fórmula lê. Como o resultado fica guardado no registro, ele funciona em todo lugar: grade, Kanban, ficha do registro, Studio, filtros, ordenação, exportação e API.

**Calculada na hora.** Fórmulas que usam `TODAY()` ou `NOW()`, e campos que dependem delas, mudam de valor só com a passagem do tempo. Por isso, elas são calculadas no momento em que o registro é lido, e não gravadas. Exemplo: `DAYS([Prazo], TODAY())` (dias até o prazo).

Você não precisa escolher: o editor identifica o modo sozinho e mostra abaixo da fórmula se ela é **gravada** ou **calculada na hora**.

***

## Recálculo da tabela inteira

Quando você cria ou altera uma fórmula em uma tabela com muitos registros, o Brainchat recalcula a tabela inteira em segundo plano. Enquanto isso:

* A tela da tabela mostra o aviso **"Calculando fórmulas: X de Y registros"** com uma barra de progresso.
* O campo fica **vazio** nos registros que o cálculo ainda não alcançou.
* A tabela continua funcionando normalmente: dá para consultar, editar e criar registros.

> [!TIP]
>
> Em tabelas grandes, revise a fórmula com calma antes de salvar: cada alteração recomeça o recálculo de todos os registros.

***

## Ler dados de outras tabelas

Uma fórmula pode buscar e somar dados de outras tabelas da mesma organização.

### Buscar um valor: LOOKUP

```text theme={null}
LOOKUP("Tabela", [coluna de busca], valor procurado, [coluna de retorno])
```

Exemplo: trazer o CPF da tabela "Cadastros" pelo e-mail do registro atual:

```text theme={null}
LOOKUP("Cadastros", [E-mail], [E-mail], [CPF])
```

O primeiro `[E-mail]` é a coluna da tabela "Cadastros" onde procurar; o segundo é o e-mail do registro atual. Se nenhuma linha combinar, o resultado fica vazio.

* `LOOKUP_ALL` tem os mesmos argumentos e devolve uma **lista** com o valor de todas as linhas que combinam.
* `SELECT("Tabela", [coluna], condição)` devolve a lista dos valores de uma coluna nas linhas que atendem a uma condição. Exemplo: `SUM(SELECT("Itens", [Total], [Pedido] = [Número]))`.

> [!WARNING]
>
> **A ordem dos argumentos de `LOOKUP` e `SELECT` é a do Brainchat, diferente do AppSheet.** No Brainchat, o nome da tabela vem sempre primeiro: `LOOKUP("Tabela", [coluna de busca], valor, [coluna de retorno])` e `SELECT("Tabela", [coluna], condição)`. Se você copiar uma fórmula do AppSheet, reorganize os argumentos.

### Somar e resumir registros relacionados

Use `[Relação].FUNÇÃO(...)`, em que `[Relação]` pode ser:

* uma **coluna de conexão** do registro atual (os registros ligados a ele); ou
* o **nome de outra tabela** que tem uma conexão apontando para esta (os registros de lá que apontam para o registro atual).

| Objetivo | Fórmula |
| - | - |
| Total gasto pelo cliente, somando os pedidos ligados a ele | `[Pedidos].SUM([Valor])` |
| Total só dos pedidos pagos | `[Pedidos].SUM([Valor], [Status] = "Pago")` |
| Quantidade de pedidos | `[Pedidos].COUNT()` |
| Data do último agendamento | `[Agendamentos].MAX([Data])` |
| Unidade do último agendamento | `[Agendamentos].MAXBY([Data], [Unidade])` |

As funções aceitas depois do ponto são `SUM`, `SUMUNIQUE` (soma uma vez por chave), `COUNT`, `AVERAGE`, `MAX`, `MIN`, `FIRST`, `LIST`, `UNIQUE`, `MAXBY` e `MINBY`. A condição, quando houver, vai como último argumento.

`MAXBY` e `MINBY` trazem **outro campo** do registro com o maior (ou menor) valor: `[Agendamentos].MAXBY([Data], [Unidade])` devolve a Unidade do agendamento com a Data mais recente. Para limitar, acrescente a condição como terceiro argumento: `[Agendamentos].MAXBY([Data], [Unidade], [Status] = "Realizado")`.

### Nome da tabela

As tabelas são citadas pelo nome, entre aspas. O editor guarda a referência à tabela e sempre mostra o nome atual, então **renomear uma tabela não quebra as fórmulas** que a usam.

### Quem pode citar outra tabela

* Ao salvar a fórmula, só podem ser citadas tabelas **da mesma organização** que **você consegue ler**.
* Depois de salva, quem vê o registro vê o valor calculado, mesmo sem acesso à tabela de origem (como no AppSheet). Pense nisso antes de trazer dados sigilosos para uma tabela com acesso mais amplo.

***

## Atributos do registro

Todo registro tem atributos fixos, que não fazem parte das colunas da tabela: **Código**, **Criado em**, **Atualizado em**, **Criado por** e **Atualizado por**. Eles são preenchidos pelo sistema; você só escolhe mostrar ou esconder cada um.

Quando um **fluxo do Flow** cria ou altera o registro, **Criado por** e **Atualizado por** mostram o fluxo, como se ele fosse uma conta de serviço. Gravações da API, de sincronização ou do agente aparecem sem autor (feitas pelo sistema).

Nas expressões, use:

| Função | Valor |
| - | - |
| `CREATED_AT()` | Data de criação do registro |
| `UPDATED_AT()` | Data da última alteração do registro |
| `USERID()` | Identificador da pessoa |
| `USEREMAIL()` | E-mail de login da pessoa |
| `USERNAME()` | Nome da pessoa (use só para exibir) |
| `USERROLE()` | Papel da pessoa na organização: "dono", "admin" ou "membro" |

Exemplo de fórmula: dias desde a criação do registro, `DAYS(TODAY(), CREATED_AT())`.

> [!NOTE]
>
> As funções de pessoa (`USERID()`, `USEREMAIL()`, `USERNAME()`, `USERROLE()`) indicam **quem cria o registro** em **Valor inicial** e **quem vê ou age** nas regras de exibição, edição e validação. Em um campo com **Fórmula** e em gravações sem pessoa (Flow, API, agendamento) elas ficam vazias. Para guardar quem criou o registro, use **Valor inicial** `USEREMAIL()` ou mostre o atributo **Criado por**.

***

## Datas e fuso horário

Todas as datas das fórmulas (`TODAY()`, `NOW()`, dia, mês, hora, diferença entre datas) usam o **fuso horário da organização**, e não o do computador de quem está vendo.

***

## No Flow

O Flow usa as mesmas expressões:

* nas **condições** de passos e caminhos;
* dentro de **qualquer texto**, com `{{=expressão}}`.

No Flow, os campos são citados pelo caminho, com pontos: `[trigger.row_data.valor]`. Exemplo de mensagem com o total calculado:

```text theme={null}
Total do pedido: {{=[trigger.row_data.valor] * [trigger.row_data.qtd]}}
```

### Filtrar a Busca com uma expressão

No passo **Buscar registro**, o campo **Só registros em que** aceita uma expressão avaliada em cada registro da tabela. Os campos do registro são citados pelo nome da coluna; os dados do fluxo, pelo caminho:

```text theme={null}
[Vencimento] < TODAY()
[Cliente] = [trigger.row_data.cliente]
AND([Status] <> "Pago", [Valor] > 1000)
```

As datas usam o fuso da organização. A tabela é lida em páginas; quando a expressão compara uma coluna com um valor fixo ou do fluxo (`[Cliente] = ...`), essa parte já filtra no banco.

> [!TIP]
>
> `TODAY()` e `NOW()` não disparam um fluxo sozinhos: o valor muda com o tempo, mas o registro não é alterado. Para agir sobre registros vencidos, crie um fluxo **Em um horário** (por exemplo, todo dia às 7h) com uma **Busca** filtrada por `[Vencimento] < TODAY()` e uma **Repetição** sobre os registros encontrados.

### Quem criou e quem alterou o registro

Em fluxos disparados por uma tabela, o gatilho traz quem criou e quem alterou o registro:

| Variável | Valor |
| - | - |
| `{{trigger.updated_by.kind}}` | `person` (uma pessoa), `flow` (um fluxo) ou `system` (API, sincronização, agente) |
| `{{trigger.updated_by.name}}` | Nome da pessoa ou do fluxo |
| `{{trigger.updated_by.email}}` | E-mail da pessoa |
| `{{trigger.updated_by.person.name}}` | Pessoa que acionou o fluxo, quando houver |
| `{{trigger.created_by...}}` | O mesmo, para quem criou |

Para o fluxo só rodar quando **uma pessoa** alterou o registro (e não outro fluxo), use no filtro do gatilho: `trigger.updated_by.kind` **é igual a** `person`.

***

## Erros comuns

| Situação | O que acontece | Como resolver |
| - | - | - |
| Campo vazio em uma conta | Nas contas (`+ - * /`), vazio vale **0**. `[Preço] * [Quantidade]` dá 0 se a quantidade estiver vazia. | Teste antes: `IF(ISBLANK([Quantidade]), "", [Preço] * [Quantidade])` |
| Divisão por zero | O resultado fica vazio. | Proteja a divisão: `IF([Total] = 0, 0, [Pago] / [Total])` |
| `LOOKUP` copiado do AppSheet | Os argumentos ficam na ordem errada e a busca não encontra nada. | Use a ordem do Brainchat: tabela, coluna de busca, valor, coluna de retorno. |
| Comparar pelo nome da pessoa | A própria pessoa pode mudar o nome. | Compare por `USERID()` ou `USEREMAIL()`. |
| Campo com fórmula aparece vazio logo depois de salvar | A tabela ainda está sendo recalculada. | Acompanhe o aviso "Calculando fórmulas" na tela da tabela. |
| Tabela não aparece para citar | Ela é de outra organização ou você não tem acesso de leitura a ela. | Peça acesso à tabela ou use uma tabela da mesma organização. |

***

## Próximo passo

> [card] [Referência de funções](https://docs.brainchat.app/insights/tabelas/funcoes.md)
>
> Todas as funções disponíveis, com exemplos.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.