What is KPI Studio?

KPI Studio is where custom KPIs are defined. A KPI collection groups KPIs and dimensions that belong together, and each KPI inside it holds one metric definition plus the dimensions it can be sliced by.

You find it under Engineering → Semantic → KPI Studio. The list shows every KPI collection in your space with its status (active, draft, deprecated), the number of KPIs and dimensions, the version, and whether it is owned by you or shared with you.

Managed vs custom: Collections that come with an integration are built and maintained by Indicate. A collection you create yourself is custom, and you are responsible for its definition and its dimensions.

When do I need a custom KPI?

• The managed integration does not deliver the number you need, for example a KPI that combines fields in your own way.

• You want a business specific definition, for example your own definition of a qualified request.

• You need a KPI on top of data that only exists in your warehouse.

• You uploaded your own data and want to access it via an LLM. The LLM gets access to the KPIs but not to your raw data.

Where is the documentation?

Metrics in Indicate are declarative JSON, not SQL text. They are written in the DSL of the semantic layer, which compiles into an execution plan with SQL semantics. Every metric filters on _connection_id, so it returns data for one source connection only.

Two references, both public:

• The DSL language reference → docs.indicate-data.io/reference/semantic-layer: Statements, expressions, functions, data types, and schema. Use it when you write or read a definition.

• How metrics are built → github.com/insanetic/data-max. The workflow from a raw file to a finished metric and dimension definition, packaged as three skills you can download. The skills are helpful when building metrics with AI.

How do I build metrics with the data-max skills?

The repository is a plugin with three skills. You can download them and let an AI assistant do the heavy lifting, from a raw export all the way to a finished metric definition.
Make sure you have admin rights and the correct subscription plan allowing you to build your own metrics.

Install (for example) in Claude Code

1. Run /plugin marketplace add insanetic/data-max

2. Run /plugin install data-max@data-max

Use with another agent

The skills are portable. Copy the folders from skills/ into your agent's skills folder, for example ~/.codex/skills/ or ~/.gemini/skills/.

The three skills

• data-review cleanses and pares down. It inspects a raw export (CSV, TSV, JSON, XML, Excel) and produces a tiered report on how to clean it for a warehouse. It only inspects, it never changes your data.

• data-transform executes that review. It turns the file into clean, warehouse ready tables via a rerunnable script. It needs a review first.

• metric-creator builds DSL compatible metric (data cube) and dimension definitions on top of clean data. It produces versioned JSON metric files and a dimensions.md with the matching dimension definitions.

Use them in that order when you start from a raw file: review, then transform, then create the metric. If your data is already loaded and clean, you can use metric-creator on its own.

The metric-creator skill needs the DDL of your tables as input. In the Data Studio, open the table and use `⋯` → Show DDL to copy the `CREATE TABLE` statement, then hand it to the skill. `⋯` → Copy query gives you an existing query as a DSL JSON object, which is a good starting point too.

How do I create a KPI collection?

A KPI collection is the container for your KPIs. Create it first, then add KPIs inside it.

1. Go to Engineering → KPI Studio.

2. Click + New KPI in the top right corner.

3. In the New KPI Collection dialog, enter a Display name, for example ReGuest my metrics.

4. Optionally add a Description so your team knows what the collection covers.

5. Click Create.

The collection appears in the KPI Collections list and opens with the tabs KPIs, Dimensions, Sharing, and Settings.

How do I create a KPI?

Every KPI lives inside a collection, so open the collection first.

1. Open your collection from Engineering → KPI Studio.

2. On the KPIs tab, click + New KPI.

3. Enter a Display name, for example Reservations, and an optional Description.

4. Click Create.

The KPI editor opens. On the left you see Metadata, DSL Editor, Grouping Dimensions, and Perspective Dimensions. On the right the Warehouse panel lists the tables and fields available in your space.

How do I add the metric definition?

1. In the left panel of the KPI, click DSL Editor.

2. Click into the editor area.

3. Write your metric definition; feel free to use the metric builder skill if you want to write the metrics with AI or find all information in the documentation.

4. Use the Warehouse panel on the right to confirm the exact table and field names.

