> ## Documentation Index > Fetch the complete documentation index at: https://learn.kubit.ai/llms.txt > Use this file to discover all available pages before exploring further. # Setup Kubit in the Modeler > Map warehouse tables to fact tables, dimensions, subjects and fields with the Modeler agent, then apply the draft so reports can query it. The Modeler tells Kubit how to read the tables in your warehouse. You map them to fact tables, dimensions, subjects and fields once, and every report, Activity view and MCP query reads that model. The same model holds clickstream events and agent traces, so a warehouse workspace can join the two. Most people start with the Modeler agent. It reads your warehouse, proposes a mapping in a draft, and changes nothing until you apply it. You can also map every table by hand, but using the agent is faster. The Modeler is under **Data** > **Modeler** in the left nav. Creating a workspace with one of the origins below opens it right away. ## Which workspaces have a Modeler A workspace has a Modeler when its data lives in a warehouse. The workspace **Origin**, picked in **Create Workspace**, sets what the Modeler shows. | Origin | What the Modeler shows | Warehouse | | - | - | - | | **Warehouse** | A connection form, then manual or agent mapping of any table | Snowflake, Databricks, BigQuery or ClickHouse | | **MLflow Tracing** | A **MLflow** preset tab that maps the trace tables for you | Databricks only | | **Cortex Agents** | A **Cortex Agent** preset tab | Snowflake only | | **Google ADK** | A **Google ADK** preset tab | BigQuery only | | **Langfuse** | A **Langfuse** preset tab | ClickHouse only | | **Sandbox** | An **Uploads** tab for trace files. The schema comes from the first upload. | A Kubit-managed warehouse | | **Agent**, **User** | No Modeler | None | To create the workspace, see [Set up your organization](https://learn.kubit.ai/start-here/admin.md#create-a-workspace). ## Before you start * [ ] A workspace with one of the origins above * [ ] The **Admin** or **Owner** role in the organization. **Viewer** and **Member** can open the Modeler but can't change it. * [ ] Your warehouse set up for Kubit, with the identity and grants from its page: [Snowflake](https://learn.kubit.ai/warehouses/connect/snowflake.md), [BigQuery](https://learn.kubit.ai/warehouses/connect/bigquery.md), [Databricks](https://learn.kubit.ai/warehouses/connect/databricks.md) or [ClickHouse](https://learn.kubit.ai/warehouses/connect/clickhouse.md) * [ ] The table that holds your events or spans, with one row per event and a timestamp column ## How a model fits together A Kubit model is a set of mapped warehouse tables. The **Schema** tab lists them. Each part has one job: | Part | What it is | Needs | | - | - | - | | **Fact table** | A table of events or spans, one row each. Kubit combines all fact tables into one union. | One column with the **Event** role, one with **Timestamp** and at least one with **Subject** | | **Dimension** | A table that adds attributes to fact rows, such as a user's plan or campaign | A **One-to-one** or **Temporal** join to a fact table | | **Subject** | The thing you count, such as a user, session or trace | A column mapped with the **Subject** role | | **Field** | Any mapped column that reports can use | **Group by**, **Filterable** and **Activity** settings | | **Trace roles** | Agent trace columns: **Node**, **Parent** and **Container** link spans into trees and runs | Traces only. Product analytics models don't need them. | ![Modeler Schema tab with one fact table tagged Timestamp and Subject, two dimensions joined one-to-one on TRACE\_ID, and the subjects Trace, User, Session and Span, each with an enable switch. Edit with agent and Add table sit above Fact Tables, Add with agent and Add dimension above Dimensions.](https://mintcdn.com/kubit/vzHVKaCpdKYs1x9f/images/modeler/schema-tab.png?fit=max\&auto=format\&n=vzHVKaCpdKYs1x9f\&q=85\&s=666268f948e0f8e52b0740aa15d8269b) The **Timestamp** column is the event time. Kubit derives Hour of Day, Date, Day of Week, Week, Four Week, Month, Quarter and Year from it. Subjects in a warehouse workspace come from your data. You choose which columns become subjects. The presets create **Trace ID**, **Session ID** and **User ID**. Agent workspaces have four fixed subjects instead, described in [Concepts](https://learn.kubit.ai/agent-observability/concepts.md#subjects). ## Map your data with the Modeler agent The Modeler agent is a chat panel inside the Modeler. You can map a table you picked, or ask the agent to find the best fact table in your warehouse. **1. Connect your warehouse** On the **Warehouse Connection** screen, pick **New connection**, set **Warehouse type** and fill in the fields from your warehouse's setup page. Click **Test connection**, then **Connect warehouse**. To reuse a connection from another workspace, pick **Use existing**, choose the **Source workspace** and click **Copy connection & schema**. That copies the source workspace's whole model and activates this workspace, so you can skip the rest of these steps. **2. Start the agent** On the **Schema** tab, under **Fact Tables**, click **Set up with agent**. A draft opens with the **Set this up with the agent** card. **3. Pick a table or let the agent find one** Choose your fact table in the warehouse browser and click **Map with agent**. If you don't know which table to use, click **Find a table for me**. The agent then looks through your warehouse for the best fit. The agent maps names, roles, derived columns and trace roles. Its proposal appears in the draft editor next to the chat. **4. Ask for changes** Type follow-ups in the **Modeler agent** panel (**Ask the agent about this mapping**). You can also edit any row of the draft yourself. **5. Apply the draft** Click **Apply**. The first apply asks you to confirm: ```text theme={null} This saves the mapping as the workspace's live model, in one version. Reports and Activity read from it once it is saved, and the workspace activates if it is not active yet. ``` Click **Apply and continue** instead to apply and open a new draft right away. **6. Add dimensions** Under **Dimensions**, click **Add with agent** and pick the table. The agent maps it and proposes its join to the fact table. Review the join, then apply. To change the model later, click **Edit with agent** under **Fact Tables**. ### Prompts for the Modeler agent Type these in the **Modeler agent** panel. They're written the way you'd ask a person. > "Map the `events` table as the fact table. Use `event_name` as the event, `received_at` as the timestamp and `user_id` as the subject." > "Add `user_plans` as a dimension joined on user ID, and keep the plan each user had at the time of the event." > "Map `spans` as the fact table and set up trace roles from `span_id`, `parent_span_id` and `trace_id`." ### What the agent can change The Modeler agent edits a draft, never the live model. Nothing changes until you click **Apply**. | Your model | The agent can | | - | - | | No fact table yet | Find and map the first fact table | | One or more fact tables | Re-map or add fact tables, add, re-map or remove dimensions, map a column, rename a field | | Either | Edit derived fields | Raw SQL in a mapping needs a custom connection, one you set up with your own warehouse credentials. The Kubit MCP server and the Claude Code plugin read the model, but they can't create or edit it. Use the Modeler agent for that. ## Map a table by hand The same mapping works without the agent, from the **Schema** tab. 1. Under **Fact Tables**, click **Add table**. The **Add fact table** drawer opens. 2. In **Browse warehouse**, pick the table. Tables already in the model are marked **Already mapped**. 3. Under **Columns**, set a **Field mapping** for each column you want. Give one column the **Event** role, one **Timestamp** and at least one **Subject**. 4. Optionally add a **Row filter**, and check **Preview**. 5. Click **Save**. For a dimension, click **Add dimension**, pick the table and set the **Join type**: | Join type | Use for | Settings | | - | - | - | | **One-to-one** | A table with one row per key, such as a users table | **Field pairs** between the fact table and the dimension | | **Temporal** | A table whose values change over time, such as plan history | **Field pairs**, a **Dimension temporal key** and a **Join match**, such as **Last at or before** | ![Join section of the Edit dimension drawer: Join type set to One-to-one, three field pairs (TRACE\_ID to TRACE\_ID, SPAN\_ID to SPAN\_ID, START\_TIME to EVENT\_TS) with Add pair below, and a Preview table of the dimension's rows.](https://mintcdn.com/kubit/vzHVKaCpdKYs1x9f/images/modeler/dimension-join.png?fit=max\&auto=format\&n=vzHVKaCpdKYs1x9f\&q=85\&s=d2a8f7b771e382c62a13733e211475a7) **Add dimension** stays disabled until the model has a fact table. ## Drafts and versions A draft is a private copy of the model where you or the agent make changes. Only the person who started it can see it. | Action | What happens | | - | - | | **Apply** | Writes every change in the draft to the live model as one version | | **Apply and continue** | Applies, then opens a new draft | | **Discard** | Deletes the draft. The live model doesn't change. | | **New conversation** | Restarts the agent chat. The draft keeps its changes. | A draft can't be applied once the live model changes after it was started. Kubit shows `An unfinished draft was started before this model last changed. It can no longer be applied.` Click **Discard draft** and start again. > [!WARNING] > > An apply that removes or retypes fields warns `Saved reports that use these fields may break.` Kubit doesn't check saved reports for you. Open the reports that use those fields after you apply. ## Agent Observability presets A preset maps a known trace format for you. The MLflow Tracing, Cortex Agents, Google ADK and Langfuse origins each open on their preset tab. 1. Connect the warehouse the preset needs (see the origin table above). 2. On the preset tab, click **Set up MLflow**, **Set up Cortex Agent** or **Set up Google ADK**, and choose the trace table. A Langfuse workspace opens on its **Langfuse** tab. 3. Review the **Tables to create**, then apply. > [!WARNING] > > Apply the preset before you map anything on the **Schema** tab. Mapping a table by hand turns the preset off for that workspace, and it can't be turned back on. A **Sandbox** workspace has no connection to set up. On the **Uploads** tab, drop a span file in OTLP, Langfuse, Phoenix, MLflow, LangSmith, Braintrust, Datadog, AWS CloudWatch or Snowflake Cortex format. The first upload creates the schema. ## Verify A workspace activates once it has all three of these: * A warehouse connection * A fact table with an **Event** and a **Timestamp** column * At least one enabled subject Kubit activates it on the apply that completes the list. No separate button exists. Before that, the workspace shows the banner `No data yet. Finish setting up your model.` with a **Set up model** button. To check the model, open a [Query report](https://learn.kubit.ai/product-analytics/reports/query.md) and look for your events and fields in the pickers. ## Limits | Constraint | Value | | - | - | | Delete a subject | **Not possible.** Disable it instead. | | Turn a subject back into a regular field | **Not possible** | | Disable the only enabled subject | **Not possible.** Enable another subject first. | | Subject name length | **50** characters | | Remove the last fact table | **Not possible** | | Event and Timestamp columns per fact table | **1** each | | Field name | Starts with a letter. Stored as uppercase letters, digits and underscores (`^[A-Z][A-Z0-9_]*$`). | | Raw SQL joins, raw SQL derived fields, row filters, **Data Refresh Look-Back** | Custom connection only | | Redshift connection in the Modeler | **Not supported.** The form shows `Redshift connections aren't supported yet.` | ## If it fails | Symptom | Cause | Fix | | - | - | - | | `A fact table needs an event, a timestamp, and at least one subject.` | The fact table is missing a required role | Give one column the **Event** role, one **Timestamp** and one **Subject** | | `A fact table can have only one event.` or `A fact table can have only one timestamp.` | Two columns have the same role | Map the second column as a regular field | | `Add a fact table first — dimensions join to a fact table.` | The model has no fact table yet | Add a fact table, then the dimension | | `The join requires at least one field pair or sql condition.` | The dimension join is empty | Add a field pair under **Field pairs** | | `Raw SQL join conditions require a custom (user-supplied) connection.` | The workspace doesn't use your own warehouse credentials | Use field pairs instead | | `A subject cannot be converted back to a regular field — disable it instead.` | Subjects are permanent | Disable the subject on the **Subjects** panel | | `Cannot disable the only enabled subject — enable another first.` | Every model needs one enabled subject | Enable another subject, then disable this one | | `Field '' is still referenced and cannot be removed.` | Another part of the model still uses the field | Remove that use first, then the field | | `This workspace's model changed since you opened it. Reload the page, then try again.` | Someone applied a change while you were editing | Reload the page and make the change again | | `An unfinished draft was started before this model last changed. It can no longer be applied.` | The live model moved on after the draft started | Click **Discard draft** and start a new one | | `You have read-only access. Modifications are not permitted.` | Your role is **Viewer** or **Member** | Ask an **Admin** or **Owner** to change the model or your role | | The **Schema** tab is disabled on a preset workspace | The preset hasn't been applied yet | Apply the preset from its tab first | ## Next steps * [Bring your own warehouse](https://learn.kubit.ai/warehouses/overview.md): how Kubit connects to your warehouse, and links to each setup page. * [Reports overview](https://learn.kubit.ai/product-analytics/reports/overview.md): the report types that read your model. * [Concepts](https://learn.kubit.ai/agent-observability/concepts.md): traces, spans, sessions and execution paths in Agent Observability. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.