> For the complete documentation index, see [llms.txt](https://docs.onelens.cloud/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.onelens.cloud/observe-visibility-and-insights/unit-economics/unit-cost-engine.md).

# Unit Cost Engine

The Unit Cost Engine is where you build an allocation rule. You place datasets and cost on a canvas, connect them, and build up tables one at a time until you reach a final report, such as cost per customer. You can run each table as you build it, so you can see the problem in a calculation the moment it breaks, not only at the end.

Go to **Observe → Unit Economics → Unit Cost Engine**.

### Allocation rules list

<figure><img src="https://3963693991-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FiyNGpqVYfmDF6qt7Lzar%2Fuploads%2FXyKtLZawREZryJ0QSsul%2Fimage.png?alt=media&amp;token=c4b3f24b-b530-4a95-974b-1e25f4117283" alt=""><figcaption></figcaption></figure>

Each row is one allocation rule and the report it produces.

| Column                                              | What it shows                                                                                |
| --------------------------------------------------- | -------------------------------------------------------------------------------------------- |
| Report Name                                         | The name of the rule and its report                                                          |
| Status                                              | **Draft** or **Published**                                                                   |
| Version                                             | The current version, such as v4                                                              |
| Contributors                                        | How many datasets and cost sources feed the rule                                             |
| Intermediate Tables                                 | How many working tables it has                                                               |
| Created By, Updated By, Created At, Last Updated At | Who created and changed the rule, and when                                                   |
| Actions                                             | The chart icon becomes available once the report is published. The menu (⋮) has more options |

Click **Create Allocation Rule** to start a new one.

### The canvas

<figure><img src="https://3963693991-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FiyNGpqVYfmDF6qt7Lzar%2Fuploads%2Fpskk0PWxJGLjbgU77RiP%2Fimage.png?alt=media&amp;token=2f59eb3f-4c5a-4940-bf81-1ab9713ac78a" alt=""><figcaption></figcaption></figure>

The canvas has three lanes, which follow three steps:

1. **Add Contributors.** The inputs: your datasets and cost sources. Contributors are read-only.
2. **Build Intermediate Tables.** Working tables that combine contributors, such as each customer's share of database size.
3. **Create Final Report.** The table that becomes your report.

Rename the rule with the pencil icon next to its name. The top right shows the version and status (for example **v1 · Draft**), with **Save as Draft**, **Test Run** and **Publish**.

### Step 1: Add contributors

Click **Add Contributor** and pick the inputs your rule needs. A contributor can be any dataset (entity, mapping or metric) or a cost source from Cost 360, such as your AWS or GCP cost.

<figure><img src="https://3963693991-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FiyNGpqVYfmDF6qt7Lzar%2Fuploads%2Fu1styjpzO0hwm7lkdNSb%2Fimage.png?alt=media&amp;token=1fcd35f8-7d48-47a8-bcdc-eb7fa5b50305" alt=""><figcaption></figcaption></figure>

A contributor marked **Granularity needed** needs one more setting before you can use it. Click it and open **Granularity Settings**:

* **Granularity** sets the time grain to use, such as Monthly.
* **Non-daily handling** sets how values are spread when the data is not daily.

The contributor panel also has a **Details** tab and a **Used By** tab, which shows the tables that read this contributor.

<\<CONFIRM = options for Non-daily handling>>

### Step 2: Build intermediate tables

Click **Add Intermediate Table**. A guided panel takes you through seven steps. An intermediate table can read contributors and other intermediate tables, so you can chain them, for example Total Database Size → Database Share per Customer → Cloud Cost per Customer.

<figure><img src="https://3963693991-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FiyNGpqVYfmDF6qt7Lzar%2Fuploads%2Fr7VAPoSkIRNRe59LbzJm%2Fimage.png?alt=media&amp;token=9c9d924b-eb70-4291-8569-f5b3ab734e10" alt=""><figcaption></figcaption></figure>

#### Connect your contributors

Tell OneLens how the data in your tables relates. OneLens uses these connections to write more accurate SQL.

| Connection        | Use it when                                                                                                   |
| ----------------- | ------------------------------------------------------------------------------------------------------------- |
| **Match Columns** | A column in one contributor lines up with a column in another, such as `db_name` in both database size tables |
| **Look-up**       | You need a value from a contributor for a calculation, without adding it as a column in the output table      |

Under **Suggested Connections**, OneLens proposes connections based on your table definition and column names. Click **Use Connection** to accept one, or dismiss it. To add your own, click **Add Connection**.

#### Set safeguards

Decide what should happen when data is missing, unexpected, or fails a check. For each item, choose **what should happen** and **who should be notified**. Untick any you don't need.

<figure><img src="https://3963693991-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FiyNGpqVYfmDF6qt7Lzar%2Fuploads%2FD0bgmBwttnEKUEoHHJmh%2Fimage.png?alt=media&amp;token=f8ad0cfe-24e7-4afe-b987-17a2a00a892a" alt=""><figcaption></figcaption></figure>

**Safeguards** are checked on the tables this query reads, before it runs.

| Safeguard                                                                    | Default               |
| ---------------------------------------------------------------------------- | --------------------- |
| Current month source data is not healthy                                     | Continue With Warning |
| Source data is healthy but does not have complete data for the current month | Continue With Warning |
| Source data is healthy but no data                                           | Continue With Warning |
| Negative numbers in the source data                                          | Continue With Warning |
| Empty or non-finite numbers in the source data                               | Treat As Zero         |
| Exchange rate lookup failed                                                  | Stop The Run (fixed)  |

**Query guards** are not checks. Each answer becomes a rule in the SQL guide, so the generated SQL handles the case.

| Query guard                          | Default             |
| ------------------------------------ | ------------------- |
| A row could not be matched           | Put In Unknown Row  |
| A match produced more than one row   | Collapse to one row |
| A value matches more than one target | Divide equally      |
| A row has no value to allocate on    | Put In Unknown Row  |
| Something is divided by zero         | Exclude The Row     |
| Every weight in a group is zero      | Split Evenly        |
| The shares do not add up to 100%     | Normalise To 100%   |

#### Generate your SQL

OneLens turns your table definition, connections and safeguards into a structured guide, **GUIDE.MD**. Copy it into your preferred LLM to generate the SQL for this table.

<figure><img src="https://3963693991-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FiyNGpqVYfmDF6qt7Lzar%2Fuploads%2FLcYvvMnMcMFpMpkNhpwX%2Fimage.png?alt=media&amp;token=3596adb8-925d-4489-8758-30c33f07da3d" alt=""><figcaption></figcaption></figure>

The guide tells the LLM:

* The table being built and its table name, such as `db_size_per_customer`.
* The tables it reads, with every column, type and unit.
* That the query runs on ClickHouse and must be valid ClickHouse SQL.
* That OneLens joins the whole report into one statement before running it, with each table as a named CTE, so the query must use those table names as they are.

### Step 3: Create the final report

Click **Add Report** to add the final report. It reads from the tables before it and becomes the output of the rule.

<figure><img src="https://3963693991-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FiyNGpqVYfmDF6qt7Lzar%2Fuploads%2FUXxNBvZgbuqgLniSCNhk%2Fimage.png?alt=media&amp;token=39005a6d-322d-4be8-8ce1-e94a0e9f45eb" alt=""><figcaption></figcaption></figure>

### Test and publish

Click **Test Run** to run every table. When all tables the report reads run successfully, the run results say the report is ready to be published. Each table that passes shows **Validated** on the canvas.

<figure><img src="https://3963693991-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FiyNGpqVYfmDF6qt7Lzar%2Fuploads%2FBhbfmqSbNElgZC7C8vRy%2Fimage.png?alt=media&amp;token=1f546854-00b2-40ea-bdd3-b19e96ce9aec" alt=""><figcaption></figcaption></figure>

Click **Publish** and confirm the details.

<figure><img src="https://3963693991-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FiyNGpqVYfmDF6qt7Lzar%2Fuploads%2FBs1rYC1Fu5IYB1oZEQg5%2Fimage.png?alt=media&amp;token=dd477b1a-0e31-4c09-990c-878105d2a85b" alt=""><figcaption></figcaption></figure>

| Field                                | What to enter                                                                                                                              |
| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------ |
| Report Name                          | The name people will see                                                                                                                   |
| Output Table Name                    | The table name for the results. Lowercase letters, digits and underscores only                                                             |
| What Is This Report Used For?        | A short purpose, such as "Share the database bill across customers by how much database space each uses"                                   |
| Frequency, Day of Month, Time of Day | When the report runs, for example monthly on day 3 at 12:00 PM. If a month is shorter than the chosen day, the report runs on the last day |
| Retry Window (Days)                  | <\<CONFIRM = what the retry window does>>                                                                                                  |

Click **Save & Publish Report**.

Each rule keeps a version number, such as v5. Earlier versions stay available as archived versions, and you can still view them in Analytics.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.onelens.cloud/observe-visibility-and-insights/unit-economics/unit-cost-engine.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