5. Click Dry Run in the top bar to run the definition without saving it.

Errors from the dry run appear directly under the editor, including the failing SQL statement.

What are grouping and perspective dimensions?

Both are dimensions, but they do different jobs:

• Grouping dimensions control how the data is displayed. They are added to the GROUP BY of the query, for example the x axis of a chart.

• Perspective dimensions control which data is included. They are added to the filters of the query, for example whether a date range filters on created date or arrival date.

Every KPI needs at least one grouping dimension and at least one perspective dimension. If your definition returns a column that no dimension maps to, the KPI fails to execute.

What is the semantic type?

The semantic type tells Indicate what kind of value the dimension holds:

• Temporal for date and time columns, for example a created date or an arrival date. Temporal dimensions are what Time Range and Granularity work on.

• Categorical for discrete values, for example channel, country, status, or a category name.

Pick the type that matches the column: a DATE, TIME, TIMESTAMP, or TIMESTAMPTZ column is temporal, everything else is categorical. See the data types reference for the full list.

How do I add a dimension?

Dimensions are added in the left panel of the KPI, under Grouping Dimensions or Perspective Dimensions.

1. Click + Add Dimension under the section you need.

2. Click Create New Dimension.

3. Enter a Display name, for example Created Date. This is the name users see.

4. Check the Scope: Grouping or Perspective. It is preselected based on the section you started from.

5. Choose the Semantic type: Categorical or Temporal.

6. Under Physical Mapping, fill in the Identifier, the exact column name from your table, for example created_date, and the Alias, the label the dimension is projected as, for example rgc_label_created_date. The alias has to match the one used in your definition.

7. Optionally, under Qualifier, enter the Table and Schema so the column is fully qualified, for example table rgc. Use the same table alias that your definition uses in $from.

8. Click Create.

Use Browse Schemas in the dialog, or the Warehouse panel on the right, to copy the exact column name instead of typing it.
A single typo in Identifier or Alias is the most common reason a KPI does not run. If you built the definition with metric-creator skill, take the identifiers and aliases straight from the generated `dimensions.md`.

How do I edit or remove a dimension?

Dimensions can be corrected at any time, which is what you do when the dry run reports an unknown column or alias.

1. In the left panel, click the dimension you want to change.

2. In the Edit Dimension dialog, update Display name, Semantic type, Identifier, Alias, or Qualifier.

3. Click Save, or click Remove to delete the dimension.

4. Run Dry Run again to confirm the KPI executes.

How do I check the result before saving?

The tabs at the bottom of the editor show the KPI from four angles:

• Preview: the KPI as it will appear to users.

• Chart: the result as a chart.

• Table: the result as rows and columns.

• Emulated: the generated query and its parameters.

Next to the result you can change Time Range (default Last 30 Days), Granularity, Grouping, Perspective, and Visualization to see how the KPI behaves. These settings are for testing only and are not saved with the KPI.

How do I save the KPI?

Click Save in the top bar, or press ⌘ S / Ctrl S.

To make the KPI available in dashboards and widgets, the collection has to be published as an Insight. See → Publish a KPI collection as an Insight

Troubleshooting

Dry Run fails with "Failed to execute KPI collection query".

• The message below the editor contains the generated SQL. In most cases an alias or a table reference in the definition does not exist. Compare the Alias and Identifier of every dimension with the names used in your definition, correct them in Edit Dimension, click Save, and run Dry Run again.

A referenced table is not found.

• Open the Qualifier section of the dimension and set Table (and Schema if needed) so the column is fully qualified. The table alias has to match the one used in the $from of your definition. You can look up the exact table name in the Warehouse panel or in the Data Studio.

I do not know which column name to use.

• Open the table in the Data Studio and check the Schema view for the exact column names, or copy the full CREATE TABLE statement with ⋯ → Show DDL. Only Admins can access the Data Studio.

My KPI returns no data at all.

• Check that the definition filters on _connection_id and that the Insight has a source connection assigned. Without that filter the metric cannot tell which connection to read from.

My KPI does not appear in a dashboard or widget.

• A KPI in KPI Studio is a definition. It becomes usable in the app once the collection is published as an Insight and a source connection is assigned.