# Galdera Help

> Product guide for Galdera — concepts, workflows, and how the app works.

## Creating Metrics with the Formula Builder

A **metric** is a derived value — it isn't imported from a data source like a measure is. Instead, you define it with a formula that combines your existing measures and metrics.

To create one, go to the **Metrics** section of the [Targets](/targets/what-are-targets) page and click **Add**. The formula builder assembles the calculation from **operand chips** — the measures and other metrics the formula references — chained with operators from one family (all `+`/`−`, or all `×`/`÷`) plus plain numbers where needed (× 365, × −1). A metric can depend on both measures and other metrics, so you can layer calculations (for example, a margin metric built from revenue and cost measures, then a ratio built on top of that metric).

Each operand chip carries a **time shape**: this period (the default), previous period, same period last year, a trailing sum over N periods, year to date, or an average balance. This is how cross-period definitions like a depreciation rate (D\&A ÷ previous-period PP\&E) or DSO (AR ÷ trailing-12 Revenue × 365) are built. As you edit, a **sentence preview** below the builder shows the definition in words — that sentence is exactly what the formula means. See [How Metrics Are Calculated](/data-model/metric-calculations) for the rules.

Because a metric is defined by its formula, it **recalculates automatically** whenever its underlying inputs change — including when you apply an overlay to a measure it depends on. This is what lets an adjustment to a raw measure flow through to every metric built on it.

Measures, by contrast, aren't created here — they appear in the Measures section when you import data from your [Sources](/sources/what-is-source). For how calculations propagate through the model, see [Metric and Measure Dependencies](/data-model/dependencies).


### Targets

Managing the measures and metrics you forecast, and building metric formulas.

* [What Are Targets?](/targets/what-are-targets) — Targets is where you manage the measures and metrics you forecast; a "target" is any single measure or metric you pick to act on.
* [Creating Metrics with the Formula Builder](/targets/creating-metrics) — Metrics are derived values built from a formula that references measures and other metrics as operands, and they recalculate automatically when their inputs change.


## What Are Targets?

**Targets** is the area where you manage the things you forecast and track — your measures and metrics. Its purpose, as the page describes it, is to *manage your metrics and measures*.

The Targets page has two sections:

* **Measures** — raw data. Measures are created when you import data from your [Sources](/sources/what-is-source), so this section fills in as you connect data. Each measure card carries a **Type** toggle — **Flow** (amounts that sum over time, the default) or **Stock** (balances shown at period end, like Cash or PP\&E). See [Flows and stocks](/concepts/metric-vs-measure).
* **Metrics** — derived values calculated from a formula that references your measures and other metrics. See [Creating Metrics with the Formula Builder](/targets/creating-metrics).

For the conceptual difference between the two, see [Metrics vs. Measures](/concepts/metric-vs-measure).

#### "Target" as a term

Throughout Galdera, a **target** is any single measure or metric you select to act on — what an overlay applies to, or what a report or chart displays. In selection controls you'll see each option labeled with a **Measure** or **Metric** badge, and the picker prompts you to *Select targets…*. So when Galdera asks for a "target," it's asking which measure or metric you mean.


## Connecting a CSV Source

To bring data in from a CSV file:

1. **Create a new source** -- Click the add button and select **CSV** as your source type
2. **Upload your file** -- Select a .csv file from your computer (up to 250 MB)
3. **Wait for processing** -- Galdera reads your file and detects the columns. This usually takes 2-5 minutes.
4. **Map your columns** -- Once processing completes, you'll see a column mapping screen:
   * **Target columns**: Select which numeric columns contain the values you want to forecast (e.g., revenue, costs, headcount). Each becomes a **measure**.
   * **Dimension columns**: Select which categorical columns you want to slice data by (e.g., region, product, department). Each becomes a **dimension**.
   * **Date column**: Tell Galdera which column contains your dates (e.g., "month" or "date")
5. **Save** -- Galdera creates your measures and dimensions. You're ready to forecast.

**Tips:**

* Column names become measure and dimension names -- use clear, descriptive headers in your CSV
* Galdera auto-detects whether your data is in wide format (multiple numeric columns) or long format (one name column + one value column)
* If an upload fails, you can retry or restore to your last successful configuration


## Connecting a Databricks Source

A Databricks connector imports one shared table using OpenSharing. Your Databricks administrator shares the data, and the Galdera team connects that share to your workspace. Creating a connector in Galdera does not create the share.

#### Before you start

Ask your Databricks administrator and Galdera contact to arrange the share and recipient details for your workspace. Include the schema and tables you want to import. You need a table with a date column and numeric values to forecast.

If your workspace already has a share connected, you can use it for another table without repeating the external setup.

#### Set up the connector

1. Open **Connectors** and choose **Databricks** under **Data Warehouses**.
2. **Connect:** click **Check access**. Continue when the check succeeds. If the share is not ready, ask your administrator and Galdera contact to finish the setup. You can leave and return later.
3. **Choose data:** select a **Schema**, **Table**, and **Start date** for the history to import. The import ends at today. Check the sample preview to confirm you have the right table.
4. **Review columns:** confirm the date/index column, choose at least one target measure, and set the data frequency. Review inferred roles and any format questions before continuing.
5. **Import:** review the table, history, frequency, and measures, then click **Start import**. Galdera imports the data and applies your column choices automatically.

#### Return to an unfinished or completed connector

Setup choices are saved as you go. An unfinished connector resumes at the first incomplete step. An import already running shows its progress; you do not need to start it again.

If an import finds no rows, widen the start date and try again. If applying the column mapping fails after the data arrives, **Retry** applies the mapping without reading the shared table again.

Once setup finishes, open the connector to see its status and run history. Updates are manual: use **Sync now** for fresh data. To import another table, create another Databricks connector using the same workspace share.


## Connecting to Snowflake

Getting data from Snowflake into Galdera has two parts:

* **Part 1: Connect your Snowflake account.** This gives Galdera read-only access to a database in Snowflake. You enter a few details, your Snowflake administrator runs a setup script that Galdera creates, and you check that the connection works. You do this once.
* **Part 2: Import a table.** You choose a table or view, tell Galdera what each column means, and import the data. You repeat this for each table you want, using the same connection.

You never enter a Snowflake password in Galdera.

#### Before you start

You need:

* **Your Snowflake account URL**, such as `ab12345.snowflakecomputing.com`. Ask your Snowflake administrator if you are not sure.
* **The name of the database** that holds your data.
* **An existing Snowflake user (optional).** If your IT team has already created a Snowflake user for Galdera, get its name. Otherwise the script creates one called `GALDERA_SVC`.
* **Someone to run the setup script.** This is usually your IT or data team. If you are a Snowflake administrator yourself, you can run it.
* **A table or view with a date column** and the numbers you want to forecast.

#### Part 1: Connect your Snowflake account

##### Step 1: Create the setup script

1. Open **Connectors**.
2. Find **Snowflake** under **Additional connectors** and click **Connect**.
3. Enter the **Account URL** and **Database**. If your team already created a Snowflake user for Galdera, enter it under **Snowflake user (optional)**.
4. Click **Generate setup script**.
5. Click **Copy script**.

The setup script is specific to your connection, so it must come from Galdera. Your administrator cannot write it themselves.

##### Step 2: Have the script run in Snowflake

**If someone else manages Snowflake**, send them the script by email, chat, or ticket, and ask them to run it. The script is safe to share: it contains no passwords or secret keys. The section **For your Snowflake administrator** at the end of this page explains what it does, so you can send them this page too.

