A Common Expression Language (CEL) é uma linguagem de expressão simples criada pelo Google. A linguagem CEL é usada para escrever fórmulas de forma rápida, portátil e segura. Este guia mostra todas as funções que você pode usar ao escrever fórmulas para criar expressões poderosas.

É bom saber

Para saber mais, consulte os recursos oficiais:

• Especificação de CEL
• Implementação de CEL Go
• Definição da linguagem CEL

Operações básicas (operadores)

A tabela a seguir mostra os símbolos básicos que você pode usar em suas fórmulas.

➡️ Para saber mais, consulte Operadores de CEL.

Funções disponíveis

Conversão entre tipos

As funções a seguir permitem que você altere os dados de um tipo para outro.

➡️ Para saber mais, consulte Conversões de tipo CEL.

bool() Converter em verdadeiro/falso

Converte texto ou outros valores em verdadeiro/falso.

Por exemplo:

bool(verdadeiro) // retorna: verdadeiro
 bool("verdadeiro") // retorna: verdadeiro (converte o texto em verdadeiro/falso)
 bool("falso") // retorna: falso

bytes() Converter em dados binários

Converte dados em bytes (formato binário bruto). A maioria dos usuários não precisará disso.

Por exemplo:

bytes(b'hello') // retorna: b'hello'
 bytes("hello") // retorna: b'hello' (converte texto em binário)

double() Converter em número decimal

Converte valores em números decimais (números com um ponto, como 3,14).

Por exemplo:

double(3.14)      // retorna: 3,14
 double(42) // retorna: 42.0 (adiciona ponto decimal)
 double("3.14")    // retorna: 3,14 (converte texto em número)
 double(100) // retorna: 100.0

int() Converter em número inteiro

Converte valores em números inteiros (sem casas decimais).

Por exemplo:

int(42)                                 // retorna: 42
int(3.14)                               // retorna: 3 (remove .14)
int(duration("1h"))                     // retorna: 3600 (segundos em 1 hora)
int("123")                              // retorna: 123 (converte texto)
int(timestamp("2024-01-01T00:00:00Z"))  // retorna: 1704067200

string() Converter em texto

Converte qualquer valor em texto.

Por exemplo:

string("hello")                        // retorna: "hello"
string(verdadeiro)                           // retorna: "verdadeiro"
string(3.14)                           // retorna: "3.14"
string(123)                            // retorna: "123"
string(timestamp("2024-01-01T00:00:00Z")) // retorna: "2024-01-01T00:00:00Z"

type() Descobrir o tipo de algo

Indica o tipo de dados que você possui (texto, número, verdadeiro/falso etc.).

Por exemplo:

type(42) // retorna: int (tipo número inteiro)
 type("hello") // retorna: string (tipo texto)
 tipo(3.14)        // retorna: double (tipo número decimal)
 type(true) // retorna: bool (tipo verdadeiro/falso)

Trabalho com datas e horas

As funções a seguir permitem trabalhar com datas, horas e carimbos de data e hora.

➡️ Para saber mais, consulte Carimbos de data/hora de CEL.

timestamp() Criar ou converter uma data/hora

Cria um valor de data e hora a partir de fontes diferentes.

Por exemplo:

timestamp("2024-01-01T00:00:00Z") // cria: 1 de janeiro de 2024 à meia-noite
 timestamp(1704067200) // cria: 2024-01-01T00:00:00Z

getFullYear() Obter o ano

Obtém o ano a partir de uma data (como 2024).

Por exemplo:

timestamp("2024-01-15T10:30:00Z").getFullYear()                      // retorna: 2024
timestamp("2024-01-01T02:00:00Z").getFullYear("America/New_York")   // retorna: 2023 (noite de 31 de dezembro)
createdAt.getFullYear()                                              // obtém o ano de createdAt

getMonth() Obter o mês

Obtém o mês a partir de uma data.

Por exemplo:

timestamp("2024-03-15T10:30:00Z").getMonth() // retorna: 2 (Março é o 3º mês)
 timestamp("2024-03-01T02:00:00Z").getMonth("America/New_York")     // retorna: 1 (fevereiro)
