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

# Set up data ingestion

> Prepare your warehouse, connect it to Minoa, and route metrics to business case inputs.

Setup is a one-time admin job. Once a connection and its metric links exist, anyone working on a business case can flip syncing on without touching any of this — see [Use ingested data in a business case](/pages/integrations/data-platforms/using-in-business-case).

## Setup checklist

<Steps>
  <Step title="Create a view or table in your data warehouse">
    Expose only the metrics Minoa should read, shaped the way the connector expects.
  </Step>

  <Step title="Connect Minoa to your warehouse">
    Add the credentials in **Settings → Data ingestion** and test the connection.
  </Step>

  <Step title="Add tables and map columns">
    Pick the table or view, then map each column to a role (account, metric ID, value, timestamp, cursor).
  </Step>

  <Step title="Map external metrics to business case inputs">
    Tell Minoa which input each external metric should write into.
  </Step>
</Steps>

<Info>
  You need administrator (or integration) permissions in Minoa to complete the in-product steps. The warehouse side is
  usually owned by your data team.
</Info>

***

## 1. Create a view or table in your data warehouse

Focus on the metrics you want to bring into Minoa — your source doesn't need to line up one-to-one with every input on every deal. We recommend exposing a **dedicated view** instead of a raw production table. A view lets you filter, rename, and reshape without granting Minoa access to the underlying data.

### Required schema

Minoa expects one row per (account, metric, period). Column names are flexible — you'll map them later — but the **types and semantics** need to match the table below.

| Role               | Example column          | Type               | Required | Notes                                                                                                                                 |
| ------------------ | ----------------------- | ------------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| Account identifier | `salesforce_account_id` | STRING             | Yes      | Stable ID Minoa can align to a Minoa account (often the Salesforce 18-character account ID).                                          |
| External metric ID | `metric_id`             | STRING             | Yes      | Stable per-metric key, e.g. `product.mtt_resolve`. Used by metric links to route the value.                                           |
| Metric value       | `value`                 | FLOAT64            | Yes      | Numeric measurement. Must be FLOAT64 — NUMERIC is not accepted by the connector.                                                      |
| Measurement time   | `measured_at`           | TIMESTAMP          | Yes      | When the measurement applies — typically end-of-period (e.g. `2026-03-31 23:59:59 UTC` for March).                                    |
| Cursor column      | `cursor_ts`             | TIMESTAMP          | Yes      | Strictly monotonic per (account, metric). Lets Minoa fetch only new or changed rows.                                                  |
| Business interval  | `month_id`              | STRING (`YYYY-MM`) | Yes      | Period label (e.g. `2026-02`). Every row must carry an interval so Minoa can route the value to the right month in the business case. |

<Tip>
  Need an example view to get started? Reach out to your Minoa support team — we're happy to walk you through a
  reference setup.
</Tip>

### Pick a good cursor

The cursor column drives incremental polling, so getting it right matters. We recommend a timestamp that:

* **Only moves forward** for a given (account, metric) pair — never goes back when a row is updated.
* Sits **after** `measured_at` so closing-the-month writes show up promptly. A common pattern: set `cursor_ts` to the first day of the month after the row's period.
* Is set explicitly in your view — don't reuse a generic `updated_at` if it can regress when rows are reshuffled.

<Warning>
  If the cursor regresses (a new row arrives with a cursor value below one already processed), Minoa won't see that
  row on the next run. Reset the cursor manually to backfill — see [Monitor sync
  runs](/pages/integrations/data-platforms/monitoring).
</Warning>

### Least-privilege access

Create a **dedicated service principal or user** for Minoa with **read-only access** to the view, not the whole warehouse. Exact grants depend on the platform — for example `USAGE` on the database/schema and `SELECT` on the view in Snowflake. Authenticate with the method your security team requires (key pair or short-lived credentials are the usual call).

### Network allowlisting