**If you manage Snowflake yourself**, open a SQL worksheet in Snowsight (Snowflake's web interface), paste the script, and run all of it. **For your Snowflake administrator** below lists the roles it needs.

You can close Galdera while you wait. The script is saved with the connection: to get it again, open **Connectors** and click **Continue setup** next to Snowflake.

##### Step 3: Check the connection

When the script has run, return to the Snowflake setup in Galdera and click **Test connection**. If the test fails, the message explains what to fix. See [Snowflake Syncs and Troubleshooting](/sources/manage-snowflake) for common errors.

When the test succeeds, your Snowflake account is connected. Galdera can now read the database, but no data has been imported yet.

#### Part 2: Import a table

##### Step 4: Choose the table

1. Click **Next** to open **Choose data**.
2. Choose a **Schema** and **Table**. The list shows the tables and views Galdera can read.
3. Choose a **Start date**: **Last 1 year**, **Last 2 years**, **Last 3 years**, or **Custom date**. The import runs up to today. Check the sample preview to confirm it is the right data.

##### Step 5: Map the columns

In **Review columns**, tell Galdera what each column means:

* The **date column** that orders the data in time.
* At least one **measure**: a numeric column to forecast, such as revenue or units.
* Any **dimensions**: columns to break the forecast down by, such as region or product.
* The **frequency** of the data, such as daily or monthly.

Galdera suggests a role for each column. Check them, and answer any questions about the table's layout.

##### Step 6: Import

In **Import**, review your choices and click **Start import**.

If the date range contains no rows, Galdera shows the dates it checked. Choose an earlier start date and import again.

Your progress is saved as you go. If you leave, setup reopens at the first step you have not finished. When the import is done, the table appears under **Tables** on the **Connectors** page. To refresh its data later, open it and click **Sync now**.

##### Import another table

You do not need to connect again. On the **Connectors** page, click **Add table**, choose your Snowflake connection under **Use a saved connection**, and enter the database the table is in:

* **A database you already connected:** go straight to Step 4.
* **A different database:** Galdera shows a short script that adds read access to that database. Have it run as in Step 2, check the connection as in Step 3, then continue with Step 4.

#### For your Snowflake administrator

This section is for the person who runs the setup script. It explains what each part of the script does and why, so you can review it before running it.

##### Summary

* **Roles needed:** `SYSADMIN` and `SECURITYADMIN`. The script switches between them itself.
* **Access granted:** read-only (`SELECT`) on one database. No write, delete, or administrative privileges.
* **Objects created:** one user, one role, and one X-Small warehouse, all prefixed `GALDERA_`.
* **Sign-in:** key pair only. The user has no password and cannot sign in to the Snowflake web interface.
* **Safe to re-run:** every statement either creates an object if it is missing or sets a value. Nothing is dropped or replaced.

##### What the script does, step by step

Your generated script contains these steps in this order. Its comments repeat the key points.

| Step | Runs as         | Statement                                                                                                                                             | What it does and why                                                                                                                                                                                |
| ---- | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 1    | `SYSADMIN`      | `CREATE WAREHOUSE IF NOT EXISTS GALDERA_XS_WH`                                                                                                        | Creates a dedicated X-Small warehouse that starts on demand and suspends after 60 seconds idle. Galdera's queries never compete with your workloads, and its cost shows separately on your bill.    |
| 2    | `SECURITYADMIN` | `CREATE ROLE IF NOT EXISTS GALDERA_READER`                                                                                                            | Creates the role that holds all of Galdera's privileges.                                                                                                                                            |
| 3    | `SECURITYADMIN` | `GRANT ROLE GALDERA_READER TO ROLE SYSADMIN`                                                                                                          | Places the role under `SYSADMIN`, as Snowflake recommends for custom roles, so your administrators can see and manage it.                                                                           |
| 4    | `SECURITYADMIN` | `CREATE USER IF NOT EXISTS GALDERA_SVC TYPE = SERVICE`                                                                                                | Creates a service user. `TYPE = SERVICE` users cannot have a password or sign in to the web interface.                                                                                              |
| 5    | `SECURITYADMIN` | `ALTER USER GALDERA_SVC SET … RSA_PUBLIC_KEY = '…'`                                                                                                   | Installs Galdera's public key and sets the user's default role and warehouse. This is a separate statement so it also applies when the user already exists, for example when you re-run the script. |
| 6    | `SECURITYADMIN` | `GRANT ROLE GALDERA_READER TO USER GALDERA_SVC` and `GRANT USAGE ON WAREHOUSE GALDERA_XS_WH`                                                          | Lets the user act as the role, and lets the role run queries on the warehouse.                                                                                                                      |
| 7    | `SECURITYADMIN` | `GRANT USAGE ON DATABASE …`, `GRANT USAGE ON ALL / FUTURE SCHEMAS …`, `GRANT SELECT ON ALL / FUTURE TABLES …`, `GRANT SELECT ON ALL / FUTURE VIEWS …` | Gives read access to the database. `ALL` covers what exists today. `FUTURE` covers tables and views created later, except in schemas that have their own future grants (see below).                 |
| 8    | —               | `DESC USER GALDERA_SVC`                                                                                                                               | Shows the user so you can confirm the key landed: `RSA_PUBLIC_KEY_FP` should show a fingerprint.                                                                                                    |

`SECURITYADMIN` runs everything after step 1: by default it can create users and roles, and it holds the `MANAGE GRANTS` privilege that the grants, including `FUTURE` grants, require.

##### Schemas with their own future grants

Snowflake applies future grants at one level only. If a schema already has future grants for tables (or views), for any role, those schema-level grants take precedence, and the script's database-level future grants are ignored for that object type in that schema. Tables and views that already exist are unaffected, because the `ALL` grants cover them. But `GALDERA_READER` won't be able to read new ones created in that schema.

To check a schema:

```sql
SHOW FUTURE GRANTS IN SCHEMA <DATABASE>.<SCHEMA>;
```

If it lists grants for `TABLE` or `VIEW`, add schema-level future grants for Galdera for the same object type:

```sql
USE ROLE SECURITYADMIN;
GRANT SELECT ON FUTURE TABLES IN SCHEMA <DATABASE>.<SCHEMA> TO ROLE GALDERA_READER;
GRANT SELECT ON FUTURE VIEWS IN SCHEMA <DATABASE>.<SCHEMA> TO ROLE GALDERA_READER;
```

See Snowflake's [rules for future grants on database or schema objects](https://docs.snowflake.com/en/sql-reference/sql/grant-privilege#future-grants-on-database-or-schema-objects).

##### Using a user your team already created

If your organization provisions its own service users, for example `SVC_GALDERA`, give that name to the Galdera user connecting Snowflake so they can enter it under **Snowflake user (optional)**. The generated script then uses your user instead of `GALDERA_SVC`:

* `CREATE USER IF NOT EXISTS` does nothing, because the user already exists.
* `ALTER USER` installs Galdera's public key and sets the default role and warehouse. It does not change the user's type, so an existing password or sign-in method stays as it is.
* The role, warehouse, and grants are the same as for `GALDERA_SVC`. Galdera always connects with the `GALDERA_READER` role.

Before running the script, check that the user's key slot is free: `DESC USER <your user>` should show no `RSA_PUBLIC_KEY_FP`. If another tool already uses that key, the script would replace it. Contact Galdera support instead. The ownership of the user matters too: the role that runs `ALTER USER` must own it, or be above the role that does.

##### Limiting access to one schema

By default the script grants read access to every schema in the database. To limit Galdera to one schema, edit step 7 before running the script: keep `GRANT USAGE ON DATABASE`, and replace the other six grants with the schema-scoped versions listed in the script's comments. Then choose a table from that schema in Galdera.

##### Network policies

Galdera always connects from one fixed IP address, shown at the top of the script. If a network policy applies to `GALDERA_SVC`, add that address to the policy's allowed list, keeping its existing entries. If the script shows no address, contact Galdera support for it before testing.

##### How the key is handled

Galdera generates the key pair when someone clicks **Generate setup script**. The script contains only the public half. The private half is stored in Google Secret Manager, is used only by Galdera's connector, and is never displayed or sent to anyone. To replace the key, use key rotation: see [Snowflake Syncs and Troubleshooting](/sources/manage-snowflake).

##### Check what Galdera can access

After running the script, you can confirm exactly what the role holds:

```sql
USE ROLE SECURITYADMIN;
SHOW GRANTS TO ROLE GALDERA_READER;
SHOW GRANTS TO USER GALDERA_SVC;
```

##### Other scripts Galdera may give you

* **Adding a second database:** a short script with only step 7 for the new database. Run it as `SECURITYADMIN`.
* **Key rotation:** a one-line `ALTER USER GALDERA_SVC SET RSA_PUBLIC_KEY_2 = '…'` that installs a new key alongside the current one. Run it as `SECURITYADMIN`.

##### Removing access

See **Disconnect / revoke access** in [Snowflake Syncs and Troubleshooting](/sources/manage-snowflake).

##### Snowflake documentation

* [Access control best practices](https://docs.snowflake.com/en/user-guide/security-access-control-considerations): why custom roles sit under `SYSADMIN`, and what `SECURITYADMIN` is for.
* [Key-pair authentication and key-pair rotation](https://docs.snowflake.com/en/user-guide/key-pair-auth): how Galdera signs in, and how the two key slots allow rotation without downtime.
* [Controlling network traffic with network policies](https://docs.snowflake.com/en/user-guide/network-policies): allowing Galdera's IP address.
* [GRANT privileges TO ROLE](https://docs.snowflake.com/en/sql-reference/sql/grant-privilege): the grants in step 7, including future grants.


### Sources

Bring historical data into Galdera from files, Databricks shares, and Snowflake tables or views.

* [What is a Source?](/sources/what-is-source) — Learn how files and live warehouse connections become measures and dimensions.
* [Connecting a CSV Source](/sources/connect-csv) — Upload a local file and map its columns.
* [Connecting a Databricks Source](/sources/connect-databricks) — Connect to a table shared from Databricks.
* [Connecting to Snowflake](/sources/connect-snowflake) — Connect your Snowflake account and import tables from it.
* [Snowflake Syncs and Troubleshooting](/sources/manage-snowflake) — Refresh data, rotate the key, and resolve connection or data errors.
* [Data Formats](/sources/source-data-formats) — Understand the wide and long layouts Galdera can ingest.
* [Source Status and Troubleshooting](/sources/source-status) — Read source states and recover from general import problems.


## Snowflake Syncs and Troubleshooting

A configured Snowflake source has **Status**, **Data**, and **Settings** tabs. Connection tests and data reads use the same stored key, Snowflake service user, and static Galdera egress IP, so a successful test checks the same route used by a sync.

For initial prerequisites and the generated Snowflake script, see [Connecting to Snowflake](/sources/connect-snowflake).

#### Run and monitor a sync

Snowflake syncs are manual today. Open the source's **Status** tab and click **Sync now** whenever you want fresh data. Scheduled sync controls are marked **Coming soon** and do not run unattended.

A sync reads the configured history window through the source's date column, stages the result in the workspace's tenant-isolated landing storage, and then processes it into Galdera. Galdera records each run in the source history. Only one run can be active for a source at a time; you can cancel an active run from its status line.

An unchanged sync does not duplicate existing data. New rows extend the current data contract. If columns were added or removed, the source changes to **Needs review**: open **Data**, check the column roles and frequency, then click **Confirm mapping**. A failed run remains in the run history with its reason and can be retried.

#### Test the connection

Use the magnifying-glass **Test connection** action on the source status line whenever you need to verify the connection. Before a table has been selected, the test checks that Galdera can sign in and see schemas. After setup, it also checks that the selected table or view can be read.

The result is stored with the connection and remains visible after a reload. A failed test can change the source status when the problem affects the whole connection, such as a rejected key or blocked network policy.

#### Resolve common Snowflake errors

**Your Snowflake network policy is blocking Galdera**

Add the exact Galdera `/32` address shown in the setup script or error message to the allowlist that applies to `GALDERA_SVC` (or the Snowflake user you entered when connecting). Preserve the policy's existing entries. Tests, browsing, previews, and syncs all use this same address.

**Snowflake rejected our key** or **Needs re-auth**

For a new connection, confirm that the generated setup script ran in the correct Snowflake account and set the key on `GALDERA_SVC`, or on the Snowflake user you entered. For a connection that worked previously, rotate its key from **Settings → Credentials**. A credential in **Needs re-auth** cannot be reused by a new source until it is repaired.

**No schemas are visible** or **the selected database is not visible**

The sign-in worked, but `GALDERA_READER` cannot see a data schema in that database. Re-run the database and schema grants from the setup script. Confirm that the database name belongs to the connected Snowflake account.

**The table is missing or not shared with us**

Snowflake can report the same error for a misspelled object and a missing grant. Check the schema, table or view name, including capitalization, then re-run the relevant `USAGE` and `SELECT` grants. Future grants cover newly created objects only when the generated grant statements were kept, and not in schemas that have their own future grants. See **Schemas with their own future grants** in [Connecting to Snowflake](/sources/connect-snowflake).

**The selected date column is missing, ambiguous, or has the wrong type**

Choose the date column from Galdera's picker and make sure it is a Snowflake DATE or TIMESTAMP column. Rename or cast it in a view if the source column has another type.

**This sync found no rows**

The connection worked, but no rows matched the displayed date window. Return to the setup fields, choose an earlier custom start date, and run the first sync again. For an existing source, also confirm that the date column contains values in the configured range.

**The connector is temporarily unavailable** or **the test timed out**

This usually means Galdera could not start or reach its connector runtime, or Snowflake did not answer in time. Retry after a short wait. If it continues, contact Galdera support with the source name and the time of the attempt; do not send private keys or credentials.

#### Rotate the Snowflake key

Key rotation applies to every source that reuses the same Snowflake account credential.

1. Open any affected Snowflake source and go to **Settings → Credentials**.
2. Click **Rotate key**.
3. Copy the generated script and run it in Snowflake as `SECURITYADMIN`. It installs the new public key in Snowflake's second key slot, so the current key continues to work during the change.
4. Return to Galdera and click **I've run it — switch to the new key**.
5. After Galdera confirms the new key is in use, you can remove the old key using the statement included in the generated script.

Do not remove the old Snowflake key before Galdera confirms the switch.

#### Disconnect / revoke access

Disconnecting a source in Galdera deletes the stored key once no other source uses it, but leaves the Snowflake objects in place. To revoke Galdera's access in Snowflake, run these statements:

```sql
USE ROLE SECURITYADMIN;
DROP USER GALDERA_SVC;
DROP ROLE GALDERA_READER;
USE ROLE SYSADMIN;
DROP WAREHOUSE GALDERA_XS_WH;
```

Dropping `GALDERA_SVC` stops every Galdera source on that Snowflake account at once.

If you connected with a Snowflake user your team created, replace `DROP USER GALDERA_SVC` with whatever your process requires: drop that user, or remove Galdera's key with `ALTER USER <your user> UNSET RSA_PUBLIC_KEY`.


## Data Formats

Galdera works with two data layouts and auto-detects which one you're using:

**Wide format** (also called pivot format):

* Each numeric column becomes its own measure
* Example: columns named "revenue", "costs", "units" create three separate measures
* Best when your spreadsheet has one row per time period with multiple value columns

**Long format:**

* One column contains the measure names, another contains the values
* Example: a "metric" column with values like "Revenue", "Costs", "Units" paired with a "value" column
* Best when your data comes from an ETL system or database export

**Dimensions work the same in both formats** -- any categorical column (like Region, Product, or Department) can be selected as a dimension during column mapping. Galdera creates dimension values automatically from the distinct entries in each column.

**Date column:**

* Galdera needs to know which column holds your dates for time-based forecasting
* Common names: "date", "month", "quarter", "period"
* Dates should be in a standard format (e.g., 2024-01-01 or Jan 2024)
* For Snowflake sources, select a native DATE or TIMESTAMP column; use a view to cast other representations before connecting them

#### Cohorted measures in chat

A file with more than one date column is a cohort file: one column is the cohort date and one the report date. The assistant does not create a source from a cohort file or load one into a source that is not set up for its cohort date. Set up a cohort source on the source page.


## Source Status and Troubleshooting

After you upload or connect a source, it goes through several stages:

* **Draft** -- Source created but no data uploaded yet
* **Uploading** -- Data is being processed in the background
* **Uploaded** -- Processing complete, ready for column mapping
* **Saved** -- Fully configured with measures and dimensions
* **Error** -- Something went wrong during processing

**If your source shows an error:**

* Check that your CSV file is properly formatted (valid CSV, not Excel .xlsx)
* For Databricks sources, verify the schema and table name are correct
* For Snowflake sources, use **Test connection** first. Follow the displayed fix for a blocked network policy, rejected key, missing grant, or unavailable object.
* You can **retry** the upload with a corrected file
* You can **restore** to roll back to your last successful configuration

**Re-ingesting data:**

* You can upload new data to an existing source to refresh it
* For a connected warehouse source, use **Sync now** to refresh it; scheduled syncs are not available yet
* Only one upload can run at a time per source
* Previous data versions are kept for reference


## What is a Source?

A **source** is where Galdera gets its raw data. Before you can forecast anything, you need to connect a data source so the platform knows what numbers to work with.

Galdera supports these source types:

* **CSV/Excel** -- Upload a file directly from your computer. Best for one-time imports or data exported from other tools such as an ERP or accounting system.
* **Databricks Open Sharing** (formerly Delta Sharing) -- Connect to a table shared from Databricks. Best for ongoing data that is already in your data platform.
* **Snowflake** -- Connect to a Snowflake table or view with a Galdera-managed key pair and read-only service user.

Each source creates **measures** (the numeric values you'll forecast, like Revenue or Units Sold) and **dimensions** (the categories you can slice by, like Region or Product Line).


## Associating Overlays with a Scenario

An overlay becomes part of a scenario through its **blocks**: each block in the overlay editor references exactly one scenario. The set of blocks (across any overlays) that reference the same scenario together define that scenario's assumptions.

To associate an overlay with a scenario:

* Open the **overlay** in the overlay editor
* In the block's settings, select the **scenario** it belongs to — blocks use the **Default** scenario unless you change it
* Different blocks in the same overlay may reference different scenarios if their assumptions belong to different cases

The association is recorded when the overlay runs — the run's results are tagged with each block's scenario name.

> **Current limitation:** there is no way to add or remove overlays from the scenario's side — there is no Scenarios page in the navigation. Scenario membership is always set per block, inside the overlay editor. Blocks always have a scenario — there is no "unassigned" state; an overlay you never re-tag simply runs under the Default scenario.


## Comparing Scenarios

All overlays share the same baseline forecast — the ML-generated prediction with no adjustments. Each overlay layers its changes on top of that shared baseline, and every block's results are tagged with its scenario name. Differences between scenario-tagged results are therefore attributable entirely to the overlay assumptions carrying that tag.

Comparisons let you answer questions like:

* "How does the Premium Merch overlay change gross margin versus baseline?"
* "What is the revenue range between our Upside and Downside assumption sets?"
* "Which assumption set drives the biggest swing in operating profit?"

You can explore these comparisons in charts and tables on the canvas, or ask the assistant directly — e.g., *"compare this overlay to baseline."*

> **Current limitation:** scenarios are not attached to Forecast Versions, and a forecast run does not fan out per scenario. Comparison works through overlay runs whose blocks are tagged with scenario names — the overlay is the unit that runs; the scenario is the label you group results by.


## Creating a Scenario

A scenario is a named label for a coherent set of planning assumptions. Before creating one, have a clear idea of what business situation it represents.

Every workspace starts with a built-in **Default** scenario, and every overlay block carries a scenario label: when you configure a block in the overlay editor, pick the scenario it belongs to. Blocks use **Default** unless you change them.

Name scenarios to reflect the planning assumption (e.g., "Base Case," "Aggressive Growth," "Cost Reduction") and add a description so teammates (and the assistant) know what the assumption set means.

> **Current limitation:** there is no standalone Scenarios page in the navigation, and the assistant cannot open one. A scenario does not attach to a Forecast Version; it takes effect through the overlay blocks that reference it.


### Scenarios

Working with what-if scenarios and comparing outcomes.

* [Creating a Scenario](/scenarios/create-scenario) — Scenario labels are picked per block in the overlay editor; every workspace starts with a Default scenario.
* [Associating Overlays with a Scenario](/scenarios/apply-overlays) — Overlay blocks reference a scenario in the overlay editor; that per-block choice is how an overlay becomes part of a scenario.
* [Comparing Scenarios](/scenarios/compare-scenarios) — Overlay results are tagged with each block's scenario name, so outcomes can be grouped and compared by assumption set.


## Building a Report

You build a report by choosing which measures and metrics it contains and what order they appear in. Give the report a title (the field starts as "Untitled Report"), then use the two-column selector.

**Available (left column)**

The left column lists every measure and metric in your workspace. Use the search box to filter them. Each item shows its type — Measures are marked with a database icon, Metrics with a calculator icon. Click an item to add it to the report. Items already in the report are greyed out and marked **Added**.

**Selected (right column)**

The right column shows the items currently in the report, numbered in the order they'll appear. From here you can:

* **Reorder** items by dragging them with the grip handle. The order here is the order rows appear in the report.
* **Remove** an item with its X button.

If the report is empty, the Selected column prompts you to click items on the left to add them.

Once your report has the right items in the right order, set how it's displayed — see [Viewing Report Data](/reports/report-data-and-versions).


### Reports

Saved collections of ordered measures and metrics, viewable across versions.

* [What Is a Report?](/reports/what-is-report) — A report is a saved, named collection of measures and metrics arranged in a chosen order, which you can view against any forecast version.
* [Building a Report](/reports/building-a-report) — Use the two-column selector to add measures and metrics to a report, then drag to reorder and remove items until it reads the way you want.
* [Viewing Report Data](/reports/report-data-and-versions) — Each report remembers a forecast version, time grain, and date range, and can also be embedded as a block with its own Configure Report panel.


## Viewing Report Data

A report doesn't just define which measures and metrics to show — it also remembers how to display them. This data-preview configuration is saved with the report and restored the next time you open it:

* **Version** — the forecast version whose numbers the report shows.
* **Grain** — the time granularity: daily, weekly, monthly, quarterly, or yearly. Monthly is the default.
* **Date range** — the window of time to display.

#### Embedding a report

A report can also appear as a block inside another document. When embedded, a **Configure Report** panel on the right lets you tune how that instance is displayed:

* **Report** — which saved report to show.
* **Version** — the forecast version, which can be inherited from the page it's embedded in.
* **Run** — a specific forecast run, or **Latest**.
* **Layer** — the current overlay when embedded on an overlay page (also inheritable from the page).
* **Scenarios** — one or more scenarios to include.
* **Filters** — dimension filters, shown as removable pills.
* **Display** — hide the title, set the grain and date range (presets or custom), switch actuals between **Actuals** and **Cleaned**, and **Truncate Actuals** to hide actuals at or after the forecast start.


## What Is a Report?

A **report** is a saved, named collection of the measures and metrics you want to look at together, arranged in an order you choose. Each report is its own entity with a title, and you manage your reports as a collection.

The phrase "ordered measures and metrics" describes a report's contents exactly: a report holds a list of items, where each item is either a **Measure** or a **Metric**, and each item has a display order that determines the order rows appear in. (For the difference between the two, see [Metrics vs. Measures](/concepts/metric-vs-measure).)

A report is reusable across your data. It stores a data-preview configuration — a forecast version, a time grain, and a date range — so you can view the same report against different forecasts and time windows. See [Building a Report](/reports/building-a-report) to create one and [Viewing Report Data](/reports/report-data-and-versions) for how it's displayed.


## Reusing an Overlay in Another Version

Overlays belong to a specific forecast version, but you don't have to rebuild one to use it elsewhere: **copy it into the target version**.

**How to copy:**

* In the sidebar, open the overlay's menu and choose **Copy to version…**
* Pick the target forecast version in the dialog
* Before anything is created, Galdera **checks the copy** and shows warnings if the target version is missing something the overlay references — for example a dimension value or scenario that doesn't exist there
* Confirm to create the copy

**What you get:**

* A copy of the overlay — blocks, operations, values, scoping — inside the target version, keeping the same name
* The copy is independent from there on: it runs and [locks](/overlays/saving-overlays) against the target version's own baseline, and edits to one copy don't affect the other

**Remember:** the target version needs its own [locked baseline](/forecasting/saving-forecasts) before the copied overlay can run there.


## Creating an Overlay

An overlay lets you adjust forecast values without changing the underlying model. Think of it as a "what-if" layer on top of your baseline forecast.

To create an overlay:

* **Name it** descriptively (e.g., "Q4 Pricing Increase" or "New Hire Ramp")
* **Choose a target**: Select the Measure or Metric the overlay affects (e.g., "Subscription Revenue" or "Headcount")
* **Choose an operation**: Scale (percentage change), Override (replace with a fixed value), or Offset (add or subtract an amount)
* **Set the value**: The adjustment amount. For Scale, enter the percentage change — 15 for +15%, -20 for -20%, or 0 for no change. For Override, the replacement value (e.g. 500000 for $500K). For Offset, the signed amount to add.
* **Set a date range**: When the adjustment applies -- overlays only affect forecast periods, never historical actuals

Each block in an overlay is tagged with a [Scenario](/concepts/what-is-scenario) — the built-in Default scenario unless you pick another — so run results can be grouped and compared by assumption set.

#### Cohorted measures in chat

A cohorted measure is loaded from a file with a cohort date and a report date. In both Ask and Agent mode, the assistant does not create or change overlays or input tables on cohorted measures, and does not describe an input table on a cohorted measure or cohort axis. Make those changes on the overlay page.


### Overlays

Creating and configuring forecast overlays (Scale, Override, Offset).

* [Creating an Overlay](/overlays/create-overlay) — An overlay lets you adjust forecast values without changing the underlying model. Think of it as a "what-if" layer on to….
* [Overlay Operations: Scale, Override, Offset](/overlays/overlay-operations) — Galdera supports three types of overlay adjustments, each suited to different planning scenarios.
* [Overlay Scoping: Date Ranges and Dimensions](/overlays/overlay-scoping) — Overlays can be scoped precisely to apply only where they are relevant -- both in time and across your business dimensio….
* [Locking an Overlay](/overlays/saving-overlays) — Lock a completed run to make it the overlay's official output for that forecast version.
* [Running an Overlay](/overlays/running-overlays) — Computes the impact of your adjustments on the baseline — requires the version's baseline to be run and locked first.
* [Reusing an Overlay in Another Version](/overlays/copy-to-version) — Copy an existing overlay into another forecast version instead of rebuilding it.


## Overlay Operations: Scale, Override, Offset

Galdera supports three types of overlay adjustments, each suited to different planning scenarios.

**Scale** raises or lowers the baseline forecast by a percentage. In the input table, type the percentage directly — "25" means +25%, "-10" means -10%, and "0" means no change.

* Example: entering "10" in a Scale cell on Subscription Revenue applies a +10% uplift across the selected period
* Useful for modeling growth rates, price increases, or volume changes

**Override** replaces the baseline forecast value entirely with a fixed number. Use this when you have a specific target or commitment.

* Example: Overriding Headcount to 250 for Q3 when you have a firm hiring plan
* Useful for budget commitments, contracted revenue, or known one-time values

**Offset** adds or subtracts a fixed amount from the baseline forecast. Use this for incremental adjustments.

* Example: An offset of +$200,000 on Marketing Spend to reflect a new campaign budget
* Useful for modeling specific dollar-amount changes on top of the existing plan

### A rate per period, or a total to spread? The Distribute toggle

For Override and Offset, the number you type is read as a **rate for the table's granularity** — "$500 per month", not a bare $500. The **Distribute** toggle decides what is done with that rate. The same number can differ by a large factor depending on which way it is set, so it is worth being deliberate.

**Distribute off** (the default) applies the rate to every period the overlay covers. $500/month across January to June adds $500 in each of the six months. If the forecast itself runs at a finer grain than the table, the rate is converted down — $500/month on a daily forecast lands roughly $16.44 a day.

**Distribute on** turns the rate into a single total and spreads it. $500/month across January and February is $1,000 in total, split across everything the overlay matches rather than added month after month.

"Everything the overlay matches" means the forecast rows inside its date range that pass its [dimension filters](/overlays/overlay-scoping) — across both time and dimension slices. Each row's share is proportional to its baseline value, so a product carrying 60% of the matched baseline absorbs 60% of the total. Where the matched baseline sums to zero there is nothing to divide proportionally, and the overlay contributes nothing.

Distribute is unavailable for Scale — a percentage has nothing to split.

The toggle sits in the input table's own settings, next to its granularity, and belongs to that table rather than to the overlay as a whole — an overlay holding two input tables can have it set one way on one and the other way on the other. To change it on an overlay that already exists, open the overlay and set it on the table itself.

* **"Hire 5 people a month through Q3"** → Offset, Monthly, Distribute off. Each month gets 5.
* **"We have $1M of extra marketing budget for the region this year"** → Offset, Yearly, Distribute on. The $1M lands once across the year, spread over the region in proportion to existing spend.


## Overlay Scoping: Date Ranges and Dimensions

Overlays can be scoped precisely to apply only where they are relevant -- both in time and across your business dimensions.

**Date range scoping** controls when the overlay takes effect. Every overlay has a start date; the end date is optional — leave it blank and the adjustment applies from the start date through the end of the forecast horizon, and keeps tracking the horizon if it is later extended. Set an explicit end date to pin the adjustment to a bounded window. Outside the effective range, the baseline forecast applies unchanged. This lets you model open-ended changes (a price increase "from January onward") as well as time-limited events like a promotional period, a seasonal adjustment, or a contract term.

**Dimensional scoping** lets you target specific slices of your business. For example, rather than scaling all Revenue up by 10%, you can scope the overlay to the "Enterprise" product line or the "Western" region only. You can filter by one or more Dimension Values.

**Pivot overlays** allow you to set different values for each time period or dimension combination within a single overlay -- for example, specifying different growth rates per month, or different pricing assumptions per region. This gives you fine-grained control without creating dozens of separate overlays.


## Running an Overlay

:::note[Beta: Agent mode]
Agent mode is in beta. Available actions depend on your workspace and permissions. If an action is unavailable, the assistant can explain how to do it in the app.
:::

Running an overlay computes the impact of your adjustments on the baseline forecast. Like forecast versions, this is done with the Play button and is a separate step from configuring the overlay.

**Prerequisites:**

* The overlay must have at least one block configured (target, operation, value, dates)
* **The version's baseline must be run and locked.** Every overlay belongs to a forecast version (shown in the breadcrumb at the top of the overlay page), and it computes against that version's official baseline — so the version needs a completed forecast run that has been [locked](/forecasting/saving-forecasts). If the baseline isn't locked yet, the run is rejected with "Forecast version must have a locked baseline before overlays can run."

**How to run:**

* Open the overlay document (from its version, or via the sidebar)
* Click the **Play button** (triangle icon) in the upper-right toolbar
* The status badge changes to "Running" while the computation executes (typically 2-5 minutes)
* When complete, the status changes to "Ready"

**Reviewing results:**

* Once ready, charts and tables update to show the overlay-adjusted forecast alongside the baseline
* You can see exactly how your adjustments change the numbers
* If the results aren't what you expected, edit the overlay configuration and run again

**You can re-run as many times as needed** while the overlay is unlocked. Each run replaces the previous results. To pin a run as the overlay's official result for this version, [lock it](/overlays/saving-overlays).

#### Run or cancel through the assistant

In Agent mode, name the overlay and its forecast version, ask to run it, and review Allow/Deny. The same prerequisites apply: valid saved configuration, an unlocked overlay and a locked baseline. The accepted run is observed in mounted chat; it is not reported as completed merely because it started.

To cancel, ask for the specific running overlay job. The assistant resolves its exact run identity before confirmation. The current overlay lifecycle records a cancelled run as failed; that status does not mean another run was cancelled. No new background continuation is promised after all observing pages close.


## Locking an Overlay

:::note[Beta: Agent mode]
Agent mode is in beta. Available actions depend on your workspace and permissions. If an action is unavailable, the assistant can explain how to do it in the app.
:::

After running an overlay and reviewing the results, **lock** the run to make it the overlay's official output for the forecast version it belongs to.

**How to lock:**

* After a successful run (status "Ready"), the **Lock toggle** in the toolbar becomes active
* Click it — that run is designated as the overlay's official result for this version

**What locking does:**

* Pins the completed run as the official overlay output that charts, comparisons, and reports read
* Prevents new runs for this overlay on this version while locked — the result stays stable
* Locking is per **overlay + version** pair: an overlay copied into another version is locked (or not) there independently

**To re-run a locked overlay**, unlock it first (the same toggle), run again, and lock the new result.

**Lock vs. Run — the key distinction:**

* **Run** = compute the overlay's impact (repeatable while unlocked)
* **Lock** = designate a completed run as the official output (reversible via unlock)

#### Lock or unlock through the assistant

In Agent mode, ask to lock a specific completed overlay run in its version, or unlock that overlay. Each action requires Allow/Deny. The server only locks a successful run belonging to that overlay/version and the version’s current locked baseline. A run from another baseline is refused. Unlocking does not start or cancel a run.


## Finding Entities in Galdera

Galdera organizes your financial model into distinct entity types — Metrics, Measures, Overlays, Scenarios, Dimensions, and Forecast Versions. Each entity type has its own section of the application where you can browse and manage items.

To find a specific entity:

* Use the **main navigation** to go to the relevant section (e.g., "Overlays" to see all overlays)
* Browse the list view to find the item you need
* Click into an entity to see its details, relationships, and narrative canvas

You can also ask the Galdera assistant directly: "Show me the Q4 Pricing overlay" or "Navigate to Gross Margin" — the assistant will open the entity in the UI for you. This is often faster than navigating manually, especially if you are not sure where something lives.


### Navigation

Finding and navigating to entities in the Galdera UI.

* [Navigating the Galdera UI](/navigation/navigating-ui) — The main sections of the Galdera interface correspond to the core entity types—….
* [Finding Entities in Galdera](/navigation/finding-entities) — Galdera organizes your financial model into distinct entity types — Metrics, Measures, Overlays, Scenarios, Dimensions, ….
* [Using Search](/navigation/using-search) — Galdera's search finds entities across all types by name; you don't need to know the exact name, since partial and fuzzy matches work.


## Navigating the Galdera UI

The main sections of the Galdera interface correspond to the core entity types:

* **Metrics & Measures**: Browse your financial data model, see formulas, and explore dependencies
* **Overlays**: Create and manage forecast adjustments; view each overlay's canvas with narrative documentation
* **Forecast Versions**: Manage forecast runs and set date horizons
* **Dimensions**: View the categorical breakdowns available for slicing your data
* **Analytics**: View forecast numbers, charts, and actuals-vs-forecast comparisons

The Galdera assistant can navigate you to any of these sections or to a specific entity's page. Just ask: "Take me to the Gross Margin metric" or "Open the Q2 2026 Forecast Version."


## Using Search

Galdera's search finds entities across all types by name. You don't need to know the exact name — partial and fuzzy matches work.

Tips for effective search:

* Search by business name (e.g., "merch revenue" rather than an internal identifier)
* If results are ambiguous, the assistant will clarify which entity you mean before acting
* Search works across Metrics, Measures, Overlays, Scenarios, Dimensions, and Forecast Versions simultaneously

The Galdera assistant uses search automatically when you mention an entity by name in conversation. You can also ask it to "find everything related to pricing" or "search for overlays targeting headcount" — it will surface relevant results across related entities.


### Getting Started

Galdera turns your historical data into an explainable forecast you can shape with your own assumptions. If you're new, this is the place to begin.

* **[Quickstart](/getting-started/quickstart)** — the end-to-end path in five steps: connect data → define what you track → run a baseline forecast → layer on assumptions → compare scenarios.
* **[Workspace & Access](/access-and-sso)** — connect SSO and manage people, roles, and permissions.

Once you've run through the quickstart, the rest of this guide goes deeper:

* **[Core Concepts](/concepts/what-is-overlay)** — the vocabulary: measures, metrics, overlays, scenarios, and forecast versions.
* **[Guides](/overlays/create-overlay)** — step-by-step workflows for sources, overlays, scenarios, forecasts, and reports.
* **[Using the App](/assistant/using-the-assistant)** — navigating the UI, reading analytics, the canvas, and the in-app assistant.


## Quickstart

This is the shortest path from an empty workspace to a forecast you can reason about. Each step links to a detailed guide.

:::steps
#### Connect a data source

Bring your historical data in by connecting a [Source](/sources/what-is-source) — a CSV/Excel file, a Databricks share, or a [Snowflake table or view](/sources/connect-snowflake). Your raw values arrive as **Measures**.

#### Define what you track

Open [Targets](/targets/what-are-targets) to see your Measures and to build **Metrics** — derived values calculated from a [formula](/targets/creating-metrics). Together, measures and metrics are the things you forecast.

#### Run a baseline forecast

Create a [Forecast Version](/concepts/what-is-forecast-version) and run it. Galdera produces a [baseline forecast](/forecasting/baseline-pipeline) from your history — no assumptions applied yet.

#### Layer on your assumptions

Add an [Overlay](/concepts/what-is-overlay) to encode business judgment — *"revenue grows 15% in Q3"* — using a Scale, Override, or Offset [operation](/overlays/overlay-operations).

#### Compare scenarios

Tag your overlay blocks with [Scenarios](/concepts/what-is-scenario) and [compare the outcomes](/scenarios/compare-scenarios) against the shared baseline to see how different assumptions change the picture.
:::

:::tip
You don't have to do this alone — the [in-app assistant](/assistant/using-the-assistant) can answer questions at any step, pull numbers for you, and walk you through creating overlays. In beta Agent mode, where available, it can also create overlays after your confirmation.
:::


## Sharing and permissions

Use **Share** to control access to the version, overlay, or document you are viewing.

#### Permission levels

* **Can view** lets a person open and read the asset.
* **Can edit** also lets them make changes and manage sharing.
* **No access** removes general workspace access to this asset. People with an individual grant may still have access.

Your own access is shown as a disabled control because you cannot change it from the asset's Share menu.

#### Share with a person

Search for a workspace member, choose **Can view** or **Can edit**, and select their name. You can change or remove their access later from the same menu.

#### General access

General access applies to everyone in your workspace. It is separate from access granted to individual people and can only raise access for this asset above the workspace default.

Workspace administrators can access all assets. A member with edit access can manage sharing for that asset.

#### Copy a link

**Copy link** copies the current asset URL. The link does not bypass permissions; recipients still need access to open it.


## How the Baseline Forecast Is Generated

The **baseline forecast** is the model's prediction with no user overlays applied. It is generated entirely from historical data using statistical and machine-learning models.

The baseline process:

1. **Ingest historical data** from your connected sources -- revenue, costs, headcount, and other Measures
2. **Select models** -- for each ML-forecast target, candidate models are evaluated against its history and the best fit is chosen
3. **Train and project** the Independent and Dependent targets across the forecast horizon defined by the Forecast Version
4. **Derive the configured lines** -- targets set to [Roll forward or Derived](/forecasting/configuring-a-forecast-version) are then computed period by period from the ML outputs and your actuals: stocks accumulate their flows from the last actual balance, derived measures evaluate their formulas (including previous-period references)

Derived lines are stored exactly like every other forecast value, so they appear in charts, tables, comparisons, and exports with no special handling -- and like everything else, they refresh when a run completes.

The baseline is your neutral starting point -- what the model expects to happen if current trends continue. Overlays and Scenarios then express your business judgment on top of that baseline. The final forecast output for any Scenario is the baseline plus all overlay adjustments that scenario includes.


## Configuring a Forecast Version

:::note[Beta: Agent mode]
Agent mode is in beta. Available actions depend on your workspace and permissions. If an action is unavailable, the assistant can explain how to do it in the app.
:::

A version’s settings live in its **Model Configuration** block on the Forecast Version document. Edits in the document save automatically. Three things must be configured before you can run.

#### 1. Select training data

In the **Configure Training Data** section, choose which **ingestions** (uploads/syncs from your sources) this version trains on. This is how you control which data a version uses — for example, a version that only looks at your Variable Costs source, or one that uses everything.

Each measure you forecast is tied to the ingestion that provides its history. When a measure comes from exactly one selected ingestion, Galdera assigns it automatically; otherwise pick it in the measure's row.

#### 2. Choose measures and their strategy

In the measure table, select which measures this version forecasts. Each selected measure has a **Strategy** — four to choose from:

* **Independent** (the default): the measure is forecast directly from its own history by the ML models.
* **Dependent (via Metric)**: the measure is *not* forecast directly. Instead, Galdera forecasts a **metric that decomposes it** and reconstructs the measure from that forecast. For example, forecasting *Streaming Revenue* dependently via *Revenue per Viewer* means the model forecasts the per-viewer ratio and rebuilds revenue as ratio × viewers — useful when the ratio is more stable or better understood than the raw measure. The picker only offers metrics that actually decompose that measure.
* **Roll forward**: for [stocks](/concepts/metric-vs-measure) — balances like PP\&E, inventory, or debt. The measure is not forecast by a model at all. Instead it starts from its **anchor** (the last actual balance) and accumulates the flows you pick as **terms**, each with a + or − sign (e.g. PP\&E = last actual + capex − depreciation). The pane shows anchor coverage so you can confirm every slice has a starting balance.
* **Derived**: the measure's forecast is computed each period from a formula over other targets, built with the same formula builder used for metrics — including references to the **previous period** (e.g. Additions = Capex × −1, or D\&A = PP\&E − previous-period PP\&E). Like Roll forward, a Derived measure is never an ML target.

Roll forward and Derived exist so balance-sheet and cash-flow lines can be forecast in a way that keeps the statements consistent: a stock's change always equals its flows. See [Modelling the Three Statements](/forecasting/three-statement-modelling) for a worked setup.

Two rules the configuration enforces:

* **At least one measure must remain Independent** — the run needs at least one ML-forecast target, so the other strategies are unavailable on the last Independent measure.
* **No same-period loops.** Definitions may reference each other across periods (that's how stocks accumulate), but a loop where every step is in the same period is rejected when you save, with the loop named so you can pick one direction.

#### 3. Set the date range

* **Training start**: how far back the model learns from history
* **Forecast start / end**: the prediction window

Forecast start and end are required before running, and the forecast window must come after the training start.

Once configured, see [Running a Forecast Version](/forecasting/running-forecasts).

#### Cohorted measures in chat

A cohorted measure is loaded from a file with more than one date column: a cohort date and a report date. Configure its forecast, including its cohort settings, on the forecast version page. In both Ask and Agent mode, the assistant:

* Does not add a cohorted measure to a version, change its forecast settings, or set cohort settings.
* Does not describe a cohorted measure's forecast configuration; it names the measure and points to the version page instead.
* In beta Agent mode, where available, can still change version-wide settings, such as the forecast dates, on a version that includes cohorted measures.

#### Configure through the assistant

In Agent mode, ask for a new named Forecast Version or a change to an existing version’s Model Configuration. For example: “In Annual Plan, change only the forecast end to December 31, 2027. Keep everything else and do not run it.” The assistant presents the resolved version and changes for Allow/Deny.

The server validates the resulting settings and references before saving. Unmentioned settings and canvas notes are preserved. Derived or roll-forward strategy changes can affect shared measure definitions; review the named effects in the confirmation. Saving configuration does not start a job. If an edit fails, the assistant must not run the old settings as a substitute.


## End-to-End Workflow: From Data to Signed-Off Forecast

Here is the complete linear workflow for producing a forecast in Galdera. Each step builds on the previous one.

**Step 1: Connect your data sources**

* Create a Source from a CSV/Excel file, Databricks share, or an enabled Snowflake connection
* Map columns to measures and dimensions
* Wait for ingestion to complete (status: "Active")

**Step 2: Create and configure a Forecast Version**

* Create a new Forecast Version
* [Configure it](/forecasting/configuring-a-forecast-version): select the training data (ingestions), choose the measures to forecast and their strategy (Independent, Dependent, Roll forward, or Derived), and set the date range
* For balance-sheet and cash-flow lines, see [Modelling the Three Statements](/forecasting/three-statement-modelling)

**Step 3: Run and lock the baseline**

* Click the **Play button** to run the baseline forecast
* Wait for the run to complete (status: "Ready") and review the baseline numbers
* Click the **Lock toggle** to designate the run as the version's official baseline
* Locking is what makes the baseline available for overlays and exports

**Step 4: Create and configure overlays**

* Create overlays under the version for your business assumptions (e.g., "Q4 Pricing Increase")
* In each block, set the operation (Scale, Override, or Offset), target measure/metric, values, date range, and the scenario the block belongs to
* Scope to specific dimensions if needed (e.g., only the "Enterprise" segment)

**Step 5: Run each overlay**

* Open the overlay (it runs against its version's locked baseline)
* Click the **Play button** to compute the overlay's impact
* Wait for the run to complete (status: "Ready")
* Review the adjusted forecast vs. the baseline

**Step 6: Lock each overlay**

* Click the **Lock toggle** to pin the run as the overlay's official output for this version
* Repeat for each overlay you want to finalize

**Step 7: Compare outcomes by scenario**

* Overlay results carry the scenario tags set on their blocks (e.g., "Base Case" vs. "Upside")
* Compare scenario-tagged outputs side-by-side to evaluate different planning assumptions

You can also work on multiple overlays in parallel -- steps 4-6 can be repeated independently for each overlay. The linear flow above is the simplest path from raw data to a signed-off forecast.


## Exporting a Forecast Version

**Export** takes a forecast version's numbers out of Galdera: as CSV files you download, as a publication to the consumer-facing tables that downstream integrations read, or both. It is a separate step from locking: [locking](/forecasting/saving-forecasts) designates the official baseline inside Galdera; exporting is how that locked set leaves.

**What gets exported — the locked set:**

* The version's **locked baseline** run
* Every overlay on the version that is **locked** and whose run was computed against that same locked baseline. An overlay locked against an older baseline is not part of the current locked set and is skipped.

**How to export:**

* Open the version and choose **Export** from the toolbar's overflow menu (the item reads "Exporting…" while in progress)
* Export requires a locked baseline — with nothing locked, the export is rejected
* The dialog offers two things, and you can pick either or both. **Download CSV files** gives you the numbers as files you download from the dialog. **Publish to warehouse** writes the locked forecast to your export tables, where downstream integrations pick it up. Pick at least one
* The forecast window applies to the CSV files only. It defaults to the version's full horizon; narrow it if you only need part of the forecast
* Progress shows in the dialog while the export runs. Closing the dialog does not stop the run
* When it finishes, the dialog confirms the warehouse publication and, if you asked for files, lists one download per source plus **Download all** for everything in one zip
* If the export fails, the dialog says why and offers **Retry export**, which re-runs the same request
* The dialog's address changes while it is open, so that link — or a reload — reopens the same export and its downloads
* The files for a completed export stay available for 30 days after the export runs. Nothing extends that. Reopening the dialog, downloading a file, and re-requesting the same export all reuse the files already there. Export again after 30 days and you get fresh files with a fresh 30 days
* Exported runs are marked in the version's run history

**Export does not freeze the version.** You can unlock, re-run, re-lock, and export again — an export always reflects the locked set at the moment you trigger it. If you move locks after exporting, the published data lags behind until you export again.


## Forecast Versions

A **Forecast Version** is a named, time-bounded forecast run. It defines:

* **Training start**: How far back the model looks at historical data to learn patterns
* **Forecast start**: When the prediction period begins (typically the current or next period)
* **Forecast end**: The horizon out to which predictions are generated

Versions are the top-level container for all your planning work. Overlays live inside a version (their blocks tagged with scenarios), and all forecast outputs are tied to a specific version. You might maintain a "Q2 2026 Rolling Forecast" version updated monthly, alongside a "FY2026 Annual Plan" version that is locked once approved.

Previous versions remain accessible for audit and comparison -- you can always go back and see what was forecast in a prior period and compare it to actuals.


### Forecasting

Forecast versions, baseline models, and running forecasts.

* [Forecast Versions](/forecasting/forecast-versions) — A Forecast Version is a named, time-bounded forecast run with training start, forecast start, and forecast end.
* [Configuring a Forecast Version](/forecasting/configuring-a-forecast-version) — Select training data, choose measures and their forecasting strategy (Independent or Dependent), and set the date range.
* [How the Baseline Forecast Is Generated](/forecasting/baseline-pipeline) — The baseline forecast is the model's prediction with no user overlays applied. It is generated entirely from historical ….
* [Running a Forecast Version](/forecasting/running-forecasts) — Running a forecast executes the computation pipeline that produces your baseline forecast numbers. This is a separate st….
* [Locking a Forecast Version](/forecasting/saving-forecasts) — Lock a completed run to make it the version's official baseline — locking is what enables overlays and exports.
* [Exporting a Forecast Version](/forecasting/exporting-forecasts) — Export publishes a version's locked set — the locked baseline plus its locked overlays — to the consumer-facing tables.
* [End-to-End Workflow: From Data to Signed-Off Forecast](/forecasting/end-to-end-workflow) — Here is the complete linear workflow for producing a forecast in Galdera. Each step builds on the previous one.


## Running a Forecast Version

:::note[Beta: Agent mode]
Agent mode is in beta. Available actions depend on your workspace and permissions. If an action is unavailable, the assistant can explain how to do it in the app.
:::

Running a forecast executes the computation pipeline that produces your baseline forecast numbers. This is a separate step from configuring your version -- configuration is instant, but computation takes a few minutes.

**How to run:**

* Open the Forecast Version document (see [Configuring a Forecast Version](/forecasting/configuring-a-forecast-version) for what must be set first)
* Click the **Play button** (triangle icon) in the upper-right toolbar
* The status badge will change from "Draft" to "Running" and show progress through two stages: data cleaning, then forecasting
* When complete, the status changes to "Ready" and you can view results in charts and tables

**Important:** Your data sources must be fully ingested (status "Active") before you can run. If any source is still processing, the run button will be disabled.

**When to re-run:**

* After changing the version's date range or training period
* After connecting new or updated data sources
* You can re-run as many times as needed while the version is unlocked

**What "Ready" means:** Your forecast results are computed and available for review. To make this run the version's official baseline — which is what enables overlays and exports — [lock it](/forecasting/saving-forecasts).

#### Run or cancel through the assistant

In Agent mode, ask to run a named version using its saved configuration, then review Allow/Deny. A locked version must be explicitly unlocked before rerunning. If you also requested configuration changes, those must save successfully before the run is proposed.

The response identifies the accepted run; acceptance does not mean completion. Chat observes that run while mounted, even with its version page closed. Reopening chat resumes the existing status handling; closing every observing page adds no background continuation guarantee. You can ask to cancel the specific run; cancellation requests do not guarantee it has already stopped. Running never implicitly locks the result.


## Locking a Forecast Version

:::note[Beta: Agent mode]
Agent mode is in beta. Available actions depend on your workspace and permissions. If an action is unavailable, the assistant can explain how to do it in the app.
:::

After running a forecast and reviewing the results, **lock** the run to make it the version's official baseline.

**How to lock:**

* After a successful run (status "Ready"), the **Lock toggle** in the upper-right toolbar becomes active
* Click it — the completed run is designated as the version's official (canonical) baseline

**What locking does:**

* Marks that specific run as the version's baseline — the numbers charts, tables, and analytics read
* **Enables overlays**: overlays can only run against a locked baseline
* **Enables export**: exporting requires a locked baseline
* Prevents re-running while locked — the baseline stays stable for the work built on top of it

**To re-run a locked version**, unlock it first (the same toggle). Unlocking clears the official-baseline designation — overlays that referenced it will need the new run locked before they can run again.

**Lock vs. Run — the key distinction:**

* **Run** = compute forecast numbers (repeatable while unlocked)
* **Lock** = designate a completed run as the official baseline (reversible via unlock)

#### Lock or unlock through the assistant

In Agent mode, ask to lock a specific completed baseline or to unlock a named version. The assistant discovers the exact run and presents Allow/Deny; the server refuses an unsuccessful run or one belonging to another version. Choosing a different baseline rebases layers and clears incompatible layer locks, which the confirmation discloses. Unlocking clears the baseline selection without cancelling jobs or clearing layer locks. A later run is a separate action.


## Modelling the Three Statements

Income-statement lines are flows the ML models can forecast directly. Balance-sheet and cash-flow lines are different: they are connected **across time** — a balance accumulates its flows, and cash-flow lines are the period-to-period change of balances. Forecasting each line independently would give you statements that don't tie. Galdera instead lets you declare those relationships, and derives the connected lines so that **every stock's change equals its flows, every period**.

Three ingredients, in order:

#### 1. Mark your stocks

On the [Targets](/targets/what-are-targets) page, set the **Type** toggle to **Stock** on every balance — PP\&E, Inventory, Debt, Cash. This makes quarters and years display the period-end balance rather than a sum. See [Flows and stocks](/concepts/metric-vs-measure).

#### 2. Define cross-period metrics where you need drivers

Ratios that drive reconstruction are ordinary [metrics](/targets/creating-metrics), built with time shapes. A depreciation rate, for instance: *D\&A ÷ previous-period PP\&E*. The formula builder's time-shape menu (previous period, trailing sum, year to date…) is what makes these expressible.

#### 3. Assign strategies in the version config

In [the version's measure table](/forecasting/configuring-a-forecast-version), give each statement line the strategy that matches how it behaves:

* Flows the business controls or the model can learn — **Independent** (ML), or ingested plans.
* Flows best explained by a ratio — **Dependent (via Metric)** on a driver metric.
* Stocks — **Roll forward**: last actual balance plus signed flow terms.
* Lines that are a formula of other lines — **Derived**, with previous-period references allowed.

### A worked example: PP\&E, Capex, and D\&A

The classic triangle, using only the pieces above:

| Line                       | Strategy               | Definition                                                   |
| -------------------------- | ---------------------- | ------------------------------------------------------------ |
| Capex                      | Independent            | forecast from its own history                                |
| PP\&E (Stock)              | Roll forward           | last actual + Capex − D\&A                                   |
| Depreciation rate (metric) | —                      | D\&A ÷ previous-period PP\&E                                 |
| D\&A                       | Dependent (via Metric) | reconstructed from the forecast rate × previous-period PP\&E |

The run forecasts capex and the depreciation rate, then walks forward period by period: each month's D\&A comes from the rate and last month's PP\&E, and PP\&E rolls forward with that month's capex and D\&A. The result: PP\&E's movement equals its flows exactly, so the P\&L's depreciation, the balance sheet's asset line, and the cash-flow statement's capex all tie.

The same pattern covers the other statement mechanics — Inventory rolling forward with change-in-inventory, Debt with drawdowns and repayments, interest expense driven by an average-rate metric on previous-period debt.

### What articulation guarantees — and what stays yours

The guarantee is per line: every stock you roll forward or derive always equals its own flows, period by period, including after an overlay runs. That is enforced by construction, not something you check by hand.

Galdera does **not** check that your whole balance sheet balances.

### Overlays on a three-statement model

Adjust the **drivers**, not the derived lines: a capex overlay flows through to PP\&E and downstream lines when the overlay runs. Derived and roll-forward lines can't be targeted by overlays directly — an asserted PP\&E with unchanged capex would break the very consistency the setup provides. Which lines you keep as drivers is a per-version choice: it *is* the choice of what's adjustable.

### Things the configuration checks for you

* **Anchors**: a roll-forward stock needs a starting balance in your actuals; the strategy pane shows anchor coverage per slice.
* **Direction**: a loop where every reference is same-period ("D\&A from PP\&E, PP\&E from D\&A, both this month") is rejected at save with the loop named — cross-period loops are fine, that's the mechanism working.
* **At least one Independent** target must remain — the run needs something for the models to forecast.


## Metric and Measure Dependencies

The dependency structure of your financial model describes which entities feed into which. Understanding dependencies helps you:

* Predict the downstream impact of an overlay before running the forecast
* Identify which Measures are the true "levers" for a given outcome
* Troubleshoot unexpected changes in a Metric's forecast values

**Upstream dependencies**: What feeds into a given Metric? For example, Gross Margin depends on Gross Profit, which depends on Revenue and COGS.

**Downstream impact**: What does a change to a Measure affect? For example, changing Subscription Revenue will flow through to Gross Profit → Gross Margin → Net Revenue Retention (if applicable).

Dependencies are not only metric formulas. A **measure** forecast with the [Roll forward or Derived strategy](/forecasting/configuring-a-forecast-version) depends on the measures in its definition — Capex feeds PP\&E, so a capex adjustment flows through to the balance-sheet line even though both are measures.

Two things worth knowing about cross-period definitions:

* The same input can appear at **two points in time** — Depreciation = PP\&E − previous-period PP\&E is one dependency read at two times, not two dependencies.
* Definitions may loop **across periods**: PP\&E accumulates depreciation, and depreciation is computed from last period's PP\&E. That loop is legal because it steps back one period each time around. A loop where every step is in the *same* period is rejected when you save.

You can ask the Galdera assistant to trace dependencies for any Metric or Measure — it will show you the full chain upstream and downstream.


### Data Model

How metrics are calculated, dependencies, and the forecast graph.

* [The Forecast Graph](/data-model/the-graph) — How Galdera models your data as a connected graph so it can instantly trace what any change affects.
* [How Metrics Are Calculated](/data-model/metric-calculations) — Metrics in Galdera are defined by formulas that combine Measures and other Metrics. The four supported operations are—….
* [Metric and Measure Dependencies](/data-model/dependencies) — Upstream and downstream dependency chains in the financial model.


## How Metrics Are Calculated

Metrics in Galdera are defined by formulas that combine Measures and other Metrics. A formula **chains any number of operators from one family**, evaluated left to right:

* **Additive**: `+` and `−` in any mix (e.g., Invested Capital = Debt + Equity − Cash)
* **Multiplicative**: `×` and `÷` in any mix (e.g., EBITDA Margin = EBITDA ÷ Revenue × 100)

The two families cannot be mixed in one formula — `Revenue + Units × 2` is rejected. When a calculation needs both, give the intermediate step its own metric with a name someone would say out loud (NOPAT = EBIT − Taxes on EBIT, with *Taxes on EBIT* defined first). Formulas can also include plain **numbers** (× 365, × −1 to flip a sign).

Each operand can reference a different **point in time**: this period, previous period, same period last year, a trailing sum over N periods, year to date, or an average balance. The same input may appear twice at different times — Depreciation = PP\&E − previous-period PP\&E is one measure read at two times, not two inputs. That is what makes balance-sheet and cash-flow formulas expressible.

You never type this as syntax: formulas are assembled visually, and every definition displays as a **plain sentence** (e.g., "DSO = Accounts Receivable ÷ Revenue (trailing 12 periods) × 365").

Metrics recalculate automatically when any of their inputs change — including when overlays adjust the underlying Measures. This means a 10% scale on Subscription Revenue will automatically flow through to Gross Profit, Gross Margin, and any other Metrics that depend on it. You do not need to manually update derived metrics.


## The Forecast Graph

Galdera models your financial data as a connected **graph** — every measure, metric, overlay, and scenario is linked to the others it relates to. This is what makes it possible to instantly answer questions like "what does this overlay affect?" or "what feeds into Gross Margin?"

The graph connects:

* **Measures** to the **Sources** they come from
* **Metrics** to the **Measures and Metrics** they depend on (with roles like numerator, denominator, addend)
* **Overlays** to the **Measures or Metrics** they target
* **Scenarios** to the **Overlays** they include
* **Dimensions** to the **Measures and Metrics** they slice

This connected structure means Galdera can traverse your entire model to show you the impact of any assumption change — across multiple hops, instantly, without you needing to manually trace formulas through a spreadsheet.


### Concepts

Core Galdera concepts — metrics, measures, overlays, scenarios, dimensions.

* [Metrics vs. Measures](/concepts/metric-vs-measure) — In Galdera, your financial data is organized into two distinct types— Measures and Metrics.
* [What Is a Dimension?](/concepts/what-is-dimension) — A dimension is a categorical attribute used to break down your Measures and Metrics. Common examples include Region (Nor….
* [What Is an Overlay?](/concepts/what-is-overlay) — An overlay is a user-defined adjustment to your forecast. Think of it as a "what-if" layer that sits on top of the model….
* [What Is a Scenario?](/concepts/what-is-scenario) — A scenario is a named collection of overlays that together represent a coherent planning assumption set. Common examples….
* [What Is a Forecast Version?](/concepts/what-is-forecast-version) — A Forecast Version defines the execution context for a forecast run. It specifies the time boundaries — when the model s….


## Metrics vs. Measures

In Galdera, your financial data is organized into two distinct types: **Measures** and **Metrics**.

A **Measure** is a raw value that comes directly from your data sources — things like Revenue, Units Sold, or Headcount. Measures are the building blocks of your financial model. They represent real observations from your business.

A **Metric** is a calculated value derived from one or more Measures (or other Metrics). Examples include Gross Margin (Revenue minus COGS), Revenue per Employee (Revenue divided by Headcount), or Net Revenue Retention. Metrics are defined by formulas and automatically update when their underlying Measures change.

Key distinction for forecasting:

* You apply overlays directly to Measures to change raw inputs
* Metrics recalculate automatically based on any upstream changes
* Understanding this relationship helps you target adjustments at the right level

#### Flows and stocks

Every measure is one of two types, set with the **Type** toggle on its [Targets](/targets/what-are-targets) card:

* A **Flow** is an amount *per period* — Revenue, Capex, Costs. Quarters and years show the **sum** of their months. This is the default.
* A **Stock** is a *balance at a point in time* — Cash, PP\&E, Inventory, Debt. Summing a balance across months is meaningless, so quarters and years show the **period-end value** instead.

The distinction matters everywhere values roll up in time, and it is what lets balance-sheet lines display and forecast correctly — see [Modelling the Three Statements](/forecasting/three-statement-modelling). Dimension breakdowns always sum regardless of type: a total balance is the sum of its slice balances.


## What Is a Dimension?

A **dimension** is a categorical attribute used to break down your Measures and Metrics. Common examples include Region (North, South, East, West), Product Line (Enterprise, SMB, Consumer), Sales Channel (Direct, Reseller, Online), or Department.

Dimensions enable granular forecasting — instead of projecting total Revenue as a single number, you can forecast Revenue by Region, or by Product Line, or by both simultaneously. This lets your overlays target specific slices of your business (e.g., "increase Enterprise Revenue by 20% in the Western region").

Each dimension has a set of **Dimension Values** — the specific categories within that dimension. Dimension Values are shared across dimensions, so a value like "Sweden" can belong to both a Billing Country and a Shipping Country dimension.

**Where dimension values come from:**

* **Ingestion**: values are discovered automatically from the distinct entries in your mapped dimension columns when a source is ingested.
* **Manual add**: you can add a value directly, without touching your source data. Open the **Dimensions** page from the left navigation, find the dimension's card, and click **Add Value** — enter a display name and technical name (and an optional alias).

Adding a value manually is how you model a category that has no historical data yet — for example, a region you plan to launch in. Add the value on its dimension, then target it from an overlay: an Override block with a [dimension filter](/overlays/overlay-scoping) scoped to the new value writes forecast rows for a slice the baseline knows nothing about.


## What Is a Forecast Version?

A **Forecast Version** defines the execution context for a forecast run. It specifies the time boundaries — when the model starts training on historical data, when the forecast period begins, and when it ends.

Think of a Forecast Version as a "snapshot" of your forecast at a point in time. Each version holds its own overlays, whose blocks are tagged with Scenarios — so Base, Upside, and Downside outcomes can be compared within the same version. Each version captures a specific set of assumptions for record-keeping and auditability — create a new version for each planning cycle and leave prior ones untouched for historical comparison.

You might create a new Forecast Version each quarter (e.g., "Q2 2026 Forecast") with the overlays that express your current assumptions. Previous versions remain accessible for historical comparison.


## What Is an Overlay?

An **overlay** is a user-defined adjustment to your forecast. Think of it as a "what-if" layer that sits on top of the model's baseline predictions without changing the underlying historical data.

Overlays let you express business judgment in quantitative form — for example, "revenue will grow 15% in Q3 due to a new product launch" or "we expect to hire 10 additional engineers in H2." Each overlay targets a specific Measure, applies a specific operation (Scale, Override, or Offset), and is scoped to a date range and optional dimensional filters.

Overlays are the primary way FP\&A teams encode assumptions into Galdera:

* They are versioned and auditable
* They can be grouped into Scenarios for comparison
* They do not affect historical actuals — only forecast periods


## What Is a Scenario?

A **scenario** is a named planning-assumption label — "Base Case," "Upside," "Downside," "New Product Launch" — that overlay blocks reference. Every block inside an overlay carries a scenario, and when the overlay runs, its results are tagged with that scenario's name. This lets you group and compare overlay outcomes by assumption set.

Every workspace has a **Default** scenario, created automatically. New overlay blocks use it unless you pick a different scenario in the overlay editor.

How scenarios relate to the rest of the model today:

* **Scenarios are referenced *from* overlay blocks.** You choose a block's scenario inside the overlay editor when configuring the block. There is no screen for attaching overlays to a scenario from the scenario's side.
* **The association is recorded when the overlay runs.** Until a run happens, the scenario choice lives only in the overlay's configuration.
* **Forecast runs are scenario-independent.** Running a Forecast Version produces one baseline; scenarios do not select or multiply what runs. Scenario tags become meaningful on *overlay* results layered on top of that baseline.

> **Current limitation:** scenarios cannot be attached to Forecast Versions, and there is no bulk "add these overlays to this scenario" management surface. Scenario membership is set per overlay block in the overlay editor; there is no standalone Scenarios page in the navigation.


## Adding Notes to the Canvas

:::note[Beta: Agent mode]
Agent mode is in beta. Available actions depend on your workspace and permissions. If an action is unavailable, the assistant can explain how to do it in the app.
:::

Notes on the canvas capture the business thinking behind a forecast assumption. Good notes explain:

* **Why** the adjustment was made (e.g., "Based on signed LOI with new enterprise customer")
* **What data or signal** informed the assumption (e.g., "Pipeline data as of March 2026 board review")
* **Confidence level** or conditions (e.g., "Assumes customer goes live by August 1")
* **Owner** and review date if applicable

You can ask the assistant to draft a note in chat and paste it onto the canvas yourself.

You can also ask the Galdera assistant to add notes to a canvas on your behalf (in Agent mode). Just describe what you want documented: "Add a note to the Q4 Pricing overlay explaining that this reflects the approved pricing table from the March board deck." The assistant will draft and write the note, and you will be prompted to Allow or Deny the change before it is saved.


## Documenting Assumptions

Well-documented assumptions are the foundation of a credible forecast. Each overlay in Galdera represents one assumption — and its canvas is the right place to capture everything a reviewer needs to evaluate that assumption.

Best practices for documenting overlay assumptions:

* **Be specific about the source**: "Based on signed contract" is stronger than "Based on sales estimate"
* **State the key dependencies**: "This assumes the product launches in Q3 as scheduled"
* **Note the review trigger**: "Revisit if churn rate exceeds 8% in Q2"
* **Capture the date of the assumption**: Business conditions change; knowing when the assumption was made matters

The canvas documentation on a Forecast Version records what was believed at the time of the forecast, creating an auditable trail that boards and auditors can review. Keep past versions' canvases untouched once a planning cycle closes so that record stays meaningful.


### Canvas

Documenting assumptions and notes on the narrative canvas.

* [The Narrative Canvas](/canvas/narrative-canvas) — Every Overlay and Forecast Version in Galdera has a narrative canvas — a structured document where you can record the re….
* [Adding Notes to the Canvas](/canvas/adding-notes) — Notes on the canvas capture the business thinking behind a forecast assumption.
* [Documenting Assumptions](/canvas/documenting-assumptions) — Well-documented assumptions are the foundation of a credible forecast. Each overlay in Galdera represents one assumption….


## The Narrative Canvas

Every **Overlay** and **Forecast Version** in Galdera has a narrative canvas — a structured document where you can record the reasoning, assumptions, and context behind your forecast adjustments.

The canvas is a living document that travels with the entity. When a colleague views an overlay, they see not just the numbers but the business rationale: why this adjustment was made, what information it was based on, and what conditions would cause you to revise it. This makes your forecasts explainable and auditable.

The canvas supports rich content including text, notes, and data tables. It is designed to bridge the gap between quantitative adjustments and qualitative business context — the "why" behind the "what."


## What the Assistant Can Change

:::note[Beta: Agent mode]
Agent mode is in beta. Available actions depend on your workspace and permissions. If an action is unavailable, the assistant can explain how to do it in the app.
:::

Where Agent mode is available, the assistant works in one of two modes. The mode controls whether it can change your data.

**Ask mode** is read-only. The assistant can look up entities, query your metrics, pull numbers, chart data, and answer questions — but it cannot modify anything. Use it when you want to explore or understand your forecast without any risk of changing it.

**Agent mode** can act on your behalf. In addition to everything Ask mode does, it can create an overlay — one input table or the whole set at once — or add an input table to an existing one, modify an overlay's properties or cell values (including a value per period), apply or remove it from a scenario, write analysis documents with charts in them, ingest a CSV you attach in chat into a new or existing source, and open the relevant screen for you. It can also create a named Forecast Version, update its Model Configuration while preserving canvas notes, and run, cancel, lock or unlock a forecast baseline or overlay. Saving configuration and running it are separate actions. Supported strategy changes can affect shared measure formulas or dependencies; the confirmation names those effects. Other graph edits depend on the tools enabled for your workspace.

Switching modes: use the mode dropdown in the chat input bar, or **Shift+Tab** to cycle between Ask and Agent.

Every data-changing step in Agent mode surfaces an inline **Allow / Deny** confirmation in the chat before it runs. Nothing is written until you approve it, so you always stay in control of what the assistant does. The assistant does not ask for permission in prose — it shows you the concrete action and waits for your choice.

You can also ask the assistant how to make a change yourself. It provides step-by-step instructions for the app. Ask for an analysis or report in chat if you want to copy it into a document yourself.


### Assistant

Using the in-app AI assistant — what it can answer, and how it guides you through changes.

* [Using the Assistant](/assistant/using-the-assistant) — The in-app AI assistant is a chat panel where you ask questions about your data and get step-by-step guidance for making changes in the app.
* [What the Assistant Can Change](/assistant/ask-vs-agent-mode) — What the assistant can change in your model, in Ask mode and in Agent mode, and how every change stays under your control.
* [What You Can Ask the Assistant](/assistant/what-you-can-ask) — Ask conceptual how-to questions, look up your metrics, overlays, and versions, pull numbers and charts, and get step-by-step guidance for making changes yourself.


## Using the Assistant

:::note[Beta: Agent mode]
Agent mode is in beta. Available actions depend on your workspace and permissions. If an action is unavailable, the assistant can explain how to do it in the app.
:::

The **assistant** is an in-app chat panel where you talk to Galdera in plain language. You can ask questions about your forecast and data, and — in Agent mode — have the assistant make changes on your behalf, always behind an Allow/Deny confirmation.

The assistant is aware of the page you're on. If you're viewing a specific forecast version or overlay, questions default to that context, so you can ask things like *"what does this overlay do?"* without naming it explicitly.

Working with conversations:

* **Multiple conversations** run as tabs. Use the tab bar (with an overflow dropdown when you have many) to switch between them.
* Start a fresh thread with **New conversation**. Each conversation keeps its own history and title.
* Open a conversation **full-page** for more room, or close the panel when you're done.

Adding context:

* **Drop a CSV** onto the chat to upload it as context.
* **@-mention** entities to attach them. Attachments and mentions appear as removable context badges above the message box, so you can see and adjust exactly what the assistant is looking at.

There are two ways to work with the assistant — read-only **Ask** mode and change-making **Agent** mode. See [What the Assistant Can Change](/assistant/ask-vs-agent-mode).


## What You Can Ask the Assistant

:::note[Beta: Agent mode]
Agent mode is in beta. Available actions depend on your workspace and permissions. If an action is unavailable, the assistant can explain how to do it in the app.
:::

The assistant can answer questions across Galdera and guide you through anything you want to change. What follows is the range of things it handles.

**Understand the product**

Ask how-to and conceptual questions — *"How do I create an overlay?"*, *"What is a scenario?"*, *"How does the baseline forecast work?"* — and the assistant answers from Galdera's product documentation.

**Explore your model**

* Look up a specific **Overlay, Forecast Version, Metric, Measure, or Scenario** to see its details, configuration, and current state. If a name is ambiguous, the assistant offers candidates.
* Trace **relationships and dependencies** — which measures feed a metric, what a change would affect downstream.
* List your **overlays, forecast versions, and analysis documents**, and read the narrative content of any of them.
* **Navigate** — ask the assistant to open the relevant entity's page when you want to work on it directly.

**See the numbers**

* Pull **actuals, baseline forecast, and overlay-adjusted forecast** values at the granularity you choose, along with totals, trends, and comparisons.
* Ask the assistant to **chart** something — *"show me revenue over time"* or *"compare this scenario to baseline"* — and it renders the plot inline in the chat.

**Cohorted measures**

The assistant reads calendar totals for cohorted measures but does not change, configure, break down or ingest cohort data. See [Viewing Forecast Numbers](/analytics/viewing-numbers), [Configuring a Forecast Version](/forecasting/configuring-a-forecast-version), [Creating an Overlay](/overlays/create-overlay) and [Data Formats](/sources/source-data-formats).

**Make changes (Agent mode)**

In [Agent mode](/assistant/ask-vs-agent-mode), and with your Allow/Deny confirmation, the assistant can:

* **Create an overlay** (including Scale, Offset, and Override operations) — one input table, or every table the overlay needs in one step — or add an input table to an existing one.
* **Modify an overlay** — update its properties or cell values, set a different value per period, delete it, or apply/remove it to a scenario.
* **Write up analysis** — append notes to an overlay or version canvas, or create a standalone analysis document, with charts placed in it.
* **Ingest a CSV** — attach a file in chat and the assistant profiles it, proposes the ingestion configuration, and loads it into a new or an existing source.
* **Create or configure a forecast version** — create a named version, or change its dates, training data, selected measures and supported strategies while preserving other settings and canvas notes.
* **Control forecast jobs** — run, cancel, lock or unlock a baseline or overlay. Cancelling or locking identifies a specific run, and running does not automatically lock it.
* **Open a screen** — navigate to an overlay, version, document, or report for you.

These forecast actions do not export results or restore historical configuration. Chat follows accepted jobs while open using the same polling lifecycle as the forecast pages; closing all observing pages adds no background completion guarantee. Other graph edits depend on the tools enabled for your workspace.


## Actuals vs. Forecast

One of the most valuable views in Galdera is comparing your actual results against what was forecast. This comparison shows:

* **Actuals**: Real historical values from your data sources
* **Baseline forecast**: What the model predicted (no overlays)
* **Scenario forecast**: The model prediction plus your overlay adjustments

Variance analysis helps you understand where your assumptions were right or wrong, and how much of the variance came from your overlays versus the baseline model. Over time, this feedback loop improves the quality of your planning assumptions.

Actuals are ingested automatically from your connected data sources. The comparison view aligns actuals and forecast on the same time axis so you can spot trends, step changes, and outliers at a glance.


### Analytics

Viewing forecast numbers, actuals vs forecast, and trends.

* [Viewing Forecast Numbers](/analytics/viewing-numbers) — Galdera's analytics section gives you access to the actual forecast values produced by the model. You can view numbers f….
* [Actuals vs. Forecast](/analytics/actuals-vs-forecast) — One of the most valuable views in Galdera is comparing your actual results against what was forecast. This comparison sh….
* [Viewing Trends Over Time](/analytics/trends) — Trend views for measures and metrics across the forecast horizon.


## Viewing Trends Over Time

Trend views show how a Measure or Metric changes over the forecast horizon. This is useful for:

* Identifying growth trajectories (is revenue accelerating or decelerating?)
* Spotting inflection points where overlays take effect
* Comparing period-over-period growth rates (month-over-month, year-over-year)

The Galdera assistant can describe trends verbally: "Subscription Revenue grew from $4.2M in January to $5.8M in June, a 38% increase." You can request specific time windows, specific granularity, or comparisons across scenarios.

Trend data is available at the Measure and Metric level, and can be filtered by Dimension Values — for example, viewing revenue trends for the Enterprise segment only, or comparing trend lines across regions side by side.


## Viewing Forecast Numbers

Galdera's analytics section gives you access to the actual forecast values produced by the model. You can view numbers for any Measure or Metric, within any Forecast Version, broken down by Scenario.

To view numbers:

* Navigate to the **Analytics** section or to a specific Metric or Measure page
* Select the Forecast Version you want to view
* Choose the Scenario (Base Case, Upside, etc.)
* Select the time granularity: monthly, quarterly, or annual

**How values roll up to coarser granularities** depends on the measure's [type](/concepts/metric-vs-measure): a **flow** (Revenue, Capex) shows the sum of its months, while a **stock** (Cash, PP\&E) shows the period-end balance — Q1 cash is the March balance, not January + February + March. Dimension breakdowns always sum across slices for both types.

You can also ask the Galdera assistant for specific figures: "What is our total Subscription Revenue forecast for H2 2026 in the Base Case?" The assistant will retrieve and present the numbers directly in the conversation, with key figures highlighted.

#### Cohorted measures in chat

For a cohorted measure — one loaded from a file with a cohort date and a report date — the assistant reads **calendar totals**: each period's value summed across every cohort. It says so with the figures: "These figures are calendar totals across all cohorts. Cohort-level breakdowns aren’t available in chat."

It does not provide **cohort-level breakdowns**, such as values per cohort or by cohort date, and does not answer them with calendar totals instead. Open the forecast version to see a cohorted measure by cohort.


## Connect your identity provider

Use the secure setup link from Galdera to connect your identity provider. Galdera supports SAML and OpenID Connect (OIDC).

Your Galdera workspace must exist before you begin. If your IT team has not received a setup link, ask your Galdera contact to resend it.

#### Before you begin

You’ll need:

* Administrator access to your identity provider.
* The secure setup link for your Galdera workspace.
* The work account for the person who will become your first Galdera administrator.

#### Connect and test SSO

:::steps
##### Open your setup link

Open the secure setup link from Galdera and choose your identity provider.

##### Connect Galdera

Follow the guided instructions for your provider.

##### Test the connection

In a private browser window, sign in with the account that will become your first Galdera administrator. Confirm that they reach the correct workspace and can open **Settings → People**.
:::

Assign the Galdera application only to the people who should be able to sign in.

Once the test succeeds, the administrator can invite other people, including approved guests and contractors, and manage their roles from Galdera.

:::info[If you are asked to verify your domain]
Your setup may include domain verification. This proves that your organization controls the domain and may be used to support automatic membership in your existing workspace.

The setup portal will provide the DNS record and instructions you need. If your organization’s DNS process prevents you from completing verification, ask your Galdera contact for help.

Domain verification does not create a workspace. Automatic membership applies only when just-in-time provisioning is enabled for your organization.
:::

:::details[Group-based roles (beta)]
Group-based role assignment is not available for every workspace. If your rollout depends on identity-provider groups, tell your Galdera contact before configuration begins. In that case, test both an Admin and a Member assignment before wider rollout.

Identity-provider groups do not control access to individual Galdera assets. Manage that access in the asset’s **Share** menu.

Directory sync and SCIM are not required to connect SSO. If automated provisioning or deprovisioning is a requirement, discuss it with your Galdera contact before rollout.
:::


### Set up access to Galdera

Connect your company’s identity provider so your team can sign in using their existing work accounts.

:::info[Your workspace comes first]
Galdera creates your workspace before identity setup begins. When it is ready, we’ll send your IT team a secure setup link. SSO gives people access to that workspace; it does not create new workspaces.
:::

#### Get started

* **[Connect your identity provider](/access-and-sso/connect-sso)** — configure SAML or OIDC and test sign-in.
* **[Add and manage people](/access-and-sso/manage-people)** — invite people, check their status, or remove access.
* **[Understand roles and access](/access-and-sso/roles-and-permissions)** — choose who can administer the workspace and who can access its content.
* **[Troubleshoot sign-in](/access-and-sso/troubleshoot-access)** — resolve common SSO, invitation, and access problems.


## Add and manage people

Organization administrators can manage workspace membership from **Settings → People**.

Use invitations for approved guests, people whose domain is not part of your SSO setup, or anyone who needs access before SSO is ready.

#### Invite someone

1. Open **Settings → People**.
2. Enter the person’s email address under **Invite people**.
3. Choose **Member** or **Admin**.
4. Select **Send invite**.

The person will receive an email inviting them to your existing Galdera workspace.

#### Check an invitation

The **Members** list shows whether someone is active, has a pending invitation, or has been removed.

* **Invitation sent** means the invitation has not been accepted yet.
* **Invitation expired** means you need to send a new invitation.
* **Active** means the person has joined the workspace.
* **Removed** means the person no longer has workspace access.

Select the envelope action to resend a pending or expired invitation.

#### Change someone’s role

Find the person in the **Members** list, then choose **Admin** or **Member** from their role menu.

Keep at least two active administrators where practical. Galdera prevents you from removing or demoting the last active administrator.

Changing an organization role does not change the person’s access to a particular forecast version, overlay, or document. Manage those permissions from the asset’s **Share** menu.

#### Remove or restore access

Select the trash action beside a person to remove their workspace access. You cannot remove yourself.

Select the restore action to reactivate someone who was previously removed. If the person should no longer sign in through SSO, also remove their assignment to the Galdera application in your identity provider.

If just-in-time provisioning is enabled, eligible people signing in through your SSO connection may be added automatically to the existing workspace. Otherwise, invite them from **Settings → People**. Unless Galdera has confirmed group-based role assignment for your workspace, manage their role in Galdera.


## Understand roles and access

Galdera controls access at two levels:

* Your **organization role** determines what you can administer across the workspace.
* Your **asset access** determines which forecast versions, overlays, and documents you can view or edit.

#### Organization roles

| Role       | What it can do                                                                                        |
| ---------- | ----------------------------------------------------------------------------------------------------- |
| **Admin**  | Manage people and organization settings, set default member access, and access every workspace asset. |
| **Member** | Use Galdera and open the assets they are allowed to view or edit.                                     |

An administrator can change someone’s role in **Settings → People**.

Group-based role assignment is an optional workspace configuration. Do not depend on identity-provider groups unless Galdera has confirmed they are enabled and your team has tested both Admin and Member assignments.

#### Asset access

Open a forecast version, overlay, or document and select **Share** to manage access to it.

* **Can view** lets someone open and read the asset.
* **Can edit** lets someone change the asset and manage its sharing.
* **No access** removes general access to the asset. Someone with an individual grant may still be able to open it.

Identity-provider groups do not manage asset access.

#### Default member access

An administrator can choose the workspace default in **Settings → General**:

* **None** — members need access to be granted.
* **Read** — members can view assets by default.
* **Write** — members can edit assets by default.

An asset’s **General access** setting applies only to that asset and can give everyone in the workspace **Can view** or **Can edit** access.

See [Sharing and permissions](/getting-started/sharing-and-permissions) for the full sharing workflow.


## Troubleshoot sign-in and access

Start with the message or behavior you see below. After changing an invitation, application assignment, or role, sign out and sign in again.

#### I see “Awaiting Access”

Your sign-in succeeded, but your account is not connected to a Galdera workspace.

Ask an administrator to open **Settings → People** and check your email address:

* If your invitation is pending or expired, resend it.
* If you were removed, restore your access.
* If you are not listed, send you an invitation or confirm that your account is assigned to the Galdera application and uses an approved domain.

#### My invitation did not arrive or has expired

Ask an administrator to select the envelope action beside your name in **Settings → People**. This sends a new invitation.

Check your spam and quarantine folders, and make sure the invitation address matches the address you use for SSO.

#### I should be an administrator

An existing administrator can change your role in **Settings → People**.

If your workspace uses group-based roles, ask your IT team to check your identity-provider group. Group-based roles must be enabled for your workspace before those assignments have an effect.

#### I can sign in but cannot open an asset

Workspace membership does not necessarily give you access to every forecast version, overlay, or document. Ask an administrator or an editor of the asset to open **Share** and give you **Can view** or **Can edit** access.

#### I cannot find People in Settings

Only organization administrators can open **Settings → People**. Ask an existing administrator to check your organization role.

#### Contact Galdera

If the problem continues, send your Galdera contact:

* The affected email address.
* The exact error message or a redacted screenshot.
* The approximate time of the sign-in attempt and your time zone.
* Whether the problem concerns SSO, an invitation, a role, or an individual asset.

Never send passwords, private keys, or unredacted SAML assertions.