Basics of Coda formulas

Learn the core concepts you'll need to get started with formulas, Coda's formula builder, and more

Updated over a week ago

With hundreds of formulas to offer, the Coda formula language is the key to unlocking endless possibilities as you build out your docs. From calculations to automations, it’s part of the secret sauce that makes Coda super powerful.

This article will help you develop a strong foundation and understanding of the Coda formula language and get you up and running with a few key formulas. Get ready to level up your productivity and make magic happen with Coda’s Formula language! 🚀

# The Coda Formula Language explained

The Coda formula language is similar to spoken or written words; it's a language. This means that although there are rules to improve efficiency and comprehension, there is no one specific way to accomplish anything.

For example, a greeting could look like:

• Hello!

• Hey there!

• Greetings, fellow Coda user!

All different greetings, but they accomplish the same thing. If you think of all the ways to greet someone, some of them are longer, and some are more efficient, and some might make more sense given the context of where you are and who you’re interacting with.

So when working with the Coda formula language, you’ll have your way of writing it, which might differ from the way other Makers write their formulas, and that’s okay!

The other thing to remember is that you don’t need to know every word in the dictionary in order to be a proficient speaker.

The same goes for the Coda formula language. You don’t need to know every formula to be successful, but we do have our formula dictionary should you ever need it 🧠

# Breaking down a Coda formula

Coda formulas are made up of two major components: Objects and Functions.

To stay with our language analogy, you can think of Objects as Nouns, and Functions as Verbs.

### Nouns = Objects

If you’ve ever used Excel or Google Sheets, you may be used to using coordinates to pinpoint a cell. In Coda, all objects have names. No coordinates needed! Simply type the name of the object you want to reference.

Objects hold the data we want to work with:

• A table is an object

• A column is an object

• A row is an object

### Verbs = Functions

Functions are things that we want to do to the given object:

• `Filter()` - filter the given dataset down based on specific criteria

• `Count()` - count the given dataset

• `ToText()` - convert the given dataset to plain text values

# Formula Chips

When we click on `Fruit` chip in this formula example above, we can see that this is an option in the `Fruit or Vegetable` column in the `Produce` table.

### Color coding tells you the location

Formula chips of the same color mean that those objects are located in the same table:

Take a look at the example above. Based on the color of the chips, you can see that `Produce` and `Fruit or Vegetable` are part of the same table, and `thisRow.Category` is part of the `Categories` table.

### Icons tell you the type of data, and how many

Take a look at the reference below. These icons will be at the far-right of each chip in your formulas, and will note what type of data you are working with.

The icon will also tell you whether you are referencing a singular value vs a list of values, or an array of values — a list or array is more than one value. Notice the “stacked” icons for lists:

# Formula Syntax

The Coda formula language is a little bit Excel, a little bit JavaScript. What we mean by that is that you can choose to use the wrapping method, or the chaining method while writing your formulas.

In Excel’s formula language, you use a lot of parentheses:

`Modified(thisDocument)`

This is called wrapping. This syntax is totally valid in the Coda formula language, but as your formulas become longer and more complex, this method can become a bit difficult to read as the number of parentheses increases.

In Coda, you can also get the same answer this way:

`thisDocument.Modified()`

This is called chaining. The chaining method allows you to write your formulas in a more sentence structured way, similar to JavaScript syntax.

Either way works! It all comes down to personal preference and what feels best to you!

## Parentheses

Things inside of parentheses can be viewed as one statement, or one sentence. Coda is going to look at that one statement and evaluate it as a whole.

In lengthy formulas, parentheses will help note where one sentence ends and the next begins. You can click on a parenthesis to see it’s highlighted pair. This will show you where your sentence begins and ends.

Additionally, just like in math problems, you'll use parentheses to separate multiple `AND` and `OR` functions so that all of your calculations happen in the right order. Coda will calculate anything inside of a parentheses first:

`(2*2)/(4+4) = .5`

In the example above, we will execute `2*2` and `4+4` before doing the division.

In the same way, use parentheses to specify how multiple `AND` or `OR` functions should be grouped.

By default, the formula applies the logic from left to right in the order that it appears. If you want to specify a specific order, just use parentheses 😉

## The Dot Operator

With the help of the Dot Operator, you can using the chaining method to write formulas for better readability.

Chaining separates steps in your formula by using a dot operator which is just a fancy descriptor for a `.`

At its most basic level, chaining looks like this:

# The Formula Builder

Coda’s formula builder is where you will write all your formulas, whether they are located in a table or directly on the canvas.

### Open up the formula builder

There are two main ways you’ll access the formula builder — either directly on the canvas or in a table column:

To open the formula builder on the canvas:

1. click anywhere on your page canvas and type `=`

💡 Trying to type `=` and not open the formula builder?

Press `Esc` on your keyboard to exit the formula builder and keep the `=` character on your canvas.

To open the formula builder in a specific table column:

1. Navigate to the column you want to add a formula to.

2. Right click on that column to open up the column menu, or click on the column-type icon to access the column menu

3. Click Calculate to open up the calculation builder

4. In the lower left corner of the menu, click on the small cursive f to open the formula builder for that specific column.

💡 Once your cursor is inside the formula builder, you do not need to type `=` at the beginning of your formula.

### Auto-suggestions, Formula Details, and Errors

Coda’s formula builder tries to make writing formulas as easy as possible for you. Here’s a few cool things within the formula builder that will help you in writing great formulas for your docs:

