The Common Expression Language (CEL) is a simple expression language designed by Google. CEL is used to write fast, portable, and safe formulas. This guide shows you all the functions you can use when writing formulas so you can create powerful expressions.

Good to know

To learn more, check the official resources:

• CEL Specification
• CEL Go Implementation
• CEL Language Definition

Basic operations (Operators)

The following table shows the basic symbols you can use in your formulas.

➡️ To learn more, check CEL Operators.

Available functions

Converting between types

The following functions allow you to change data from one type to another.

➡️ To learn more, check CEL Type Conversions.

bool() Convert to true/false

Changes text or other values into true/false.

For example:

bool(true)        // gives you: true
bool("true")      // gives you: true (converts text to true/false)
bool("false")     // gives you: false

bytes() Convert to binary data

Converts data to bytes (raw binary format). Most users won’t need this.

For example:

bytes(b'hello')   // gives you: b'hello'
bytes("hello")    // gives you: b'hello' (converts text to binary)

double() Convert to decimal number

Changes values into decimal numbers (numbers with a dot, like 3.14).

For example:

double(3.14)      // gives you: 3.14
double(42)        // gives you: 42.0 (adds decimal point)
double("3.14")    // gives you: 3.14 (converts text to number)
double(100)       // gives you: 100.0

int() Convert to whole number

Changes values into whole numbers (no decimal points).

For example:

int(42)                                 // gives you: 42
int(3.14)                               // gives you: 3 (removes .14)
int(duration("1h"))                     // gives you: 3600 (seconds in 1 hour)
int("123")                              // gives you: 123 (converts text)
int(timestamp("2024-01-01T00:00:00Z"))  // gives you: 1704067200

string() Convert to text

Changes any value into text.

For example:

string("hello")                        // gives you: "hello"
string(true)                           // gives you: "true"
string(3.14)                           // gives you: "3.14"
string(123)                            // gives you: "123"
string(timestamp("2024-01-01T00:00:00Z")) // gives you: "2024-01-01T00:00:00Z"

type() Find out what type something is

Tells you what kind of data you have (text, number, true/false, etc.).

For example:

type(42)          // gives you: int (whole number type)
type("hello")     // gives you: string (text type)
type(3.14)        // gives you: double (decimal number type)
type(true)        // gives you: bool (true/false type)

Working with dates and times

The following functions allow you to work with dates, times, and timestamps.

➡️ To learn more, check CEL Timestamps.

timestamp() Create or convert a date/time

Creates a date and time value from different sources.

For example:

timestamp("2024-01-01T00:00:00Z")             // creates: January 1, 2024 at midnight
timestamp(1704067200)                         // creates: 2024-01-01T00:00:00Z

getFullYear() Get the year

Gets the year from a date (like 2024).

For example:

timestamp("2024-01-15T10:30:00Z").getFullYear()                      // gives you: 2024
timestamp("2024-01-01T02:00:00Z").getFullYear("America/New_York")   // gives you: 2023 (evening of Dec 31)
createdAt.getFullYear()                                              // gets year from createdAt

getMonth() Get the month

Gets the month from a date.

For example:

timestamp("2024-03-15T10:30:00Z").getMonth()                        // gives you: 2 (March is the 3rd month)
timestamp("2024-03-01T02:00:00Z").getMonth("America/New_York")     // gives you: 1 (February)
createdAt.getMonth()                                                // gets month from createdAt

// Remember: January=0, February=1, March=2, April=3, May=4, June=5,
//           July=6, August=7, September=8, October=9, November=10, December=11

getDate() Get the day of month

Gets the day of the month (1-31).

For example:

timestamp("2024-03-15T10:30:00Z").getDate()                         // gives you: 15 (the 15th day)
timestamp("2024-03-01T02:00:00Z").getDate("America/New_York")      // gives you: 28 (Feb 28)
createdAt.getDate()                                                 // gets day from createdAt

getDayOfWeek() Get the day of week

Gets the day of the week.

For example:

timestamp("2024-03-15T10:30:00Z").getDayOfWeek()                    // gives you: 5 (Friday)
timestamp("2024-03-17T02:00:00Z").getDayOfWeek("America/New_York") // gives you: 6 (Saturday)

// Remember: Sunday=0, Monday=1, Tuesday=2, Wednesday=3,
//           Thursday=4, Friday=5, Saturday=6

getHours() Get the hour

Gets the hour from a time (0-23, where 0 is midnight and 23 is 11 PM).

For example:

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

getMinutes() Get the minutes

Gets the minutes from a time (0-59).

For example:

timestamp("2024-03-15T14:45:00Z").getMinutes()                      // gives you: 45 minutes
timestamp("2024-03-15T14:45:00Z").getMinutes("America/New_York")   // gives you: 45 minutes
duration("2h30m").getMinutes()                                      // gives you: 150 (total minutes)

getSeconds() Get the seconds

Gets the seconds from a time (0-59).

For example:

timestamp("2024-03-15T14:45:30Z").getSeconds()                      // gives you: 30 seconds
timestamp("2024-03-15T14:45:30Z").getSeconds("America/New_York")   // gives you: 30 seconds
duration("2h30m45s").getSeconds()                                   // gives you: 9045 (total seconds)

Working with time periods

The following functions allow you to create and work with durations (lengths of time).

➡️ To learn more, check CEL Durations.

duration() Create a time period

Creates a duration representing a length of time (not a specific date).

For example:

duration(3600)              // creates: 1 hour (3600 seconds)
duration("1h30m")           // creates: 1 hour and 30 minutes
duration("90s")             // creates: 90 seconds
duration("2h")              // creates: 2 hours

Time period format: You can use h for hours, m for minutes, s for seconds. Combine them like “1h30m15s”.

Text functions

The following functions allow you to work with text (strings).

➡️ To learn more, check CEL String Functions.

contains() Check if text contains something

Checks if a piece of text is inside another piece of text.

For example:

"hello world".contains("world")     // gives you: true (found it!)
"hello world".contains("xyz")       // gives you: false (not found)
status.contains("active")           // checks if status contains "active"
contact.email.contains("@")         // checks if email has @ symbol

startsWith() Check if text starts with something

Checks if text begins with specific characters.

For example:

"hello world".startsWith("hello")           // gives you: true
"hello world".startsWith("world")           // gives you: false (starts with "hello" not "world")
contact.email.startsWith("admin")           // checks if email starts with "admin"
status.startsWith("pending")                // checks if status starts with "pending"

endsWith() Check if text ends with something

Checks if text finishes with specific characters.

For example:

"hello world".endsWith("world")             // gives you: true
"hello world".endsWith("hello")             // gives you: false (ends with "world" not "hello")
contact.email.endsWith("@example.com")      // checks if email domain is @example.com
status.endsWith("_approved")                // checks if status ends with "_approved"

matches() Check if text matches a pattern

Checks if text matches a pattern (uses regular expressions - advanced feature).

For example:

// Check if text looks like an email
"test@example.com".matches("^[a-zA-Z0-9+_.-]+@[a-zA-Z0-9.-]+$")    // gives you: true
"not-an-email".matches("^[a-zA-Z0-9+_.-]+@[a-zA-Z0-9.-]+$")        // gives you: false

// Validate email format
contact.email.matches("^[a-z]+@[a-z]+\\.[a-z]+$")                   // checks email format

trim() Remove characters from both ends

Removes specific characters from the start and end of text (like removing spaces).

For example:

trim("  hello  ", " ")      // gives you: "hello" (removed spaces)
trim("###test###", "#")     // gives you: "test" (removed # symbols)
trim("___name___", "_")     // gives you: "name" (removed underscores)
trim("000123000", "0")      // gives you: "123" (removed zeros)

ltrim() Remove characters from the left (Start)

Removes specific characters only from the beginning of text.

For example:

ltrim("  hello  ", " ")     // gives you: "hello  " (spaces removed from left)
ltrim("###test###", "#")    // gives you: "test###" (# removed from left)
ltrim("000123", "0")        // gives you: "123" (zeros removed from left)

rtrim() Remove characters from the right (End)

Removes specific characters only from the end of text.

For example:

rtrim("  hello  ", " ")     // gives you: "  hello" (spaces removed from right)
rtrim("###test###", "#")    // gives you: "###test" (# removed from right)
rtrim("123000", "0")        // gives you: "123" (zeros removed from right)

Math functions

The following functions are for mathematical calculations.

➡️ To learn more, check CEL Numeric Functions.

abs() Get absolute value

Removes the negative sign from a number (makes it positive).

For example:

abs(-5)                     // gives you: 5
abs(10)                     // gives you: 10 (already positive)
abs(-100)                   // gives you: 100
abs(0)                      // gives you: 0

round() Round to nearest whole number

Rounds a decimal number to the nearest whole number.

For example:

round(3.7)                  // gives you: 4 (rounds up)
round(3.2)                  // gives you: 3 (rounds down)
round(3.5)                  // gives you: 4 (exactly halfway rounds up)
round(-2.5)                 // gives you: -2
round(amount)               // rounds the amount variable

roundUp() Always round up

Always rounds up to the next whole number (ceiling).

For example:

roundUp(3.2)                // gives you: 4 (rounds up even though close to 3)
roundUp(3.9)                // gives you: 4
roundUp(3.0)                // gives you: 3 (already whole)
roundUp(-2.5)               // gives you: -2

roundDown() Always round down

Always rounds down to the previous whole number (floor).

For example:

roundDown(3.8)              // gives you: 3 (rounds down even though close to 4)
roundDown(3.2)              // gives you: 3
roundDown(3.0)              // gives you: 3 (already whole)
roundDown(-2.5)             // gives you: -3

min() Find the smaller number

Returns the smaller of two numbers.

For example:

min(5, 10)                  // gives you: 5 (smaller number)
min(-3, 2)                  // gives you: -3 (negatives are smaller)
min(age, 100)               // gives you: whichever is smaller, age or 100
min(3.5, 5)                 // gives you: 3

Use case: min(age, 65) ensures age doesn’t exceed 65.

max() Find the larger number

Returns the larger of two numbers.

For example:

max(5, 10)                  // gives you: 10 (larger number)
max(-3, 2)                  // gives you: 2
max(age, 18)                // gives you: whichever is larger, age or 18
max(3.5, 5)                 // gives you: 5

Use case: max(age, 18) ensures age is at least 18.

List and map functions

The following functions allow you to work with lists (ordered collections) and maps (key-value pairs).

➡️ To learn more, check CEL Lists and CEL Maps.

size() Count items

Counts how many items are in a list, map, or how many characters in text.

For example:

size([1, 2, 3])             // gives you: 3 (three items in list)
[1, 2, 3].size()            // gives you: 3
partners.size()             // gives you: how many partners you have
size({"a": 1, "b": 2})      // gives you: 2 (two key-value pairs)
addresses.size()            // gives you: how many addresses you have
size("hello")               // gives you: 5 (five letters)
"hello".size()              // gives you: 5
contact.email.size() > 5    // checks if email is longer than 5 characters

in() Check if item exists

Checks if a value exists in a list or if a key exists in a map.

For example:

5 in [1, 2, 3, 4, 5]                            // gives you: true (5 is in the list)
10 in [1, 2, 3]                                 // gives you: false (10 is not in list)
"active" in ["active", "pending", "completed"]  // gives you: true
"name" in {"name": "John", "age": 30}           // gives you: true (key "name" exists)
"email" in {"name": "John", "age": 30}          // gives you: false (no "email" key)
"home" in addresses                             // checks if "home" address exists

Our recommendations for beginners

To learn more, check: 

• CEL Language Definition - Complete language guide
• CEL Intro Tutorial - Getting started with CEL
• CEL Best Practices - Tips and patterns

Understanding data types

To learn more, check CEL Type System.

• Text (string): Words and sentences, always in quotes: "hello"
• Numbers (int): Whole numbers without quotes: 42
• Decimals (double): Numbers with decimal points: 3.14
• True/False (bool): Just true or false, no quotes
• Lists: Multiple items in brackets: [1, 2, 3] or ["a", "b", "c"]
• Maps: Key-value pairs in curly braces: {"name": "John", "age": 30}

Using member functions (dot notation)

Some functions are called using a dot (.) after the value:

"hello".contains("e")           // Check if "hello" contains "e"
[1, 2, 3].size()                // Count items in list
timestamp("2024-01-01T00:00:00Z").getFullYear()  // Get year from date

Using regular functions

Other functions wrap around the value:

int("123")                      // Convert text to number
round(3.7)                      // Round decimal to whole number
min(5, 10)                      // Find smaller number

Combining functions

You can nest functions inside each other:

string(round(3.7))              // First rounds 3.7 to 4, then converts to "4"
int(duration("1h"))             // Converts 1 hour to 3600 seconds

Time zones

Some date functions accept a timezone (like “America/New_York” or “Europe/Paris”):

createdAt.getHours()                    // Gets hour in UTC (universal time)
createdAt.getHours("America/New_York") // Gets hour in New York time

Remember

• Months start at 0: January is 0, December is 11
• Days of week start at 0: Sunday is 0, Saturday is 6
• Hours use 24-hour format: 0 is midnight, 13 is 1 PM, 23 is 11 PM
• Use quotes for text: "hello" not hello
• No quotes for numbers: 42 not "42"

⏭️ What's next?

• CEL Official Documentation
• Language Reference
• CEL Playground

🤔 ¿Tiene alguna duda?

Si tiene alguna pregunta, no dude en ponerse en contacto con nuestro equipo de asistencia mediante la creación de un ticket desde su cuenta. Si todavía no tiene una cuenta, puede ponerse en contacto con nosotros aquí.

Si necesitas ayuda con un proyecto usando Brevo, podemos ponerte en contacto con la agencia partner de Brevo adecuada.