If your network policy requires IP allowlisting for inbound connections, contact our support team for the current egress addresses.

***

## 2. Connect Minoa to your warehouse

Once the view is ready in your warehouse, add the connection inside Minoa.

<Steps>
  <Step title="Open data ingestion settings">Go to **Settings → Data ingestion**.</Step>

  <Step title="Pick your warehouse">
    Click **Connect Snowflake** (username + private key) or **Connect BigQuery** (service-account JSON).
  </Step>

  <Step title="Fill in account-level details">
    Depending on the warehouse, you'll be asked for details like an account URL or project ID. Add a friendly name
    so the connection is easy to spot later.
  </Step>

  <Step title="Test the connection">
    Click **Test connection**. Minoa attempts to authenticate against your warehouse and reports back. Fix any
    errors before saving.
  </Step>

  <Step title="Save">
    Click **Save** to store the connection. Credentials are encrypted at rest; only the connection metadata is
    visible in the panel afterwards.
  </Step>
</Steps>

<Warning>
  Treat warehouse credentials like production secrets. Use a secure channel for handoff, rotate keys if they may have
  been exposed, and never paste plaintext keys into email or shared docs.
</Warning>

***

## 3. Add tables and map columns

A connection on its own doesn't read any data. You add one or more **tables** under the connection, each pointing at a specific view in your warehouse.

<Steps>
  <Step title="Open the connection">
    From **Settings → Data ingestion**, click into the connection you just created.
  </Step>

  <Step title="Click Add table">A modal opens that walks you through schema → table → column mapping.</Step>

  <Step title="Pick the schema or dataset">
    Minoa lists the available schemas or datasets (e.g. schemas in Snowflake, datasets in BigQuery) your principal
    can see. Pick the one that contains your view.
  </Step>

  <Step title="Pick the table or view">
    Minoa lists tables and views inside the schema. Pick the one you prepared in step 1.
  </Step>

  <Step title="Map each column">
    For each role — account identifier, external metric ID, metric value, measurement time, cursor, business
    interval — pick the matching column from your view. Refer to the schema table above if you renamed any of them.
  </Step>

  <Step title="Choose a sync interval">
    Pick **Hourly** or **Daily** depending on how fresh you need the values. Daily is usually plenty for monthly
    metrics; hourly makes sense if your team watches metrics intraday.
  </Step>

  <Step title="Optionally backfill from a date">
    Set a backfill start date if you want the first run to pull historic rows. Leave it empty to only ingest data
    from today forward.
  </Step>

  <Step title="Save">
    Minoa re-validates the mapping against fresh warehouse metadata when you save, so schema changes since you
    opened the picker are caught immediately.
  </Step>
</Steps>

<Info>
  You can add multiple tables under the same connection — one per logical feed. Each table runs on its own schedule
  and tracks its own cursor.
</Info>

***

## 4. Map external metrics to business case inputs

The connector pulls rows into Minoa, but it still needs to know **which input** each external metric belongs on. That's what metric links do.

<Steps>
  <Step title="Open the Mapping subpage">
    From **Settings → Data ingestion**, click **Mapping**. You'll see one row per external metric ID that has
    appeared in any synced table.
  </Step>

  <Step title="Pick the Minoa input">
    For each external metric, choose the input it should write into. The dropdown lets you filter by use case or
    input type so finding the right one is quick on long lists.
  </Step>

  <Step title="Save the link">
    Once saved, future syncs route matching rows to that input automatically. Existing unmatched rows are
    reprocessed on the next run.
  </Step>
</Steps>

<Tip>
  Click into a single mapping row to open the audit drawer — it shows recent rows that matched (or didn't) and is your
  fastest path to debugging "why isn't this value showing up on the business case?"
</Tip>

<Check>
  You're done with admin setup. Sales reps and customer success managers can now turn syncing on inside any business
  case — see [Use ingested data in a business case](/pages/integrations/data-platforms/using-in-business-case).
</Check>