createdAt.getMonth()                                                // obtém o mês de createdAt

 // Lembre-se: Janeiro=0, Fevereiro=1, Março=2, Abril=3, Maio=4, Junho=5,
 // Julho=6, Agosto=7, Setembro=8, Outubro=9, Novembro=10, Dezembro=11

getDate() Obter o dia do mês

Obtém o dia do mês (1-31).

Por exemplo:

timestamp("2024-03-15T10:30:00Z").getDate() // retorna: 15 (o 15º dia)
 timestamp("2024-03-01T02:00:00Z").getDate("America/New_York")      // retorna: 28 (28 de fevereiro)
createdAt.getDate()                                                 // obtém o dia a partir de createdAt

getDayOfWeek() Obter o dia da semana

Obtém o dia da semana.

Por exemplo:

timestamp("2024-03-15T10:30:00Z").getDayOfWeek() // retorna: 5 (sexta-feira)
 timestamp("2024-03-17T02:00:00Z").getDayOfWeek("America/New_York") // retorna: 6 (sábado)

// Lembre-se: Domingo=0, Segunda-feira=1, Terça-feira=2, Quarta-feira=3,
// Quinta-feira=4, Sexta-feira=5, Sábado=6

getHours() Obter a hora

Obtém a hora a partir de um horário (0-23, onde 0 é meia-noite e 23 são 23h).

Por exemplo:

timestamp("2024-03-15T14:30:00Z").getHours() // retorna: 14 (14:30)
 timestamp("2024-03-15T14:30:00Z").getHours("America/New_York") // retorna: 10 (10:30 AM EST)
 duration("2h30m").getHours() // retorna: 2 horas

getMinutes() Obter os minutos

Obtém os minutos de um determinado horário (0-59).

Por exemplo:

timestamp("2024-03-15T14:45:00Z").getMinutes()                      // retorna: 45 minutos
timestamp("2024-03-15T14:45:00Z").getMinutes("America/New_York")   // retorna: 45 minutos
duration("2h30m").getMinutes()                                      // retorna: 150 (minutos no total)

getSeconds() Obter os segundos

Obtém os segundos de um horário (0-59).

Por exemplo:

timestamp("2024-03-15T14:45:30Z").getSeconds()                      // retorna: 30 segundos
timestamp("2024-03-15T14:45:30Z").getSeconds("America/New_York")   // retorna: 30 segundos
duration("2h30m45s").getSeconds()                                   // retorna: 9045 (total de segundos)

Trabalho com períodos

As funções a seguir permitem criar e trabalhar com durações (períodos).

➡️ Para saber mais, consulte Duração de CEL.

duration() Criar um período

Cria uma duração que representa um período (não uma data específica).

Por exemplo:

duration(3600)              // cria: 1 hora (3600 segundos)
duration("1h30m")           // cria: 1 hora e 30 minutos
duration("90s")             // cria: 90 segundos
duration("2h")              // cria: 2 horas

Formato de período: use h para horas, m para minutos e s para segundos. Combine-os da seguinte forma: “1h30m15s”.

Funções de texto

As funções a seguir permitem que você trabalhe com texto (strings).

➡️ Para saber mais, consulte Funções de string de CEL.

contains() Verifica se o texto contém algo

Verifica se um trecho de texto está dentro de outro.

Por exemplo:

"hello world".contains("world")     // retorna: verdadeiro (encontrei!)
"hello world".contains("xyz")       // retorna: falso (não encontrado)
 status.contains("ativo")           // verifica se status contém "ativo"
 contato.email.contains("@")         // verifica se o e-mail contém o símbolo @

startsWith() Verificar se o texto começa com algo

Verifica se o texto começa com caracteres específicos.

Por exemplo:

"hello world".startsWith("hello")           // retorna: verdadeiro
"hello world".startsWith("world")           // retorna: falso (começa com "hello" e não com "world")
contact.email.startsWith("admin")           // verifica se o e-mail começa com "admin"
status.startsWith("pending")                // verifica se o status começa com "pending"

endsWith() Verificar se o texto termina com algo

Verifica se o texto termina com caracteres específicos.

Por exemplo:

"hello world".endsWith("world")             // retorna: verdadeiro
"hello world".endsWith("hello")             // retorna: falso (termina com "world" e não com "hello")
contact.email.endsWith("@example.com") // verifica se o domínio do e-mail é @example.com
status.endsWith("_approved")                // verifica se o status termina com "_approved"