• As you write your formula in the formula builder, Coda will provide you with auto-suggestions for the data you might be trying to target with your formula.

• To the right of the list of auto-suggestions, if you select a formula rather than a table or column, you can access the details of a formula like the correct inputs, expected outputs, and examples on how to use them.

### Expanding the editor and auto-formatting

If you’re writing a formula and feel like you want a little more space to work, you can expand the formula builder to a modal view:

1. Open the formula builder

2. Click the Expand icon in the bottom-right corner of the formula builder.

In the expanded view modal, you now have the option to auto-format your formula for clarity.

To do so, click auto-format in the top-right corner of the expanded formula builder modal:

# The top 5 formulas you need to know

There are five formulas in the Coda formula language you’ll use in doc after doc after doc. Let’s add these MVP formulas to your toolbox.

## Filter

You’ll use the Filter formula when you want to look at part of a table to answer a question. The criteria for this formula can be as simple or as complex as you need.

The basic structure of filter is:

`[Table you want to look at].Filter([Part of the table you are interested in]).[What you want Coda to do with this piece of data] `

## User

The User() formula simply returns the user’s name. In your Coda doc, open the formula builder in the canvas and add this:

`User()`

Then hit Enter. This should now display your name!

Next try this:

`Concatenate("Welcome to Coda ", User(), ". Have a lovely day!")`

The `User` object in Coda holds a few key pieces of information:

• The user’s name

• The user’s Coda avatar (photo)

You can use the Dot Operator to access these pieces of information held within the user object. Try out the following in your Coda doc:

• `User().Name`

• `User().Email`

• `User().Photo`

Beyond using this formula for custom greetings, you can use it to:

## thisRow

In Excel, the smallest unit is a cell. Since Coda is a database at heart, the smallest unit is a row. Working with rows, we're able to access all of the contextual details for each value (aka columns or attributes of the row).

Additionally, it gives you the ability to take all of the contextual details of an item with you, and the ability to use thisRow to focus your formulas.

Because rows always travel together, you can use the `thisRow` formula component to do a few things within your formula, and you can combine this with the Dot Operator to show more of the context:

## Contains

The Contains formula checks if a list contains a specified value. If the value is found, it returns true:

`List("Dog", "Giraffe").Contains("Cat", "Mouse", "Dog") = true`

Additionally, with multi-select columns where you might have multiple values in that column for a given row, `Contains()` will be your best friend, especially combined with the `Filter()` formula!

## If and SwitchIf

The If() formula
The If formula allows you to handle `if/then` logic. The basic structure of the `If()` formula is as follows:

`If(Condition, What you want to happen if this condition is true, What you want to happen if this condition is false)`

The SwitchIf() Formula

The SwitchIf formula lets you get a value conditionally. It handles multiple conditions with a fallback.

💡 You can use the `SwitchIf()` formula instead of long `if/then` statements with the `If()` formula.

The basic structure of the `SwitchIf()` formula is as follows:

`SwitchIf(Condition, What you want to happen if Condition 1 is true, Condition 2, What you want to happen if Condition 2 is true, Condition 3, What you want to happen if Condition 3 is true, ...)`

`SwitchIf()` Outputs the first value where condition is true and exits the formula. If the first condition is false, it cycles through the rest of the conditions until it finds a true condition. If none of the conditions are true, it outputs an optional final value.

For example:

`SwitchIf(Today() > Date(2030, 01, 20), "Hello future!", Year(Today()) = 2023, "Hello present!", Today() < Date(2023, 17, 07), "Hello past!")`

# FAQs

## What is the “dot operator?”

With the help of the Dot Operator, you can using the chaining method to write formulas for better readability.

Chaining separates steps in your formula by using a dot operator which is just a fancy descriptor for a `.`

## What other operators can I use in my formulas besides the Dot Operator?

• Equal to: `=`

• Not equal to: `!=`

• Less than: `<`

• Greater than: `>`

• Less than or equal to: `<=`

• Greater than or equal to: `>=`

• And: `&&` or `AND` *(not case-sensitive)

• Or: `||` or `OR` *(not case-sensitive)

## What is a formula chip, and how do I read it?

Chips represent the objects you are referencing and pulling information from in your formula. When you click on a chip, you can learn more about that specific Object.

## Can I auto-format my formulas?

Yes! Auto-formatting is an option in the expanded view of the formula builder. Once you’ve expanded the editor, click auto-format in the top-right corner.

## Can I expand the formula builder to make the writing surface larger?

Yes! If you’re writing a formula and feel like you want a little more space to work, you can expand the formula builder to a modal view:

1. Open the formula builder

2. Click the Expand icon in the bottom-right corner of the formula builder.

Yes! In the formula builder, use `//` before one-line comments, or wrap your longer (more than one line) comments in `/*` and `*/`:

`// This is an example of a one-line comment.`

`/* This is an example of a much longer comment. These are great to use to help others in your doc understand what a particular formula is doing, or to simply remind yourself while you learn! */`

## Can I add formulas to the canvas, or can I only use them in Tables?

You can use formulas in both the canvas and in tables 💥

## Can I name a formula I’m going to use multiple times so I don’t have to re-write it?

Yes! As you start building out your docs, you may find that you want to use one of your handy formulas in multiple places.

Rather than having to copy/paste, or remember your work, you can name a formula and use it like a doc variable.

You can name your formula by clicking Add Name in the Formula Builder above where you’ve written your formula.

## What are some best practices for writing formulas?

Check out this article for best practices for writing formulas, and be sure to check out the resources linked below!