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

# Spreadsheet

> Collaborative spreadsheet attached to a record or page.

## Overview

Spreadsheet embeds a Custral spreadsheet on a record or page. Cells, formulas, formatting: same model as a standalone spreadsheet, just embedded.

## Configuration

| Setting              | What it does                                                      |
| -------------------- | ----------------------------------------------------------------- |
| Spreadsheet property | The record property the spreadsheet attaches to (in record mode). |

## Record vs standalone mode

Same two modes as Notes and Whiteboard: attach the spreadsheet to a property so each record keeps its own sheet (record mode), or leave the property unset so the sheet belongs to the page itself (standalone mode).

## Custral formulas

Alongside the standard spreadsheet functions, cells can pull current data from your workspace with the `CUSTRAL.*` formulas. They read your workspace each time the sheet opens, so reopening or reloading always shows fresh values. While the sheet stays open, formulas that read the same object share one request, and an open sheet does not refresh itself. Use the **Reference Records** button (bottom bar) if you'd rather paste a static snapshot instead.

| Formula                                            | What it returns                                                                                                                 |
| -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `CUSTRAL.OBJECTS("Contacts")`                      | Every record of an object as a table (header row + one row per record). Spills across cells.                                    |
| `CUSTRAL.RECORDS(record, "Email")`                 | A single field value for one record. `record` is a record ID (`rec_…`) or a record name (the most recently updated match wins). |
| `CUSTRAL.COLUMN("Deals", "Amount")`                | One column of values for all records, as a vertical array, e.g. `=SUM(CUSTRAL.COLUMN("Deals", "Amount"))`.                      |
| `CUSTRAL.LOOKUP("Contacts", "Email", A1, "Phone")` | The `Phone` of the first record whose `Email` matches `A1` (VLOOKUP-style).                                                     |
| `CUSTRAL.COUNT("Contacts")`                        | The number of records in an object.                                                                                             |

Object names, record names, and column names are all case-insensitive. The value `CUSTRAL.LOOKUP` matches on is compared exactly, including case, so `acme corp` does not match a record named `Acme Corp`. `CUSTRAL.RECORDS` returns the same value `CUSTRAL.OBJECTS` shows for that column.

<Note>
  `CUSTRAL.OBJECTS` replaces the former `CUSTRAL.RECORDS("ObjectName")`. `CUSTRAL.RECORDS` now reads a single field off one record, update any existing sheets that used the old name.
</Note>

### Troubleshooting

| Symptom                            | Cause / fix                                                                                                                                                                                                                                                                                                                 |
| ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Cell shows `#N/A` after "Loading…" | The lookup failed. Hover the cell for the reason. Most often the **object or record name doesn't match** (check spelling; only non-system objects are reachable by name) or the **column isn't an exportable property**, `notes`, `whiteboard`, `spreadsheet`, `formula`, `rollup`, and `relation` columns aren't returned. |
| `#VALUE!`                          | A required argument is missing (e.g. `CUSTRAL.RECORDS` with no column).                                                                                                                                                                                                                                                     |
| Wrong record returned by name      | Record names aren't unique, `CUSTRAL.RECORDS` returns the most recently updated match. Reference the record by its `rec_…` ID for an exact result.                                                                                                                                                                          |
| Data looks stale                   | Formulas read your workspace when the sheet opens and are not refreshed while it stays open. Close and reopen the sheet (or reload the page) to read current values, or insert anything with **Reference Records**, which clears the cache for every `CUSTRAL.*` formula on the sheet.                                      |

## Use cases

Quote line items on a Deal. Budget sheet on an Account. Custom forecast tables on a Project.

## See also

* [Spreadsheet property type](/data/properties/communication/spreadsheet)
* [Notes](/blocks/embedded/object/notes)


## Related topics

- [Spreadsheet](/data/properties/communication/spreadsheet.md)
- [Data Migration](/start/onboarding/migration.md)
- [Overview](/data/properties/communication/overview.md)
- [Notes](/blocks/embedded/object/notes.md)
- [Whiteboard](/blocks/embedded/object/whiteboard.md)