matches() Verificar se o texto corresponde a um padrão

Verifica se o texto corresponde a um padrão (usa expressões regulares - recurso avançado).

Por exemplo:

// Verificar se o texto se parece com um e-mail
"test@example.com".matches("^[a-zA-Z0-9+_.-]+@[a-zA-Z0-9.-]+$")    // retorna: verdadeiro
"not-an-email".matches("^[a-zA-Z0-9+_.-]+@[a-zA-Z0-9.-]+$")        // retorna: falso

// Validar formato de e-mail
contact.email.matches("^[a-z]+@[a-z]+\\.[a-z]+$")                   // verifica o formato do e-mail

trim() Remover caracteres das duas extremidades

Remove caracteres específicos do início e do fim do texto (como remover espaços).

Por exemplo:

trim("  hello  ", " ")      // retorna: "hello" (espaço removidos)
trim("###test###", "#")     // retorna: "test" (símbolos # removidos)
trim("___name___", "_")     // retorna: "name" (sublinhados removidos)
trim("000123000", "0")      // retorna: "123" (zeros removidos)

ltrim() Remover caracteres da esquerda (Início)

Remove caracteres específicos apenas do início do texto.

Por exemplo:

ltrim("  hello  ", " ")     // retorna: "hello  " (espaços removidos da esquerda)
ltrim("###test###", "#")    // retorna: "test###" (# removido da esquerda)
ltrim("000123", "0")        // retorna: "123" (zeros removidos da esquerda)

rtrim() Remover caracteres da direita (Fim)

Remove caracteres específicos apenas do final do texto.

Por exemplo:

rtrim("  hello  ", " ")     // retorna: "  hello" (espaços removidos da direita)
rtrim("###test###", "#")    // retorna: "###test" (# removido da direita)
rtrim("123000", "0")        // retorna: "123" (zeros removidos da direita)

Funções matemáticas

As funções a seguir são para cálculos matemáticos.

➡️ Para saber mais, consulte Funções numéricas de CEL.

abs() Obter o valor absoluto

Remove o sinal negativo de um número (tornando-o positivo).

Por exemplo:

abs(-5) // retorna: 5
abs(10) // retorna: 10 (já positivo)
abs(-100) // retorna: 100
abs(0) // retorna: 0

round() Arredondar para o número inteiro mais próximo

Arredonda um número decimal para o número inteiro mais próximo.

Por exemplo:

round(3.7) // retorna: 4 (arredonda para cima)
round(3.2) // retorna: 3 (arredonda para baixo)
round(3,5)                  // retorna: 4 (exatamente a metade, arredondado para cima)
round(-2,5)                 // retorna: -2
round(valor) // arredonda a variável de valor

roundUp() Sempre arredondar para cima

Arredonda sempre para o próximo número inteiro (teto).

Por exemplo:

roundUp(3.2) // retorna: 4 (arredonda para cima mesmo estando próximo de 3)
roundUp(3.9)                // retorna: 4
roundUp(3.0)                // retorna: 3 (já inteiro)
roundUp(-2.5)               // retorna: -2

roundDown() Sempre arredondar para baixo

Arredonda sempre para baixo, para o número inteiro anterior (piso).

Por exemplo:

roundDown(3.8)              // retorna: 3 (arredonda para baixo mesmo estando próximo de 4)
roundDown(3.2)              // retorna: 3
roundDown(3.0)              // retorna: 3 (já inteiro)
roundDown(-2.5)             // retorna: -3

min() Encontrar o menor número

Retorna o menor de dois números.

Por exemplo:

min(5, 10) // retorna: 5 (número menor)
min(-3, 2) // retorna: -3 (números negativos são menores)
min(idade, 100) // retorna: o menor valor entre idade e 100
min(3.5, 5) // retorna: 3

Caso de uso: min(idade, 65) garante que a idade não exceda 65.

max() Descobrir o número maior

Retorna o maior dos dois números.

Por exemplo:

max(5, 10) // retorna: 10 (número maior)
 max(-3, 2) // retorna: 2
max(idade, 18) // retorna: o que for maior, idade ou 18
 máx(3,5, 5)                 // retorna: 5

