Skip to main content
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. To create the workspace, see Set up your organization.

​
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, BigQuery, Databricks or ClickHouse
  • 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:
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.
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.

​
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:
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. 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 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.
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. 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.
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.
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 and look for your events and fields in the pickers.

​
Limits

​
If it fails

​
Next steps