Caso de uso: max(idade, 18) garante que a idade seja pelo menos 18.

Funções de lista e mapa

As funções a seguir permitem trabalhar com listas (coleções ordenadas) e mapas (pares de chave-valor).

➡️ Para saber mais, consulte Listas de CEL e Mapas de CEL.

size() Contar itens

Conta quantos itens existem em uma lista, um mapa ou quantos caracteres há em um texto.

Por exemplo:

size([1, 2, 3]) // retorna: 3 (três itens na lista)
[1, 2, 3].size() // retorna: 3
partners.size()             // retorna: quantos parceiros você tem
size({"a": 1, "b": 2}) // retorna: 2 (dois pares de chave-valor)
addresses.size()            // retorna: quantos endereços você tem
size("olá") // retorna: 5 (cinco letras)
"hello".size()              // retorna: 5
contact.email.size() > 5 // verifica se o e-mail tem mais de 5 caracteres

in() Verificar se o item existe

Verifica se um valor existe em uma lista ou se uma chave existe em um mapa.

Por exemplo:

5 em [1, 2, 3, 4, 5] // retorna: verdadeiro (5 está na lista)
10 em [1, 2, 3] // resulta em: falso (10 não está na lista)
"ativo" em ["ativo", "pendente", "concluído"] // retorna: verdadeiro
"nome" em {"name": "John", "age": 30} // retorna: verdadeiro (a chave "nome" existe)
"e-mail" em {"name": "John", "age": 30} // retorna: falso (nenhuma chave "e-mail")
"início" nos endereços // verifica se o endereço "início" existe

Nossas recomendações para iniciantes

Para saber mais, confira: 

• Definição de linguagem CEL - Guia de linguagem completo
• Tutorial introdutório sobre CEL - Primeiros passos com CEL
• Práticas recomendadas de CEL - Dicas e padrões

Compreendendo os tipos de dados

Para saber mais, consulte Sistema de tipos de CEL.

• Texto (string): palavras e frases, sempre entre aspas: "hello"
• Números (int): números inteiros sem aspas: 42
• Decimais (duplo): números com casas decimais: 3.14
• Verdadeiro/Falso (bool): apenas verdadeiro ou falso, sem aspas.
• Listas: vários itens entre colchetes: [1, 2, 3] ou ["a", "b", "c"]
• Mapas: pares de chave-valor entre chaves: {"name": "John", "age": 30}

Uso de funções membro (notação de ponto)

Algumas funções são chamadas usando um ponto (.) depois do valor:

"hello".contains("e") // Verificar se "hello" contém "e"
[1, 2, 3].size() // Contar os itens na lista
timestamp("2024-01-01T00:00:00Z").getFullYear()  // Obter o ano a partir da data

Uso de funções regulares

Outras funções envolvem o valor:

int("123") // Converter texto em número
round(3.7)                      // Arredondar decimal para número inteiro
min(5, 10) // Encontrar o menor número

Combinação de funções

Você pode aninhar funções umas dentro das outras:

string(round(3.7))              // Primeiro arredonda 3,7 para 4, depois converte em "4"
int(duration("1h")) // Converte 1 hora em 3600 segundos

Fusos horários

Algumas funções de data aceitam um fuso horário (como “America/New_York” ou “Europe/Paris”):

createdAt.getHours()                    // Obtém a hora em UTC (horário universal)
createdAt.getHours("America/New_York") // Recebe uma hora no horário de Nova York

Lembrate

• Os meses começam em 0: janeiro é 0, dezembro é 11
• Os dias da semana começam em 0: domingo é 0, sábado é 6
• As horas são indicadas no formato de 24 horas: 0 é meia-noite, 13 é 13h, 23 é 23h
• Use aspas para o texto: "hello" e não hello
• Sem aspas para números: 42 e não "42"

⏭️ O que vem a seguir?

• Documentação oficial da CEL
• Referência de linguagem
• Demonstração de CEL

🤔 Dúvidas?

Em caso de dúvida, sinta-se à vontade para entrar em contato com nossa equipe de suporte, criando um tíquete a partir da sua conta. Caso ainda não tenha uma conta, entre em contato conosco aqui.

Se você está procurando ajuda com um projeto usando o Brevo, podemos encontrar à agência parceira da Brevo certa.