# Mitzu Documentation - full text > Mitzu runs product analytics - funnels, retention, segmentation, journeys and user lookup - directly on your data warehouse, without copying event data out of it. An index of the same pages is available at https://docs.mitzu.io/llms.txt The REST API reference is omitted here; use the OpenAPI spec at https://docs.mitzu.io/contracts/api/v1/api.yaml --- # Get Started: Mitzu environments Source: https://docs.mitzu.io/connect-mitzu Mitzu can be hosted in different environments. The table below shows the possible ways to connect Mitzu with your data warehouse. | | [Mitzu Cloud](#mitzu-cloud) | [Private Mitzu Instance](#private-mitzu-instance) | | --- | --- | --- | | Biggest benefit | Works out of the box; you don't need to engage in hosting and maintenance tasks. | Can be fully isolated from the Internet to comply with your privacy policies. | | Data warehouse **is** reachable through the Internet | Sign up and configure the data warehouse connection following the [Setup Mitzu](https://docs.mitzu.io/setup-mitzu) guide. | | | Data warehouse **is not** reachable through the Internet | We can establish a custom network connection between Mitzu Cloud and your data warehouse if it is feasible (e.g. using AWS VPC Peering, AWS VPC Endpoint, etc...). | The Private Mitzu Instance environment can be linked to your private network without breaching any privacy policies. Establishing network connectivity is the company's responsibility; the Mitzu team is happy to help resolve any connectivity issues. | ## Mitzu Cloud [https://app.mitzu.io](https://app.mitzu.io) is publicly available to everyone over the Internet. This environment is continuously updated with the most recent Mitzu versions, containing the newest features and bug fixes. ## Private Mitzu instance The Mitzu team can deploy a Mitzu instance right into your cloud. This instance can be isolated from the Internet to increase privacy and to comply with your company's privacy policies. The Mitzu team requires access to the environment for maintenance purposes and to deploy the latest version on a prearranged schedule. --- # Get Started: Quick Start with Mitzu Source: https://docs.mitzu.io/ Let's get started with Mitzu. We will walk you through the steps to create a simple workspace and connect your data. ## Prerequisites Depending on your current situation, there are two ways to get started with Mitzu. Because Mitzu is warehouse-native, you need a data warehouse or data lake to work with. > **INFO** > > **No data warehouse? No problem!** > > We have guides to help you get started with a data warehouse. Setting one up is simple and can be done in a few minutes. ## Choose one of the options below [ ![We don't have a data warehouse](https://docs.mitzu.io/img/setup-data-warehouse/play-circle-line.svg) ### We don't have a data warehouse Follow this guide to get started with a data warehouse or data lake. We will walk you through how to ingest data to your data warehouse. ](https://docs.mitzu.io/setup-data-warehouse)[ ![We have a data warehouse](https://docs.mitzu.io/img/setup-data-warehouse/database-2-line.svg) ### We have a data warehouse Choose this option if you already have a data warehouse and you already collect product or business data. ](https://docs.mitzu.io/setup-mitzu) --- # Get Started: Set up Mitzu on your data warehouse Source: https://docs.mitzu.io/setup-mitzu Let's get started with Mitzu. This page will help you set up your first workspace and connect your data. ## Sign up for Mitzu Open the [https://app.mitzu.io](https://app.mitzu.io) website and click the `Log in with Google` button to use your Google account, or click `Sign up` to register with an email and password. After you sign up, you will receive an email to verify your account. ![image](https://docs.mitzu.io/img/setup-mitzu/login.png) ![image](https://docs.mitzu.io/img/setup-mitzu/signup.png) > **WARNING** > > Login with company SSO is only available for existing organizations on an Enterprise plan. ## Create a new organization After logging in, name your organization and click `Create Organisation`. ![image](https://docs.mitzu.io/img/setup-mitzu/create-org.png) ## Connect your data warehouse to Mitzu Your organization contains an empty workspace. To use Mitzu, you need to configure this workspace. The remaining steps to configure Mitzu are listed in the left sidebar of the main page. ![image](https://docs.mitzu.io/img/setup-mitzu/onboarding-connection.png/) Click the `Connect Mitzu with your data warehouse` button to configure your connection. The [warehouse integrations](https://docs.mitzu.io/warehouse-integrations) page provides more information about the connection settings. > **INFO** > > Throughout this example, we will use BigQuery as our data warehouse. Mitzu currently supports 11 data warehouse solutions: > > - AWS Athena > - Google BigQuery > - ClickHouse > - Databricks > - Firebolt > - Microsoft Fabric > - Postgres > - Redshift > - Snowflake > - Starburst > - Trino / Presto ![image](https://docs.mitzu.io/img/bigquery/connection.png/) ## Add tables to your workspace Add event tables on the `Event tables` tab. Event tables are regular tables in BigQuery (or in any data warehouse). The only requirement is that they have some kind of `user ID` and `event time` columns. Optionally, they can also have an `event name` field. Event tables are the basis of Mitzu's event catalog. Based on the event tables you define, you can uncover new insights from your data without any SQL knowledge. ![image](https://docs.mitzu.io/img/event-tables/image.png) The [event tables](https://docs.mitzu.io/event-tables) page provides more information about the event table configuration. ## Create your first insight Configuring a single event table is enough to create your first insight. Click the `Create insight` button in the top-left corner of the navbar; this loads the [Insights page](https://docs.mitzu.io/insights-basics). When you click the `Select an event` button, you should see your events. Once you choose an event, the chart will appear. ![image](https://docs.mitzu.io/img/setup-data-warehouse/image-19.png) ## Event tables for product analytics Your application should track events that are ultimately stored in your data warehouse. These events should be stored either as **separate tables** or as a **single table**. - In the case of separate tables, Mitzu will automatically discover the event names from the table names. - In the case of a **single big table**, please provide the `Event name` column on the workspace settings page. > **NOTE** > > More on this subject in the [event tables](https://docs.mitzu.io/event-tables) section. ## Dimension tables for product analytics Your data warehouse may contain dimension tables with additional information about certain entities, such as users, groups, or sessions. By configuring these tables, you can filter your events based on the dimension values. > **NOTE** > > More on this subject in the [dimension tables](https://docs.mitzu.io/dimension-tables) section. ## Event tables for marketing analytics Your landing page should track events that are ultimately stored in your data warehouse. The setup is similar to the one for product analytics. > **INFO** > > Mitzu unifies marketing and product analytics in a single platform. This means you can analyze the entire user life cycle in one place. > > The key to this challenge is user ID unification. You can learn more about this [here](https://www.mitzu.io/post/identifying-users-in-the-data-warehouse). > > More content on this subject is coming soon. --- # Get Started: Set up a data warehouse Source: https://docs.mitzu.io/setup-data-warehouse ## Data warehouses for dummies Historically, setting up a data warehouse **was** a complex task that required a dedicated team of data engineers. However, we now live in an era where setting up a cloud data warehouse is a breeze. This guide will walk you through the steps to set up a data warehouse for Mitzu. > **INFO** > > The great thing about this guide is that it will continue to serve you in the later stages of your data journey. ## Step 1. Choose a data warehouse solution For most companies, we recommend starting with one of the simplest solutions: - Clickhouse - Snowflake - BigQuery - PostgreSQL In this guide, we will use **BigQuery** as an example. > **INFO** > > Google BigQuery is an excellent choice for most companies that are starting out with data warehouses. It is easy to set up and has a free tier. > > Please get in touch with us if you want to use another data warehouse. You can find our [Slack community](https://join.slack.com/t/mitzu-io/shared_invite/zt-1h1ykr93a-_VtVu0XshfspFjOg6sczKg) here. ## Step 2. Set up BigQuery (5-10 mins) Getting started with BigQuery is easy: 1. Go to the [BigQuery console](https://console.cloud.google.com/bigquery). 2. Create a new free account (a credit card is required), but the first 10GB of data storage is free. 3. Go to the BigQuery console: [BQ Admin](https://console.cloud.google.com/bigquery). Here, you should see your default project. 4. Create a new dataset. ![image](https://docs.mitzu.io/img/setup-data-warehouse/image.png) We suggest keeping it as a single-region dataset. 5. Once done, your BigQuery project should look like this: ![image](https://docs.mitzu.io/img/setup-data-warehouse/image-1.png) 6. Create a [service account](https://console.cloud.google.com/iam-admin/serviceaccounts) to access your data warehouse. The service account should have the `BigQuery Admin` role. You can change this later if needed. 7. Create a new JSON access key under the `Manage keys` menu item. ![image](https://docs.mitzu.io/img/setup-data-warehouse/image-2.png) ![image](https://docs.mitzu.io/img/setup-data-warehouse/image-3.png) Mitzu will use this JSON key to access your data warehouse in the next steps. > **SUCCESS** > > **Congratulations!** You have successfully set up your data warehouse. ## Step 3. Collect data into BigQuery (10-15 mins) Moving data into your data warehouse is also very simple. You have multiple options available: - **Using a CDP** (Customer Data Platform) like [Segment](https://segment.com), [RudderStack](https://rudderstack.com), [Jitsu](https://jitsu.com), or [Snowplow](https://snowplow.io) - **DIY** - build your own solution to collect data (not recommended) This guide will use **Jitsu**, as it is the simplest way to get started. > **NOTE** > > Jitsu is an excellent choice for most companies that need to ingest data into a data warehouse. It is easy to set up and has a very generous free tier. By the end of this guide, you will have a Jitsu account, with data from your landing page, your application, and Stripe collected into BigQuery. You should see the result below: ![image](https://docs.mitzu.io/img/setup-data-warehouse/image-6.png) Let's get started! Go to [Jitsu](https://jitsu.io) and create a new free account. ![image](https://docs.mitzu.io/img/setup-data-warehouse/image-4.png) ### 3.1. Add BigQuery as a destination Create your first destination by clicking the `+ Add` button under destinations. Choose `BigQuery` as the destination. ![image](https://docs.mitzu.io/img/setup-data-warehouse/jitsu_dest.png) ### 3.2. Add your landing page visits as a data source Create your first data source by clicking the `+ Add` button under data sources. Then, name your data source and create a browser key. You can leave the rest as default. ![image](https://docs.mitzu.io/img/setup-data-warehouse/image-7.png) You must embed a JavaScript snippet into your website to finalize your setup. This part is probably the easiest. Copy Jitsu's JavaScript snippet and paste it into your website's `` section. You can find the snippet under the `Setup instructions` menu item. ![image](https://docs.mitzu.io/img/setup-data-warehouse/image-5.png) Finally, connect your new data source to the BigQuery destination. You can do this by clicking the `Connections` button in the middle of the overview page. ### 3.3. Add your application as a data source Adding the application data source is similar to adding the landing page data source. However, you will most likely use an SDK to collect the data. Jitsu currently supports multiple SDKs. You can find the list of supported SDKs under the `Setup instructions` menu item. ![image](https://docs.mitzu.io/img/setup-data-warehouse/image-9.png) > **INFO** > > Remember to connect your data source to the BigQuery destination. ### 3.4. Add Stripe as a data source Now we will add Stripe as a data source. This is valuable for measuring revenue inside Mitzu. Mitzu lets you analyze revenue based on user segments. > **WARNING** > > Mitzu works best with Stripe data for consumer products. The product `userID` must also be stored as metadata on your Stripe customers. Follow this [guide](https://docs.stripe.com/metadata) to add metadata to your Stripe customers. The best way to integrate Stripe with Mitzu is to follow the guide provided by Jitsu. This guide will appear when you add your Stripe connector. ![image](https://docs.mitzu.io/img/setup-data-warehouse/image-16.png) Here is what it should look like: ![image](https://docs.mitzu.io/img/setup-data-warehouse/image-12.png) ## Step 4. Verify your setup As a final step, let's verify that everything is working as expected. You should see the following tables in BigQuery: ![image](https://docs.mitzu.io/img/setup-data-warehouse/image-13.png) ## Step 5. Connect BigQuery to Mitzu (10 mins) Follow the [Setup Mitzu](https://docs.mitzu.io/setup-mitzu) guide. --- # Get Started: Warehouse-native architecture Source: https://docs.mitzu.io/warehouse-native Mitzu runs product analytics directly on your data warehouse. Mitzu connects to your warehouse with read-only credentials, generates SQL, and runs every analytical query inside the warehouse itself. Event data is never ingested, duplicated, or stored outside your warehouse. This page describes the mechanism: what Mitzu queries, what Mitzu stores, who pays for compute, and what access Mitzu needs. ## How queries run Every insight in Mitzu — a [funnel](https://docs.mitzu.io/funnel), a [retention](https://docs.mitzu.io/retention) chart, a [segmentation](https://docs.mitzu.io/segmentation), a [journey](https://docs.mitzu.io/journey) — is an analysis specification: the events, filters, breakdowns, and time windows that define it. Mitzu's query engine translates that specification into SQL. Your warehouse executes the SQL and returns aggregated results. - Mitzu generates the SQL. Your warehouse executes it. - Results returned to Mitzu are aggregates — counts, rates, and time series — not raw event rows. - Every generated query is inspectable: the `Show SQL` option on the [Insights page](https://docs.mitzu.io/insights-basics) displays the exact SQL Mitzu produced, and the [Query Admin](https://docs.mitzu.io/query-admin) tab lists the queries Mitzu has sent to your warehouse, with warehouse-reported status and statistics. ## What Mitzu queries Mitzu connects to the following data warehouses and query engines: - [Snowflake](https://docs.mitzu.io/snowflake) - [Google BigQuery](https://docs.mitzu.io/bigquery) - [Databricks](https://docs.mitzu.io/databricks) - [AWS Redshift](https://docs.mitzu.io/redshift) - [AWS Athena](https://docs.mitzu.io/aws-athena) - [PostgreSQL](https://docs.mitzu.io/postgresql) - [ClickHouse](https://docs.mitzu.io/clickhouse) - [Self-hosted Trino / Presto](https://docs.mitzu.io/trino) - [Starburst](https://docs.mitzu.io/starburst) - [Firebolt](https://docs.mitzu.io/firebolt) - [Microsoft Fabric](https://docs.mitzu.io/fabric) Teams without event data in a warehouse can also start from an [uploaded CSV](https://docs.mitzu.io/uploaded-csv). The [warehouse integrations](https://docs.mitzu.io/warehouse-integrations) page covers connection settings for each engine. Mitzu works on raw event tables as well as modeled tables. dbt-modeled tables, Segment `tracks` tables, Snowplow events, GA4 exports, and Firebase analytics tables are all queried in place — see [data modeling](https://docs.mitzu.io/data-modeling). ## What Mitzu never copies > **SUCCESS** > > Mitzu never copies event data out of your warehouse, and never modifies data in it. Raw event rows are not ingested, duplicated, or stored outside your warehouse. What Mitzu stores on its side is the semantic layer and your saved work: - **Semantic-layer metadata** — event names, event and dimension property names, and sampled filter values discovered during [indexing](https://docs.mitzu.io/indexing). Sampled filter value lists are capped at 500 values per property; high-cardinality columns are not extracted. - **Saved assets** — insight definitions, dashboards, and cohort definitions. A cohort is stored as its definition, not as a list of user rows. - **Aggregated results** — cached chart results, so a dashboard can render without re-querying your warehouse. Raw event data is not part of any cache. The [AI Data & Privacy](https://docs.mitzu.io/ai-data-privacy) page describes the same isolation guarantees for the agent surfaces: raw event data never leaves your warehouse for the model. ## Who pays for compute Queries run in your warehouse, so query compute appears on your warehouse bill, under your control. Mitzu's own pricing is seat-based and does not meter events or queries. You control the cost of that compute directly: - Warehouse sizing stays your decision — Mitzu queries whatever engine and size you configure. - [Performance settings](https://docs.mitzu.io/performance-settings) control sampling and resolution, which bound how much data each query scans. - Cached results and auto-refresh windows on [dashboards](https://docs.mitzu.io/dashboards/edit-dashboard) avoid re-running queries whose results are still fresh. - The [Query Admin](https://docs.mitzu.io/query-admin) tab shows warehouse-reported statistics — bytes processed, rows returned, elapsed time — for every query Mitzu runs, and lets you cancel running queries. ## What read access Mitzu needs Mitzu needs read access to the databases, schemas, and tables you configure in your workspace — nothing more. We strongly recommend creating a dedicated read-only user for Mitzu in your data warehouse; see [connection settings](https://docs.mitzu.io/connection-settings). Concrete, per-warehouse requirements where the platform defines named roles: | Warehouse | Required access | | --- | --- | | BigQuery | A service account with the `BigQuery User`, `BigQuery Data Viewer`, `BigQuery Job User`, and `BigQuery Read Session User` roles — see [BigQuery](https://docs.mitzu.io/bigquery) | | AWS Athena | An IAM user with Athena query execution, Glue catalog read, and S3 read access to your data, plus write access to the S3 query-results bucket only — see [AWS Athena](https://docs.mitzu.io/aws-athena) | | Trino | A read-only rule for the configured catalogs in the System Access Control file — see [Trino](https://docs.mitzu.io/trino) | | Starburst | A user and role with read-only privileges on your data catalog — see [Starburst](https://docs.mitzu.io/starburst) | | All others | A dedicated user with `SELECT` access to the configured schemas and tables — see the [connector pages](https://docs.mitzu.io/warehouse-integrations) | Connecting validates with a `SELECT 1;` — Mitzu asks for no write access to your data. ## How the semantic layer is configured You do not hand-author the semantic layer. The [Configuration Agent](https://docs.mitzu.io/configuration-agent) builds it by scanning your warehouse: 1. It identifies event tables and dimension tables, recognizing vendor patterns such as Segment `tracks`, Snowplow events, GA4 event tables, and Firebase analytics. 2. It maps user and group identifiers, timestamps, and event names, and configures the tables it is confident about automatically. Ambiguous tables are confirmed with you. 3. [Indexing](https://docs.mitzu.io/indexing) then populates the semantic layer with the events, properties, and sampled filter values the query engine uses to answer questions. Configuring a single event table is enough to create your first insight, and most workspaces are configured in minutes. As your warehouse evolves, re-running the agent keeps the semantic layer in sync. ## Deployment options Mitzu Cloud runs at [app.mitzu.io](https://app.mitzu.io) and connects to your warehouse over the network. For stricter isolation requirements, the Mitzu team can deploy a private Mitzu instance into your own cloud, which can be isolated from the Internet — see [connect Mitzu](https://docs.mitzu.io/connect-mitzu). In both deployments the architecture is the same: queries run in your warehouse, and event data stays there. --- # Get Started: CSV Uploads Source: https://docs.mitzu.io/get_started/csv-uploads You can upload CSV files directly in Mitzu to create a new data table that can be used in analysis. ## Uploading a file Open the project's CSV upload widget and pick a file from the file chooser — the file is ingested as soon as it is selected and shown in the list as **Pending save**. Repeat for additional files, then click **Save** to commit them to the project. Pending uploads can be removed with the trash icon before saving. ## Supported column types Mitzu automatically detects and maps common scalar types from CSV values. - `Int` - whole numbers, for example `1`, `42`, `9000` - `Float` - decimal numbers, for example `10.2`, `0.75` - `Date` - calendar dates, for example `2024-01-01` - `Timestamp` - date and time values, for example `2024-01-01 10:15:01` - `String` - text values If a value is empty, Mitzu keeps it as null. ## CSV upload limits and behavior - Maximum file size: **20 MB** per upload - File must be in valid CSV format - Uploads are processed in chunks for reliability on larger files - Column names are normalized to safe names (for example, spaces become underscores) ## Important limitations - Only CSV input is supported in this flow - Complex nested data structures are not inferred from CSV values - Type detection is based on the values present in the uploaded file - Mixed formats in a single column may be interpreted as text ## Tips for best results - Include a header row with clear column names - Keep each column semantically consistent (for example, do not mix numbers and free text) - Use ISO-like date and timestamp formats where possible --- # Mitzu Agent: Mitzu Agent Source: https://docs.mitzu.io/mitzu-agent Mitzu Agent is your AI-powered analytics partner. It operates in two modes to help you get the most out of your product data. ## Analytics Agent The analytics agent answers questions about your product data in natural language. Ask about user behavior, trends, and conversions, and get answers as charts and insights. It can create segmentation, funnel, and retention analyses, search your existing saved insights, and explore your data catalog. You can also ask questions directly from [Slack](https://docs.mitzu.io/slack-agent). ## Scheduled Agents [Scheduled agents](https://docs.mitzu.io/scheduled-agents) run a Mitzu agent automatically on a schedule you set — daily or weekly — and email the results to your team. Add a plain-English trigger and the agent emails you only when a run's answer meets the condition, so quiet weeks stay quiet. Every run opens a real Mitzu conversation, one click from the email. ## MCP Server The [MCP server](https://docs.mitzu.io/mcp-server) connects Claude, Cursor, ChatGPT, and other MCP-compatible AI tools directly to your Mitzu workspace, so you can ask analytics questions from your editor or chat client. ## Configuration Agent The configuration agent helps you set up your workspace. It scans your data warehouse schemas, identifies event and dimension tables, maps the right columns, and triggers indexing — taking you from a raw warehouse to a working analytics setup with minimal effort. It recognizes common vendor patterns like Segment, Snowplow, GA4, and Firebase. ## Learn more [ ![Analytics Agent](https://api.iconify.design/tabler/chart-line.svg?width=36&height=36) ### Analytics Agent Ask questions about your data, create insights, and explore your analytics. ](https://docs.mitzu.io/analytics-agent)[ ![How the Agent Works](https://api.iconify.design/tabler/topology-star-3.svg?width=36&height=36) ### How the Agent Works The architecture: the agent composes analysis specifications, a deterministic query engine generates the SQL. ](https://docs.mitzu.io/how-the-agent-works)[ ![Scheduled Agents](https://api.iconify.design/mdi/calendar-clock.svg?width=36&height=36) ### Scheduled Agents Run an agent on a schedule and get emailed only when the results meet a condition you set. ](https://docs.mitzu.io/scheduled-agents)[ ![Configuration Agent](https://api.iconify.design/tabler/settings-cog.svg?width=36&height=36) ### Configuration Agent Set up your workspace by scanning your data warehouse and configuring tables. ](https://docs.mitzu.io/configuration-agent)[ ![Slack Agent](https://api.iconify.design/logos/slack-icon.svg?width=36&height=36) ### Slack Agent Use Mitzu Agent directly in Slack channels and DMs. ](https://docs.mitzu.io/slack-agent)[ ![MCP Server](https://docs.mitzu.io/img/mitzu-agent/mitzu-mcp.png) ### MCP Server Connect Claude, Cursor, ChatGPT, and other MCP-compatible AI clients to your workspace. ](https://docs.mitzu.io/mcp-server)[ ![Data & Privacy](https://api.iconify.design/tabler/shield-lock.svg?width=36&height=36) ### Data & Privacy How Mitzu Agent handles your data: metadata isolation, no model training, and retention controls. ](https://docs.mitzu.io/ai-data-privacy) --- # Mitzu Agent: Analytics Agent Source: https://docs.mitzu.io/analytics-agent The analytics agent helps you understand your product data through natural language. Ask a question, and the agent will search your workspace, explore your data catalog, and create the right analysis for you. ![image](https://docs.mitzu.io/img/mitzu-agent/agent-demo.gif) ## Where to access the agent You can start a conversation with the agent from several places: - **Home page** — type your question directly in the input area. - **Sidebar navigation** — click **Mitzu Agent** in the left sidebar to start a new conversation in a full-screen interface. - **Floating button** — the agent button in the bottom-right corner is available on every page. Click it to open the agent in sidebar mode without leaving your current view. ![image](https://docs.mitzu.io/img/mitzu-agent/agent-entry-points.png) The floating button opens the agent in **sidebar mode**, letting you chat while keeping your current page visible. You can switch between sidebar and full-screen modes at any time using the **Expand** and **Minimize** buttons. ## What you can ask The agent supports several types of analysis. Here are examples for each. ### Segmentation Count events, unique users, trends over time, and breakdowns by properties. - "How many users signed up this week?" - "Show me daily active users over the last 3 months" - "Compare signups by country" - "What percentage of active users made a purchase?" ### Funnels Track conversion rates through sequential steps. - "What's the conversion rate from signup to first purchase?" - "Which campaigns drive the best conversion?" - "How long does it take users to go from trial to paid?" Ask for two funnels at once, or for a funnel next to something else, and you get **one** chart rather than two: - "Compare the signup funnel and the trial funnel by country, as a pivot table" - "Show the signup funnel conversion next to the number of trials started" If a saved funnel matches the question, the agent uses it, so the chart runs the workspace's own definition. If none matches, it builds the funnel, saves it, and names the insights it saved. See [Metrics](https://docs.mitzu.io/metrics). ### Retention Measure whether users return after an initial action. - "What's our day 1, day 7, day 30 retention?" - "Show me retention by signup source" - "Are users who signed up last month coming back?" ### Discovery Explore existing insights and your data catalog. - "What insights do we have about engagement?" - "What events do we track?" - "Show me the top insights" ## How the agent works When you ask a question, the agent follows a structured workflow: 1. **Searches your workspace** for existing saved insights that match your question. If a relevant insight exists, the agent runs it and shows you fresh results rather than creating a duplicate. 2. **Explores your data catalog** if no existing insight matches. The agent discovers the right events, properties, and dimension tables to answer your question. 3. **Creates an analysis** — a segmentation, funnel, or retention insight — and runs it to generate a chart and key findings. 4. **Presents the results** with a summary highlighting the most important numbers, alongside a chart visualization. Occasionally the agent will also embed a [custom chart](#custom-charts) when a derived view — a ratio, a joined top-N, or an overlay — would make the answer easier to read. ## Custom charts Custom charts let the agent go a step beyond running individual Mitzu insights. It can combine the results of multiple insights and run its own calculations on top of them — a ratio between two metrics, a period-over-period diff, a trend overlay — to answer questions that no single saved insight can answer on its own. The agent then presents the derived result as a **custom chart**: a collapsible card with a violet **Custom** badge, embedded directly inside its summary so the calculation is easy to digest in context. ![image](https://docs.mitzu.io/img/mitzu-agent/custom-chart-inline.png) ### When the agent draws one - **Derived ratios** — e.g., "Show me DAU/MAU ratio over the last 90 days." The ratio isn't a saved insight, so the agent computes it from DAU and MAU and plots just the ratio as a line. - **Period-over-period comparisons** — e.g., "Show me signups by plan tier in Q3 vs Q4 with the % change." The agent runs both periods, computes the growth, and renders a small comparison table with the diff column already filled in. - **Funnel trends on one chart** — e.g., "Plot the signup → activation conversion rate week over week alongside the trial → paid conversion rate." A single funnel has multiple steps and can't share one chart with another, but the overall conversion rate of each funnel is one number per week, so the agent renders both as lines on the same chart and you can see the trends moving together (or apart). ### Working with a custom chart Custom charts are presentation only — they expand and collapse, but cannot be saved as insights, added to dashboards, or opened in the explore view, and only one appears per agent message. The Mitzu insights the calculation is built on are already shown above the summary — those are the savable artifacts, and you can [save them or add them to a dashboard](#working-with-results) from there. ## Working with results When the agent creates an insight, you can: - **Click the insight link** to open it in the full explore interface - **Edit the metric** — change filters, time windows, breakdowns, or aggregation types - **Save it** as a workspace insight for future use - **Add it to a dashboard** to track alongside other metrics The agent can also create and update [cohorts](https://docs.mitzu.io/other_assets/cohorts) directly from a request — for example, "save the users who dropped off at checkout as a cohort." The same goes for [global annotations](https://docs.mitzu.io/other_assets/annotations): "add an annotation for the v2.0 release on 15 March" creates one, and "hide the Black Friday annotation" or "move the pricing change to 10 February" edits an existing one. The agent proposes the title, time and change first and saves only after you confirm. On dashboards, the agent works with more than charts: it can add [text cards and section dividers](https://docs.mitzu.io/dashboards/edit-dashboard#text-cards), place new content directly above a chosen panel ("add an Activation header above the signup funnel"), rewrite an existing text card or divider label, and add its own summaries to a dashboard when you ask. When you edit the dashboard you are currently viewing, the page updates in place as soon as the agent finishes — added panels appear, removed ones disappear, and renames, text edits, and dashboard-wide filter changes apply without a reload, so the sidebar conversation keeps its place. The refresh only reads already-computed results: panels without a stored result for a new filter show **Results are missing** with their own Refresh button, so re-running queries stays your call. Dashboard panels are cached, so the agent checks how old they are before it uses them. Ask what a dashboard shows and it reports the values on screen, tells you when they were last refreshed if they are older than the dashboard's refresh schedule, and offers to refresh the dashboard for you. Ask for a number and the agent treats a matching dashboard panel as the definition to reuse: if the panel is out of date it re-runs the insight for current figures, tells you the dashboard itself still shows the older values until it is refreshed, and applies the dashboard's own filters only when you are looking at that dashboard. ## Conversations The agent supports multi-turn conversations. You can ask follow-up questions in the same thread, and the agent will maintain context from previous messages. - **Start a new conversation** anytime using the "New conversation" button in the header - **Switch views** between full-screen and minimized sidebar mode - **Find past conversations** — recent chats are shown in the sidebar agent panel. Click **View all** to see your full conversation history on the All Content page. ![image](https://docs.mitzu.io/img/mitzu-agent/agent-chat-history.png) ## AI settings Configure the agent's behavior in **Settings → Insight Settings → AI Settings**. ![image](https://docs.mitzu.io/img/mitzu-agent/ai-settings.png) ### Custom instructions Add workspace-specific context that the agent uses for every query. This is useful for: - Domain-specific terminology (e.g., "a 'conversion' means a completed purchase") - Default conventions (e.g., "always use weekly time groups" or "our conversion window is 7 days") - Business context (e.g., "our fiscal year starts in April") > **INFO** > > Custom instructions apply to all agent queries in the workspace. Keep them concise and focused on context that would help the agent give better answers for your specific product and data. ### Web search Off by default. When enabled, the agent can look up information on the public internet to enrich its answers. Two situations where this is most useful: - **Correlating your data with real-world events** — e.g., "did our signups dip the week of the AWS us-east-1 outage?" or "compare our traffic on Black Friday to last year". The agent can pull in the external context (dates, news, public benchmarks) and combine it with the numbers from your workspace. - **Updating your workspace config from your own website** — e.g., "look at our pricing page and add the plan tiers as a dimension" or "fetch our public docs and use them to rename these events". The agent can read your public-facing pages and use them to inform catalog changes. Enable it from **Settings → AI Settings → Web search**. See [AI settings](https://docs.mitzu.io/ai-settings#web-search) for details. ## Getting better results The agent discovers events, properties, and dimensions from your configured data catalog. The quality of its answers depends directly on how well-organized your analytics data is — better naming, organization, and completeness mean better insights. Here are actionable ways to improve the agent's output: - **Use descriptive display names** — if your raw column names are cryptic (e.g., `evt_pg_vw`), add clear display names (e.g., "Page View") so the agent can find the right events - **Create [custom events](https://docs.mitzu.io/custom-events)** for key business actions — this gives the agent clean, meaningful concepts to work with instead of raw event table names - **Configure [dimension tables](https://docs.mitzu.io/dimension-tables)** for user attributes you frequently analyze — the agent uses these for breakdowns like "by country" or "by plan" - **Add property descriptions** — descriptions help the agent understand what a property means and when to use it for filters and breakdowns - **Keep your catalog up to date** — re-index after adding new tables or columns so the agent has access to your latest data - **Use custom instructions** (see above) to give the agent domain context it can't infer from the data alone - **Use [planning mode](https://docs.mitzu.io/planning-mode)** for broad or multi-step questions — the agent proposes a plan you can review and refine before any work runs, so you steer the investigation rather than redirect a finished one --- # Mitzu Agent: How the Analytics Agent works Source: https://docs.mitzu.io/how-the-agent-works Mitzu's Analytics Agent does not write SQL. The agent composes **analysis specifications** — the structured parameters of a funnel, retention, or segmentation analysis — against a semantic layer specialised for product analytics. A deterministic query engine turns each specification into SQL and your warehouse executes it. The same specification always produces the same SQL, and the same answer. This page describes that architecture. For day-to-day usage — where to open the agent and what to ask — see the [Analytics Agent](https://docs.mitzu.io/analytics-agent) page. ## The division of labor | The agent | The query engine | | --- | --- | | Interprets your question | Generates the SQL | | Discovers the right events, properties, and dimensions in the [data catalog](https://docs.mitzu.io/event-catalog) | Applies product analytics methodology — conversion windows, cohort bucketing, deduplication | | Assembles the analysis specification: events, filters, breakdowns, time windows | Executes deterministically: same specification, same SQL, same answer | | Summarises and explains the results | Returns the generated SQL for inspection | The specification for a funnel names the first event, the subsequent steps, the conversion window, and the breakdowns. The specification for retention names the cohort-defining event, the return event, and the time granularity. The specification for a segmentation names the event, filters, breakdown, and time window. The agent fills in these parameters; it never authors the query text. ## Why the agent does not write SQL Product analytics errors are usually methodology errors, not syntax errors: a funnel computed without a conversion window, a retention chart that does not bucket cohorts by time, a segmentation that counts the same user twice. A query can be syntactically valid and still methodologically wrong. Mitzu removes that failure mode by taking SQL authorship away from the language model entirely. The query engine that turns specifications into SQL is the same deterministic code that powers the [Insights page](https://docs.mitzu.io/insights-basics) — methodology is implemented once, in the engine, and every query inherits it. The model cannot introduce a methodology error into SQL it never writes. Every generated query remains inspectable: the `Show SQL` option displays the exact SQL the engine produced, and the [Query Admin](https://docs.mitzu.io/query-admin) tab lists every query sent to your warehouse. The SQL is a verification artifact — it is there for your analysts to review, not the agent's authored output. ## What the semantic layer expresses The agent's vocabulary is the semantic layer that the [Configuration Agent](https://docs.mitzu.io/configuration-agent) builds from your warehouse and [indexing](https://docs.mitzu.io/indexing) keeps populated: - **Events and event properties** discovered from your event tables - **Entities** — users and groups — and the dimension properties attached to them - **Sampled filter values**, so filters are suggested from values that actually exist in your warehouse rather than invented - **Saved insights, dashboards, and cohorts**, which the agent searches and reuses before creating anything new This layer is shaped for product analytics rather than for BI. A metrics-and-dimensions semantic layer has no native representation of a funnel's step sequence and conversion window, a retention cohort and its return event, or a user journey. Mitzu's semantic layer and engine express these directly — the engine constructs [funnel](https://docs.mitzu.io/funnel), [retention](https://docs.mitzu.io/retention), [segmentation](https://docs.mitzu.io/segmentation), and [journey](https://docs.mitzu.io/journey) queries from specifications, deterministically. See [data modeling](https://docs.mitzu.io/data-modeling) for how the layer is structured. ## What the agent can do - Create and run **segmentation, funnel, and retention insights**, and present the results with charts and a summary — the four-step workflow is described in [How the agent works](https://docs.mitzu.io/analytics-agent#how-the-agent-works) - **Reuse saved insights** that already answer your question, instead of creating duplicates - **Explore the data catalog** — events, properties, existing insights — to answer discovery questions - Create and update **cohorts** from a request - Combine insight results into presentation-only [custom charts](https://docs.mitzu.io/analytics-agent#custom-charts) — ratios, period-over-period diffs, overlays - Hold **multi-turn conversations**, propose a reviewable plan in [planning mode](https://docs.mitzu.io/planning-mode), and run on a schedule as a [Scheduled Agent](https://docs.mitzu.io/scheduled-agents) ## What the agent cannot do - It cannot write or run free-form SQL against your warehouse. Analyses outside the engine's methodology — arbitrary statistical modelling, custom SQL transformations — are out of its scope. - It cannot see raw event rows. The model receives aggregated results and metadata; raw event data never leaves your warehouse for the model — see [AI Data & Privacy](https://docs.mitzu.io/ai-data-privacy). - It cannot answer from data that is not in the semantic layer. The quality of its answers depends on the configured catalog — see [getting better results](https://docs.mitzu.io/analytics-agent#getting-better-results). ## The same architecture on every surface The in-app agent, the [Slack Agent](https://docs.mitzu.io/slack-agent), the [MCP Server](https://docs.mitzu.io/mcp-server), and [Scheduled Agents](https://docs.mitzu.io/scheduled-agents) all share the same semantic layer and the same deterministic query engine. A question asked in Slack and the same question asked in the app produce the same specification, the same SQL, and the same answer. All of it runs on Mitzu's [warehouse-native architecture](https://docs.mitzu.io/warehouse-native): the engine's queries execute inside your data warehouse, and event data is never copied out of it. --- # Mitzu Agent: Planning Mode Source: https://docs.mitzu.io/planning-mode Planning mode turns a complex question into an explicit, editable plan that you review and approve before the agent starts working — so you catch wrong assumptions in seconds instead of waiting for a finished analysis to spot them. ![image](https://docs.mitzu.io/img/planning-mode/hero.png) ## When to use planning mode Planning mode is most useful when the right approach to a question isn't obvious — you want to align on direction before the agent spends time pulling data. Good fits: - **Broad, open-ended questions** — "Why is retention dropping for our paid users?" - **Multi-step investigations** — questions that need a sequence of analyses, breakdowns, or comparisons to answer well - **Ambiguous scope** — when there are several reasonable ways to interpret the question, and you'd rather pick one than have the agent guess - **High-stakes analyses** — when you'll act on the result, getting the approach right matters more than getting an answer fast Skip it for direct questions that just want a number. "How many users signed up last week?" doesn't need a plan — it needs an answer. ## How to invoke planning mode There are two ways to start a conversation in planning mode. ### Slash command Type `/plan` followed by your question in any agent input — the home page input bar, the full-screen Mitzu Agent page, or the floating sidebar agent. ``` /plan why is retention dropping for our paid users? ``` Typing `/plan` on its own shows brief inline help describing what the command does: ![image](https://docs.mitzu.io/img/planning-mode/inline-help.png) ### Natural language The agent also recognizes methodology phrasings and switches into planning mode without a slash command. Examples: - "How should we investigate the onboarding drop-off?" - "What's the best way to figure out why churn spiked last month?" - "Make a plan first before doing anything." Direct questions ("why is retention dropping?") still get the agent's default behavior — straight to the investigation, no plan. ## What the agent does before proposing a plan The plan you see isn't generic. Before suggesting anything, the agent has a quick look at your workspace — existing insights that might already answer the question, and the events and properties relevant to what you're asking. Then it writes a short plan grounded in what it actually found, usually three to seven steps in plain language. Nothing runs yet. No insights get created, no charts get drawn. The plan is a proposal — what the agent intends to do if you approve. ## Reviewing and approving the plan The plan arrives as a checklist with every step ticked. Three ways to respond: - **Approve everything** — click **Approve plan** and the agent starts executing. - **Skip a step** — untick it, then click **Approve plan**. The button counts what is left ("Approve plan 4 steps"), and the agent runs only the steps you kept. - **Suggest changes** — type your modifications in the chat input instead. The agent will revise the plan and wait again. You can iterate on the plan as many times as you need before approving. Nothing runs until you say go. ## Modifying the plan before approval Unticking a step drops it. For anything else, describe the change in plain language: - **Drop steps** — untick them, or say "skip the last two", "no need to check cancellations" - **Narrow scope** — "focus only on retention", "just look at the monthly plan" - **Add steps** — "also break down by country", "include a comparison to last quarter" - **Reorder** — "do step 3 first" - **Rewrite from scratch** — "let's start over, just compare paid vs free retention" The agent rewrites the plan based on your feedback and waits for approval again. This loop is the core of planning mode — it's faster to refine a plan in chat than to wait for a finished analysis and then redirect. ## Execution after approval Once you approve, the plan turns into a live todo widget. The agent works through the steps in order, marking each one in-progress, then completed, as it goes. Charts and intermediate findings appear inline as each step finishes. ![image](https://docs.mitzu.io/img/planning-mode/executing.png) When the last step completes, the agent ends with a written findings summary: headline, key details, and recommended next steps. ## How it differs from a regular question | | Regular question | Planning mode | | --- | --- | --- | | **First agent action** | Starts investigating immediately | Light discovery, then proposes a plan | | **You review before work?** | No — you see results | Yes — you approve the steps | | **Best for** | Direct, well-scoped questions | Broad, multi-step investigations | | **Time to first answer** | Faster | Slower — but the answer is more likely to be the one you wanted | ## When planning mode is the wrong choice Planning mode adds a step. Skip it when: - **You already know exactly what to ask for** — "show me weekly active users for the last quarter" doesn't benefit from a plan - **You want a single metric** — counts, conversion rates, retention numbers, lookups - **You're exploring conversationally** — quick follow-up questions in an existing chat flow on their own For everything else where the question is broader than the answer, planning mode is worth the extra step. --- # Mitzu Agent: Scheduled Agents Source: https://docs.mitzu.io/scheduled-agents A scheduled agent runs a Mitzu agent on its own schedule. You give it a question and a cadence, and it runs that investigation without you having to ask — a weekly churn-risk digest, an anomaly watch on activation, a daily check for new events landing in your warehouse. What makes a scheduled agent more than a recurring query is the optional **trigger**: a plain-English condition Mitzu checks against each run's answer before deciding whether to email you. Quiet weeks stay quiet. When something matches, the email is a short brief — and one click opens the full investigation as a real Mitzu conversation. ![image](https://docs.mitzu.io/img/mitzu-agent/scheduled-agents-list.png) ## Where to find them Click **Scheduled Agents** in the left sidebar. The list shows every agent in the project with its schedule, when it runs next, and whether it's active or paused. From here you can create a new agent, open one to see its run history, or run, pause, edit, and delete an existing one. > **INFO** > > Scheduled Agents is available on workspaces with AI enabled. If you don't see it in the sidebar, ask a workspace admin to enable it. ## Monitoring a dashboard A dashboard you have to remember to check is worse than one that watches itself. Click **Monitor** in a dashboard's action bar to turn it into a scheduled agent in one step — and to see who's already watching, so you don't set up a second agent for something already covered. - If no agent watches the dashboard yet, the popover explains what a monitoring agent does and offers a **Create agent** button. - If agents are already watching, the popover lists them — each with its last run, run count, and owner — alongside **New agent** and **See all agents**. Either button opens the [scheduled-agent form](#creating-a-scheduled-agent) prefilled to monitor this dashboard: a name, a description, a prompt describing the dashboard, and notifications preset to **Every run** with you added as a recipient. Nothing is scheduled until you confirm — every field stays editable. Once created, a confirmation appears with a link to open the agent, and the agent shows up in the dashboard's Monitor popover from then on. The link is provenance, not a promise: editing the agent's prompt later never drops it from the list, and if the dashboard is deleted the agent is kept and simply stops appearing there. A monitoring agent reports the dashboard as it is. It never refreshes the panels itself — if they are older than the dashboard's refresh schedule, the run says so and points out when auto-refresh is off or not keeping up, so the fix lands on the schedule rather than on a one-off refresh nobody sees. ## Creating a scheduled agent Click **New agent** and fill in four sections. ### Details - **Name** — how the agent appears in the list and in the subject line of its emails. - **Description** (optional) — a short note on what it keeps an eye on. ### Instructions - **Agent** — which agent runs on each cycle. **Analytics** (the default) answers questions about your data. **Config** maintains your project setup and applies changes automatically on every run; it's only available to **workspace admins**. See [Agent types](#agent-types) below. - **Prompt** — the instructions sent to the agent on every run. Write it the way you'd ask the question in a normal conversation, e.g. _"Analyse the sign-up funnel for the last 7 days, compare it to the previous week, and summarise where users drop off."_ - **Use template** — start from a ready-made prompt instead of a blank box. Two starter templates are available: **Daily KPI watch** and **Sign-up funnel check**. You can edit the prompt after applying a template. ![image](https://docs.mitzu.io/img/mitzu-agent/scheduled-agents-instructions.png) ### Schedule Pick the **days of the week** and the **time** the agent runs, in the **timezone** you select. The form shows a preview of when the next run will happen. - For a **daily** agent, select all seven days. - For a **weekly** agent, select a single day. - Any combination in between works too — for example weekdays only. New agents default to weekdays at 09:00. You must choose a timezone before saving. ![image](https://docs.mitzu.io/img/mitzu-agent/scheduled-agents-form.png) ### Notifications This section decides when — and to whom — the agent emails its results. - **When to email** — choose one of three modes: - **Off** — the agent runs and records its results, but never emails. You can still open each run from the agent's history. - **Every run** — email the recipients after every completed run. - **When triggered** — email only when the run's answer meets a condition you describe. See [The trigger](#the-trigger). - **Trigger** — shown when you pick **When triggered**. Describe in plain English when the results are worth an email, e.g. _"Email only when sign-ups drop more than 10% week over week."_ After each run, an AI check reads the answer and decides whether this condition is met. - **Recipients** — who gets the email. Only workspace members can be added as recipients. - **Email on failure** — when on, recipients are also notified if a run fails or errors. The agent's owner always receives failure notifications. ## The trigger Anything that runs on a schedule has the same problem: it emails you whether or not there's anything to say, and before long you learn to ignore it. The trigger is how a scheduled agent avoids that. You tell it in plain English what's worth knowing, and on each run it decides whether that's actually happened. Keep it precise — _"flag any cohort whose 30-day retention fell below 40%"_ — or leave it open — _"tell me if anything looks off with activation"_ — and let the agent make the call. **How it works on each run:** 1. The agent runs your prompt and produces its answer, exactly as it would in a normal conversation. 2. A separate AI check reads the agent's instructions, your trigger condition, and the run's final answer, then decides whether the condition is met. 3. If it's met, the recipients get an email. The body isn't a raw dump of the run — it's a concise brief written for the reader, with a link to the full conversation. 4. If it isn't met, no email is sent. The run is still saved to the agent's history so you can review it anytime. Every outcome is recorded on the run in the agent's [run history](#run-history), so you can always see why a given run did or didn't email you. ## What lands in your inbox The insight that arrives isn't a throwaway line of text. The email contains: - The agent's name and whether the run **completed** or **failed**. - A short summary of the run's findings. - An **Open conversation** button. Because every run happens inside a real Mitzu conversation, you're never starting from scratch. Open the conversation and you can see how the agent built the analysis and reached its read — the charts, the segments, the reasoning. From there you can ask a follow-up, save a result as a cohort, or hand the whole thread to a colleague. ![image](https://docs.mitzu.io/img/mitzu-agent/scheduled-agents-email.png) ## Run history Open an agent to see its details and a history of every run, newest first. Each run shows: - A **status** badge — Pending, Queued, Running, Succeeded, Failed, or Cancelled. - When it was **scheduled for**. - Whether it was a **Scheduled** run or a **Manual** one (started with **Run now**). - For **When triggered** agents, the **notification outcome**: - **Email sent** — the trigger condition was met and the email went out. - **No email** — the run completed but didn't meet the condition. - **No recipients** — the condition was met, but no recipients are configured. - **Trigger check failed** — the trigger couldn't be evaluated for that run. Hover the badge to see the reason. - A **findings** badge, when something changed since the previous run — see [What the agent remembers](#what-the-agent-remembers) below. - An **Open conversation** link to the full run. ![image](https://docs.mitzu.io/img/mitzu-agent/scheduled-agents-detail.png) ### Managing an agent - **Run now** — start an immediate run without waiting for the next scheduled time. It's recorded as a Manual run and follows the same notification settings. - **Pause / Resume** — pause to stop the schedule without losing the configuration; resume to put it back on its days. - **Edit** — change any field, including the prompt, schedule, and notifications. - **Delete** — remove the agent and its schedule. ## What the agent remembers Each run records a short summary of what it reported: a headline, and one entry for each thing it singled out as changed, anomalous or wrong. The next run is given that summary before it starts. This is what makes "since the last run" mean something. An agent whose instructions say _"summarise how each chart has moved since the last run"_ is told when the last run actually completed, so it reports on the right window instead of guessing one. If a run fails, the gap simply widens and the next run covers both periods. It also stops an agent re-reporting the same thing every day. A conversion drop flagged on Monday is described on Tuesday as still present, rather than raised again as a new discovery. The summary is not the conversation. Previous runs are never replayed — only their recorded summaries are available, so the cost of this history stays the same however long an agent has been running. ### The findings badge Each finding is compared against the previous run and marked **new**, **continuing** or **resolved**. The badge in the run history counts only what moved — new and resolved — so a run that merely restates yesterday's problems carries no badge at all, and the runs worth opening stand out. Hover the badge to see the findings grouped under **New**, **Resolved** and **Continuing**. > **NOTE** > > Agents that were already running before this existed have no recorded history, so their first run afterwards has nothing to compare against. Continuity starts from the run after that. ## Agent types A scheduled agent can run either of two agents on each cycle. - **Analytics** (default) — runs the [analytics agent](https://docs.mitzu.io/analytics-agent) against your prompt: segmentation, funnels, retention, and discovery, returned as findings and charts. This is the right choice for standing investigations and monitoring. - **Config** — runs the [configuration agent](https://docs.mitzu.io/configuration-agent) unattended to keep your project setup current. On a scheduled run it applies non-destructive changes automatically without stopping to ask, so it's useful for tasks like picking up new events that land in your warehouse. As a safeguard, removing tables is never performed on an unattended run. The Config option only appears for **workspace admins**. ## Limits and permissions - A project can have up to **10 scheduled agents**. - **Recipients must be members of the workspace** — you can't send to an arbitrary email address. - Each agent runs under its **owner's** permissions (the member who created it). If the owner loses access to the workspace or to the selected agent, the agent can't run until that's resolved. - The **Config** agent is restricted to **workspace admins** (users with the Admin role). ## Example use cases The format — a prompt, a schedule, and an optional trigger that decides when to write — fits any standing investigation your team would otherwise wish it could keep up with: - A **weekly churn-risk digest** for customer success, triggered only when at-risk accounts appear. - An **anomaly watch on activation conversion**, emailing you when it moves off its recent average. - A **daily check for new events** landing in your warehouse. - A **weekly retention report** by cohort. ## Tips for better results - **Write the prompt the way you'd ask it in a conversation.** The same things that improve [analytics agent](https://docs.mitzu.io/analytics-agent#getting-better-results) answers — clear event and property names, configured dimension tables, custom instructions — apply here, because a scheduled agent runs the same agent. - **Make the trigger specific when you can.** A precise condition (_"more than 10% week over week"_) produces fewer, higher-signal emails than a vague one. Use an open-ended trigger only when you genuinely want the agent to use its judgement. - **Start with Every run, then tighten.** If you're not sure what a useful trigger looks like, run a few cycles on **Every run** to see the kind of answers the agent produces, then switch to **When triggered** with a condition based on what you saw. - **Use Run now to test.** A manual run uses the exact prompt, schedule context, and notification settings of a real run, so it's the fastest way to check both the analysis and the email before you rely on the schedule. --- # Mitzu Agent: Configuration Agent Source: https://docs.mitzu.io/configuration-agent The configuration agent helps you set up your workspace by scanning your data warehouse and configuring the right tables for analytics. Instead of manually mapping event tables, dimension tables, and columns, the agent handles it for you — building the semantic layer that Mitzu's analytics engine queries against. ## What it can do - **Scan your warehouse** — list schemas and tables, inspect column types and names - **Identify event tables** — recognizes common patterns from vendors like Segment, Snowplow, GA4, and Firebase, as well as custom event tables - **Identify dimension tables** — finds user and account profile tables to enrich your analytics with user-level attributes - **Map columns automatically** — detects timestamp, user ID, and event name columns with high confidence - **Configure tables** — adds event and dimension tables to your workspace with the correct field mappings - **Trigger indexing** — starts indexing after configuration so your data is ready to query - **Clean up the data catalog** — reads the event property and dimension property catalogs, then fills in descriptions, renames properties, and hides the ones nobody should see ## What the agent produces The output of the configuration agent is a semantic layer over your warehouse: a mapping of event tables, dimension tables, user and group identifiers, timestamps, and event names. Mitzu's query engine uses this layer to translate questions into SQL. As your warehouse evolves, you can re-run the agent to keep the semantic layer in sync. ## During onboarding The first time you set up a workspace, the home page shows a **Set up with AI** button. Click it to connect your data warehouse and let the configuration agent take over. ![Onboarding home page with Set up with AI button](https://docs.mitzu.io/img/mitzu-agent/onboarding-home.png) In onboarding mode, the agent works with minimal friction: 1. **Connect your warehouse** — provide your data warehouse credentials. 2. **Automatic scanning** — the agent explores your schemas, identifies event and dimension tables, and maps columns. 3. **Auto-configuration** — high-confidence tables are configured automatically. The agent asks about ambiguous ones. 4. **Indexing** — once configured, indexing starts so your data is ready for analysis. > **INFO** > > The agent starts with a minimum viable set of 4-6 event tables and 1-2 dimension tables. You can always add more tables later — getting started quickly is more important than configuring everything up front. ![Configuration agent setup summary with discovered events and next steps](https://docs.mitzu.io/img/mitzu-agent/onboarding-agent-summary.png) ## After initial setup Switch to the configuration agent at any time using the **agent mode selector** — the dropdown in the corner of the agent chat input. It is available everywhere the agent appears: the home page, the full-screen agent view, and the sidebar panel. You can also access it directly from the **Settings** pages. ![Agent mode selector showing Analytics and Config options](https://docs.mitzu.io/img/mitzu-agent/config-agent-selector.png) Outside of onboarding, the agent is more conversational — it asks clarifying questions and requires your confirmation before making changes. Common use cases: - **New events in your tracking** — you've added new analytics events to your data warehouse and want to pull them into Mitzu - **New dimension tables** — a user profiles or account attributes table was added, and you want to use it for breakdowns - **Reconfigure field mappings** — column names or roles have changed and the existing mappings need updating - **Remove stale tables** — deprecated or replaced tables that should no longer appear in the data catalog - **Describe and tidy properties** — a freshly indexed workspace has hundreds of undocumented properties, and the agent can describe, rename, and hide them in bulk instead of one row at a time - **Explore your warehouse** — discover other schemas and tables that are available but not yet configured ## Cleaning up the property catalog Right after indexing, most properties carry a name generated from the column name and no description at all. Ask the agent to fix that in plain language — "fill in the descriptions for the properties on `checkout completed`", "rename `utm_src` to UTM Source", "hide every `_internal_*` property" — and it reads the catalog, proposes the changes, and applies them once you confirm. The changes show up in **Data catalog** straight away; no re-indexing is needed. Two things are worth knowing before you confirm: - **Event properties are shared.** An event property is identified by its field path, so renaming or hiding one changes it on every event that carries that field path, for everyone in the workspace. The agent says how many events are affected before it writes. Dimension properties belong to a single dimension table and affect only themselves. - **Display names must be unique.** If the name you asked for already belongs to another property, nothing is written — the agent tells you which property is holding the name so you can pick another one or rename that one first. The agent reports exactly what it wrote and what it skipped. A property it could not find in the catalog is named in the result rather than silently ignored. > **INFO** > > The agent can set display names, descriptions, and visibility. It cannot create or delete properties, or change their data types — those follow your warehouse schema and the indexing configuration. ## What it recognizes The agent understands common data warehouse patterns: - **Vendor tables** — Segment tracks, Snowplow events, GA4 event tables, Firebase analytics - **Event table signals** — tables with the `_events` suffix, or names like `tracks`, `pages`, `sessions` - **Dimension table signals** — tables with the `_profiles` suffix, or names like `users`, `accounts` - **Skipped automatically** — tables with `deprecated`, `tmp`, `staging`, `backup`, or `archive` in the name ## Permissions - **Admins** can discover, configure, and remove tables, and edit the property catalog - **Non-admins** can discover tables, read the property catalog, and get recommendations but cannot make changes — the agent presents its suggestions for an admin to implement --- # Mitzu Agent: Slack Agent Source: https://docs.mitzu.io/slack-agent Use Mitzu Agent directly in Slack to ask analytics questions without leaving your team's communication tool. The Slack agent has the same analytical capabilities as the web agent: segmentation, funnels, retention, and data exploration. ## Setting up the Slack app ### Install the app Install the Mitzu Slack app using the button below. Anyone with permission to add apps to the Slack workspace can complete the installation. [![Add to Slack](https://platform.slack-edge.com/img/add_to_slack.png)](https://slack.com/oauth/v2/authorize?client_id=7076828981205.10676456899346&scope=app_mentions:read,channels:history,channels:read,chat:write,files:read,files:write,groups:history,groups:read,im:history,links:read,links:write,mpim:history&user_scope=channels:read,groups:read,links:read,links:write) ### Invite the app to channels After installing the app, you need to invite it to every channel where you want to use it. In the channel, type: > /invite @Mitzu ![Inviting Mitzu to a Slack channel](https://docs.mitzu.io/assets/images/invite_mitzu_app-a43ccccf7b45f215c7aa0c1e94c8ae53.png) The bot will only respond to mentions in channels where it has been invited. ## Authentication The first time you mention the Mitzu bot, it will reply with an ephemeral message (only visible to you) asking you to log in. Click the **Log in** button to connect your Slack account to your Mitzu workspace. Once authenticated, mention the bot again, and it will process your question. ![Mitzu authentication prompt in Slack](https://docs.mitzu.io/assets/images/mitzu_app_auth-aeab6048ed49e88fad90e1be594776dc.png) > **NOTE** > > Each Slack user needs to authenticate individually. The bot uses your Mitzu account permissions to determine which workspaces and data you can access. ## How to use Mention the Mitzu bot in any channel where it's been added: > **@Mitzu** How many users signed up last week? The bot will reply in a thread with the analysis results, including a text summary and a chart. At the bottom of the response, you'll find two buttons: - **Open AI conversation** — opens the full conversation in the Mitzu web app - **Open insight** — takes you directly to the generated chart in Mitzu ![Slack agent response with chart and action buttons](https://docs.mitzu.io/assets/images/slack_agent_response-15a1acdaf07a81cda4347973f8785eaa.png) ### Thread conversations Follow-up questions in the same Slack thread maintain conversation context. The agent remembers what you discussed earlier in the thread, so you can refine your analysis step by step. Always mention **@Mitzu** in each message; the bot only processes messages that tag it directly. > **@Mitzu** Show me signups this month > > _Agent responds with chart and summary_ > > **@Mitzu** Break that down by country > > _Agent updates the analysis with a country breakdown_ ### Chat history Slack conversations are part of your chat history in the Mitzu web app. You can find and continue any Slack conversation from the **All Content** page, just like conversations started from the web interface. --- # Mitzu Agent: Mitzu MCP Server Source: https://docs.mitzu.io/mcp-server ![Mitzu MCP](https://docs.mitzu.io/img/mitzu-agent/mitzu-mcp.png)![Mitzu MCP](https://docs.mitzu.io/img/mitzu-agent/mitzu-mcp-dark.png) Mitzu's MCP server lets you ask questions about your product data from any MCP-compatible AI client — Claude, Cursor, ChatGPT, and others. It exposes the Mitzu analytics agent over a remote endpoint, so you can run analyses, inspect artifacts, and continue conversations from your editor or chat tool. ## Connect your client Server URLhttps://app.mitzu.io/mcp Most clients connect with a one-click install button or an in-app Connectors UI that takes the URL above. On first connect your client opens a browser for WorkOS login and prompts you to pick a workspace — the client stores the rotating access token automatically, so there is no token to copy from the Mitzu UI. Claude Desktop & .aiUIClaude CodeCLICursorOne-clickCodexCLI + appChatGPTUIVS CodeOne-clickGemini CLICLIOther clientsWindsurf, raw Pick a client above to see step-by-step connect instructions. Advanced connection details | Setting | Value | | --- | --- | | Server URL | `https://app.mitzu.io/mcp` | | Transport | Streamable HTTP (Server-Sent Events) | | Authentication | OAuth 2.0 (WorkOS), discovered automatically by the client | | Protected resource metadata | `https://app.mitzu.io/.well-known/oauth-protected-resource` | | Authorization server metadata | `https://app.mitzu.io/.well-known/oauth-authorization-server` | | Required `Accept` header | `application/json, text/event-stream` | Raw HTTP clients must send `Accept: application/json, text/event-stream`. The agent endpoint streams live progress over SSE; a JSON-only `Accept` header is rejected with a 406 response. ## What the agent can do The MCP server exposes the same Mitzu analytics agent that powers the in-app and Slack experiences — natural-language segmentation, funnels, retention, and data discovery. See [Analytics Agent](https://docs.mitzu.io/analytics-agent) for the full capability list and example prompts. ## Tools The MCP server exposes 8 tools in agent mode. Most clients only need `run_analytics_agent` — the rest let you drill into the artifacts the agent produces without paying for another agent run. | Tool | Purpose | | --- | --- | | `run_analytics_agent` | Start an analytics run on a natural-language question. Returns immediately with a `conversation_id`. | | `get_analytics_agent_status` | Poll an in-flight run. Long-polls by default and streams live progress over SSE. | | `list_agent_artifacts` | List every data artifact the agent has produced in the current session. | | `inspect_artifact` | Inspect metadata for a stored artifact. | | `describe_table_artifact` | Get row count, columns, dtypes, and a head sample for a table artifact. | | `query_table_artifact` | Filter, sort, project columns, and paginate rows from a table artifact. | | `read_json_artifact` | Read bounded slices from one or more JSON artifacts. | | `grep_json_artifact` | Regex-search rows of a JSON artifact. | > **ASYNC START/POLL CONTRACT** > > `run_analytics_agent` is **asynchronous**. It spawns the agent as a background task in the server process and returns immediately with `{status: "running", conversation_id, prompt_id, conversation_url}`. Clients poll `get_analytics_agent_status` to retrieve progress and the final answer. > > All other tools are synchronous and return a single JSON response. Tool reference ### `run_analytics_agent` Kick off the Mitzu analytics agent on a natural-language analytics question. Returns immediately; the background task owns the full lifecycle and persists the transcript on completion. | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `question` | string | yes | The analytics question, phrased in natural language. | | `max_turns` | integer | no | Cap on the number of agent turns. | | `conversation_id` | string | no | Id of an existing conversation to continue. Omit to start a fresh conversation. | | `cancel_running` | boolean | no | If `true`, stop any in-flight run on the same `conversation_id` and execute this request instead. Defaults to `false`, which returns `{status: "busy"}` while a run is in flight. | ### `get_analytics_agent_status` Poll a `run_analytics_agent` run. Long-polls by default, emitting `notifications/progress` over SSE for every new step (plus periodic heartbeats) until the run finishes or the timeout elapses. | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `conversation_id` | string | yes | The `conversation_id` returned by `run_analytics_agent`. | | `wait_for_completion` | boolean | no | Defaults to `true`. Set to `false` for a single non-blocking snapshot. | | `timeout_seconds` | integer | no | Per-call wait budget when `wait_for_completion=true`. Default 90 s, capped at 300 s. | Possible result shapes: - `{status: "running", last_progress, progress, conversation_id, conversation_url}` — agent is still working. - `{status: "done", answer, artifacts, session_id, progress, conversation_id, conversation_url}` — run finished successfully. - `{status: "error", message, conversation_id, ...}` — agent raised. - `{status: "superseded", conversation_id, ...}` — another `run_analytics_agent` call with `cancel_running=true` took over. - `{status: "lost", conversation_id, ...}` — the server restarted mid-run; re-issue `run_analytics_agent` to retry. ### `list_agent_artifacts` List every data artifact (table or JSON) the agent has produced in the current MCP session, newest first. Each entry includes the originating question, source tool, row count, columns (for tables), size, and a short summary. No parameters. ### `inspect_artifact` Inspect metadata for a stored artifact. | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `artifact_id` | string | yes | The artifact ID to inspect. | ### `describe_table_artifact` Describe a table artifact: row count, columns with dtypes, and a small head sample. Call this before `query_table_artifact` to understand the table's shape. | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `artifact_id` | string | yes | The table artifact ID to describe. | ### `query_table_artifact` Filter, sort, project columns, and paginate rows from a table artifact. Use this for any ranking, top-N, or filtering question — never sort or filter rows in your own reasoning. | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `artifact_id` | string | yes | The table artifact ID to query. | | `sort_by` | string\[\] | no | Column names to sort by. | | `order` | string | no | `asc` (default) or `desc`. | | `filters` | object\[\] | no | Each filter is `{column, op, value}`. Supported ops: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `contains`. Filters are AND-combined. | | `columns` | string\[\] | no | Subset of columns to return. Omit to return all columns. | | `top_n` | integer | no | Maximum rows to return. | | `offset` | integer | no | Zero-based row offset for pagination. | ### `read_json_artifact` Read bounded slices from one or more JSON artifacts in a single call. | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `reads` | object\[\] | yes | List of `{artifact_id, offset, limit}` slices. Request every artifact you need in a single call. | ### `grep_json_artifact` Search a JSON artifact for rows matching a regex. Returns matching rows with their offsets so you can follow up with `read_json_artifact` for surrounding context. | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `artifact_id` | string | yes | The JSON artifact ID to search. | | `pattern` | string | yes | Python regular expression matched against each row's JSON-serialized form. | | `case_insensitive` | boolean | yes | If `true`, the regex matches without case sensitivity. | | `max_results` | integer | no | Maximum number of matching rows to return. | ## Conversations and artifacts `run_analytics_agent` is a **durable conversation**, not a stateless call. Every run is persisted server-side and surfaces a `conversation_url` deep link into the Mitzu webapp. Pass the returned `conversation_id` back into another `run_analytics_agent` call to continue the same conversation — including conversations that originally started in the webapp or in Slack. Artifacts are scoped per user and project, so they're shared across every tool call you make on the MCP server. Drill into artifacts the agent produced with `list_agent_artifacts` followed by `query_table_artifact`, `read_json_artifact`, or `grep_json_artifact` — much faster than re-running the agent for follow-up questions. ## Troubleshooting - **The MCP integration is turned off for this Mitzu organisation** — every tool call returns this error and the MCP tab is hidden under Workspace settings while MCP is disabled for your organization. It is on for every organization by default; contact [support@mitzu.io](mailto:support@mitzu.io) to have it turned back on. Turning it back on takes up to a minute to reach every server. - **Authentication expired** — re-authenticate from the client. WorkOS access tokens rotate every few minutes; refresh is automatic, but a long-idle client may need to re-run the connect flow. - **`406 Not Acceptable`** — the client is sending `Accept: application/json` only. Add `text/event-stream` to the `Accept` header. - **`{status: "busy"}` on `run_analytics_agent`** — an earlier run is still in flight on the same `conversation_id`. Pass `cancel_running=true` to take over, or start a new conversation by omitting `conversation_id`. - **`{status: "lost"}` on `get_analytics_agent_status`** — the server restarted mid-run, leaving no transcript. Re-issue `run_analytics_agent` to retry. --- # Mitzu Agent: AI Data & Privacy Source: https://docs.mitzu.io/ai-data-privacy Mitzu Agent is designed so you can put AI to work on your product data without handing that data over. This page explains what the agent sends to the underlying language model, what it never sends, and the controls you have over AI features and the data they generate. ## At a glance | Guarantee | What it means | | --- | --- | | **Metadata isolation** | Only aggregated query results and catalog metadata reach the model — never raw, event-by-event data. | | **No model training** | Your data is never used to train or fine-tune language models. | | **Per-workspace controls** | AI features are governed by per-project settings and can be disabled entirely for a workspace on request. | | **Configurable retention** | AI conversation logs are stored in your Mitzu workspace and can be deleted on request. | | **Bring your own model** | Optionally run the agent against your own model-provider account, arranged via support. | ## The foundation Mitzu Agent — the in-app analytics agent, the configuration agent, [Scheduled Agents](https://docs.mitzu.io/scheduled-agents), the [Slack Agent](https://docs.mitzu.io/slack-agent), and the [MCP Server](https://docs.mitzu.io/mcp-server) — runs on Anthropic's Claude models (Sonnet and Haiku) through the Claude Agent SDK. Anthropic is the only language-model provider Mitzu uses for these features. Every agent runs against **your own warehouse data**, scoped to the workspace and to the permissions of the authenticated user who started the run. The agent queries your warehouse the same way the Mitzu app does, then reasons over the results. ## Metadata isolation The agent works with **aggregated query results and catalog metadata**, not raw event streams. - **Aggregated results only.** When the agent runs a segmentation, funnel, retention, or journey analysis, it receives the same aggregated figures you would see on a chart — distinct breakdown values with their counts — not a per-event log. Results are truncated before they enter the model's context, so large result sets are capped rather than streamed in full. - **Large results stay out of context.** Any oversized tool result is written to a server-side artifact instead of being passed to the model. The agent then pages, filters, and sorts that artifact through dedicated tools — the raw rows never all land in the prompt. - **Metadata, not data, for context.** When you ask the agent to explain a chart, it receives the chart's specification (its title, metric, and configuration) plus a small preview — not the underlying dataset. - **Raw events stay in your warehouse.** The agent cannot export or stream event-by-event logs. If you ask for raw per-event rows, it will tell you that isn't available and point you back to your warehouse. > **AUTHENTICATED ACCESS TO MODELED DATA** > > The agent acts on behalf of the signed-in user and respects that user's role and permissions. Values that are modeled in your data catalog — including user attributes — can appear in an aggregated result if a member with access asks for them, exactly as they would in the Mitzu app. The isolation guarantee is about **raw event data**: that never leaves your warehouse for the model. ## No model training Under Mitzu's commercial agreement with Anthropic, **data sent to the model is never used to train or fine-tune it.** Prompts and results are processed to answer your question and are not retained by the provider to improve its models. ## Using your own model provider Mitzu Cloud runs every agent on Anthropic's Claude models through a single, Mitzu-managed provider credential — there are no keys for you to configure. If you would rather the agent run against your own model-provider account, using an API key you control, that can be arranged for your workspace. Contact [support](mailto:support@mitzu.io) to set it up. ## Access control and authentication - **The MCP Server authenticates with OAuth 2.0 (WorkOS).** Clients complete a browser login on first connect and receive a short-lived, automatically rotating access token — there is no long-lived key to copy or store. See the [MCP Server](https://docs.mitzu.io/mcp-server) page for details. - **Per-tool scopes and permissions.** MCP tools are gated by OAuth scopes (`mitzu:workspace:read`, `mitzu:data:query`, `mitzu:workspace:manage`) and by the caller's Mitzu role. A client granted read-only scopes cannot invoke write tools. - **Role-gated configuration.** The configuration agent only exposes tools that change your workspace — adding tables, editing mappings, triggering indexing — to members with the **Manage workspace** permission. Everyone else gets a read-only agent. ## Controlling AI features You control where and how the agent runs: - **Model selection** — choose the model (Auto, Sonnet, or Haiku) per project in **Workspace settings → AI**. - **Web search** — off by default. The agent only performs web searches if you explicitly enable it for a project. - **Custom instructions** — add per-project guidance that is prepended to every run. - **Usage quotas** — each organization has a monthly AI query quota. Once it is exhausted, new runs are refused until the quota resets. - **Kill-switch** — AI features can be disabled entirely for a workspace. Contact [support](mailto:support@mitzu.io) to turn the agent off for your tenant. ## Data storage and retention Mitzu Cloud runs on Amazon Web Services (AWS). This section describes what the agent stores, where, and for how long. Self-hosted and private-cloud deployments keep all of this data in your own infrastructure instead. ### What is stored When you use the agent, Mitzu records the conversation so you can revisit it from the **All Content** page. A stored conversation includes: - the prompt text you sent and the context of the page you started from; - the agent's responses, reasoning steps, and the tools it called with their inputs; - any charts the agent produced — the rendered image and the aggregated result data behind them; - the model used and timestamps; - a reference to the originating Slack thread, for Slack conversations; - any feedback you leave on a response. ### Where it is stored - **Conversations** are stored in Mitzu's primary database, an **encrypted PostgreSQL instance on AWS RDS**. - **Agent session state** — used to resume a conversation where you left off — is stored on an **encrypted AWS EFS volume**. - **Working artifacts** — the large intermediate result sets the agent pages through during a single run — are held only in **ephemeral, container-local storage**. They are never written to durable object storage, and are discarded when the run's compute is recycled. - Provider credentials live in **AWS Secrets Manager**, never in application tables. Consistent with [metadata isolation](#metadata-isolation), raw event data is not copied out of your warehouse into any of these stores — only aggregated results and metadata are. ### Retention Conversation logs are retained for as long as their workspace and project exist, so your history stays available. They are **permanently deleted when the associated project or workspace is deleted**, at which point the records are removed from the database. Encrypted database backups are retained for **14 days** before they are purged. If you need conversation logs deleted sooner — or want a specific retention window applied to your workspace — contact [support](mailto:support@mitzu.io), and we will remove them or configure a policy for you. ## Questions For security reviews, data processing agreements, or questions not covered here, reach out to [support@mitzu.io](mailto:support@mitzu.io). --- # Warehouse Connectors: Warehouse integrations Source: https://docs.mitzu.io/warehouse-integrations Mitzu can be integrated with several kinds of data warehouses. [ ![AWS Athena](https://docs.mitzu.io/img/warehouse-integrations/athena.svg) ### AWS Athena Get started with AWS Athena integration ](https://docs.mitzu.io/aws-athena)[ ![BigQuery](https://docs.mitzu.io/img/warehouse-integrations/bigquery.svg) ### BigQuery Get started with BigQuery integration ](https://docs.mitzu.io/bigquery)[ ![Databricks](https://docs.mitzu.io/img/warehouse-integrations/databricks.svg) ### Databricks Get started with Databricks integration ](https://docs.mitzu.io/databricks)[ ![PosgreSQL](https://docs.mitzu.io/img/warehouse-integrations/postgresql.svg) ### PosgreSQL Get started with PostgreSQL integration ](https://docs.mitzu.io/postgresql)[ ![Redshift](https://docs.mitzu.io/img/warehouse-integrations/redshift.svg) ### Redshift Get started with Redshift integration ](https://docs.mitzu.io/redshift)[ ![Snowflake](https://docs.mitzu.io/img/warehouse-integrations/snowflake.svg) ### Snowflake Get started with Snowflake integration ](https://docs.mitzu.io/snowflake)[ ![Starburst.io](https://docs.mitzu.io/img/starburst-icon.png) ### Starburst.io Get started with Starburst integration ](https://docs.mitzu.io/starburst)[ ![Trino / Presto](https://docs.mitzu.io/img/warehouse-integrations/trino.svg) ### Trino / Presto Get started with Trino integration ](https://docs.mitzu.io/trino)[ ![ClickHouse](https://docs.mitzu.io/img/warehouse-integrations/clickhouse.svg) ### ClickHouse Get started with ClickHouse integration ](https://docs.mitzu.io/clickhouse)[ ![Microsoft Fabric](https://docs.mitzu.io/img/warehouse-integrations/fabric.svg) ### Microsoft Fabric Get started with Microsoft Fabric integration ](https://docs.mitzu.io/fabric)[ ![Firebolt](https://docs.mitzu.io/img/warehouse-integrations/firebolt.svg) ### Firebolt Get started with Firebolt integration ](https://docs.mitzu.io/firebolt)[ ![Uploaded CSV](https://docs.mitzu.io/img/warehouse-integrations/uploaded-csv.svg) ### Uploaded CSV Upload a CSV file directly, no warehouse required ](https://docs.mitzu.io/uploaded-csv) --- # Warehouse Connectors: AWS Athena Source: https://docs.mitzu.io/aws-athena ## Overview Mitzu connects to AWS Athena using an AWS user with the right permissions to access your data. To connect Mitzu to AWS Athena, you need to create this user first and then configure its credentials in Mitzu. If you use other AWS services, we recommend creating a dedicated AWS service account that only has the permissions required to run Athena, and using the IAM credentials from that account to connect Mitzu to Athena. See [Identity and access management in Athena](https://docs.aws.amazon.com/athena/latest/ug/security-iam-athena.html). ## Supported data types Mitzu will map the types of the data warehouse based on the following table: | Mitzu type | Data warehouse type | | --- | --- | | String | CHAR, CHAR(length), STRING, VARCHAR(length) | | Number | TINYINT, SMALLINT, INT, INTEGER, BIGINT, FLOAT, DOUBLE | | Boolean | BOOLEAN | | Datetime | TIME, DATE, TIMESTAMP | | Map | MAP | | Struct | STRUCT | | Array | ARRAY | > **INFO** > > All unrecognized types will be handled as strings. ## Create an AWS Athena service user Head to [AWS IAM](https://us-east-1.console.aws.amazon.com/iam/) and create a new user. This user needs access to three primary resources: - `Files in S3` - `AWS Glue` - `AWS Athena` [Here](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users_create.html), you can find more information about AWS users and how to create them. Here is an example **IAM Policy** document containing the proper permissions: ``` { "Version": "2012-10-17", "Statement": [ { "Sid": "Athena", "Effect": "Allow", "Action": [ "athena:BatchGetNamedQuery", "athena:BatchGetQueryExecution", "athena:GetNamedQuery", "athena:GetQueryExecution", "athena:GetQueryResults", "athena:GetQueryResultsStream", "athena:GetWorkGroup", "athena:ListDatabases", "athena:ListDataCatalogs", "athena:ListNamedQueries", "athena:ListQueryExecutions", "athena:ListTagsForResource", "athena:ListWorkGroups", "athena:ListTableMetadata", "athena:StartQueryExecution", "athena:StopQueryExecution", "athena:CreatePreparedStatement", "athena:DeletePreparedStatement", "athena:GetPreparedStatement" ], "Resource": "*" }, { "Sid": "Glue", "Effect": "Allow", "Action": [ "glue:BatchGetPartition", "glue:GetDatabase", "glue:GetDatabases", "glue:GetPartition", "glue:GetPartitions", "glue:GetTable", "glue:GetTables", "glue:GetTableVersion", "glue:GetTableVersions" ], "Resource": "*" }, { "Sid": "S3ReadAccess", "Effect": "Allow", "Action": ["s3:GetObject", "s3:ListBucket", "s3:GetBucketLocation"], "Resource": [ "arn:aws:s3:::bucket1", "arn:aws:s3:::bucket1/*", "arn:aws:s3:::bucket2", "arn:aws:s3:::bucket2/*" ] }, { "Sid": "AthenaResultsBucket", "Effect": "Allow", "Action": [ "s3:PutObject", "s3:GetObject", "s3:AbortMultipartUpload", "s3:ListBucket", "s3:GetBucketLocation" ], "Resource": ["arn:aws:s3:::bucket2", "arn:aws:s3:::bucket2/*"] } ]} ``` ## Set the credentials in Mitzu Find and copy the `AWS_ACCESS_KEY_ID` and `AWS_SECRET_KEY` into Mitzu. For AWS Athena, the Catalog should stay set to AwsDataCatalog, or you can leave the field empty. For `S3 Staging Dir`, make sure you choose the correct bucket for storing intermediate files. ![image](https://docs.mitzu.io/img/aws-athena/image.png) Click the `Test connection` button to check if Mitzu can connect to your data warehouse using the entered values. > **WARNING** > > Mitzu will try to connect to your data warehouse and execute a `SELECT 1;`command. You may need to grant further permission Mitzu to see and query your data tables. To save the settings, click the `Test connection & Save` button. ## Next steps Once the connection is tested an saved the event end dimension tables can be configured. Please follow the [setting up event tables](https://docs.mitzu.io/event-tables) guide. --- # Warehouse Connectors: Big Query Source: https://docs.mitzu.io/bigquery ## Overview Mitzu connects to Google BigQuery using an IAM service account with the proper permissions to access your data. To connect Mitzu to Google BigQuery, you must first create the service account and then configure its credentials in Mitzu. ## Supported data types Mitzu will map the types of the data warehouse based on the following table: | Mitzu type | Data warehouse type | | --- | --- | | String | STRING | | Number | FLOAT64, INT64 with alias INT, SMALLINT, INTEGER, BIGINT, TINYINT, BYTEINT | | Boolean | BOOL | | Datetime | DATE, DATETIME, TIME, TIMESTAMP | | Map | JSON | | Struct | STRUCT | | Array | ARRAY | > **INFO** > > All unrecognized types will be handled as strings. ## Create a Service Account You need to grant Mitzu four permissions from your Google Cloud console so that we can access your BigQuery data. 1. In your GCP console, create a [Service account](https://console.cloud.google.com/iam-admin/serviceaccounts?project=mitzu-358611). ![image](https://docs.mitzu.io/img/bigquery/image.png) ![image](https://docs.mitzu.io/img/bigquery/image-1.png) 2. Add four roles to this account: ![image](https://docs.mitzu.io/img/bigquery/image-2.png) - `BigQuery User` - `BigQuery Data Viewer` - `BigQuery Job User` - `BigQuery Read Session User` 3. Click Done\\ ![image](https://docs.mitzu.io/img/bigquery/image-3.png) 4. Create a BigQuery **JSON** key by clicking the `Manage Keys` button.\\ ![image](https://docs.mitzu.io/img/bigquery/image-4.png) ![image](https://docs.mitzu.io/img/bigquery/image-5.png) 5. Save the key in a secure location. ## Set the credentials in Mitzu Set the BigQuery project ID, and then either copy the credentials or upload the credentials JSON file from Google BigQuery. ![image](https://docs.mitzu.io/img/bigquery/connection.png) You can configure the connection query parameters. To do so, click on the`Advanced settings` section and enter your parameters into the`URL Query Params` textbox. You must write each parameter in a new line in the `=` format. Click the `Test connection` button to check if Mitzu can connect to your data warehouse using the entered values. > **WARNING** > > Mitzu will try to connect to your data warehouse and execute a `SELECT 1;`command. You may need to grant further permission Mitzu to see and query your data tables. To save the settings, click the `Test connection & Save` button. ## Next steps Once the connection is tested an saved the event end dimension tables can be configured. Please follow the [setting up event tables](https://docs.mitzu.io/event-tables) guide. --- # Warehouse Connectors: ClickHouse Source: https://docs.mitzu.io/clickhouse ## Overview Mitzu connects to ClickHouse using username/password authentication. > **WARNING** > > If the ClickHouse is hosted by you then please make sure the `99.81.21.134` ip is allowed inbound traffic to the specified port. ## Supported data types Mitzu will map the types of the data warehouse based on the following table: | Mitzu type | Data warehouse type | | --- | --- | | String | String, FixedString | | Number | UInt8, UInt16, UInt32, UInt64, UInt128, UInt256, Int8, Int16, Int32, Int64, Int128, Int256, Float32, Float64 | | Boolean | Boolean | | Datetime | Date, Date32, DateTime, DateTime64 | | Map | Map | | Struct | Tuple | | Array | Array | > **INFO** > > All unrecognized types will be handled as strings. ## Configure the connection details in Mitzu ![image](https://docs.mitzu.io/img/clickhouse/image.png) Please fill out the form with your connection details. For an encrypted connection, use port `9440` or `8443` and check the `Secure connection (SSL)` checkbox. For an unencrypted connection (not recommended), use port `9000` or `8123`. > **NOTE** > > When entering URLs in our system, please include only the "Host" portion, omitting the protocol scheme such as https. > **NOTE** > > The minimum supported ClickHouse server version is 23.3.13.6. You can configure the connection query parameters. To do so, click on the`Advanced settings` section and enter your parameters into the`URL Query Params` textbox. You must write each parameter in a new line in the `=` format. Click the `Test connection` button to check if Mitzu can connect to your data warehouse using the entered values. > **WARNING** > > Mitzu will try to connect to your data warehouse and execute a `SELECT 1;`command. You may need to grant further permission Mitzu to see and query your data tables. To save the settings, click the `Test connection & Save` button. ## Next steps Once the connection is tested an saved the event end dimension tables can be configured. Please follow the [setting up event tables](https://docs.mitzu.io/event-tables) guide. --- # Warehouse Connectors: Databricks Source: https://docs.mitzu.io/databricks ## Overview Mitzu connects to Databricks using User Access Token-based authentication. ## Databricks cluster support Mitzu supports all Databricks SQL Warehouse and cluster types. The recommended engines are Serverless SQL Warehouse and PRO SQL Warehouse. Mitzu supports Databricks on all three major cloud infrastructure providers: - AWS - Azure - GCP Currently, Mitzu only supports User Access Token-based authentication. ## Supported data types Mitzu will map the types of the data warehouse based on the following table: | Mitzu type | Data warehouse type | | --- | --- | | String | STRING | | Number | BIGINT, DOUBLE, FLOAT, INT, SMALLINT, TINYINT | | Boolean | BOOLEAN | | Datetime | DATE, TIMESTAMP | | Map | MAP | | Struct | STRUCT | | Array | ARRAY | > **INFO** > > All unrecognized types will be handled as strings. ## Getting connection information 1. Create an access token with read access to your experiment data and write access to the staging database. 2. Follow the [Databricks documentation](https://docs.databricks.com/integrations/jdbc-odbc-bi.html#get-connection-details-for-a-cluster) to get the hostname and HTTP path of the cluster you'll use to run your experimental analysis. You may want to create a dedicated cluster for this use case. ![image](https://docs.mitzu.io/img/databricks/image.png) 3. Follow [these instructions](https://docs.databricks.com/dev-tools/auth.html#databricks-personal-access-tokens) to get the personal access token that Mitzu will use to calculate experiment results in your warehouse. ![image](https://docs.mitzu.io/img/databricks/image-1.png) ## Configure the connection details in Mitzu Add the connection information to Mitzu. ![image](https://docs.mitzu.io/img/databricks/image-2.png) You can configure the connection query parameters. To do so, click on the`Advanced settings` section and enter your parameters into the`URL Query Params` textbox. You must write each parameter in a new line in the `=` format. Click the `Test connection` button to check if Mitzu can connect to your data warehouse using the entered values. > **WARNING** > > Mitzu will try to connect to your data warehouse and execute a `SELECT 1;`command. You may need to grant further permission Mitzu to see and query your data tables. To save the settings, click the `Test connection & Save` button. ## Next steps Once the connection is tested an saved the event end dimension tables can be configured. Please follow the [setting up event tables](https://docs.mitzu.io/event-tables) guide. --- # Warehouse Connectors: Microsoft Fabric Source: https://docs.mitzu.io/fabric ## Overview Mitzu connects to Microsoft Fabric using email/password authentication. ## Supported data types Mitzu will map the types of the data warehouse based on the following table: | Mitzu type | Data warehouse type | | --- | --- | | String | char, varchar | | Number | bit, smallint, int, bigint, decimal, numeric, float, real | | Boolean | Currently not supported | | Datetime | date, time, datetime2 | | Map | Currently not supported | | Struct | Currently not supported | | Array | Currently not supported | > **INFO** > > All unrecognized types will be handled as strings. ## Configure the connection details in Mitzu ![image](https://docs.mitzu.io/img/fabric/image.png) Please fill out the form with your connection details. > **NOTE** > > When entering URLs in our system, please include only the "Host" portion, omitting the protocol scheme such as https. Click the `Test connection` button to check if Mitzu can connect to your data warehouse using the entered values. > **WARNING** > > Mitzu will try to connect to your data warehouse and execute a `SELECT 1;`command. You may need to grant further permission Mitzu to see and query your data tables. To save the settings, click the `Test connection & Save` button. ## Next steps Once the connection is tested an saved the event end dimension tables can be configured. Please follow the [setting up event tables](https://docs.mitzu.io/event-tables) guide. --- # Warehouse Connectors: Firebolt Source: https://docs.mitzu.io/firebolt ## Overview Mitzu connects to Firebolt using email/password authentication. > **WARNING** > > If the Firebolt is hosted by you then please make sure the `99.81.21.134` ip is allowed inbound traffic to the specified port. ## Supported data types Mitzu will map the types of the data warehouse based on the following table: | Mitzu type | Data warehouse type | | --- | --- | | String | text | | Number | integer, bigint, numeric, real, double precision | | Boolean | boolean | | Datetime | date, timestamp, timestamptz | | Map | Currently not supported | | Struct | Currently not supported | | Array | Currently not supported | > **INFO** > > All unrecognized types will be handled as strings. ## Configure the connection details in Mitzu ![image](https://docs.mitzu.io/img/firebolt/image.png) Please fill out the form with your connection details. > **NOTE** > > When entering URLs in our system, please include only the "Host" portion, omitting the protocol scheme such as https. Click the `Test connection` button to check if Mitzu can connect to your data warehouse using the entered values. > **WARNING** > > Mitzu will try to connect to your data warehouse and execute a `SELECT 1;`command. You may need to grant further permission Mitzu to see and query your data tables. To save the settings, click the `Test connection & Save` button. ## Next steps Once the connection is tested an saved the event end dimension tables can be configured. Please follow the [setting up event tables](https://docs.mitzu.io/event-tables) guide. --- # Warehouse Connectors: PostgreSQL Source: https://docs.mitzu.io/postgresql ## Overview Mitzu connects to PostgreSQL using username/password authentication. > **WARNING** > > If the PostgreSQL is hosted by you then please make sure the `99.81.21.134` ip is allowed inbound traffic to the specified port. ## Supported data types Mitzu will map the types of the data warehouse based on the following table: | Mitzu type | Data warehouse type | | --- | --- | | String | character, character varying, text, uuid | | Number | bigint, bigserial, integer, real, smallint, smallserial, serial | | Boolean | boolean | | Datetime | date, time, timestamp | | Map | json, jsonb | | Struct | Currently not supported | | Array | array | > **INFO** > > All unrecognized types will be handled as strings. ## Configure the connection details in Mitzu ![image](https://docs.mitzu.io/img/postgresql/image.png) You can configure the connection query parameters. To do so, click on the`Advanced settings` section and enter your parameters into the`URL Query Params` textbox. You must write each parameter in a new line in the `=` format. Click the `Test connection` button to check if Mitzu can connect to your data warehouse using the entered values. > **WARNING** > > Mitzu will try to connect to your data warehouse and execute a `SELECT 1;`command. You may need to grant further permission Mitzu to see and query your data tables. To save the settings, click the `Test connection & Save` button. ## Next steps Once the connection is tested an saved the event end dimension tables can be configured. Please follow the [setting up event tables](https://docs.mitzu.io/event-tables) guide. --- # Warehouse Connectors: AWS Redshift Source: https://docs.mitzu.io/redshift ## Overview Mitzu connects to AWS Redshift using username/password authentication. ## Supported data types Mitzu will map the types of the data warehouse based on the following table: | Mitzu type | Data warehouse type | | --- | --- | | String | CHAR, VARCHAR | | Number | SMALLINT, INTEGER, BIGINT, REAL, DOUBLE PRECISION | | Boolean | BOOLEAN | | Datetime | DATE, TIME, TIMETZ,TIMESTAMP, TIMESTAMPTZ | | Map | Currently not supported | | Struct | Currently not supported | | Array | Currently not supported | > **INFO** > > All unrecognized types will be handled as strings. ## Getting connection information 1. Head to AWS Redshift under your account in your AWS region and find the following information. ![image](https://docs.mitzu.io/img/redshift/image.png) ![image](https://docs.mitzu.io/img/redshift/image-1.png) The service user's password should be available during user creation, or you can generate a new password on the same page. ## Configure the connection details in Mitzu ![image](https://docs.mitzu.io/img/redshift/image-2.png) You can configure the connection query parameters. To do so, click on the`Advanced settings` section and enter your parameters into the`URL Query Params` textbox. You must write each parameter in a new line in the `=` format. Click the `Test connection` button to check if Mitzu can connect to your data warehouse using the entered values. > **WARNING** > > Mitzu will try to connect to your data warehouse and execute a `SELECT 1;`command. You may need to grant further permission Mitzu to see and query your data tables. To save the settings, click the `Test connection & Save` button. ## Next steps Once the connection is tested an saved the event end dimension tables can be configured. Please follow the [setting up event tables](https://docs.mitzu.io/event-tables) guide. --- # Warehouse Connectors: Snowflake Source: https://docs.mitzu.io/snowflake ### Overview Mitzu connects to Snowflake clusters using username/password authentication. ## Supported data types Mitzu will map the types of the data warehouse based on the following table: | Mitzu type | Data warehouse type | | --- | --- | | String | VARCHAR, CHAR, CHARACTER, STRING TEXT | | Number | INT, INTEGER, BIGINT, SMALLINT, TINYINT, BYTEINT, FLOAT, FLOAT4, FLOAT8, DOUBLE, DOUBLE PRECISION, REAL | | Boolean | BOOLEAN | | Datetime | DATE, DATETIME, TIMESTAMP, TIMESTAMP\_LTZ, TIMESTAMP\_NTZ, TIMESTAMP\_TZ | | Map | VARIANT | | Struct | OBJECT (not supported) | | Array | ARRAY | > **INFO** > > All unrecognized types will be handled as strings. ## Configure the connection details in Mitzu ![image](https://docs.mitzu.io/img/snowflake/image.png) You can find your account ID by following the [Account Identifier](https://docs.snowflake.com/en/user-guide/admin-account-identifier.html) guide. For example, if you’re running Snowflake on AWS and your account URL is `https://IVMDAAM-DH09820.snowflakecomputing.com`: - ``: `IVMDAAM-DH09820` You’d enter `IVMDAAM-DH09820` as the account name in Mitzu. > **INFO** > > Some regions require the cloud platform identifier. For the per-region requirements, see [the official Snowflake documentation](https://docs.snowflake.com/en/user-guide/admin-account-identifier.html#non-vps-account-locator-formats-by-cloud-platform-and-region). For more information, please visit the [official Snowflake documentation](https://docs.snowflake.com/en/user-guide/admin-account-identifier). You can configure the connection query parameters. To do so, click on the`Advanced settings` section and enter your parameters into the`URL Query Params` textbox. You must write each parameter in a new line in the `=` format. Click the `Test connection` button to check if Mitzu can connect to your data warehouse using the entered values. > **WARNING** > > Mitzu will try to connect to your data warehouse and execute a `SELECT 1;`command. You may need to grant further permission Mitzu to see and query your data tables. To save the settings, click the `Test connection & Save` button. ## Next steps Once the connection is tested an saved the event end dimension tables can be configured. Please follow the [setting up event tables](https://docs.mitzu.io/event-tables) guide. --- # Warehouse Connectors: Starburst.io Source: https://docs.mitzu.io/starburst ## Overview Mitzu connects to Trino / Presto clusters using username/password authentication. ## Supported data types Mitzu will map the types of the data warehouse based on the following table: | Mitzu type | Data warehouse type | | --- | --- | | String | CHAR, VARCHAR | | Number | INTEGER, TINYINT, SMALLINT, BIGINT, REAL, DOUBLE | | Boolean | BOOLEAN | | Datetime | DATE, TIME, TIMESTAMP | | Map | MAP | | Struct | ROW | | Array | ARRAY | > **INFO** > > All unrecognized types will be handled as strings. ### Configuring a Trino / Presto connection 1. Log in to Starburst.io. 2. (Recommended) Set up a new user and role with read-only privileges on your data catalog. 3. Navigate to the Clusters tab and click your data cluster's "Connection info" button. Note that a `/` character separates your username from your role in the User field. ![image](https://docs.mitzu.io/img/trino-cluster-hosted-by-starburst.io/image.png) ## Configure the connection details in Mitzu Add the connection info to Mitzu, and set the role as a URL Query Param (e.g., `role=`). In addition to the role, you can add other connection parameters in the same field. Each parameter should be on a separate row in the `=` format. ![image](https://docs.mitzu.io/img/trino-cluster-hosted-by-starburst.io/image-1.png) You can configure the connection query parameters. To do so, click on the`Advanced settings` section and enter your parameters into the`URL Query Params` textbox. You must write each parameter in a new line in the `=` format. Click the `Test connection` button to check if Mitzu can connect to your data warehouse using the entered values. > **WARNING** > > Mitzu will try to connect to your data warehouse and execute a `SELECT 1;`command. You may need to grant further permission Mitzu to see and query your data tables. To save the settings, click the `Test connection & Save` button. ## Next steps Once the connection is tested an saved the event end dimension tables can be configured. Please follow the [setting up event tables](https://docs.mitzu.io/event-tables) guide. --- # Warehouse Connectors: Self-hosted Trino / Presto Source: https://docs.mitzu.io/trino ## Overview Mitzu connects to Trino / Presto clusters using username/password authentication. > **WARNING** > > If the Trino / Presto is hosted by you then please make sure the `99.81.21.134` ip is allowed inbound traffic to the specified port. ## Supported data types Mitzu will map the types of the data warehouse based on the following table: | Mitzu type | Data warehouse type | | --- | --- | | String | CHAR, VARCHAR | | Number | INTEGER, TINYINT, SMALLINT, BIGINT, REAL, DOUBLE | | Boolean | BOOLEAN | | Datetime | DATE, TIME, TIMESTAMP | | Map | MAP | | Struct | ROW | | Array | ARRAY | > **INFO** > > All unrecognized types will be handled as strings. ### Configuring a Trino / Presto connection to a self-hosted cluster 1. Create a principal in your Trino / Presto authentication provider (e.g., LDAP, Kerberos, etc.). 2. Add the rule below to your System Access Control file to grant read-only access to specific catalogs. Set `` to the name of the newly created user that Mitzu will use. `` should be the name of the catalog you want to share with Mitzu. You can share multiple catalogs by listing them all, delimited by a `|` character (e.g., `(catalog_1|catalog_2|catalog_3)`).\\ ``` {"catalogs": [...{"user": "","catalog": "","allow": "read-only"}...]} ``` ## Configure the connection details in Mitzu Add the connection information to Mitzu at step 3 of the new Workspace creation flow, or in the Manage Workspace / Connection tab. Using URL Query Params, you can add additional parameters to the connection. Each parameter should be on a separate row in the `=` format. ![image](https://docs.mitzu.io/img/self-hosted-trino-presto-cluster/image.png) You can configure the connection query parameters. To do so, click on the`Advanced settings` section and enter your parameters into the`URL Query Params` textbox. You must write each parameter in a new line in the `=` format. Click the `Test connection` button to check if Mitzu can connect to your data warehouse using the entered values. > **WARNING** > > Mitzu will try to connect to your data warehouse and execute a `SELECT 1;`command. You may need to grant further permission Mitzu to see and query your data tables. To save the settings, click the `Test connection & Save` button. ## Next steps Once the connection is tested an saved the event end dimension tables can be configured. Please follow the [setting up event tables](https://docs.mitzu.io/event-tables) guide. --- # Warehouse Connectors: Uploaded CSV Source: https://docs.mitzu.io/uploaded-csv ## Overview If you don't have a data warehouse handy — or just want to try Mitzu against a sample dataset — you can upload a CSV directly from the connection settings page. Mitzu ingests the file into a managed warehouse and treats it like any other event source. ## Starting from an empty workspace When you open a workspace that doesn't have a connection yet, the project home shows a setup card with two halves: **Set up with the agent** and **Upload CSV**. Click **Upload CSV** to skip warehouse credentials entirely — you'll be dropped into a guided agent conversation that walks you through picking a file, mapping columns, and ingesting it into the managed warehouse. ![image](https://docs.mitzu.io/img/uploaded-csv/empty-workspace-onboarding.png) If you'd rather configure things by hand, use the connection settings entry point below. ## Uploading from connection settings Open **Workspace settings → Connection settings** and pick **Uploaded CSV** under "Or upload a CSV". The connection is saved automatically — no credentials required. ![image](https://docs.mitzu.io/img/uploaded-csv/connection-page.png) Drag and drop a `.csv` file (or click to browse). Mitzu auto-detects comma, semicolon, and tab delimiters and treats the first row as a header when one can be inferred. ## Staged save flow Each file you select is ingested into a managed warehouse immediately and added to the **Uploaded files** list with a **Pending save** badge. Repeat for additional files, then click **Save uploads** to commit them. ![image](https://docs.mitzu.io/img/uploaded-csv/pending-save.png) While a row is in **Pending save**, the trash icon removes it before commit. After saving, the trash icon becomes a soft-delete: the row is marked **Pending delete** and you can undo the change before clicking **Save uploads** again. Soft deletes hide the file from the UI but keep the underlying warehouse table, so accidental deletions can be recovered by support. ## Validation As soon as a file finishes uploading, Mitzu checks it and shows the outcome in the **Status** column of the **Uploaded files** list: - A green check icon means the file is ready to save. - A red alert icon appears when the file fails one or more checks. Hover the icon to see the specific problems. A staged file is considered valid when it is under 20 MB, can be parsed as CSV with a header row, and contains at least one date or timestamp column and at least one string column. **Save uploads** is blocked while any staged file is invalid — remove the offending file (or upload a fixed version) before saving. ## Limits - Maximum file size: **20 MB** per upload. - Empty files and non-CSV file types are rejected with a clear error. - Each upload becomes its own table; uploading the same filename twice is rejected — old data is never overwritten silently. ## Next steps Once your CSV is uploaded, configure the [event data tables](https://docs.mitzu.io/connection-settings) so Mitzu knows which columns represent users, events, and timestamps. From there the standard Mitzu workflows — [insights](https://docs.mitzu.io/insights-basics), [funnels](https://docs.mitzu.io/funnel), [retention](https://docs.mitzu.io/retention) — apply. --- # Data Models: Introduction Source: https://docs.mitzu.io/data-modeling > **INFO** > > **Mitzu can work on top of RAW data**. > > It doesn't require any transformations, normalizations, or other modeling. This makes it a great tool for datasets that are ingested into the data warehouse via: > > - **ELT/ETL tools**, like Fivetran, Airbyte, Rivery, Stitch, etc. > - **CDPs**, like Segment, RudderStack, Jitsu, etc. > > However, you might have use cases where other tools and services require your data to be modeled. In this section, we will cover the basics of data modeling for Mitzu. Together, the event tables, dimension tables, and the relationships between them form the semantic layer that Mitzu queries against. Mitzu builds this layer from your warehouse schema during configuration and indexing. In this section, we will cover the basics of data modeling for Mitzu. ## Events and dimensions Mitzu works well on top of event data models. If you are familiar with the [facts and dimensions model](https://en.wikipedia.org/wiki/Star_schema) (Star schema), the event data model is very similar. The main difference is that every fact is always related to a User. This means each "event table" contains two columns: - **User ID:** The ID of the user that performed the event. - **Event time:** The time when the event occurred. Optionally, you can also add a **Group ID** column to the event table. This column is used to mark the team or organization the user belongs to. **Every event performed by the user in the product or service must have a single row in the event table.** > **INFO** > > Some event tables might contain an `event_name` or `event_type` column. This column represents the name of the event the user performed at a given time. Event tables that have an `event_name` column are called **multi event tables**. They are also referred to as "one big table" or "wide tables". Tables that don't have an `event_name` column are called **single event tables**. > **SUCCESS** > > Mitzu supports both single and multi event tables. ### Event properties Any column that is present in an event table is considered an event property. If your tables have complex column types such as JSON, MAP, VARIANT, STRUCT, etc., the nested key-value pairs can be considered event properties as well. More on this subject [here](https://docs.mitzu.io/event-modeling). ### Dimension tables Dimension tables contain information about entities in your business. Typically, these are: - Orders - Users - Products - Items These don't have an `event_time` or `event_name` column. However, they can have a "primary key" column used to identify the entity. > **INFO** > > Mitzu currently supports two types of dimension tables: > > - User > - Group > > In the future, we will introduce support for arbitrary dimension tables. The primary keys in the dimension tables should match the `user_id` and `group_id` columns in the event tables. ## What Mitzu's semantic layer covers Mitzu's semantic layer captures the elements product analytics depends on: events, event properties, filter values, user and group entities, dimension properties, and the relationships between them. The analytics engine uses this layer to construct funnel, retention, and segmentation queries deterministically. --- # Data Models: Event Modeling Source: https://docs.mitzu.io/event-modeling On this page, you will find the three event data model architectures that Mitzu supports. You can find more information in this [blog post](https://www.mitzu.io/post/modeling-product-events-in-the-data-warehouse). ## Single event tables This is the simplest of the three event data models. Each event you want to track should be stored in a separate table. Each table must contain the following columns: - **User ID:** The ID of the user that performed the event. - **Event time:** The time when the event occurred. > **INFO** > > For single event tables, the name of the table describes the event that the user performed. ## Wide multi event tables This event table model stores every event in a single table. The event properties for each event are stored in separate columns within the same table. This makes the table "wide", since the properties for each event don't always overlap and 100+ columns are often required. The multi event table must contain the following columns: - **User ID:** The ID of the user that performed the event. - **Event time:** The time when the event occurred. - **Event name:** The name of the event that the user performed. > **WARNING** > > Maintaining this table has some drawbacks. This table often has 100+ columns, which can be hard to maintain. > **INFO** > > Since this table also contains all events for the product or service, it can hold a lot of data. This can make the table slow to query. We suggest **partitioning** this table by the `event_name` column and indexing it by the `event_time` column. ## Short multi event tables This event table model stores every event in a single table. The event properties for each event are stored as MAP, JSON, or VARIANT types in the same table. This makes the table "short" because, with a single `event_properties` column, it is possible to store all of the event properties. The multi event table must contain the following columns: - **User ID:** The ID of the user that performed the event. - **Event time:** The time when the event occurred. - **Event name:** The name of the event that the user performed. > **WARNING** > > Maintaining this table has some drawbacks. The JSON, Map, or Variant types can cause performance issues. > **INFO** > > Since this table also contains all events for the product or service, it can hold a lot of data. This can make the table slow to query. We suggest **partitioning** this table by the `event_name` column and indexing it by the `event_time` column. > > If you are using Iceberg or Delta Lake tables, make sure your tables are optimized for querying. --- # Data Indexing: Data Indexing Source: https://docs.mitzu.io/indexing Before creating the first insight, Mitzu must collect information about how you structured the events in your data warehouse. We call this process indexing. Indexing populates Mitzu's semantic layer with the events, properties, and filter values discovered in your warehouse, and keeps it in sync as the underlying data changes. ## Stored data To generate the [insights](https://docs.mitzu.io/insights-basics) and [Catalog](https://docs.mitzu.io/event-catalog) pages, Mitzu collects the following information during the indexing process: - **events:** Lists all events Mitzu finds in the configured [event tables](https://docs.mitzu.io/event-tables). Mitzu uses this to generate the insights and catalog pages. - **event properties:** Lists all event properties assigned to each event found. - **event filter values:** Lists the possible values of each event property found. - **event volume statistics:** Counts each event's rows per day for the 14 days before the indexing run's end date. The Catalog page and the analytics agent use these counts to show whether an event currently records data. - **dimension properties:** Lists all dimension properties that Mitzu finds in the configured [dimension tables](https://docs.mitzu.io/dimension-tables). - **dimension filter values:** Lists the possible values of each dimension property found. Together, these elements form the runtime semantic layer the analytics engine uses to answer questions and construct queries. > **SUCCESS** > > Mitzu will never copy data from your data warehouse or fetch data not required to generate the forms in the Mitzu web app. > **INFO** > > For performance reasons, the number of `Event filter values` and `Dimension filter values` is limited to 500. For example, Mitzu won't store the possible values of the event time property due to its high cardinality. If you contact Mitzu support, we will increase this limit. ## Event table indexing When you [add a new event table](https://docs.mitzu.io/event-tables#adding-new-event-tables) or [re-index an existing table](https://docs.mitzu.io/event-tables#re-indexing), Mitzu fetches a sample from the event table and stores the events found in this sample. You can configure the sample size in several ways: - Mitzu calculates the time window of the sample so that it ends on the [Default End Date Config](https://docs.mitzu.io/insight-settings) and begins N days earlier, where N is set by the [Lookback Days](https://docs.mitzu.io/indexing-settings) option. - You can configure the sample size on the [indexing settings](https://docs.mitzu.io/indexing-settings) page. - You can enable [Data Scrambling](https://docs.mitzu.io/indexing-settings) to randomize the order of the queried records. > **INFO** > > You should configure the sample size to maximize the cardinality of your events in the sample; otherwise, Mitzu will not recognize some of your events. If you need help with this configuration, please contact support at [support@mitzu.io](mailto:support@mitzu.io). Once Mitzu has identified your events, it indexes each event's available properties. As with event indexing, Mitzu fetches a sample of the events containing all event properties. If your event tables contain many columns, consider enabling [Bucketed table indexing](https://docs.mitzu.io/indexing-settings). You can then configure how many columns Mitzu should index simultaneously, decreasing the indexing time of large tables. Indexing also collects volume statistics for each recognized event: one aggregate query counts the event's rows per day over the 14 days ending on the [Default End Date Config](https://docs.mitzu.io/insight-settings). Unlike event and property discovery, this count is not sampled. Events with no rows in that window are stored with a count of zero. Mitzu records both the counted window and the time the indexing run computed it — on workspaces with a custom end date, the window can lie in the past even when the stats were collected moments ago. The counts appear in the **14d volume** column of the [Catalog](https://docs.mitzu.io/event-catalog) page and refresh on every re-index. Mitzu can generate the insights page from the recognized `events` and `event properties`. ## Dimension table indexing When you [add a new dimension table](https://docs.mitzu.io/dimension-tables#add-new-dimension-tables), Mitzu fetches a sample from the dimension table and stores the dimension properties found in this sample. You can configure the sample size in several ways: - You can configure the dimension sample size on the [indexing settings](https://docs.mitzu.io/indexing-settings) page. - You can enable [Data Scrambling](https://docs.mitzu.io/indexing-settings) to randomize the order of the queried records. - You can enable [Bucketed table indexing](https://docs.mitzu.io/indexing-settings). This way, the sample will contain a randomized selection of rows from the source table. > **INFO** > > You should configure the sample size to maximize the cardinality of your dimension properties in the sample; otherwise, Mitzu will not recognize some of your properties. If you need help with this configuration, please contact support at [support@mitzu.io](mailto:support@mitzu.io). Mitzu can generate the insights page from the recognized `dimension properties`. Mitzu only indexes dimension filter values when needed. For example, when you add a new dimension filter on the insight page, Mitzu will index the possible values of that specific dimension property using the same sampling mechanism. --- # Data Indexing: Supported Data Types Source: https://docs.mitzu.io/data_indexing/supported-data-types ## High-level overview Mitzu distinguishes several data type categories: - scalar - numbers with floating point precision, integers - text - strings, varchars, and chars - date - date types - timestamp - timestamp types with or without timezones - map/json/variant - dynamically varying complex type - struct - static complex types - array - repeated value type - exotic types - UUID, Blob, etc. ### Generic type support Mitzu generally supports all type categories except "Exotic types" across all data warehouse and data lake types. | Type | Support | | --- | --- | | Scalar | ✅ | | Text | ✅ | | Date | ✅ | | Timestamp | ✅ | | Map / JSON / Variant | ✅ | | Struct | ✅ | | Array | ✅ - only arrays of scalars and arrays of strings | | Exotic types | ❌ (GEO spatial types, UUIDs, Binaries etc) | > Exotic types support is not included, as every data warehouse has a different set of exotic types. ## Type recommendations per use-case In this section, we describe our recommended types for each use case. ### Data type for user ids Generally, the data community has agreed to use UUID4 (or later versions once released) or [CUID](https://github.com/paralleldrive/cuid)s to identify users in data. For simplicity, we recommend using UUID4s. Except for a single character in the middle, these are strings of random characters. ✅ The recommended type category for user ids is **text**. ### Data type for event times Event times can mean four things in product event tracking: - **client time** - the client's timestamp for when the event was logged - **client upload time** - the client's timestamp for when the event was sent to a server or CDP - **server time** - the timestamp for when the server received the event - **corrected client time** - the timestamp calculated from the client time and the difference between the server time and client upload time Generally, we recommend using the **corrected client time** for product analytics. Most CDPs store the corrected client timestamp as the client time in the data warehouse. ✅ The recommended type category for event times is **timestamp** (without timezones). ### Data type for event names Event names should be human-readable or quasi-human-readable text. ✅ The recommended type category for event names is **text**. ### **Data type for date partitions** Date partitions help efficiently read data from a data lake. Data lakes store files in "folders" with formats such as: `/date=2024-04-01/raw_data.parquet` Naturally, you might assume that date partitions should use a date type. However, experience shows that many data teams keep this information in text format in the table definition. Text format is acceptable as long as the date string is in ISO format. Mitzu supports both text and date formats for partition columns. ✅ The recommended type category for date partitions is **DATE** or **TEXT**. ## **Other recommendations** ### Dynamic complex type support for data warehouses This section discusses which data types can be used in each data warehouse for storing dynamic types. | Data warehouse | Supported dynamic type | | --- | --- | | Snowflake | ✅ Flat Object type - no nesting | | Databricks | ✅ Map or MAP | | BigQuery | ✅ JSON Strings | | Trino | ✅ Map or MAP | | Athena | ✅ Map or MAP | | Postgres | ✅ Json or jsonb | | Clickhouse | ✅ Json types | Dynamic complex types are essential for modeling a large number of events with different sets of properties. ### Static complex type support Generally, we don't recommend using static complex types when storing events in a data warehouse or data lake. These types are common in: - Databricks, Athena, Trino - **struct types** - Clickhouse - **tuples** Try to avoid these types and use a flat-column hierarchy instead. --- # Insights Page: Insights Basics Source: https://docs.mitzu.io/insights-basics Now, let's dive into the basics of insight creation with Mitzu. We recommend reading this section before creating segmentation, funnel, retention, or journey insights. ## Mitzu insights Insights are the main building blocks of Mitzu. Currently, we support four categories of insights: - Segmentation - Funnel - Retention - Journey You may be familiar with these from other marketing, sales, or product analytics tools. These insight categories let you create a wide range of metrics and KPIs for your business. This is also where you can dive into the behavior of individual users, groups, or cohorts. A saved insight can also be reused inside another one: a segment of a segmentation can be a saved funnel instead of a single event. See [Metrics](https://docs.mitzu.io/metrics). ![image](https://docs.mitzu.io/img/insights_basics/empty-insight-page.png) ## Mitzu segment In this section, we will cover the most important concepts of the segments panel on the insights page. A segment in Mitzu is a set of events performed by users or groups. A segment is the main building block of every insight in Mitzu. You construct insights by defining segments in the UI. A segment can be a single event you want to measure. For example: how many users visited your landing page? ![image](https://docs.mitzu.io/img/insights_basics/segment-with-single-event.png) However, filters are most often applied to segments. For example: how many users visited your landing page from a specific country? ![image](https://docs.mitzu.io/img/insights_basics/segment-with-single-event-with-filter.png) You can combine multiple events into the same segment, e.g., page visits or sign-ups. ![image](https://docs.mitzu.io/img/insights_basics/segment-with-combined-event-with-filters.png) More about this later. > **INFO** > > It is essential to understand segments to make the best use of Mitzu. You can interpret a segment as: "Find the users who performed X and Y actions matching these filter criteria." > **NOTE** > > You will often see different decorators on the segment panels, such as `breakdown` or `count uniques`. These are not actually part of the segment definition; they are applied to the segments during analysis. ### Subsegments When we refer to a subsegment, we mean one of the sub-definitions of users that make up the segment. The best way to explain it is with an example. The following segment has two subsegments: - Users who performed a `Page Visit` event (visited the landing page). - Users who performed a `User Signed Up` event and are currently paying. ![image](https://docs.mitzu.io/img/insights_basics/segment-with-combined-event-with-filters.png) Using the same event twice to build two subsegments is very common, for example, during experimentation (A/B test) analytics. ![image](https://docs.mitzu.io/img/insights_basics/segment-with-experiment-groups.png) As you will see later, funnels and retention insights benefit greatly from subsegments. > **INFO** > > You can add subsegments with the `+` button at the top of the segment panel. You can add as many subsegments as you want. ### Combining events into a single subsegment Within a single subsegment, you can combine multiple events with an `OR` operator using the `Combine events` button on the subsegment header. This is useful when you want to treat several different events as the same step — for example, "Page Visit OR Email Click" — without splitting them into separate subsegments. ![image](https://docs.mitzu.io/img/insights_basics/segment-combine-or.png) > **INFO** > > Combined events inside a subsegment are joined with `OR`. Filters set on each combined event still apply with `AND` to that event's own conditions. ### Hiding segments In segmentation insights, each segment has a hide/show toggle in its menu. Hidden subsegments are kept in the configuration but excluded from the chart and table — useful for temporarily comparing variants without losing the segment definition. ![image](https://docs.mitzu.io/img/insights_basics/segment-hide-toggle.png) ### Saving a segment as a custom event If your workspace has custom events enabled, the segment menu offers a `Save as custom event` action. The saved event becomes reusable across insights as if it were a regular event. ## Event filters Event filters are also among Mitzu's most important concepts. They are used to narrow down segment definitions. ![image](https://docs.mitzu.io/img/insights_basics/segment-with-most-event-filters.png) As you can see above, there are multiple types of filters. We will explore each of them in the following sections. > **CAUTION** > > When event filters are stacked in a subsegment, they are combined with an `AND` operator. Between two **subsegments**, they are combined with an `OR` operator. ![image](https://docs.mitzu.io/img/insights_basics/segment-combined-events-example.png) In the example above, this is how you can interpret the filters: > Select all users who `viewed` our sites coming from one of the two `Campaigns` **_and_** where the site hostname is `acme.com`, **or** performed an `Invitation Sent` operation with an `Email` address containing `@gmail.com` **_and_** whose `User Country Code` is `us`. ### Event property filters The most common property filters are the event property filters. These are marked with a `.` in the filter dropdown. ![image](https://docs.mitzu.io/img/insights_basics/image-10.png) Event property filters exclude users who **didn't perform the events** matching the given filter condition. > **INFO** > > Mitzu collects event properties for each event during the table indexing process. If tables in your data warehouse change, you must re-index the event tables to reflect the changes. ### Recent Event Usage Indicator The blue circles in the event selection dropdown indicate recent usage frequency for that specific event. The number of times an event has been used recently is also shown when you hover over the event. ![image](https://docs.mitzu.io/img/insights_basics/image-52.png) ### Complex event properties Mitzu supports complex event properties. Complex event properties are event properties nested inside other event properties. For example, you can have a `user_properties` event property containing nested `country_code` and `language` event properties. Mitzu shows these properties in the following format in the property filter dropdown: ![image](https://docs.mitzu.io/img/insights_basics/image-19.png) In the example above, we have an `Event props` event property containing nested `Cost Usd` and `Number of items` properties. > **NOTE** > > Properties can be renamed on the catalog page. ### User and group property filters User and group properties are not bound to specific events. The user and group profile tables are the source of these properties. In the property filter dropdown, you will see the `User Property` and `Group Property` options with the following icons: ![image](https://docs.mitzu.io/img/insights_basics/image-11.png) If you filter on these properties, you directly narrow down the users based on their properties. Groups are associated with a set of users, so filtering on a group property filters on the corresponding set of users. ### Cohort filters A cohort is a "cherry-picked" set of users. You can create cohorts in Mitzu in multiple ways: - Import from a CSV file - Create a cohort on the chart on the insights page - Create a cohort on the lookup page > **INFO** > > Cohort filters scope an insight to the "cherry-picked" set of users, or filter your insights for users that are **not** in the "cherry-picked" set. ![image](https://docs.mitzu.io/img/insights_basics/segment-with-cohort-filter.png) > **INFO** > > **What is the difference between a cohort and a segment of users?** > > Both refer to a set of users. However, a segment is a set of users who share a common property, such as: > > - Country > - Language > - Gender > - Age > - etc. > > A cohort is a set of users that doesn't necessarily share a common property. For example, two users who don't share a single property can still be in the same cohort. You can stack cohort filters in the same subsegment. This is useful when you want to filter for users who belong to two cohorts. ![image](https://docs.mitzu.io/img/insights_basics/segment-with-multiple-cohort-filter.png) Selecting users in one of two cohorts is equivalent to selecting users in two segments. ![image](https://docs.mitzu.io/img/insights_basics/segment-combined-events-with-cohorts.png) ### Filter operators The available operators depend on the property filter type and the type of property data. Event, user, and group property filters have the following operators available: 1. **Scalar data types (integers, float, dates):** - `Is` - Property is **equal** to any of the values listed for the filter - `Is not` - Property is **not equal** to any of the values listed for the filter - `>` - Property is strictly greater than the single value selected for the filter - `<` - Property is strictly less than the single value selected for the filter - `>=` - Property is greater than or equal to the single value selected for the filter - `<=` - Property is less than or equal to the single value selected for the filter - `Present` - Property has some value in the event - `Missing` - Property has no value in the event > **INFO** > > Date and time filters are also supported. To type a specific date or time, use the `YYYY-MM-DD` or `YYYY-MM-DD HH:MM:SS` ISO formats. ![image](https://docs.mitzu.io/img/insights_basics/segment-operators.png) > **NOTE** > > The example above selects users who performed a `Page Visit` event and whose country codes are any of the following: `gb`, `br`, `de`, `in`. 2. **String data type:** In addition to the operators above, the following operators are available: - `Contains` - The value of the event property contains any of the values listed for the filter - `Not contains` - The value of the event property does not contain any of the values listed for the filter > **INFO** > > The `>`, `<`, `>=`, and `<=` operators are also available for string data types. They compare string values based on the ASCII codes of the characters. ![image](https://docs.mitzu.io/img/insights_basics/segment-operators-string.png) > **NOTE** > > The example above selects users who performed a `Page Visit` event and whose country codes contain either of the following letters: `a` or `b`. 3. **Boolean data type:** The following operators are available for boolean data types: - `Is` - Property is **equal** to any of the values listed for the filter - `Is not` - Property is **not equal** to any of the values listed for the filter - `Present` - Property has some value in the event - `Missing` - Property has no value in the event ![image](https://docs.mitzu.io/img/insights_basics/segment-operators-boolean.png) 1. **Array data type:** Array data types in Mitzu are special. Mitzu currently supports arrays only with scalar and string element types. Complex types are not supported inside arrays. The following operators are available for array data types: ![image](https://docs.mitzu.io/img/insights_basics/segment-operators-array.png) - `Has` - The array value of the event property contains any of the values listed for the filter - `Doesn't have` - The array value of the event property does not contain any of the values listed for the filter - `Value like` - At least one element of the array matches one of the SQL `LIKE` patterns listed for the filter (use `%` as a wildcard) - `Value not like` - No element of the array matches the SQL `LIKE` patterns listed for the filter - `Present` - Property has some value in the event - `Missing` - Property has no value in the event ## Segment filters Segment filters are applied to the entire segment. They are most often used to select specific events in the sequence of events triggered by users. Currently, we support the `Nth event filter`. ![image](https://docs.mitzu.io/img/insights_basics/segment-filter-menu.png) > **INFO** > > This helps you: > > - Pinpoint the Nth instance of a user action > - Identify customers based on the number of times they've performed a critical action To enable this segment filter, click the `Nth event filter` button in the segment menu. ![image](https://docs.mitzu.io/img/insights_basics/segment-filter-menu-item.png) With the Nth event filter, you can easily capture each Nth instance of any user action (up to the 99th). This helps you quickly pinpoint and resolve areas of friction for first-time users so you can boost your overall North Star metric. You can also use it to identify your best customers based on the number of times they've taken a critical action in your product, like completing a purchase on an e-commerce platform or playing a song in a music streaming app. Clicking the filter badge opens its settings: - **Nth event** — which occurrence to select (`1`–`99`). - **Type** — the scope the occurrences are counted in: `In window` (the analyzed time window), `Per period` (each period of the trend granularity separately), or `Ever` (the user's whole history). - **Order** — `Chronological order` counts from the user's first event, `Reverse order` from their most recent one. - **Exactly N times** — instead of selecting the Nth occurrence, keep only the users whose event count equals `N` within the chosen scope — for example, users who purchased exactly twice. Those users are represented by their last matching event. This option always counts in chronological order, so the `Order` setting is disabled while it is checked. ![image](https://docs.mitzu.io/img/insights_basics/nth-filter-settings.png) > **INFO** > > Segment filters don't only work with `user` as the subject. You can use them with any entity present in your data. `Groups` are typical candidates for segment filters, and so are `sessions`, etc. > > We will cover this topic in more detail in the [**Analyze uniques by?**](#analyze-uniques-by) section. ### Understanding Segment Filters The following image highlights which user event is selected for each segment filter. Consider this situation for our actor: - Their activity occurs during the first four months of 2024. - The time window we are looking at starts on January 15, 2024, and ends on March 15, 2024. - We are looking at Segmentation with Monthly Trends. ![image](https://docs.mitzu.io/img/insights_basics/first_filter.drawio.png) - **No segment filter**: all 6 events inside the selected time window are considered. - **First event**: none of the events are considered, because the actor's first event happened before the start of the time window. - **First event in window**: only 1 event is considered, which is the last event of the user in January. - **First event per period**: only 3 events are considered: the last event of the user in January, the first event in February, and the first event in March. These are the first events in each period, which corresponds to our months. ## Segment breakdowns Breakdowns are powerful tools for understanding how your users behave across the different subsegments that make up the segment. ![image](https://docs.mitzu.io/img/insights_basics/segment-breakdown-chart-basic.png) You can add as many breakdowns as you want. If you combine two or more events on the segment panel, you will see the combined properties of all of those events. ![image](https://docs.mitzu.io/img/insights_basics/segment-breakdown-multiple-fields.png) > **CAUTION** > > You can use any event, user, or group property as a breakdown except properties with an `array` type. ### Breakdown with subsegment index In segments that contain multiple subsegments, the breakdown dropdown shows `subsegment` as an option. ![image](https://docs.mitzu.io/img/insights_basics/segment-subsegment-breakdown-field.png) This option breaks down your segment analysis by the **index** of the subsegment. This is very useful when you want to compare the behavior of users who performed the same event with different property filters. A great example of this is funnel analysis for A/B test variants. ![image](https://docs.mitzu.io/img/insights_basics/segment-subsegment-funnel-chart.png) ### Breakdown by frequency The breakdown dropdown also offers a `Frequency` option under **Other breakdowns**. It breaks down your analysis by **how many times each user performed the event** within the analyzed date range: users who did it once, twice, three times, and so on. Each user is counted exactly once, in the bucket that equals their total number of occurrences in the range. The buckets are labelled with plain numbers (`1`, `2`, `3`, …), and each user is represented by their last matching event in the range. ![image](https://docs.mitzu.io/img/insights_basics/breakdown-frequency.png) This is useful for questions such as "how many of our users purchased only once, and how many came back for more?" — a segmentation broken down by frequency shows one series per occurrence count. You can combine `Frequency` with other breakdown properties; the frequency bucket is always applied last. Frequency works with segmentation, funnel (conversion), retention, and journey insights. > **INFO** > > Clicking a frequency bucket in a chart (for example to filter, zoom in, or create a cohort) narrows the analysis to the users with exactly that many occurrences — equivalent to the **Exactly N times** option of the [Nth event filter](#segment-filters). ## Analyze uniques by? "Analyze uniques by" is an essential concept in insight creation. You can set the entity that Mitzu performs the analysis on. The two most common entities are `users` and `groups`, but you can select any entity in your data as the core entity. By default, Mitzu selects the `users` entity for any analysis. This means each insight is built around users. In other words, you will analyze the behavior of user segments. If you select `groups` as the core entity, you will analyze the behavior of group segments. > **INFO** > > Mitzu performs segment filters and measurements on the entity selected in the `Analyze uniques by` dropdown. ![image](https://docs.mitzu.io/img/insights_basics/image-24.png) Mitzu also performs chart interactions on the selected entity. ![image](https://docs.mitzu.io/img/insights_basics/image-25.png) # Insight configuration This section will cover the most important configuration options on the insights level. ## Choosing the time window You will see the time window configuration component in the top center section of the insights page. ![image](https://docs.mitzu.io/img/insights_basics/time-config-modal-with-button.png) With this component, you can choose the time horizon for your analysis. You can choose between: - a relative time window: - relative date range (e.g., `1 month`, `1 week`, `1 day`, etc.) - since date (e.g., `since 1st of January 2024 to now`) - an absolute time window: - calendar date range (e.g., `This week`, `This month`, `This year`, etc.) - custom date range (e.g., `1st of December 2023` to `1st of January 2024`) ### Relative time window The relative time window measures the time horizon from the `default end date config`, which you can find on the `Workspace settings` page. ![image](https://docs.mitzu.io/img/insights_basics/image-27.png) Suppose you've set your default end date configuration to `Now`. Mitzu measures the time horizon for the analysis up to the current second. Similarly, if you set the default end date config to `Start of the current day`, the time horizon is measured up to the start of the current day, and so on. #### Adjusting the time horizon for trends If you choose to analyze your insights as "trends", the granularity of the trend also affects the time horizon. For example, if you choose to analyze your insights as "weekly trends", the start date for the analysis will be the first day of the week (Monday), which is treated as the beginning of the time horizon based on the relative time window. Similarly, Mitzu truncates the start date of the time horizon for the `Month` and `Year` time window options. > **INFO** > > Consider the following example: > > - The time horizon is set to `1M` - 1 month. > - The default end date config is set to `Start of the current day`. > - The insight type is set to `Weekly trend`. > - The current date is `1st of September 2024`. > > Normally, the time horizon would start on Thursday, the `1st of August 2024`. However, since we are looking at the weekly trend, the start date is adjusted to the Monday of the week containing the `1st of August 2024`. So the final start date for the analysis will be `29th of July 2024`. Adjusting the time horizon for trends is important; without it, you would see misleading results at the start of your analysis. #### Excluding the most recent periods Sometimes the current period is incomplete — for example, today's data is still partial, or the running week hasn't ended yet. Mitzu lets you exclude the most recent N periods from a relative time window so the analysis only covers fully-elapsed periods. ![image](https://docs.mitzu.io/img/insights_basics/time-config-exclude-options.png) The exclude dropdown sits next to the lookback selector. The available exclusion sizes follow the chosen trend granularity (e.g., excluding `2 days` on a daily trend, `1 week` on a weekly trend). The selector is disabled for the `Total` aggregation, since there is no per-period granularity to skip. > **INFO** > > Excluding periods only shortens the **end** of the analysis window — the start date stays anchored to the original lookback. For example, with a `1M` lookback and `2 days` excluded, the window ends 2 days ago but still starts 1 month before the default end date. ### Custom date range Clicking the `Choose date range` button opens a modal window where you can set the start and end dates of the custom time window for your analysis. ![image](https://docs.mitzu.io/img/insights_basics/time-config-custom-date.png) > **INFO** > > Custom time window dates are inclusive, meaning the entire day is included in the analysis. > > You can also select a single day in the custom time window calendar. > **CAUTION** > > Adjusting the time horizon for trends is also supported for custom time windows. For example, if you have chosen a start date other than Monday and choose to analyze your insights as "weekly trends", the start date for the analysis is adjusted to the Monday of the week containing the start date. ### Since date Clicking the `Choose date` button in the bottom right corner opens a modal window where you can set the start date of the since-date window for your analysis. ![image](https://docs.mitzu.io/img/insights_basics/time-config-since-date.png) ## Trend vs. overall measurement configuration You can select the trend vs. overall measurement configuration in the top center dropdown of the insights page. ![image](https://docs.mitzu.io/img/insights_basics/time-group.png) Trend measurement types visualize the analysis as a change in measurement over the time horizon. In contrast, `Overall` insight types visualize the analysis as a single value (in most cases) for the entire time horizon. Currently, we support the following trend measurement types: - hourly - daily - weekly - monthly - quarterly - yearly The default trend type is `daily`. > **INFO** > > Not every insight type supports every granularity. For example, retention is limited to `daily`, `weekly`, `monthly`, and `yearly` trends, and quarterly is unavailable for funnels and journeys. ## Selecting the chart type Mitzu supports multiple chart types for each insight type (segmentation, funnel, retention, journey) and trend vs. overall measurement type. Trend measurement types support the following chart types: - Bar - Line - Stacked bar - Stacked area - Percentage stacked bar - Percentage stacked area - Heatmap (only in retention insights) - Sankey (only in journey insights) Overall measurement types support the following chart types: - Bar - Stacked bar - Percentage stacked bar - Horizontal bar - Number - Pivot table (only in segmentation insights) - Pie (only in segmentation insights) - GEO charts (only for breakdowns with ISO2 or ISO3 country codes) - Sankey (only in journey insights) ### Percentage stacked charts Percentage stacked charts normalize the values in your analysis to 100%. ![image](https://docs.mitzu.io/img/insights_basics/chart-type-percentage-stacked-bar.png) The same insight with regular stacked charts looks like this: ![image](https://docs.mitzu.io/img/insights_basics/chart-type-stacked-bar.png) ### GEO Charts Mitzu supports GEO charts in segmentation and funnel insights with a single breakdown by `ISO2` or `ISO3` country codes. ![image](https://docs.mitzu.io/img/insights_basics/chart-type-geo.png) ### Pie chart For overall segmentation insights, you can render the result as a pie chart. Each slice represents one segment (or one breakdown value if a breakdown is set). Use this when you want to communicate the composition of a single point in time at a glance. ![image](https://docs.mitzu.io/img/insights_basics/chart-type-pie.png) ### Pivot table For segmentation insights, the `Pivot table` chart type renders the result as a pivot table: you choose which breakdown becomes the columns, and the remaining breakdowns stay as rows. On trends the time periods become one more axis, running down the rows by default. Every event in the segment must have the same breakdowns for the pivot view to be available. ![image](https://docs.mitzu.io/img/pivot_tables/hero.png) Pivot tables also support totals and average columns, per-column sorting and filtering, and their own export behavior. See the [Pivot tables](https://docs.mitzu.io/pivot-table) page for the full picture. ### Sankey chart Sankey is the only chart type for journey insights. Each node represents an event step, and the link width represents the share of users moving from one step to the next. See the [Journeys](https://docs.mitzu.io/journey) page for details. ## Chart interactions You can see the chart tooltip by hovering the mouse cursor over a data point on the chart. ![image](https://docs.mitzu.io/img/insights_basics/tooltip-hover.png) Depending on the insight and chart type, you can perform different operations on some data points on the chart. To open the menu, click a data point on the chart. ![image](https://docs.mitzu.io/img/insights_basics/tooltip-menu.png) ### Zooming in and seeing trends If your chart shows a data trend, you can zoom in on a single data point by clicking on it and then clicking the `Zoom in` button. If your chart shows the overall result for a time window, you can click the `See trends` button to see the trends within a nearby time window. ### Filtering on a group If your insight contains a breakdown field, or multiple segments in the case of a segmentation insight, you can filter on one of the resulting groups by clicking a data point and selecting `Filter on`. This will open a new insight containing the necessary filters to show only the selected group. ### List users, groups If you have selected either `Users` or `Groups` for [Analyze uniques by](#analyze-uniques-by), you can fetch the list of users or groups for the data point you've selected. Click the `List users` or `List groups` button to easily [focus on a selected entity](https://docs.mitzu.io/user-and-group-focus) from the modal that opens. The user (or group) profile modal lets you search and filter the entity's properties and recent events. If your workspace has an external profile URL configured, the modal also exposes a link that opens the corresponding profile in your CRM, support tool, or any other system you've connected. ### Show events `Show events` opens a `List of events` modal showing the recent events behind the data point you clicked. You can pick any event property and the modal lists matching events in chronological order, so you can confirm exactly which events were counted into the chart value. ![image](https://docs.mitzu.io/img/insights_basics/list-events-modal.png) ### List of uniques (dimension table) The `List users` / `List teams` button (the entity name comes from your [Analyze uniques by](#analyze-uniques-by) selection) opens a `List of uniques` modal. When the insight has a breakdown, the modal lets you pick any property and lists every value that contributed to the data point along with the count of unique users (or groups) behind it. ![image](https://docs.mitzu.io/img/insights_basics/dimension-table-modal.png) ### Legend interactions Each entry in the chart legend is an interactive chip. Click a chip to open its editor, where you can rename, recolor and hide that series: - **Rename** the series. Type a new label (up to 100 characters) and click **Apply** (or press `Enter`). The rename is saved with the insight and is also applied to the table view and CSV export. - **Recolor** the series. Pick any swatch from the palette to override the color Mitzu assigned automatically, then click **Apply**. This is useful when two series would otherwise be drawn in near-identical colors. - **Show on chart.** Toggle the eye button off and click **Apply** to take the series off the chart. Its chip stays in the legend, dimmed and struck through, so you can open it again and toggle the series back on. At least one series always stays on the chart, so the toggle is disabled on the last visible one. ![image](https://docs.mitzu.io/img/insights_basics/legend-rename-recolor.png) Hiding a series is a presentation change only: the value axis stays where it was, so the remaining series keep the scale they had, and the chart redraws from the cached result without re-querying your warehouse. Hidden series still appear in the table view and the CSV export. To reset a **single** series, open its chip, clear the rename field (the label falls back to the original group name), re-select its default color and toggle it back on, then click **Apply**. To clear **every** rename and color override in one step, use [Reset labels & colors](#reset-labels--colors) in the More menu. The `+ N` chip at the end of the legend has a checkbox that toggles whether long-tail groups (everything beyond the top N) are bucketed into a single `Other groups` series. ### Create a new cohort You can create a new [cohort](https://docs.mitzu.io/other_assets/cohorts) from a given data point. ### Create a new global annotation If your chart type is not a GEO chart or heatmap, you can mark any date from the tooltip menu with a [global annotation](https://docs.mitzu.io/other_assets/annotations). ## Data sampling and resolution For funnel, retention, and journey insights, you can trade some calculation accuracy for faster query execution. The sampling controls live in the segment panel and combine two independent levers. ![image](https://docs.mitzu.io/img/insights_basics/data-sampling-menu.png) ### Event resolution Event resolution downsamples the events Mitzu reads for the analysis. The available options are: - `No sampling` - every event is considered. - `One user event per minute` - at most one event per user per minute is kept. - `One user event per hour` - at most one event per user per hour is kept. - `One user event per day` - at most one event per user per day is kept. Coarser resolutions translate to dramatically faster queries on long time horizons but also reduce the precision of time-based measurements (for example "average time to convert"). ### Uniques sampling Uniques sampling reduces the **number of analyzed entities** (typically users) instead of events. The supported levels are: - `No sampling` - `90% volume reduction` - keep approximately 10% of entities. - `75% volume reduction` - keep approximately 25% of entities. - `50% volume reduction` - keep approximately 50% of entities. Mitzu scales the resulting counts back up so that aggregated values remain interpretable. Uniques sampling is most useful for very large data warehouses where exploratory iteration would otherwise be slow. > **INFO** > > Workspace-level defaults for both knobs come from the `Event default resolution` and `Event auto sampling` settings in `Workspace settings`. Mitzu also auto-picks a tighter resolution for funnels, journeys, and retention when your time horizon or conversion window grows beyond a few weeks. > **CAUTION** > > Sampling does not apply to segmentation insights — segmentation always reads every event. ## More options for insights You can find options and actions for your insight in the `More` menu. ![image](https://docs.mitzu.io/img/insights_basics/more-menu.png) ### Show SQL This shows the SQL query Mitzu generates for the insight. ![image](https://docs.mitzu.io/img/insights_basics/image-34.png) ### Annotations This option turns `global annotations` on or off for the insight. ![image](https://docs.mitzu.io/img/insights_basics/image-35.png) ### Forecast When the insight is rendered as a trend, the `Forecast` toggle extends the chart with a projection of the next periods based on the historical pattern of the visible series. Forecasted values are drawn as a continuation of the existing series so you can see them in the same chart context. ![image](https://docs.mitzu.io/img/insights_basics/more-menu-forecast.png) > **INFO** > > Forecast is only available when a trend granularity is selected. It is hidden for `Overall` measurements. ### Download chart This button downloads the currently visible chart as a PNG image to your computer. ### Copy chart to clipboard This button copies the chart as a PNG image to your clipboard so you can easily paste it into other applications. ### Truncate numbers This button rounds and truncates numbers, making them easier to read. ### Consistent colors This button ensures that the same groups are shown with the same color. This is useful on dashboards that have multiple insights with the same breakdown. ### Set Y Range This button opens a modal where you can set the range of the chart's Y axis. ### Reset labels & colors This clears every legend label rename, color override **and** hidden series in the current insight at once, returning all series to their original names, the colors Mitzu assigns automatically, and the chart. To reset only one series, edit its legend chip instead (see [Legend interactions](#legend-interactions)). ### Table and CSV export Below the chart, you can see the result as a data table. The table has different columns depending on your insight type and segments. Click the `Export` button to download the table contents in CSV format. ![image](https://docs.mitzu.io/img/insights_basics/table.png) --- # Insights Page: Segmentation Source: https://docs.mitzu.io/segmentation [ ![Read insights basics first](https://docs.mitzu.io/img/logo.svg) ### Read insights basics first Before you dive into this part of the documentation, it is important to understand the basics of Mitzu insights. ](https://docs.mitzu.io/insights-basics) Segmentation is a powerful and flexible tool for visualizing trends and compositions in your data. You can analyze events, cohorts, and user profiles, and display the results in various chart types. Advanced segmentation features let you create formulas and compare current and past data. ![image](https://docs.mitzu.io/img/segmentation/image-1.png) ## Use cases Here are some sample questions you can answer with segmentation: 1. **High-level product analytics** 1. How is my WAU (weekly active users count) changing over time? 2. How often are my users getting value? 3. What is the distribution of my users across regions, devices, etc.? (property breakdown) 2. **B2B (in this case, a messaging application)** 1. How many messages were sent in the US in the past 30 days? 2. How many users had a mobile app session yesterday? (unique events) 3. How many messages are sent per session? (formulas) 4. How much revenue was generated on plans purchased in the past year? (property aggregation) 5. How has the power users cohort grown over the past 6 months? (cohort trends) 3. **Marketing** 1. Which advertising campaigns generate the most checkouts? (property breakdown) 2. Which advertising campaigns generate the most revenue? (property aggregation) 4. **Revenue analytics** 1. Show me the change in MRR from our US-based customers over the last year. 2. What is our current MRR? ## Segmentation basics You have already learned the basics of [segments](https://docs.mitzu.io/insights-basics) in Mitzu. This section covers the most essential segment concepts for user (or any other entity) segmentation. ## Segmentation analysis Segmentation analysis finds behavioral patterns in your user (or other entity) data. In Mitzu, segmentation focuses on comparing the behavior of different segments of users (or other entities) and identifying the differences between them. ### Examples of segmentation analysis Let's look at some examples of segmentation analysis: > **NOTE** > > I want to compare the number of users who visited our landing page with the number who started a trial in the last 30 days. This can be done by simply creating two user segments in the segments panel (left side of the page). For the first segment, we choose users who performed the `Page viewed` event. For the second segment, we select users who performed the `Trial started` event. Both segment definitions will be decorated with the `Count uniques` aggregation. This means we will count the unique users in each segment, since the `Analyze uniques by` option is set to `Users`. We will set the time window to `1M` and use the `Daily trend` measurement type. Finally, we will visualize this as a line chart. ![image](https://docs.mitzu.io/img/segmentation/image-2.png) > **NOTE** > > Let's take this a step further and calculate the ratio between the two segments. You can do this by creating a simple formula under the segment panels. The formula should be `A / B`, where `A` refers to the first segment and `B` refers to the second segment. ![image](https://docs.mitzu.io/img/segmentation/image-3.png) As you can see, there are, on average, 50 page visits per `Trial started` event, which is great for our hypothetical SaaS business. However, I want to see the big picture. Let's zoom out and see how this measurement has changed over the last six months. To do this, I need to change the time horizon to `6M` and use the weekly trend measurement type. ![image](https://docs.mitzu.io/img/segmentation/image-4.png) As you can see, the overall pattern stays the same. However, six months ago, we had a lot fewer page visits for every trial. This is something we should investigate further. In practice, to investigate further, I would switch to funnel analysis and see which marketing campaigns drove the most traffic to our landing page, and which had the highest conversion rate to trial-start events. For now, I will stop here. This example was intended to show you what an investigation looks like in Mitzu. ## Segmentation features In this section, we will cover the features that extend the basics of Mitzu insights. Segmentation is a special insight type because you can select multiple segments of users for comparison. You can also choose how you measure the segments. ### Segment aggregation types You can perform per-segment measurements with the Aggregation type component. By default, the aggregation type is set to `Count uniques`, which means we count the number of unique users in each segment. ![image](https://docs.mitzu.io/img/segmentation/image-6.png) > **INFO** > > If the `Analyze uniques by` setting is set to `Groups`, Mitzu counts the number of groups in each segment. If `Analyze uniques by` is set to anything else, such as `session_id`, count uniques measures the number of unique sessions in each segment. #### Count event totals This aggregation type counts the number of events in the segment. ![image](https://docs.mitzu.io/img/segmentation/image-7.png) In the example above, two segment definitions were defined with the same event, `Page viewed`. The blue line shows the number of events performed by the segment's users, while the green line shows the number of unique users in the segment. #### Average `Average` divides the number of events in the segment by the number of unique entities (users by default). It answers questions like "How many events does each unique user perform on average?" without forcing you to write a formula. > **INFO** > > This is equivalent to the formula `A / B`, where `A` is the same segment with `Count event totals` and `B` is the same segment with `Count uniques`. Use `Average` when you want one segment instead of two. #### Aggregate property This aggregation type aggregates the property values of the segment. 1. First, choose the aggregation function. Currently, we support the following aggregation functions: 1. Count distinct 2. Sum 3. Average 4. Min 5. Max 6. Median 7. P75 8. P90 9. P95 10. P99 Except for the `Count distinct` aggregation function, the aggregation functions only work with numeric properties. > **NOTE** > > How many different marketing campaigns did we run in the last 60 days? This question can be answered by choosing the `Count distinct` aggregation function and selecting the `Campaign` property. This counts the number of distinct campaigns for which at least one page visit occurred. ### Metrics A segment does not have to be a single event. It can also be a **metric**: a saved insight, usually a funnel, reused as a segment. This is how you compare two funnels on one chart, or show a conversion rate next to the volume behind it. See [Metrics](https://docs.mitzu.io/metrics). ### Formulas With formulas, you can apply algebraic expressions to your segmentation analysis. The most common use case is calculating the average number of events per user. ![image](https://docs.mitzu.io/img/segmentation/image-9.png) In the example, we are visualizing the number of events per user per day as a trend. Formulas support the following algebraic operations: 1. `+` addition 2. `-` subtraction 3. `*` multiplication 4. `/` division Mitzu also supports parentheses `()` in these expressions. Letters refer to segment definitions, for example: - `A` - the first segment - `B` - the second segment - ... and so on ... > **TIP** > > To show a formula result as a percentage, prefix the formula with `%:` — for example `%:A/B`. This multiplies the result by 100 and adds a `%` sign to the chart axis, tooltips, and tables. (Writing `(A * 100) / B` also scales the value, but without the `%` sign.) > > Formulas are best for ratios of independent metrics. When one action only happens after or because of another, use a [funnel](https://docs.mitzu.io/funnel) instead — a funnel's conversion rate joins on the same user and stays within 0–100%. #### Formula breakdowns If you are using a formula and want to break down your results by a property, the exact same property must be used in each segment definition referenced in the formula. > **NOTE** > > What is the average number of page visits per user per day, broken down by the `Campaign` property? ![image](https://docs.mitzu.io/img/segmentation/image-13.png) ### Post-processing Post-processing options are only available in segmentation analysis. These operations are not performed in SQL in your data warehouse, but in the Mitzu backend on the result dataset. Currently, we support these post-processing operations: 1. Rolling average with various window sizes 2. Cumulative sum #### Rolling averages Post-processing with rolling averages is useful for "smoothing" your result charts. Without post-processing, the chart looks like this: ![image](https://docs.mitzu.io/img/segmentation/image-10.png) With post-processing, the chart looks like this: ![image](https://docs.mitzu.io/img/segmentation/image-11.png) The overall trend is easier to read with post-processing. #### Cumulative sum Cumulative sum helps you calculate the running total of any measurement. For example, how many total visits happened over the last 6 months? ![image](https://docs.mitzu.io/img/segmentation/image-12.png) ### Forecasting When a trend granularity is selected, segmentation insights support [Forecast](https://docs.mitzu.io/insights-basics#forecast) from the More menu. This is most useful for monitoring metrics where you care about the upcoming trajectory (DAUs, weekly signups, MRR). > **INFO** > > Segmentation insights always read every event — there are no event-resolution or uniques-sampling controls in the segment panel. See [Data sampling and resolution](https://docs.mitzu.io/insights-basics#data-sampling-and-resolution) for context on which insight types support sampling. ### Comparison The Comparison feature lets you analyze data trends by comparing them against those from a previous time period. For example, you can compare data points from the last month with those from the month before. To use this feature: 1. Select the desired comparison window from the dropdown menu. 2. Choose a comparison method by selecting the appropriate icon next to the dropdown. In segmentation, comparison can be performed using either of the following methods: - [Absolute values](#comparison-with-absolute-values) - select the `#` icon. - [Percentage values](#comparison-with-percentage-values) - select the `%` icon. ![image](https://docs.mitzu.io/img/segmentation/comparison-dropdown.png) #### Comparison with absolute values When comparing with absolute values, the system displays both: - the data points from the selected insight time window, and - the data points offset by the chosen comparison time period. Both trends are visualized together on the same chart, making it easy to identify similarities or differences between the two time windows. ![image](https://docs.mitzu.io/img/segmentation/comparison-absolute.png) #### Comparison with percentage values When comparing with percentage values, the system calculates the percentage difference between each data point and its corresponding value at the comparison time offset. The result is displayed as a single trend line representing percentage changes over time, making it easy to observe relative growth or decline. ![image](https://docs.mitzu.io/img/segmentation/comparison-percentage.png) #### Comparison on overall charts Comparison also works when the insight is set to `Overall` instead of a trend, which covers the two charts most often pinned to a dashboard: the big number and the bar chart. Whichever chart it is, the window being compared against is named in the chart's own date indicator rather than on the chart, on the same line as the range the chart covers: `2025-02-01 — 2025-03-01 vs. 2025-01-01 — 2025-02-01` on the insight page, and `Daily, Feb 01 - Mar 01 vs. Jan 01 - Feb 01` in a dashboard card's header. - A **big number** lays every segment out as a cell in a grid, separated by hairlines and ordered by value, largest first. Each cell is centred and reads as three lines: the segment's key, its value, and the change. The change is a chip carrying a direction glyph and an unsigned magnitude — `▼ 62` — with the previous period's own value beside it as `from 657`. The chip follows the `#` / `%` choice above: `#` shows the absolute difference and `%` the relative change, and the previous value is shown either way. When the previous period is zero, no percentage is shown, because a change from zero has no meaningful percentage. A segment the previous window returned nothing for still shows its value, with a neutral `no prior period` chip. At most ten segments are shown; a wider breakdown counts the rest below the grid as `+5 other segments`. Clicking a cell opens the same actions menu a bar or a pie slice does — see trends, filter on the value, create a cohort. - A **bar chart** draws the previous period as a second bar next to each current bar. With a breakdown applied, every value keeps its own pair side by side, and the previous bar is a faded version of the colour its counterpart uses. The indicator is coloured by direction: green for an increase, red for a decrease and grey when nothing moved, in shades that stay legible in both light and dark mode. > **CAUTION** > > The colour reflects the direction of the number, not whether the change is good. On a metric where falling is the goal — churn, error rate, time to value — a green indicator still means the number went up. > **INFO** > > On an overall chart the offered comparison windows are only those at least as long as the selected date range, so the two periods never overlap. A six month range offers `prev. period` and `prev. year`; a seven day range also offers `prev. month`. This differs from trends, where the window has to line up with the chart's time buckets instead. - A **pivot table** gives the previous period its own row directly under the row it belongs to, labelled for example `free (previous)`. Pie charts, country maps and the stacked charts do not offer comparison. Each of them draws a single whole, and a second period has nowhere to sit in it: a stack would either inflate its own total or, on the percentage variants, rebase every share. ## Video tutorial --- # Insights Page: Funnels in Mitzu Source: https://docs.mitzu.io/funnel [ ![Read insights basics first](https://docs.mitzu.io/img/logo.svg) ### Read insights basics first Before you dive into this part of the documentation, it is important to understand the basics of Mitzu insights. ](https://docs.mitzu.io/insights-basics) Mitzu's Funnels let you examine how end users perform a series of events. Funnels calculate and display the number of users who convert from one event to another within a particular time window. ## Use Cases Imagine your product is a B2B messaging application. You might use Funnels to answer these questions: - What percentage of users converted through my signup funnel within 7 days? - At what step of the signup funnel did most users drop off? - How did my A/B test impact conversions in the signup funnel? - How has the payment funnel conversion rate in the US changed over time? - How long does it take most users to complete my payment funnel? - What departments complete the payment funnel most often? - What flows do users take between opening an app and making a purchase? - What flows do users take that don't lead to a purchase? - How do these two paths differ? Which actions should I nudge users toward or away from? - What did the users who dropped off do instead? ## Quick Start Building a report in Funnels takes just a few clicks, and results arrive in seconds. Let's build a simple report together. > **NOTE** > > Let's measure the conversion rate of website visitors to your SaaS product. The typical question you would ask is, "How many users converted to start a trial?" We should only consider conversions valid if the user started the trial within 7 days of their first visit. > We should also look at the last 4 months of data to get reasonable results. ### Step 1. Switch to funnels Click on the `Funnels` tab on the left side of the screen. ![image](https://docs.mitzu.io/img/funnels/image-2.png) ### Step 2. Select the events Select the steps of the funnel you want to analyze: - The first step should be the website visit event. - In our case, the second step should be the conversion event "trial started". - For the `page viewed` event, select the `First event` segment filter. (This ensures we only consider the user's first visit.) ### Step 3. Conversion window Select the correct conversion window, `1 week`, in the conversion window dropdown. ![image](https://docs.mitzu.io/img/funnels/image.png) The rest of the settings are left at their defaults. - Entire funnel conversion window type - Every event conversion attribution ### Step 4. Time window Let's choose the `4M` time window to achieve the desired results. Switch to `Funnel steps` to see the overall conversion rate of the funnel. ![image](https://docs.mitzu.io/img/funnels/image-3.png) ### The results After the 4th step, you should see the following results: ![image](https://docs.mitzu.io/img/funnels/image-4.png) ### Extra step: breakdown As an extra step, you can break down the funnel by the `Campaign` event property. This visualizes how each campaign contributed to the conversion rate. ![image](https://docs.mitzu.io/img/funnels/image-5.png) ## Conversion window The conversion window is the time period during which the funnel steps must be completed. The default value is `1 day`, which means all steps must be completed within 24 hours. > **INFO** > > Mitzu currently doesn't support funnels without a conversion window. If you need an unbounded funnel, increase the conversion window to 10 years. > **CAUTION** > > The conversion window can significantly affect the funnel's performance. With longer conversion windows, the SQL engine has to join more events, resulting in longer query execution times. ## Conversion window type This setting allows you to choose the type of conversion window. Currently, we support two types of conversion windows: - Entire funnel - all the steps must be completed within the conversion window. - Between each step - the maximum amount of time that can pass between any two consecutive steps must be within the conversion window. ## Conversion attribution This setting allows you to choose the attribution of the conversion. It has no visible effect on the "Conversion rate" aggregation type (which is the default aggregation type), but it does affect the "Custom aggregations" and "Time to convert" aggregation types. Currently, we support two types of conversion attribution: - Every event - each event is considered a "converting" event of the funnel. - First event - only the first event of each step (segment) is considered a converting event. ## Conversion order The `Conversion order` setting lets you choose the temporal direction of the funnel: - **Forward** (default) - users must perform the steps in the order you defined them, with each step happening **after** the previous one. This is what you usually want. - **Reverse** - users must perform the steps in the **opposite** order. This is useful for retrospective analysis: "of the users who reached the checkout step, how many had previously visited the landing page within the conversion window?" ![image](https://docs.mitzu.io/img/funnels/conversion-order.png) > **INFO** > > Reverse funnels still use the same conversion window — only the direction of step ordering is flipped. ## Loose timestamp comparison Some funnels combine events from different sources — for example backend and frontend events — whose clocks are not always perfectly aligned for the same user interaction. When that happens, two steps that logically occurred in order can appear a few seconds out of order, and the user is counted as **not** converted. Enable **Loose timestamp comparison** (the checkbox at the bottom of the conversion window menu) to allow a **1 minute grace period** when comparing the order of events. With it on, a step can happen up to 1 minute before the previous step and the user is still counted as converted. > **INFO** > > The grace period only relaxes the **ordering** of the steps — the conversion window itself still applies. The default comes from the **Loose timestamp comparison** setting in your workspace's [insights settings](https://docs.mitzu.io/insight-settings) (which insight types it applies to) and can be overridden per funnel. ## Conversion rate base step When the measurement type is `Conversion rate`, you can configure how the per-step conversion rate is computed: - **Previous step** (default) - each step's conversion rate is `(users at this step) / (users at the previous step)`. This makes step-by-step drop-offs easy to spot. - **Base step** - each step's conversion rate is `(users at this step) / (users at the first step)`. This gives an end-to-end conversion at every step. ![image](https://docs.mitzu.io/img/funnels/conversion-rate-base-step.png) The setting has no effect on overall conversion rate (between the first and last steps) — only on the intermediate steps in `Funnel steps`. ### Practical examples Let's consider the following funnel: - Landing page visit - Payment for an item on an e-commerce website To measure the total revenue, you can use the "Every event" conversion attribution with the "Sum of revenue" aggregation type. However, if you want to measure the average time it takes to reach the first payment, you can use the "First event" conversion attribution with the "Average time to convert" aggregation type. ### Performance implications of conversion attribution Mitzu's SQL engine uses `LEFT OUTER JOIN` with the "every event" conversion attribution, and a `WINDOW FUNCTION` with the "first event" conversion attribution. > **INFO** > > Window functions are an order of magnitude faster than left outer joins. We recommend defaulting to "first event" conversion attribution if you have a large dataset. You can change the default conversion attribution in the "Conversion attribution" setting on the [Insight settings](https://docs.mitzu.io/insight-settings) page. ## Measurement types Mitzu funnels have rich support for measurement (or aggregation) types. ![image](https://docs.mitzu.io/img/funnels/image-7.png) By default, Mitzu uses the "Conversion rate" measurement type. The supported measurement types are: - **Conversion rate** - the number of converted users divided by the number of users who started the funnel. - **Count converted users** - the number of users who completed the funnel steps. - **Count converted events** - the number of converting events on the last step. Use this when a single user can convert multiple times (e.g., a user who completes several purchases) and you want to count the events rather than the unique users. - **Average time to convert** - the average time it takes for users to convert. - **Median time to convert** - the median time it takes for users to convert. - **PXX time to convert** - the XXth percentile of time it takes for users to convert. - **Min time to convert** - the minimum time it takes for users to convert. - **Max time to convert** - the maximum time it takes for users to convert. - **Aggregate property** - a custom aggregation of any property value from the funnel's last segment (step). ### Trends vs. Overall measurement configuration If you are visualizing a funnel trend, the measurements are calculated between the first and last steps only. However, users must still complete each step in the funnel in order to be considered "converted". If you want to visualize the funnel as an overall measurement, the measurement is calculated for all the steps in the funnel. The exception is the "Aggregate property" measurement type, which aggregates the values of the last step only in both cases. ## Custom holding constant As previously mentioned, a user is considered "converted" if the same user completes all the steps in the funnel. With custom holding constants, you can modify this behavior. For example, suppose you want to consider a conversion successful only if it happened within the same browser session. For this purpose, we have introduced the `Custom holding constant` setting. You can pick any property present in all the steps of the funnel. In the example above, you would set the `Custom holding constant` to `session_id`. This ensures that Mitzu measures the conversion rate of users who converted within the same browser session. A custom holding constant never replaces the analyzed entity — the entity you selected in `Analyze by` (the user by default) is always kept. The holding constant is an _additional_ requirement layered on top of it, so a conversion only counts when the **same** entity completes the steps **and** the steps share the same holding-constant value. A later step performed by a different user, or by the same user in a different session, is not counted. ### Difference between "Custom holding constant" and "Analyze by" If you change the `Custom holding constant` setting, the measurements still calculate user conversion rates (or any other user-level measurement). However, if you change the `Analyze by` setting, the target entity for the measurements changes. For example, if you set `Analyze by` to `Groups`, the measurements are calculated for unique groups. You can also set `Analyze by` to `session_id`. In this case, you will measure the number of successfully converting sessions. > **NOTE** > > This documentation uses `session_id` as an example. However, your data in the data warehouse might not have a `session_id` column. ## Funnel step breakdown You can set a breakdown on any of the funnel steps, as long as the breakdown is set on a single step. The most common way to break down the funnel is by one or more properties of the first step. If you break down the funnel by a property from the second step or later, you will often see the breakdown value ``. This represents the segment of users who didn't convert between the previous step and the step containing the breakdown. ![image](https://docs.mitzu.io/img/funnels/image-12.png) ## Trends vs. Overall measurement configuration We already discussed trends vs. overall measurement configuration in the [Insight basics](https://docs.mitzu.io/insights-basics#trend-vs-overall-measurement-configuration) section. In this section, we consider this setting in the context of funnels. ### Funnel steps The overall measurement type is called `Funnel steps`, and the visualization is a bar chart (or GEO chart). In a bar chart, each group represents the associated measurements for each step of the funnel. By default, each group in the bar chart shows the funnel's conversion rate (or other measurement) up to that step. ![image](https://docs.mitzu.io/img/funnels/image-8.png) Below, you can see the funnel steps for the time-to-convert measurement. ![image](https://docs.mitzu.io/img/funnels/image-9.png) ### Funnel trends The main thing to consider when visualizing funnel trends is that we attribute each conversion to the date of the first step of the funnel. Consider the following funnel: - Page viewed - (Checkout) Payment for an item on the e-commerce site ![image](https://docs.mitzu.io/img/funnels/image-10.png) In this case, the conversion window is set to 7 days. The checkout may have happened 6 days after the page view, but we still attribute the conversion to the date of the page view event. ![image](https://docs.mitzu.io/img/funnels/image-11.png) This is true for any number of funnel steps. > **INFO** > > Funnels support hourly, daily, weekly, monthly, and yearly trends. Quarterly is not available for funnel trends. ## Dotted lines in funnel charts ![image](https://docs.mitzu.io/img/funnels/image-13.png) Dotted lines in funnel charts indicate that users entering the funnel at a given point have not yet had sufficient time to complete the funnel within the defined conversion window. The section with the dotted line is considered **incomplete**, meaning conversions beyond this point may still occur but are not yet recorded. This helps distinguish between actual drop-offs and conversions that could still be in progress. ## Probability to be best (Bayesian) With funnel insights, you can also see the probability that a variant has the highest true conversion rate, based on Bayesian sampling from posterior distributions. This feature is only available for funnel insights with overall measurements (Funnel steps). This feature is most useful for A/B test analysis. Bayesian A/B testing calculates the probability of a variant being the best by combining prior beliefs with observed data. Given two variants (A and B), we model their conversion rates as Beta distributions (posterior beliefs) using Bayesian inference. The probability that one variant is better than the other is computed by simulating many samples from these posteriors and checking how often one exceeds the other. This Monte Carlo method estimates P(A > B) or P(B > A) directly, giving actionable probabilities instead of p-values. Unlike frequentist tests, Bayesian A/B testing continuously updates beliefs and allows stopping based on confidence thresholds. ![image](https://docs.mitzu.io/img/funnels/image-6.png) ## Comparison The Comparison feature lets you analyze and evaluate data trends by comparing them against a previous time window. For example, you can compare data points from the last month with those from the preceding month. To enable comparison, select the desired comparison window from the dropdown menu. In funnels, comparisons are currently supported using [absolute values](#comparison-with-absolute-values). Additional comparison methods will be introduced in future updates. For details on the product roadmap, please contact us at [support@mitzu.io](mailto:support@mitzu.io). ![image](https://docs.mitzu.io/img/funnels/comparison-dropdown.png) ### Comparison with absolute values When using comparison with absolute values, the chart displays: - the data points from the selected insight time window, and - the data points offset by the chosen comparison time period. Both sets of data are visualized together, making it easy to identify trends, similarities, and deviations between the two time windows. ![image](https://docs.mitzu.io/img/funnels/comparison-absolute.png) ## Using a saved funnel in a segmentation A saved funnel can be reused as a segment in a segmentation insight, which is how you compare two funnels on one chart or show a conversion rate next to the volume behind it. The segmentation sets the date range and the break downs; the funnel keeps its own steps, conversion window and measurement. See [Metrics](https://docs.mitzu.io/metrics). ## Video tutorial --- # Insights Page: Retention Source: https://docs.mitzu.io/retention [ ![Read insights basics first](https://docs.mitzu.io/img/logo.svg) ### Read insights basics first Before you dive into this part of the documentation, it is important to understand the basics of Mitzu insights. ](https://docs.mitzu.io/insights-basics) ## Use Cases Maximizing user retention is a critical part of your business's success. Mitzu's retention feature lets you analyze how users or groups are retained by your product or marketing site. ## Quick Start In this example, we will showcase how users are retained in our application. We consider users "retained" if they have paid their monthly renewal fee. The goal of the analysis is to visualize our users' overall monthly retention rate for the last year. On top of that, we want to see how the retention rate changes over time with monthly granularity (cohort retention). ### Step 1. Switch to retention and select events First, switch to the retention insight tab and select the events you want to analyze. As the `Initial event`, I will select `Subscription started`, since we are only interested in users who started a subscription. Remember that you can set a segment filter on this event. For example, `first event` narrows the scope of the analysis to the user's first subscription. We will now apply a property filter on `Plan interval`. We will select only users who performed `Subscription started` events with a monthly plan interval. For the second event, we can pick `Payment received`. ![image](https://docs.mitzu.io/img/retention/image.png) ### Step 2. Select the retention window For this example, I will set the retention period to `All groups`. ![image](https://docs.mitzu.io/img/retention/image-1.png) The retention period is the period you want to analyze retention for. `All groups` means we will analyze the **month over month** retention of our user base for the last year. Alternatively, I could pick `Month 1` retention, which would show the retention rate of users after their first month. ### Step 3. Select trends vs. overall measurement configuration Let's select the `1Y` time window for our retention analysis. By default, Mitzu shows the change in retention rate over time. However, you can also visualize the retention rate as a whole (overall retention rate). ![image](https://docs.mitzu.io/img/retention/image-2.png) ### The results By selecting the `Overall retention` configuration with `All groups` as the retention period configuration, we will see the typical retention curve on our graph. ![image](https://docs.mitzu.io/img/retention/image-3.png) This shows the month-over-month retention rate for our users, regardless of which month they started their subscription, as long as the subscription was started within the last year. ### Cohort retention / retention trend over time You can select the `Monthly trend` configuration for the trends vs. overall measurement configuration. This shows you the change in retention rate over time for each of the last 12 months. This chart can become very noisy if you have a long time window. ![image](https://docs.mitzu.io/img/retention/image-4.png) It is often better to visualize this as a heatmap. ![image](https://docs.mitzu.io/img/retention/image-5.png) However, if this is still too noisy, you can remove the `All groups` retention period config, select only months one and four, and visualize the result as a line chart. ![image](https://docs.mitzu.io/img/retention/image-6.png) ## Retention features ### Retention period The retention period is the configuration that lets you compare retention rates across different periods. In this dropdown component, you can select multiple values simultaneously. For example, by selecting `Month 1` and `Month 2`, you will see the retention rate for the first and second months after the initial step. The retention period `<1` means `Month 0`, which measures the retention rate of users in the same `Month` as the initial step. ![image](https://docs.mitzu.io/img/retention/image-7.png) > **CAUTION** > > Mitzu calculates retention in relative periods. For example, if the retention period is set to `4 weeks`, users are considered retained if they perform the retaining event between 21 and 28 days after the initial step. > > In other words, the retention period doesn't refer to calendar months or weeks. #### Retention window granularity The retention window selector lets you choose the granularity of the retention buckets: - `Day` - day-over-day retention. - `Week` - week-over-week retention. - `Month` - month-over-month retention (used in this guide's examples). - `Year` - year-over-year retention. ![image](https://docs.mitzu.io/img/retention/retention-window-granularity.png) Pick the smallest granularity that still produces meaningful cohort sizes — daily retention works for high-frequency products like messaging apps, while monthly or yearly is more appropriate for subscription products. ### Custom holding constant Similar to Funnels, you can set a custom holding constant for the retention analysis. To continue our example, we will set the `Custom holding constant` to `subscription_id`. This measures the retention rate of users who performed the `payment_received` event with the same `subscription_id` as the one their subscription was started with. This is crucial for correctly attributing the retaining events. The retaining entity is unchanged — retention is still measured for the entity set in `Analyze uniques by` (the user by default). The holding constant only adds a requirement that the retaining event shares the same value (here, the same `subscription_id`) as the initial event; it never lets a different user's event count as a retention. > **INFO** > > As with funnels, the `Analyze uniques by` config changes the target entity for the retention analysis. You can switch to `Groups` to measure the retention rate of groups that performed the `payment_received` event after a single user from the group performed the `subscription_started` event. ### Measurement types By default, Mitzu measures the retention rate of users who performed the initial and retaining events. However, you can change this behavior by selecting a different measurement type. ![image](https://docs.mitzu.io/img/retention/image-8.png) Mitzu supports the `Aggregate property` measurement type. As with funnels, this configuration makes Mitzu aggregate any property from the last step (the retaining step). For example, in our case above, we can select the `Aggregate property` measurement type and choose the `Sum` aggregation function with the `Price` event property of the `payment_received` event. ![image](https://docs.mitzu.io/img/retention/image-9.png) This visualizes the total retained revenue month over month. ![image](https://docs.mitzu.io/img/retention/image-10.png) ### Returning on or after vs. returning on specific days This configuration controls how Mitzu considers users retained. If you select `Returning on or after`, Mitzu considers users retained if they performed the retaining event **during or after** the retention period. > **INFO** > > Consider an app with sporadic usage where every user opens it once a month. If I visualize the week-over-week retention rate of users who open the app on the last day of the month, for three weeks I would see a drop in the retention rate. To reduce this noise, you can apply the `Returning on or after` configuration. This makes Mitzu consider each week before the retaining event as a retained week. In contrast, the `Returning on specific days` configuration makes Mitzu consider users retained only for the exact time period (week, month, etc.) in which they performed the retaining event. ### Can the retention rate go up? Yes, and whether that is expected depends on the measurement type and on whether the base stays fixed. - **`Returning on specific days`**: the rate can move up and down freely. Each period asks its own question — did the user return _in that period_. Someone can return in week 1, skip week 2 and come back in week 3, so a row that rises is normal, not a defect. - **`Returning on or after`**: the retained group can only shrink as the periods go on, because anyone retained in week 3 was also retained in week 2. With a fixed base the rate therefore only falls. Cohort views — the heatmap and the daily, weekly and monthly trends — always divide by the full cohort, so the base is fixed and the rule above holds exactly: `Returning on or after` only falls along a row, `Returning on specific days` may not. Overall retention with the `Eligible users` base is the exception. There the base shrinks along with the retained group, because a later period counts only the users who have had that long to return. The rate can rise at the end even with `Returning on or after`. See [Incomplete periods](#incomplete-periods) for why, and what to do about it. ### Retention attribution This setting allows you to choose the attribution of the retention. It has no visible effect on the "Retention rate" aggregation type (which is the default aggregation type). Currently, we support two types of retention attribution: - Every event - each event is considered a "retaining" event of the retention insight. - First event - only the first event of the retaining step (segment) is considered a retaining event. ### Loose timestamp comparison Retention often combines events from different sources — for example backend and frontend events — whose clocks are not always perfectly aligned for the same user interaction. When that happens, a retaining event that logically falls inside a retention period can land a few seconds before the period start and the user is counted as **not** retained for that period. Enable **Loose timestamp comparison** (the checkbox in the retention period menu) to allow a **1 minute grace period** when deciding whether a retaining event falls within a retention period. With it on, a retaining event can happen up to 1 minute before the period start and still count. > **INFO** > > The grace period only relaxes the **start** of each retention period, so returns never leak across adjacent buckets. The default comes from the **Loose timestamp comparison** setting in your workspace's [insights settings](https://docs.mitzu.io/insight-settings), which is on for retention in new workspaces, and can be overridden per retention insight. > **CAUTION** > > On ClickHouse the grace period is not applied — loose timestamp comparison only counts events at the exact period start (`>=`). Other warehouses use the full 1 minute grace. #### What it does to `Day 0` / `Week 0` / `Month 0` Period 0 starts at the initial event itself, so this setting decides what the first retention period measures: - **On**: a retaining event at the same moment as the initial one already lands in period 0. When the retaining step is **identical** to the initial one — same event, same filters — every initial event is its own return, so period 0 is **100%** by construction. Any difference between the two steps (a different event, or a filter on one side) breaks that, and period 0 measures real returns again. - **Off**: the retaining event has to land strictly after the initial one, so a retaining event at that same moment doesn't count. With identical steps, period 0 means the user performed the event **a second time**. Both readings are correct, but they are not comparable: don't compare a period 0 measured with the setting on against one measured with it off. ### Trend vs. overall measurement configuration As discussed in our example above, retention insights also support trend and overall measurement configurations. Retention trends are called `daily/weekly/monthly trend`. Once selected, they help you understand how your retention rate changes over time. Overall retention shows how the passage of time affects the retention rate for users who performed the initial event and then repeatedly performed the retaining event. ### Retention base Retention is sensitive to periods that have not fully elapsed yet: a user who performed the initial event two weeks ago has not had the chance to return in Week 5. The `Retention base` dropdown in the Retention period menu (the clock button that reads `Returning on each week`) decides how such users are counted. The chart header always shows which base is in effect, and the workspace default lives in [Insight settings](https://docs.mitzu.io/insight-settings). - **Eligible users** (the default): a user counts towards a period only once that period has fully elapsed for them — only users who could have returned are in that period's base. The later periods therefore rest on fewer users. Hover the chart header badge to see the rule. - **All users**: every user stays in the base for every period. Users who have not reached a period yet count as not returned, so the last periods dip. This is what a hand-written retention query usually produces. The two bases give identical numbers once every period has elapsed for everyone in the date range. They only differ at the recent end of the chart. The base applies to **overall retention only**. Cohort views — the heatmap and the daily, weekly and monthly trends — always divide by the full cohort so that every cell in a row stays comparable, and the setting makes no difference to them. ### Incomplete periods Whatever the base, some periods have not finished for everyone yet. Mitzu shows them and marks them, so you can see the latest values without mistaking them for final ones. - **Overall retention** with the `Eligible users` base: the last period, which even the earliest users in the date range have not finished yet, is drawn dotted and marked with `*`. It shows the users who are already inside that period, and its value can still rise until the period closes; hover the point to see how many users it is based on. With the `All users` base every user is in every period from the start, so nothing is marked. - **Cohort views** (the heatmap and the daily/weekly/monthly trend) always divide by the full cohort, so every cell in a row is comparable. A cell whose period has not finished for every member of the cohort shows the value so far, marked with `*` and a dotted outline; that value can only rise as time passes. A cell whose period has not started for anyone is left blank. The chart header shows an `Incomplete periods marked` badge whenever something is marked. Untick `Show incomplete periods` in the More menu to leave those periods out of the chart and the table instead; the badge then reads `Incomplete periods hidden`. The workspace default for new charts lives in [Insight settings](https://docs.mitzu.io/insight-settings). > **INFO** > > When the base is `Eligible users`, the overall curve can tick up at the very end: the last periods are measured on the users who joined at the start of the date range, and those are often long-time users who only look new because the range starts there. If you want cohorts of genuinely new users, add the `Nth event` segment filter to the initial step with `Nth event` set to 1 and `Type` set to `Ever`, so only each user's first-ever occurrence of the event starts a cohort. This is not a data problem, it is the base rule at work. ### Data sampling Retention queries are sensitive to long time horizons. Mitzu can downsample the events it reads and the entities it analyzes to keep queries fast — see [Data sampling and resolution](https://docs.mitzu.io/insights-basics#data-sampling-and-resolution) for the full description of `Event resolution` and `Uniques sampling`. ### Comparison The Comparison feature lets you analyze data trends by comparing them against those from a previous time period. For example, you can compare data points from the last month with data from the preceding month. To activate the comparison, select the desired comparison window from the dropdown menu. In retention analysis, comparisons are currently available using [absolute values](#comparison-with-absolute-values). Additional comparison methods will be introduced in future updates. For information about upcoming features, please contact us at [support@mitzu.io](mailto:support@mitzu.io). ![image](https://docs.mitzu.io/img/retention/comparison-dropdown.png) #### Comparison with absolute values When using comparison with absolute values, the chart displays both: - the data points from the selected insight time window, and - the data points offset by the chosen comparison time period. This lets you view both trends simultaneously and identify changes or patterns between the two time windows. ![image](https://docs.mitzu.io/img/retention/comparison-absolute.png) ## Video tutorial --- # Insights Page: Journeys in Mitzu Source: https://docs.mitzu.io/journey [ ![Read insights basics first](https://docs.mitzu.io/img/logo.svg) ### Read insights basics first Before you dive into this part of the documentation, it is important to understand the basics of Mitzu insights. ](https://docs.mitzu.io/insights-basics) Mitzu's journey charts give you a visual map of every path users take through your product. Journeys calculate the user count and conversion rate for each step along every path. ## Use Cases Imagine your product is a B2C webshop, and you bring visitors to your webshop through different blog posts and marketing campaigns. You might use journeys to answer questions like: - Which marketing campaign generates the most revenue? - In a checkout flow, which steps do users drop off at most? - How are users segmented in the middle of a funnel? ## Quick Start Building a report in journeys takes just a few clicks, and results arrive in seconds. Let's build a simple report together. Imagine we have a webshop where visitors to our landing page can subscribe to emails. Later, we email them with our latest prices. Let's say we ran a campaign called `20% off from all prices`, and we want to see in which countries these emails led to a checkout and in which countries they didn't perform. ### Step 1. Switch to journeys Click on the `Journey` tab on the left side of the screen. ![image](https://docs.mitzu.io/img/journeys/image.png) ### Step 2. Select the events Select the steps of the journey you want to analyze: - The first step should be the `Page visit` event with a filter on the `Acquisition campaign` property set to the value `promo_20off`. - Click `+ Add event` and add the following events: `Email sent`, `Email opened`, and `Checkout`. - For the `Email opened` event, select `User Country Code` as the breakdown. ### Step 3. Conversion window Select the correct conversion window, `2 weeks`, in the conversion window dropdown. ![image](https://docs.mitzu.io/img/journeys/image-1.png) You can leave the rest of the settings at their defaults. - Entire funnel conversion window type - First event conversion attribution ### Step 4. Time window Let's choose the `1M` time window to achieve the desired results. The `` nodes represent users who started the flow but did not finish it. ![image](https://docs.mitzu.io/img/journeys/image-2.png) ### The results After the 4th step, you should see the following results: ![image](https://docs.mitzu.io/img/journeys/image-3.png) On the chart, we can see all user paths through the selected events. By hovering the cursor over nodes and links, we can gather further details about each specific path. For example, only 25% of users did not open the emails within two weeks. In this case, the email tracking service may show a 75% open rate, but from the next step of the journey chart, we can see that the majority of these users dropped off before the checkout event. ![image](https://docs.mitzu.io/img/journeys/image-4.png) Another example is that users from the US, China, and Germany don't check out after these emails, so they may need to be targeted differently. ## Conversion window The conversion window is the time period during which the journey steps must be completed. The default value is `1 day`, which means all steps must be completed within 24 hours. > **INFO** > > Mitzu currently only supports journeys with a conversion window. If you need an unbounded journey, increase the conversion window to 10 years. > **CAUTION** > > The conversion window can significantly affect the journey's performance. With higher conversion windows, the SQL engine will join more events, resulting in a longer query execution time. ## Conversion window type This setting allows you to choose the type of conversion window. Currently, we support only one type of conversion window for journeys: - Entire funnel - all the steps must be completed within the conversion window. ## Conversion attribution This setting allows you to choose the attribution of the conversion. Currently, we support only one type of conversion attribution for journeys: - First event - only the first event of each step (segment) is considered a converting event. ## Loose timestamp comparison Journeys often combine events from different sources — for example backend and frontend events — whose clocks are not always perfectly aligned for the same user interaction. When that happens, two steps that logically occurred in order can appear a few seconds out of order, and the user is counted as **not** converted. Enable **Loose timestamp comparison** (the checkbox at the bottom of the conversion window menu) to allow a **1 minute grace period** when comparing the order of events. With it on, a step can happen up to 1 minute before the previous step and the user is still counted as converted. > **INFO** > > The grace period only relaxes the **ordering** of the steps — the conversion window itself still applies. The default comes from the **Loose timestamp comparison** setting in your workspace's [insights settings](https://docs.mitzu.io/insight-settings) (which insight types it applies to) and can be overridden per journey. ## Measurement types Mitzu supports only one measurement (or aggregation) type for journeys: - **Conversion rate** - the number of converted users divided by the number of users who started the funnel. ## Chart type Journey insights are always visualized as a **Sankey** diagram. Other chart types (bar, line, GEO, etc.) are not available for this insight type. - Each **node** represents a step (event) of the journey or the `` exit point. - Each **link** between two nodes represents the share of users moving from one step to the next. - The width of a link is proportional to the number of users following that path. Hovering a node or link shows the user count, conversion rate from the previous step, and any breakdown values you've configured. ### Drop-off nodes Whenever users start the journey but fail to complete the next step within the conversion window, they end up in a `` node attached to the step they didn't pass. Drop-off nodes make it visually obvious where users leave the flow — the bigger the drop-off node, the more users you're losing at that step. > **INFO** > > A user only contributes to a drop-off node from the **last step they reached**. If a user completes step 1 but never reaches step 2, they show up in the drop-off attached to step 2 — not in any earlier or later one. ### Step breakdowns You can break down any step of the journey by an event property (just like funnels). The breakdown values become separate nodes in the Sankey diagram, letting you see how each variant flows through the rest of the journey. ![image](https://docs.mitzu.io/img/journeys/step-breakdown.png) In the quick-start above, breaking the `Email opened` step down by `User Country Code` is what produces the per-country flows in the screenshot. ## Custom holding constant As previously mentioned, a user is considered "converted" if the same user completes all the steps in the journey. With custom holding constants, you can modify this behavior. For example, suppose you want to consider a conversion successful only if it happened within the same browser session. For this purpose, we have introduced the `Custom holding constant` setting. You can pick any property present in all the steps of the journey. In the example above, you would set the `Custom holding constant` to `session_id`. This ensures that Mitzu measures the conversion rate of users who converted within the same browser session. A custom holding constant never replaces the analyzed entity — the entity you selected in `Analyze by` (the user by default) is always kept. The holding constant is an _additional_ requirement layered on top of it, so a conversion only counts when the **same** entity completes the steps **and** the steps share the same holding-constant value. ## Video tutorial --- # Insights Page: Pivot tables Source: https://docs.mitzu.io/pivot-table A pivot table answers questions that have **two things in them at once** — "how many signups, by campaign **and** by plan?" It puts one of them down the side, the other across the top, and the number for each combination where they meet. A bar chart can only really show you one of the two. A pivot table shows both, so you can read a single row, compare a whole column, and spot the one combination that stands out. ![image](https://docs.mitzu.io/img/pivot_tables/hero.png) ## Use cases Pivot tables are useful whenever you want to compare two things at the same time. Typically, the questions you can answer with one look like this: **Acquisition and marketing** - Which campaigns bring in customers on our most expensive plans — not just the most signups? - Does a channel that works well in one country work anywhere else? **Product** - Which features does each type of customer actually use? - Is a new feature being adopted evenly across platforms, or carried by just one? **Experimentation** - Did the winning variant win everywhere, or only in a couple of markets? ## When you can use a pivot table The `Pivot table` chart type is available on every **segmentation** insight: - on an **`Overall segmentation`** your segment needs at least one **breakdown** — the whole date range is summed up into one number per cell; - on a **trend** (daily, weekly, monthly, ...) breakdowns are optional — the time periods give the table its second dimension. ![image](https://docs.mitzu.io/img/pivot_tables/toolbar.png) > **INFO** > > Pivot tables are not available for funnel, retention, or journey insights. Switching between `Overall segmentation` and a trend keeps the pivot table; only the axes on offer change. If your segment contains more than one event, all of them need the same breakdowns. See [When Mitzu can't build the pivot table](#when-mitzu-cant-build-the-pivot-table) below. ## Creating a pivot table 1. Build a segmentation insight as usual and add one or more **breakdowns**. 2. Pick the measurement type: **`Overall segmentation`** for one number per cell, or a trend for one row per period. 3. Click the **`Pivot table`** icon in the chart type row. 4. Choose which breakdown you want across the top, using the dropdown that appears to the right of the chart type icons. ## Choosing what goes across the top The dropdown to the right of the chart type icons decides how your breakdowns are arranged. It shows your current choice, for example `Columns: Plan`. ![image](https://docs.mitzu.io/img/pivot_tables/column-axis.png) - **`Breakdowns in rows`** — nothing goes across the top. Each breakdown becomes its own column on the left, and you get a flat list with one row per combination. - **`Columns: `** — that breakdown goes across the top. Any other breakdowns stay on the left as labels. ![image](https://docs.mitzu.io/img/pivot_tables/rows-only.png) > **INFO** > > Only **one** breakdown can go across the top. If you have three breakdowns and put one across the top, the other two appear as two label columns on the left. > **NOTE** > > Choose the breakdown with **fewer values** for the top. A breakdown with 4 values gives you 4 readable columns; one with 200 values gives you a table you have to scroll sideways forever. You can also use a breakdown set for the whole insight in the `Break downs` panel, not just one set on a single event. Both kinds appear in the same dropdown. ### Trends: the time periods are one more axis On a trend the periods join your breakdowns as an axis of their own, named after the granularity — `Day`, `Week`, `Month` and so on. - By default the periods run **down the rows**, oldest first. A daily trend over 90 days is a 90-row table you can page through, not a 90-column one you have to scroll sideways. - If the insight has **exactly one breakdown**, Mitzu puts that breakdown across the top for you the moment you switch to the pivot table: one row per period, one column per plan, country or whatever you broke down by. This is the layout most people paste into a spreadsheet. - With two or more breakdowns everything starts in the rows, and you pick what goes across the top. - **`Columns: Week`** (or `Day`, `Month`, ...) puts the periods across the top instead, with every breakdown in the rows. It reads well for short ranges at a coarse granularity — twelve months, eight quarters — and gets wide quickly on daily data. Previous-period comparison, rolling averages and cumulative sums are switched off while the pivot table is showing; the table holds the plain numbers of the current range only. Your settings are remembered rather than discarded — switch back to a line or bar chart and they apply again. ## Reading the table **The header has two rows.** The top one tells you which event the numbers belong to and what is being counted — `Unique users`, `Event count`, and so on. The row underneath lists the values of the breakdown you put across the top. **Bars behind the numbers** show you how big each value is, so you can scan the table without reading every digit. Each event gets its own scale, so bar lengths are worth comparing within an event but not across two of them. **A grey dot (`·`)** in a cell means that combination simply didn't happen — nobody on the enterprise plan came in through that campaign, for example. It is not the same as a zero. > **NOTE** > > Don't confuse the dot with ``, `` and ``, which you will see as **row labels or column headings** rather than inside cells. Those are real groups, holding the users whose property had no value. The dot means a missing **combination**; those labels mean a missing **property value**. > **INFO** > > Rows start out sorted by the first column of numbers, largest first. On a trend with the periods in the rows they are in date order instead, and with the periods across the top each row is sorted by its row total. The values across the top are sorted sensibly for what they are: numbers in numerical order, dates in chronological order, everything else alphabetically. The ``, `` and `` groups always come last, so your real values stay together at the front. ### Sorting, filtering and paging Click any column header to sort by it: once for ascending, again for descending, a third time to return to the original order. Numbers sort as numbers, not as text. Below the header is a row of `Filter` boxes, one per column. Type in one to keep only the rows containing that text. If you fill in more than one box, a row has to match all of them to stay. The counter underneath the table tells you how many rows are left. The insights page shows 20 rows at a time. Dashboard cards and the agent's chat show fewer, depending on how much room they have. ## Totals and averages When a breakdown is across the top, a second dropdown lets you add a summary column. ![image](https://docs.mitzu.io/img/pivot_tables/totals-menu.png) - **`No totals`** — the default. - **`Totals column`** — adds a `Total` column that adds up the row. - **`Average column`** — adds an `Average` column with the average of the row, ignoring empty cells. ![image](https://docs.mitzu.io/img/pivot_tables/totals-column.png) The summary column sits on the far right, with grey bars rather than coloured ones. It is almost always the biggest number in the row, so giving it the same colouring would flatten every other bar in the table. > **CAUTION** > > **A row total is not always the number you want.** Hover the summary column header and Mitzu tells you which of these apply to your insight: > > - If your table contains more than one event, the total adds those different events together. > - If you are counting **unique** users, someone who appears in two columns is counted in both. A row total of 100 does not mean 100 different people — it is the sum of each column's own count. > - On a trend with the periods across the top, the same applies to someone active in two periods. On a trend the useful summary depends on the orientation. With a breakdown across the top, `Total` is the period's total across the breakdown values. With the periods across the top, `Total` adds up the whole range and `Average` gives the average per period — the same number the standard table shows in its `AVG` column. > **INFO** > > Changing what goes across the top, or switching totals on, does not send a new query to your data warehouse. The table dims and a `Run` button appears; clicking it rearranges the data Mitzu already has, so it costs you nothing. ## Formulas Formulas work with pivot tables. The formula gets its own set of columns next to the events it is built from, and your breakdowns are kept. ## When Mitzu can't build the pivot table Every event in your segment has to be broken down by the same properties. The order you added them in doesn't matter, but the properties themselves do. If one event is broken down by `Plan` and another by `Plan interval`, there is no sensible grid to build. When that happens, Mitzu shows a `Pivot unavailable` badge, hides the pivot dropdowns, and falls back to the standard table so you still get your numbers. ![image](https://docs.mitzu.io/img/pivot_tables/pivot-unavailable.png) To fix it, give every event the same breakdowns — or set the breakdown once for the whole insight in the `Break downs` panel, which applies it to all of them at once. ## Exporting ### CSV The `Export` button below the table downloads it as `mitzu-export.csv`. > **INFO** > > The CSV contains **every** row of the result, not just the page you happen to be looking at. ### Image and clipboard > **INFO** > > Image exports, dashboard thumbnails and emailed reports show at most 12 columns of numbers. When a pivot is wider than that, each metric keeps its latest periods — or its first values, for a text breakdown — and a note under the table says how many columns were left out. `Download chart` and `Copy chart to clipboard` in the `More` menu give you the pivot table as an **image**. This is also what gets embedded into dashboard PDFs and email reports. > **INFO** > > Images can only show the first **25 rows**, with a `+ N more rows` note at the bottom telling you how many were left out. Use the CSV export when you need the whole table. ## Pivot tables elsewhere in Mitzu **Dashboards.** A saved pivot table appears as a table on your dashboard card. Since there is no chart version of a pivot table, that card has no chart/table switch. Scheduled dashboard reports and alert emails include it as a table too. **Shared insights.** Insights you share publicly show the full table, including the two-row header and the totals column. **The Mitzu agent.** You can just ask for one: "show me subscriptions by plan and sign-up source as a pivot table". The agent will also choose a pivot table on its own when you ask an overall segmentation question with two or more breakdowns, because a grid is easier to read than a bar chart with dozens of groups stacked into it. See the [Analytics Agent](https://docs.mitzu.io/analytics-agent) page for more. ## Limits | Limit | Value | | --- | --- | | Breakdowns you can put across the top | 1 | | Rows shown per page on the insights page | 20 | | Rows in an image or PDF export | 25, then a `+ N more rows` note | | Rows returned from your warehouse | 20,000, then a `Trimmed results` badge appears | | Length of a single breakdown value | 400 characters, then it is shortened | > **INFO** > > Bar and line charts only draw the top 10 breakdown values, to stay readable. That limit does **not** apply to pivot tables — a breakdown with 15 values gives you all 15 rows. --- # Insights Page: Metrics Source: https://docs.mitzu.io/metrics Some questions need more than one insight on the same chart: two funnels next to each other, or a funnel's conversion rate next to the number of users who entered it. **Metrics** are how you build those charts. A metric is a **saved insight reused as a segment in a segmentation**. Instead of picking an event for a segment, you pick a saved insight from the **Metrics** section of the same dropdown, and the segmentation draws that insight. ![image](https://docs.mitzu.io/img/metrics/hero.png) In the chart above, segment `A` is the saved `Trial to paid` funnel and segment `B` counts the unique users who performed `Trial Started`. ## Use cases - Compare two or more funnels side by side, over the same periods and with the same break downs. - Show a funnel's conversion rate next to the volume behind it, to tell a falling rate apart from a falling number of users. - Break a saved funnel down by plan, country or campaign without rebuilding it. - Keep every chart in the workspace on one shared definition of a funnel. ## Which insights can be used as a metric | Insight | Available as a metric | | --- | --- | | Funnel | Yes | | Segmentation with one segment and no formula | Yes | | Segmentation with two or more segments, or with a formula | No | | Retention, journey | No | Two further cases are excluded: - Insights measured as a user list (`Return unique users`, `Return drop-off users`). They return users rather than a value, so there is nothing to plot. - Insights that already use a metric. Metrics cannot be nested. The insight you are currently editing is also left out of its own list. ## Adding a metric to a segmentation 1. Create or open a **segmentation** insight. 2. Open the event dropdown for a segment and go to the **Metrics** section. 3. Select the saved insight. It replaces the event for that segment. 4. Add further segments as usual — more metrics, ordinary events, or a mix of the two. ![image](https://docs.mitzu.io/img/metrics/picker.png) ## What the segmentation controls, and what the metric keeps The segmentation sets the time frame and how the results are sliced. The saved insight sets what is measured. | The segmentation controls | The saved insight keeps | | --- | --- | | Date range | Its events and their order | | Trend granularity, or `Overall` | The filters saved with it | | Filters and break downs you add | Its measurement — conversion rate, count, or time to convert | | Chart type, comparison, post-processing | A funnel's conversion window and attribution | A funnel saved with a one-month window shows six months of weekly conversion rates in a six-month weekly segmentation. Its steps, conversion window and measurement do not change. > **INFO** > > A metric is measured the way it was saved and cannot be re-measured from the segmentation, which is why a metric segment has no aggregation type dropdown. To get the number of converted users from a funnel saved as a conversion rate, save a second funnel with that measurement and use it as a separate metric. ## Editing the saved insight A metric always runs the saved insight's current definition, so changes reach every insight using it. A metric cannot be edited from the segmentation itself. To change one, open the saved insight: find it in the search bar at the top of the page, or on the Insights page under **Assets**, edit it there and save. See [Saved Insights](https://docs.mitzu.io/other_assets/saved-insights). - **Editing** the saved insight — its events, filters or measurement — changes every insight that uses it as a metric, from the next run onwards. Earlier values are not kept. - **Renaming** it, or changing its labels and colours, does not change any values. - **Deleting** it breaks the insights that use it: they report that the saved insight no longer exists, and the segment is shown as invalid. Mitzu does not block the deletion, so check which insights use it first. ## Filters and break downs A metric segment has the same `+ Filter` and `+ Break downs` rows as an event segment. A filter applies to the whole saved insight and reaches every step of a funnel. Filtering a signup funnel by `User Country Code is us` gives that funnel's conversion rate among US users, rather than filtering its first step only. Only properties present on **every** step are offered. A property carried by the checkout event but not by the add-to-cart event is not offered, because filtering by it would drop the earlier step and report the wrong conversion rate. Where a filter cannot be applied, Mitzu names the insight, the property and the event rather than ignoring the filter. Break downs behave the same way. A break down set for the whole insight in the `Break downs` panel also applies to metric segments. ## Charts with more than one unit Metrics bring their own unit: a conversion rate is a percentage, a user count is a plain number, and a time to convert is a duration. A percentage between 0 and 100 and a count in the thousands cannot share a scale. **Dual axes** resolves this. On a trend, the second unit is drawn against its own axis on the right, with its own scale and title: ![image](https://docs.mitzu.io/img/metrics/dual-axes.png) Here `Conversion rate` reads on the left axis and `Unique users` on the right. Dual axes is on by default and applies to line, bar, stacked bar and stacked area charts. - To put every segment back on one axis, turn `Dual axes` off in the [`More` menu](https://docs.mitzu.io/insights-basics#more-options-for-insights). - A third unit has no axis left. Mitzu reports this and suggests a [pivot table](https://docs.mitzu.io/pivot-table), which can hold all of them. - Segments hidden from the legend do not count towards the two. - `Overall` charts and percentage comparison do not split axes; with percentage comparison every value is already a percentage. Durations are shown in the unit that fits their values: seconds, minutes, hours or days. A funnel that converts within hours is shown in hours, one that takes weeks is shown in days. ## Tables and pivot tables Each value carries its own unit (`58.9 %`, `13.3 days`, `409`). Where the segments do not share a measurement, the header reads `Calculation` instead of naming one of them. In a [pivot table](https://docs.mitzu.io/pivot-table), each column header states the measurement of the insight behind it. ![image](https://docs.mitzu.io/img/metrics/pivot.png) On the chart, a metric segment is labelled with the name of the saved insight. Renaming it in the legend changes the label on that chart only. ## Building a metric chart with the agent Ask the [Analytics Agent](https://docs.mitzu.io/analytics-agent) for the comparison and it builds the segmentation: > Compare the signup funnel and the trial funnel by country, as a pivot table, last 3 months. The result is a single chart rather than two funnel insights and a written comparison. The same applies when a funnel has to appear next to something else, as in _"the signup funnel conversion next to the number of trials started"_. If a saved funnel matches the question, the agent uses it, so the chart runs the workspace's own definition. If none matches, it builds the funnel and saves it — a funnel has to be saved before it can be used as a metric — and names the insights it saved. Repeating the question reuses them rather than creating duplicates. In Explore, a metric segment shows the steps of the funnel it runs underneath the event name (`Page Visit → User Signed Up`). --- # Insights Page: User and group focus mode Source: https://docs.mitzu.io/user-and-group-focus [ ![Read insights basics first](https://docs.mitzu.io/img/logo.svg) ### Read insights basics first Before you dive into this part of the documentation, it is important to understand the basics of Mitzu insights. ](https://docs.mitzu.io/insights-basics) ## Use cases Focus on a single user or group when creating your insight. This helps you understand individual B2B and B2C customers. ![image](https://docs.mitzu.io/img/user_and_group_focus/image-1.png) ## Quick start You can reach user and group focus mode in two primary ways. ### List users from an insight First, select the segment panel's `Analyze uniques by` option (left side of the screen). If you have selected `Users` as the `Analyze uniques by` option, you will be taken to **user focus mode**. If you have selected `Groups` as the `Analyze uniques by` option, you will be taken to **group focus mode**. Create an insight as usual and click a point on a trend or overall chart. Click `List users` to see the users who performed the event at that particular point. ![image](https://docs.mitzu.io/img/user_and_group_focus/image.png) By clicking the UserID or GroupID column, you will be taken to **focus mode**. > **NOTE** > > Clicking a user or group in the list opens a new tab in your browser. ### Lookup users and groups We cover this topic on the [Lookup users and groups](https://docs.mitzu.io/user-and-group-lookup) page. ## Prerequisites To use the lookup feature in Mitzu, you must have dimension tables connected to your data warehouse. Dimension tables store information about users and groups, such as their email addresses, names, and other properties. If you need to set up dimension tables, please check out our [integration guide](https://docs.mitzu.io/dimension-tables). ## Features ### Search for user properties One of the extras Mitzu shows in insight focus mode is the user dimension or group dimension properties. ![image](https://docs.mitzu.io/img/user_and_group_focus/image-2.png) You will find the most interesting properties of your users and groups in this panel. You can search for any property by typing the property's name into the search bar. --- # Insights Page: User and groups lookup Source: https://docs.mitzu.io/user-and-group-lookup [ ![Read insights basics first](https://docs.mitzu.io/img/logo.svg) ### Read insights basics first Before you dive into this part of the documentation, it is important to understand the basics of Mitzu insights. ](https://docs.mitzu.io/insights-basics) ## Overview The lookup users and groups feature in Mitzu gives you powerful tools to filter and study how individual users and groups use your website or application. Lookup helps you find specific users and groups with **free-text search** and **filtering by properties**. ## Quick start The lookup users and groups feature is located in the navigation bar at the top left of the page. ![image](https://docs.mitzu.io/img/user_and_group_lookup/image.png) You can switch between the Users and Groups tabs on this page. The Users tab shows all the users in your data warehouse, while the Groups tab shows all the groups in your data warehouse. Start typing any text into the search bar, and Mitzu will look for occurrences of that text in the dimension properties of users and groups. ![image](https://docs.mitzu.io/img/user_and_group_lookup/image-1.png) ## Prerequisites To use the lookup feature in Mitzu, you must have dimension tables connected to your data warehouse. Dimension tables store information about users and groups, such as their email addresses, names, and other properties. If you need to set up dimension tables, please check out our [integration guide](https://docs.mitzu.io/dimension-tables). ## Features This section covers the most important features of the lookup users and groups feature. ### Search Use the free-text search bar to find a specific user or group. Each time you type a new character, Mitzu searches for the next occurrence of that text in the dimension properties of users and groups. Each time you type a new character, Mitzu initiates a search in your data warehouse. ### Select properties By default, you will see the dimension properties that contain the text you typed in the search bar. To add more properties to the search results, select them in the top right corner of the table. ![image](https://docs.mitzu.io/img/user_and_group_lookup/image-2.png) ### Select a user or group Clicking any row in the table redirects you to the insights page in **user focus mode** or **group focus mode**. More about this mode can be found on the [User and group focus mode](https://docs.mitzu.io/user-and-group-focus) page. --- # Dashboards: Dashboards Source: https://docs.mitzu.io/dashboards/edit-dashboard Dashboards group your saved insights, text notes, and dividers into a single live view. Editing is inline: if you can edit a dashboard, you arrange it directly on the page — there is no separate edit mode. Viewers without edit permission see the same page without the editing controls. ![image](https://docs.mitzu.io/img/edit-dashboard/edit_dashboard.png) > **INFO** > > Editing needs a desktop-sized window. On smaller screens the dashboard is read-only and cards stack vertically. ## Use Cases Here are a couple of example use cases for grouping your insights: - **Business problem-based** grouping: examples include a Product Activation dashboard, a User Retention dashboard, and so on. - **Function-based** grouping: examples include an Engineering dashboard, a Sales dashboard, and so on. ## Creating a dashboard - Click **New dashboard** in the Quick Actions section of the home page. - Ask the [Mitzu Agent](https://docs.mitzu.io/analytics-agent) — describe the dashboard you want, and the agent creates it and fills it with insights. - Use **Add to dashboard** on a saved insight (in the insight's menu on the Explore page) or on a chart the agent generated in chat. Both let you pick an existing dashboard or create a new one on the spot. ![image](https://docs.mitzu.io/img/edit-dashboard/add_insight_from_explore.png) Name the dashboard by typing into the **\+ Add Name** field at the top of the page; the **\+ Add Description** field below it takes an optional description. Both save automatically. ## Adding content Click the **Add content** banner at the bottom of the dashboard. While editing, **+** buttons also appear when you hover over the top of the grid, over the gap between two cards, and below a row — each opens the same menu at that position. ![image](https://docs.mitzu.io/img/edit-dashboard/add_content_menu.png) - **Add with AI** — describe an insight and let the agent generate it. Opens the AI sidebar with the dashboard already in context. Available when the AI agent is enabled for your workspace. - **Add new insight** — takes you to the Explore page to build a new insight for this dashboard. - **Add existing insight** — pick one of your saved insights from a list. - **Add text** — adds a markdown text card. - **Add divider** — adds a full-width divider band. ### Insight cards Insight cards show a saved insight as a chart or a table — use the toggle in the card header to switch between the two views. Click the card title to rename it inline. Insights saved with the Pivot table chart type always render as a table. ![image](https://docs.mitzu.io/img/edit-dashboard/card_table_view.png) ### Text cards Text cards hold markdown: headings, bold text, and bullet or numbered lists. Click the edit button in the card header to open the editor, then the check button to save. Summaries written by the AI agent land on dashboards as text cards, so you can edit them like any other text. ![image](https://docs.mitzu.io/img/edit-dashboard/text_and_divider_cards.png) ### Dividers Dividers split the dashboard into sections. A divider always occupies a full row on its own, and you can give it a label — for example "Activation" or "Revenue". Text cards and dividers can also be added and edited by the [analytics agent](https://docs.mitzu.io/analytics-agent) — ask it to add a section header above a chart or to put a note on the dashboard. ## Arranging the layout Cards sit on a grid of rows. A row holds up to four cards; a card can span from a quarter of the row up to its full width, and a card alone in a row always spans the full width. Cards in the same row can have different widths, and rows come in two heights: ![image](https://docs.mitzu.io/img/edit-dashboard/layout_grid.png) - **Move a card**: drag it by the handle at the top center of the card. A blue indicator line shows where the card will land — inside an existing row or as a new row above or below. Dragging near the top or bottom edge of the window scrolls the page. - **Resize width**: drag the handle in the gap between two cards. - **Resize height**: drag the handle below a row. Rows snap between two heights, and all cards in a row share the same height. - Both resize handles also respond to the arrow keys. - Dividers are always full-width and have a fixed height. The card menu's **Move to top** and **Move to bottom** options jump a card across a long dashboard without dragging. ## Card actions Hover over a card to reveal its header controls: a refresh button, the chart/table toggle, and the card menu. ![image](https://docs.mitzu.io/img/edit-dashboard/card_menu.png) - **Start exploring** — opens the insight on the Explore page in a new tab **as it appears on the dashboard**: the dashboard's filters, breakdowns, and overrides are applied to this version. - **Edit original** — opens the original saved insight for editing in a new tab, **without** the dashboard's filters and breakdowns. - **Move to top** / **Move to bottom** — repositions the card. - **Remove** — removes the card from the dashboard. Removing an insight card does not delete the saved insight itself. ## Filters, breakdowns, and overrides The bar below the dashboard header configures every insight on the dashboard at once: ![image](https://docs.mitzu.io/img/edit-dashboard/dashboard_filters.png) - **Filter** — apply property or cohort filters to all insights in the dashboard. - **Break downs** — break every insight down by an extra property. - **Time window** — override the time horizon the insights were saved with. - **Trend type** — override the trend granularity (hourly, daily, weekly, monthly). - **Entity sampling** — trade accuracy for speed on funnel, retention, and journey insights (50–90% volume reduction). - The **save** button stores the current combination as the dashboard's default configuration, so everyone opening the dashboard sees it. Changed filters and overrides take effect when the insights refresh — click **Refresh all**, or rely on scheduling (see below). The **Last refreshed** text shows when the data was last computed. > **INFO** > > Filters, breakdowns, and the time window, trend type, and sampling overrides all apply at the **dashboard level**. The saved insights themselves are not modified — opening one with **Edit original** shows it exactly as it was saved. ## Refreshing - **Per card**: click the refresh button in a card's header. While a query runs, the button turns into a cancel button, and the card shows its state — **Queued**, **Running**, or **Fetching data**. - **Whole dashboard**: click **Refresh all** in the header. While a refresh is running the button becomes **Cancel all**. - **Automatically when outdated**: with an auto-refresh window configured, opening the dashboard re-runs any insight whose cached result is older than the window. The header indicator reads "Refreshed when older than …". - **On a schedule**: the **Schedule** button opens the **Scheduling settings** modal, where you set a refresh time, weekdays, and timezone. You can also subscribe recipients to an emailed report of the dashboard and send a test report. ![image](https://docs.mitzu.io/img/edit-dashboard/scheduling_settings.png) ## AI on dashboards Click the AI button in the dashboard header (**Ask / Edit with AI**) to open the agent sidebar with the dashboard already in context — ask questions about what you see, or describe a new insight for the agent to build and add to the dashboard. ![image](https://docs.mitzu.io/img/edit-dashboard/ask_ai_sidebar.png) The reverse direction also works: any chart or summary the agent produces in a chat has an **Add to dashboard** button in its top corner, which places it on an existing or new dashboard. Charts arrive as insight cards, summaries as editable text cards. ![image](https://docs.mitzu.io/img/edit-dashboard/chat_add_to_dashboard.png) To keep an eye on a dashboard without opening it, click **Monitor** in the header and create a scheduled agent that watches its trends and anomalies. See [Monitoring a dashboard](https://docs.mitzu.io/scheduled-agents#monitoring-a-dashboard) for details. ![image](https://docs.mitzu.io/img/edit-dashboard/monitor_popover.png) ## Header actions Next to **Refresh all**, the header holds: - **Schedule** — opens the Scheduling settings modal. - **Copy link** — copies the dashboard URL. - **Pin** — pins the dashboard to the workspace home page (admins only). - **Favorite** — adds the dashboard to your favorites. - A **Published** indicator appears when the dashboard is publicly shared, and an **Owned** badge when you own it. The **More** (⋮) menu contains the rest: ![image](https://docs.mitzu.io/img/edit-dashboard/more_menu.png) - **Global annotations** — toggle [global annotations](https://docs.mitzu.io/other_assets/annotations) on all charts. - **Consistent colors** — keep the same group in the same color across every insight on the dashboard. - **Reset labels & colors** — clear all series renames and color overrides. - **Publishing** — share the dashboard publicly; see [Publishing and Sharing Dashboards](https://docs.mitzu.io/dashboards/publishing-dashboard). - **Duplicate dashboard** — see below. - **Create snapshot** — see below. - **Export to PDF** — download the dashboard as a PDF document. - **Lock dashboard** — owners can lock a dashboard so only they can edit it. - **Delete dashboard** — owners can delete the dashboard. > **INFO** > > The header collapses automatically as you scroll down to leave more room for the cards, and expands again when you move the mouse over it. ## Duplicating the Dashboard **Duplicate dashboard** opens a dialog where you name the copy. The **Also duplicate insights** checkbox decides how deep the copy goes: - Left unchecked, the new dashboard contains the same insights as the original. Editing an insight in one dashboard also changes it in the other, since they share the saved insights. - Checked, copies of the insights are created for the new dashboard, so changes stay independent of the original. ## Creating a Snapshot **Create snapshot** copies the dashboard with the current time range locked in place. When you return to the snapshot, you see the exact same data. Snapshots are useful for static reports, such as those linked from Notion. ## Renaming, recoloring and hiding chart series If you can edit the dashboard, every chart legend is interactive — exactly like it is on the [Explore page](https://docs.mitzu.io/insights-basics#legend-interactions). Click any legend chip to open its editor, then **rename** the series, **recolor** it, or toggle **Show on chart** off to take it off the card, and click **Apply**. ![image](https://docs.mitzu.io/img/edit-dashboard/legend-rename-recolor.png) These edits are saved on the underlying saved insight, so they persist across refreshes and follow that insight everywhere it is used — including for anyone opening a shared link. Viewers who cannot edit the dashboard see the legend as read-only, with hidden series shown as dimmed chips. Hiding a series redraws the card from its cached result without re-querying your warehouse. On a dashboard you reset series one at a time: open a chip, clear the rename field (the label returns to the original group name), re-select its default color and toggle it back on, then click **Apply**. To clear all renames and colors for an insight in one step, open it on the Explore page and use **Reset labels & colors** there — or use **Reset labels & colors** in the dashboard's More menu to clear every insight at once. --- # Dashboards: Publishing and Sharing Dashboards Source: https://docs.mitzu.io/dashboards/publishing-dashboard Publishing makes a dashboard accessible to anyone with the link and generates links or iframes for embedding it in external websites or applications. Open a dashboard, then choose **Publishing** from the **More** (⋮) menu in the header to open the sharing options. ![image](https://docs.mitzu.io/img/publishing-dashboard/share_dashboard.png) ## Publishing options ### Share dashboard publicly The **Share dashboard publicly** option allows you to make your dashboard accessible to anyone with the link. Once you enable this option, your dashboard becomes publicly accessible, and a **Published** indicator appears in the dashboard header. Published dashboards are read-only for visitors — they see the charts and cards, but none of the editing controls. ## Embeddable link This is a direct link that allows the dashboard to be embedded in other applications or websites. You can copy the URL provided in the field labeled "Embeddable link." ## Embedding the dashboard using an IFrame This option generates an HTML iframe snippet that can be used to embed the dashboard into an external webpage. The code snippet is available in the field labeled "iFrame." Copy and paste the iframe code into the HTML of your website wherever you want the dashboard to appear. ## Public dashboard link You can also share a direct public link to the dashboard that users can visit to view it in a browser. This link is available in the "Public dashboard link" field. Anyone with this link can view the dashboard without needing to log in or have special permissions. --- # Other Assets: Annotations Source: https://docs.mitzu.io/other_assets/annotations ![image](https://docs.mitzu.io/img/application/annotations/image.png) ## Use cases for global annotations Example use cases: - Marking product release cycles - Highlighting critical events in your application's history - Noting the launch of new marketing campaigns or strategies - Naming a period you keep coming back to — a campaign window, a promotion, a fiscal quarter — so you can pick it as a date range instead of retyping the dates ## Add global annotations You have three options for adding global annotations: - On the insights page - On the application home page - By asking the analytics agent ### Adding global annotations from the insights page You can add global annotations on any insight where the X-axis is time. This means you are visualizing a "trend" in the insight. > **INFO** > > You can't add annotations from Journey or Overall Retention insights. Once the trend chart loads, click any point and then click the "Add annotations" button. This opens a new menu where you must type in the name of the annotation. ![image](https://docs.mitzu.io/img/application/annotations/image-1.png) ### Adding global annotations from the Home page You can also add annotations on the home page by clicking the "+ More" button and then selecting "New annotation." ![image](https://docs.mitzu.io/img/application/annotations/image-2.png) ### Adding global annotations with the analytics agent The [analytics agent](https://docs.mitzu.io/analytics-agent) can add an annotation from a plain request — for example "add an annotation for the v2.0 release on 15 March" or "mark the start of the spring campaign on the charts". The agent first proposes the title and the date and time (in GMT), and only saves the annotation once you confirm. If you name an event without saying when it happened, the agent asks for the date rather than guessing one. The agent can also change an existing annotation: rename it, move it to another date, recolor it, or hide and unhide it. It looks the annotation up, shows you its current values next to the change it is about to make, and waits for your confirmation. Deleting an annotation is only possible from the annotation page. ## Editing global annotations All annotations are listed in the homepage assets list. Clicking an item in the list will redirect you to the edit page. ![image](https://docs.mitzu.io/img/application/annotations/image-3.png) On the annotation edit page, you can modify the title, description, start time, end time, and color of the annotation. The selected color is used for the annotation's line and label on every chart and dashboard. New annotations default to dark gray. ## Labelled date ranges An annotation covers a period rather than a moment as soon as you give it an **End time** on the edit page. Leave the end time empty and the annotation stays a single marker, exactly as before. An annotation with an end time behaves differently in two ways: - On charts it is drawn as a shaded band spanning the period, instead of a single dashed line. Hovering the band shows the title and description. Where two bands overlap, their labels are stacked so both stay readable, and a band that starts or ends outside the chart's window is drawn up to the edge of the window. - In any date selector it can be chosen as the date range. An end time with no time of day covers that whole day, so a range from 28 November to 1 December includes all of 1 December. ### Using an annotation as a date range Open the date selector on an insight or on a dashboard. Each of the two date controls has a flag button beside it, listing the annotations that control can express: - The flag next to **Custom date range** lists annotations that have an end time, and scopes to that period. - The flag next to **Since date** lists annotations that mark a single moment, and scopes to everything since then — useful for "how have things gone since the v2.4 release". Each list has its own search. If what you are looking for is in the other list, the empty state says so and names the control to look under. A flag only appears when there is at least one annotation of that kind, so a workspace with no ranges yet sees only the one. The date button then shows the annotation's name rather than the dates, so it stays obvious which period the numbers cover. On a dashboard the tile's subtitle names it too, since a tile has no date button of its own. Because the insight keeps a reference to the annotation, correcting the annotation's dates later updates every insight and dashboard tile that uses it, the next time they load. If the annotation is deleted, or the insight is opened in a workspace that does not have it, the insight keeps working on the dates that were in effect when the range was picked — it shows those dates instead of the name. Hiding an annotation takes its band off charts but keeps it in these lists, marked as hidden. The period is still a useful thing to scope to; the marker is there so you know why no band appears on the chart. ### Labelled date ranges and the analytics agent The agent can create one from a plain request — "mark the Black Friday campaign, 28 November to 1 December" — proposing both the start and the end for you to confirm. It can also scope an insight to a range you already have: ask "how did signups do during Black Friday?" and it finds the annotation by name and builds the trend against that period. The saved insight keeps the reference, so it follows the annotation the same way one you built by hand would. ### Hiding a single annotation Tick the "Hidden" checkbox on the annotation edit page to take that annotation off every chart and dashboard without deleting it. The annotation stays in the assets list and keeps its name, description, date and color, so you can bring it back at any time by unticking the box. Use this when an annotation is still worth keeping as a record but has become noise on your charts. To turn off _all_ annotations for a single chart instead, use the "Global annotations" toggle described below. You can also ask the analytics agent to hide or show an annotation — "hide the Black Friday annotation" — and it applies the change after you confirm. You can also delete the annotation from this page by clicking the actions menu and then selecting "Delete annotation." ![image](https://docs.mitzu.io/img/application/annotations/image-4.png) ## Show/hide annotations on charts and dashboards This toggle is available on both the Dashboards page and the Insights page. ## Annotations in AI chats Charts created by the AI agent do **not** show global annotations by default, so a chat answer stays about the numbers you asked for. Ask for them and the agent turns them on for that chart — for example "show the annotations", "mark the releases on this trend", or "add the event markers". The agent does not carry the setting over to the next chart, so ask again whenever you want annotations on a follow-up insight. As everywhere else, annotations only appear on time-series charts. Retention heatmaps, journey charts, pivot tables and single-number ("total") charts never show them, so asking for annotations on one of those has no visible effect. --- # Other Assets: Cohorts Source: https://docs.mitzu.io/other_assets/cohorts In product analytics, understanding user behavior is pivotal to driving engagement, retention, and overall success. Cohorts let you isolate a specific group of users — or any other entity — and reuse it across your insights. By grouping users based on shared attributes or behaviors, you can tailor your analysis and build more focused, comparable views of your data. ## What are cohorts? A cohort is a saved group of one entity. By default that entity is your users, but if your project has other entities (for example accounts or teams), you can build a group of those too. A group of a non-user entity is called a **collection**, and you will see this wording throughout the app — for example **Create account collection** instead of **Create cohort**. Cohorts and collections live together under **Data → Cohorts & Collections**. There are three kinds of cohort, distinguished by how the members are determined: - **Dynamic** — defined by the criteria of an insight (the events, filters, and date range you built in Explore). The membership is recalculated each time the cohort is refreshed, so it always reflects the current data. - **Imported** — a fixed list of users uploaded from a CSV file. The membership stays exactly as imported until you replace it. - **Lookup** — built from an [entity lookup](https://docs.mitzu.io/user-and-group-lookup) search on entity properties. ### Example cohorts you can create - **Geographic cohorts:** Group users by their location, for example everyone in a specific country or region, to tailor your strategies accordingly. - **Engagement-level cohorts:** Group users by how often they interact with your product within a period. This helps you identify your most active users and understand what keeps them coming back. - **Acquisition cohorts:** Group users by when they first signed up or made a purchase. Analyzing these cohorts over time reveals insights into retention and the long-term value of different segments. - **Behavior-based cohorts:** Group users by a specific action they have taken, such as completing a purchase, sharing content, or reaching a milestone. This helps you understand how different behaviors correlate with retention and satisfaction. ### Benefits of using cohorts - **Enhanced user understanding:** Gain deeper insight into how different groups interact with your product. - **Improved product development:** Identify the features and content that resonate with each group. - **Optimized marketing efforts:** Tailor campaigns to the needs of each cohort. - **Data-driven decisions:** Make informed decisions based on clear insights into user behavior. ## Creating cohorts You can build a cohort three ways: from a chart in Explore, from a CSV file, or from the entity lookup. The [analytics agent](https://docs.mitzu.io/analytics-agent) can also create one for you from a natural-language request. ### From a chart Any data point on an Explore chart can become a cohort of the users behind it. 1. In Explore, build a **Segmentation**, **Funnel**, **Retention**, or **Journey** insight. 2. Make sure an entity is set under **Analyze uniques by** — a cohort always groups one entity, and your users are selected by default. Without an entity the **Create cohort** action stays disabled, with a hint to pick one. 3. Run the insight, then click the data point you want: a bar, a funnel step, a retention cell, or a journey node. 4. In the menu that appears, choose **Create cohort**. For a non-user entity the action is named after that entity — for example **Create account collection**. ![image](https://docs.mitzu.io/img/application/cohorts/create-from-chart.png) 5. Give the cohort a name and click **Create cohort**. You can also pick **Add to existing** to merge the selected users into a cohort you already have. ![image](https://docs.mitzu.io/img/application/cohorts/create-cohort-modal.png) The cohort captures the exact definition behind that data point — the events, filters, breakdown value, and date logic — as a dynamic cohort. > **INFO** > > Cohort creation is available on Segmentation, Funnel, Retention, and Journey charts. For example, clicking a point on a retention curve creates a cohort of the users counted at that step. It is not available on comparison charts, because a comparison point spans two date ranges. ![image](https://docs.mitzu.io/img/application/cohorts/retention-create-cohort.png) ### From a CSV file If you have a list of users exported from another tool, you can upload it as an imported cohort. In the top navigation, open the **Create** menu and choose **CSV Collection**. ![image](https://docs.mitzu.io/img/application/cohorts/create-menu-csv.png) > **INFO** > > Format requirement: the CSV file must contain a single column labeled `user_id`, with each subsequent row containing one unique user\_id. ### From the entity lookup You can also turn an [entity lookup](https://docs.mitzu.io/user-and-group-lookup) result into a cohort. Search users or groups by their properties, then click **Create cohort** above the results to save everyone matching the search. ![image](https://docs.mitzu.io/img/application/cohorts/lookup-create-cohort.png) ## Editing and updating cohorts How you change a cohort depends on its type. ### Dynamic cohorts A dynamic cohort is not a stored user list but the set of criteria that defines the group. You can edit those criteria directly in Explore. Open the cohort from **Cohorts & Collections** and click **Update definition**. This opens the cohort's insight in Explore in cohort-edit mode. ![image](https://docs.mitzu.io/img/application/cohorts/cohort-detail.png) In cohort-edit mode a ribbon replaces the usual insight header. It shows which cohort you are editing, a **Saved / Unsaved** indicator, and three actions: - **Update** writes your changes back to the cohort in one click. - **Save as new** keeps the original cohort untouched and creates a separate one from the current definition. - **Exit** leaves cohort-edit mode and keeps the current chart open in Explore as a regular insight. If you have unsaved changes, it asks you to confirm first. (To go back to the cohort's page instead, click the cohort name in the ribbon.) ![image](https://docs.mitzu.io/img/application/cohorts/edit-cohort-ribbon.png) **Update** stays available as long as your edit still maps cleanly back to a single group — same insight type, same number of segments, an entity set, and no breakdown. If you change the shape of the insight (add a breakdown, drop the entity, or change the structure), **Update** is disabled and a hint points you to the chart instead: click the exact group you want, then choose **Update cohort** from the data-point menu to repoint the cohort at that selection. ![image](https://docs.mitzu.io/img/application/cohorts/update-cohort-from-chart.png) To recalculate a dynamic cohort's size without changing its definition, open the cohort and use the refresh control next to **Size**. ### Imported cohorts You can edit an imported cohort's name and description at any time. To change the members, open the cohort, choose **Update cohort** from the actions menu, and upload a new CSV file. The new list replaces the existing one in place. ![image](https://docs.mitzu.io/img/application/cohorts/imported-cohort-update.png) ### Lookup cohorts To change a lookup cohort, open it and click **View Lookup** to return to the entity lookup with its search applied, then refine the search. ## Using cohorts in insights A saved cohort becomes a reusable filter, so you can narrow any segmentation, funnel, retention, or journey to the users who are in — or out of — that group. Add a filter and pick **Cohort** (it sits at the top of the filter list). Each cohort condition has an operator and one or more cohorts. ![image](https://docs.mitzu.io/img/application/cohorts/cohort-filter.png) - **Membership — `is`** keeps only the users who belong to the cohort. Add several cohorts to one `is` condition to keep users who are in _any_ of them (a union). - **Non-membership — `is not`** removes the cohort's users from the insight. This is the way to exclude a control group, churned users, or an internal/staff cohort. Conditions are combined with **And**, so you can layer them to carve out a precise segment — for example **Cohort `is` Power users** and **Cohort `is not` Trial users** isolates engaged paying users. The same pattern builds frequency or recency bands: keep everyone in the broader cohort and exclude the narrower one. Cohort conditions sit alongside any event or property filter, so you can mix them freely. ## Cohort details You can find the details of a cohort on its page. Navigate to **Cohorts & Collections** under the **Data** menu and click the name of the cohort you want to review. The following information is displayed: 1. Owner 2. Size — with a refresh control for dynamic cohorts 3. Entity 4. Type (Dynamic, Imported, or Lookup) 5. Created at 6. Last counted 7. _Update definition — dynamic cohorts only_ 8. _View Lookup — lookup cohorts only_ 9. _The member list — imported cohorts show their uploaded users_ ## Export cohorts To export a cohort to CSV, open the cohort and click **Export** (or **Export to CSV** in the actions menu). ![image](https://docs.mitzu.io/img/application/cohorts/image-4.png) ## Video tutorial --- # Other Assets: Saved Insights Source: https://docs.mitzu.io/other_assets/saved-insights ## Save an Insight After creating an insight in Explore, you can save it for later. Just give your insight a name and click the save button in the top-right corner. ![image](https://docs.mitzu.io/img/application/saved-insights/image.png) ## View a Saved Insight To view a saved insight, go to the Insights page under the Assets menu and then select the name of the insight you wish to view. ![image](https://docs.mitzu.io/img/application/saved-insights/image-1.png) ## Update a Saved Insight Select the insight you wish to update. This will open it in Explore. From there, you can modify the name, description, or settings of the insight. Once you've made your changes, click the update button in the top-right corner. ![image](https://docs.mitzu.io/img/application/saved-insights/image-2.png) ## Delete a Saved Insight To delete a saved insight, open the insight and select Delete from the top-right menu. ![image](https://docs.mitzu.io/img/application/saved-insights/image-3.png) > **CAUTION** > > A saved funnel can be reused as a segment in other insights. Deleting it is not blocked, but those insights stop working until the segment points to a different insight, so check which insights use it first. See [Metrics](https://docs.mitzu.io/metrics). --- # Data Catalog: Custom Events Source: https://docs.mitzu.io/custom-events Custom events allow you to save frequently used event combinations, making it easier to reuse them without manually selecting events each time. ## Creating a custom event - Navigate to the `Insights` page. - Select the events you want to include in the custom event. - Click on `Save as custom event`. ![image](https://docs.mitzu.io/img/custom%20events/image-2.png) - A modal will appear where you can set the name and description of the custom event. - Save the custom event by clicking the save button. ![image](https://docs.mitzu.io/img/custom%20events/image-3.png) ## Viewing and managing custom events You can manage your custom events in the `Custom events` tab on the `Workspace Settings` page. There, you will find a list of all saved custom events. ![image](https://docs.mitzu.io/img/custom%20events/image-4.png) - Clicking `View definition` will take you to the insights page, where you can use the custom event. - You can update the name and description of a custom event directly from the table. - You can remove a custom event by clicking the delete button. ![image](https://docs.mitzu.io/img/custom%20events/image-5.png) --- # Data Catalog: Dimension Property Catalog Source: https://docs.mitzu.io/dimension-property-catalog The dimension property catalog helps you track and document the properties from all configured [dimension tables](https://docs.mitzu.io/dimension-tables). Dimension properties are added and removed automatically when you add or remove a [dimension table](https://docs.mitzu.io/dimension-tables). You cannot create or remove them manually. ![image](https://docs.mitzu.io/img/dimension-property-catalog/image.png) ## Use cases Maintaining the display name and description fields of the user property records can help you: - map technical abbreviations and raw property names to human-readable labels - explain the meaning of a user property with a description ## All features ### Browsing dimension properties in the catalog The Dimension Properties tab on the catalog page lists every dimension property of the selected workspace, grouped under the dimension table it comes from. Click a table row to collapse or expand its properties. Each dimension table row shows: - the table name in `.` format - the **entity** the table describes, for example Users or Groups. Change it for the whole table on the [dimension tables page](https://docs.mitzu.io/dimension-tables). - how many properties the table has - a checkbox that shows or hides every property of the table at once. It appears half-selected when only some of the properties are visible. Each property row shows: - **Source:** The raw column name of the property. The column names of nested data structures (e.g., struct, JSON) use the `.` format. - **Display name:** The dimension property is referenced with this value on the Insights page, in charts, dashboards and tooltips. - **Description:** The property description can help you find the right property when browsing the Insights page. Click the field to expand it while you type. - **Visible:** Controls whether the property is offered on the Insights page. Clear the checkbox and the property is no longer listed in any dropdown. Insights that already use the property keep working, but they cannot be recreated. - an info icon showing the elapsed time since the property was last found while checking the dimension table for new properties - a **Show values** button, described below Use the search box to filter properties by display name, description or raw column name, the table dropdown to jump to one dimension table, and the entity dropdown to narrow the list to a single entity. Matching properties stay expanded while you search. Click any column header to sort by it, and click it again to reverse the order. The whole catalog is loaded at once, so there is no pagination to page through. ### Updating display name, description To change the display name or description of a dimension property, click the field and enter the desired value. The catalog is updated when you leave the field or press Enter. Press Escape to discard what you typed. Display names must be unique within a workspace. ### Re-indexing dimension properties Dimension tables are indexed once you have configured them. If you have added or removed properties, you may not see the new properties or you may still see the removed ones. To re-index every dimension table, open the actions menu in the top right corner and choose `Re-index all properties`. To re-index a single table, open the menu on its table row and choose `Re-index table`. Either way one [indexing](https://docs.mitzu.io/indexing) task is queued per dimension table, exactly as if you had re-indexed the tables from the [dimension tables page](https://docs.mitzu.io/dimension-tables). You are notified that indexing started; the properties in the catalog update once the tasks finish. ### Removing a dimension table Open the menu on a table row and choose `Remove table` to remove that dimension table, and all of its properties, from the workspace. You are asked to confirm first. This requires the workspace management permission. ### Reviewing dimension property values To inspect the distinct values currently stored for a dimension property, click the `Show values` button in the row of the property. The dialog lists the values that the Insights page will offer as filter options. Click `Reset values` to re-discover the values from the warehouse if the table contents have changed, or change `Property data type` if the property was detected as the wrong type. --- # Data Catalog: Event Catalog Source: https://docs.mitzu.io/event-catalog The Event catalog helps you track and document the events stored in your data warehouse. Events are automatically added and removed when you add or remove an [event table](https://docs.mitzu.io/event-tables). Additionally, you can manually add events from multi-event tables using the Add Events feature. ![image](https://docs.mitzu.io/img/event-catalog/image.png) ## Use cases Maintaining the display name and description fields of the event catalog records can help you: - map technical abbreviations and raw event names to human-readable labels - explain the circumstances of an event with a description ## All features ### Listing events in the catalog The Events tab on the catalog page lists the events stored in the catalog of the selected workspace. The table contains the following columns: - **Source:** The raw event name, as it is stored in the event data table. It is the event table name when the event comes from a single-event table. - **Display name:** The display name used to reference the event on the Insights page and in charts, dashboards, and tooltips. - **Description:** The description can help you find the right event when browsing the Insights page. - **Last discovered:** The elapsed time since the event was last indexed. - **Visibility:** You can control which events are visible on the Insights page. Select the value `Hidden` for an event and you won't see it listed in any dropdowns. Insights that already use this event won't break, but they cannot be recreated. - **Manage properties:** Links to the [Event property catalog](https://docs.mitzu.io/event-property-catalog) with a predefined filter for this event. You can filter the table using the free text search input or by selecting an event from the dropdown. If you use the free text search, the list updates with the most recent results as you type your search expression. Click the `Reset filters` button next to the search bar to clear all filters. Only 20 events are shown per page. To see the remaining events, narrow the results with a search expression or browse the other pages in the pagination bar. The results are sorted in alphabetical order by event source. ![image](https://docs.mitzu.io/img/event-catalog/image-1.png) ### Adding events from multi-event tables You can manually add events to your catalog from multi-event tables. This is useful when you want to add specific events that exist in your multi-event tables but haven't been automatically indexed yet. You can add one or more events at a time from a single multi-event table. To add events: 1. Navigate to the Events tab on the catalog page. 2. Click the `Add events` button in the toolbar. 3. In the modal that appears: - Select a multi-event table from the **Source multi event table** dropdown. The dropdown is searchable, making it easy to find the table you need. Only event tables with event name columns are supported. - Enter one or more event names in the **Event names** field. You can type multiple event names and press Enter or comma to add each one as a tag. 4. Click `Confirm` to add the events to your catalog. ![image](https://docs.mitzu.io/img/event-catalog/add-event-modal.png) The events will be immediately available in your catalog and can be used in insights, charts, and dashboards. Each event will appear in the events table in the format `
.` in the Source column. Make sure their properties are re-indexed. ### Updating display name, description To change the display name or description of an event catalog record, click the input field and enter the desired value. The catalog is updated once you stop typing. ### Re-indexing all events Event tables are indexed once you have configured them. If you have added or removed events, you may not see the new events or you may still see the removed ones. To re-index all events, click the `Re-index all events` button to start the [indexing process](https://docs.mitzu.io/indexing). --- # Data Catalog: Event Property Catalog Source: https://docs.mitzu.io/event-property-catalog The event property catalog helps you track and document the properties of all events in your data warehouse. Event properties are added and removed automatically when you add or remove an [event table](https://docs.mitzu.io/event-tables). You cannot create or remove them manually. ![image](https://docs.mitzu.io/img/event-property-catalog/image.png) ## Use cases Maintaining the display name and description fields of the event property records can help you: - map technical abbreviations and raw property names to human-readable labels - explain the meaning of an event property with a description ## All features ### Listing event properties in the catalog The Event Properties tab on the catalog page lists the event properties stored in the catalog of the selected workspace. All event properties are listed only once, even if multiple events have properties with the same name. The table contains the following columns: - **Source:** This is the column name of the event data table. The column name uses the `.` format if the event property is a nested data structure (e.g., struct, JSON). - **Display name:** The display name used to reference the event property on the Insights page and in charts, dashboards, and tooltips. - **Description:** The description can help you find a suitable event when browsing the Insights page. - **Visible:** You can control which event properties are visible on the Insights page. Clear the checkbox for a property and you won't see it listed in any dropdowns. Insights that already use this field won't break, but they cannot be recreated. - **Events:** Shows which events have this property. Only the first five events are listed; click `Show N more` to open a searchable list of every event carrying the property. Clicking an event, either in the column or in that list, narrows the page to the properties of that single event. The column is hidden once a single event is selected, since every row would then repeat that same event. You can filter the table using the free text search input or by selecting an event in the `All events` dropdown. Both filter the list as you type or select, without reloading the page. Click `Reset filters` next to the dropdown to clear them all at once. Clicking the column headers sorts the list, and every property is listed on one page. ### Updating display name, description To change the display name or description of an event property catalog record, click the input field and enter the desired value. The catalog is updated once you stop typing. ### Refreshing filter values and changing property data types You can also refresh the filter values in the Event Properties tab. Click the `Show values` button at the end of a property's row. The stored values belong to one property of one event, so the button is only active when the property resolves to a single event: either the property was discovered on exactly one event, or you selected an event in the `All events` filter. Otherwise the button is greyed out and its tooltip asks you to select a single event first. ![image](https://docs.mitzu.io/img/event-property-catalog/image-1.png) Here, you can refresh the possible filter values. You can also change the data type of any property. > **WARNING** > > Changing the data type may cause the generated SQL queries to stop working. Proceed only if you are sure the data type change is necessary. --- # Workspace Settings: Generic settings Source: https://docs.mitzu.io/generic-settings The **Generic settings** tab collects the everyday workspace-level actions: naming the workspace, flagging it as the default landing workspace for new teammates, clearing caches, and — as a last resort — deleting the workspace. ![image](https://docs.mitzu.io/img/application/general-settings/image.png) ## Workspace details - **Workspace name** (required): shown in the workspace switcher and anywhere the project is referenced. Keep it short and specific (for example `Marketing Analytics`, `EU Prod`). - **Description** (optional): a short summary that helps new members orient themselves — what the workspace is for, which team owns it, and anything else worth flagging. Both fields autosave as you type. ## Home banner Admins can pin a curated **banner** to the top of this workspace's home page — handy for announcements, maintenance windows, onboarding tips, or links the whole team should see. The banner spans the full width of the home page and sits above every other widget. Everyone with access to the workspace sees it; only **Workspace Admins** can edit it (the Generic settings tab is admin-only). ![image](https://docs.mitzu.io/img/home-banner/banner.png) Configure it from **Generic settings → Home banner** using these fields: - **Icon**: pick an icon from the icon picker. It renders on the left of the banner in a fixed-width, colored tile. - **Color**: a shade from Mitzu's chart palette. It tints the icon tile. - **Title** (required): the headline shown in bold. - **Description** (optional): a short supporting line shown under the title. - **Call to action link** (optional): a URL. When set, the banner shows an open-in-new icon on the right that links out to it in a new tab. Use the **Banner visible** toggle to show or hide the banner without losing its content — when it's off (or no banner has been saved), nothing appears on the home page. Click **Save banner** to apply your changes; they take effect on the home page immediately. ![image](https://docs.mitzu.io/img/home-banner/settings.png) ## Default workspace - **Set as default workspace**: new teammates land in the default workspace the first time they sign in. Each organization has exactly one default at a time — clicking the button on a different workspace moves the flag. When this workspace _is_ the default, a blue "This is the default workspace" banner appears under the button. ## Refresh metadata cache Mitzu caches schema, table, and column metadata so the UI stays responsive. Use **Clear cache** after you've: - Added or removed tables/columns in your warehouse and they aren't appearing in dropdowns. - Updated permissions for the Mitzu warehouse user and expect new objects to become visible. - Changed catalog configuration and want to force a re-fetch on the next use. Clearing the cache only invalidates metadata — dashboards, saved insights, and cohorts are **not** affected. ## Delete workspace Permanently removes this workspace and everything inside it: - Event and property catalog - Saved insights - Saved dashboards - Cohorts - All workspace settings (entities, connection, indexing, etc.) A confirmation dialog protects against accidents. **This action cannot be undone** — if you want to temporarily hide a workspace, unassign members or rename it instead. Changes are saved automatically (except the destructive actions above, which require explicit confirmation). --- # Workspace Settings: Connection settings Source: https://docs.mitzu.io/connection-settings ## Overview To use Mitzu, you must configure the connection to your data warehouse. > **INFO** > > Mitzu will never copy or modify any data in your data warehouse. That said, we strongly recommend creating a dedicated read-only user for Mitzu in your data warehouse. ![image](https://docs.mitzu.io/img/connection-settings/image.png) Mitzu can be configured to work with several data warehouse types. See the [warehouse integrations](https://docs.mitzu.io/warehouse-integrations) page for detailed instructions. Don't have a warehouse yet? You can also [upload a CSV file](https://docs.mitzu.io/uploaded-csv) directly to get started. ## Video tutorial A video showing how to set up your workspace in 5 minutes. --- # Workspace Settings: Event tables Source: https://docs.mitzu.io/event-tables Event tables are tables in the data warehouse that contain user events. You must select specific columns for different purposes for each event table. You can select a column for these purposes: - **Identifier columns** - **User ID Column** (mandatory): the column of the event table that contains the user ID. - **Entity ID columns**: for each entity you've added on the [Entities](https://docs.mitzu.io/entities) page, you can select the column that contains the entity ID. - **Event time columns** - **Event time Column** (mandatory): the column of the event table that contains the event time. - **Date Partition Column** (optional): queries can take a long time on large tables. To speed them up, some data warehouses support partitioning. If you've partitioned the table by event time, configure the partitioning column here. - **Other settings** - **Event Name Column** (optional): if your event table contains multiple events, set the column that distinguishes them. - **Ignore Columns** (optional): you can configure columns of the event table that you want Mitzu to ignore. Mitzu won't index or list these fields on the `Insights` page. ## List of event tables You can browse the already configured and recently added event tables in a table that shows all configured columns for each event table. The list has one column per setting: `Schema`, `Table`, `Event time settings`, `Identifiers`, `Event name`, `Other settings` and `Status`. Every column can be sorted, and the row under the header filters the list — the first six accept free text, while `Status` offers a fixed set of options such as `Errors` or `0 events found`. Each identifier is listed with its entity's icon, and columns holding several values (identifiers, other settings) show the first two with a `+N more` button. Click that button to keep the row expanded; click it again to collapse it. While a table is being indexed, its `Status` cell shows a spinner together with the progress and the estimated time remaining. The column refreshes on its own, so you can leave the page open and watch indexing finish. > **WARNING** > > The content of this list changes as you add, remove, or configure event data tables. It only shows the current state, and you must click the `Save` button to persist your changes and index the updated tables. ![image](https://docs.mitzu.io/img/event-tables/image.png) ## Table definition Every row in the list shows a small info icon to the left of the table name. Click it to open the **Table definition** modal, which shows the `CREATE` statement Mitzu read from your warehouse for that table, syntax highlighted and with a copy button. Mitzu stores the definition while indexing a table. If it has not read the definition yet, the modal says so and offers a `Fetch definition` button that queries the warehouse there and then and saves the result — no re-index needed. When a definition is already stored, the button reads `Refresh definition` and re-reads it, which is useful when the table changed since the last index. Not every warehouse exposes the `CREATE` statement of a table or a view. When Mitzu cannot read one, the modal says so — as text if nothing is stored yet, or as a notification if a definition is already stored, which is always left untouched. > **NOTE** > > Only workspace administrators can open the table definition or fetch it from the warehouse. ## Adding new event table(s) Click the `Add event tables` button to open a modal where you can select the event tables to add. ![image](https://docs.mitzu.io/img/event-tables/image-1.png) First, pick the table type. If each event table contains only a single event, choose `Single`. If the event tables contain multiple events distinguished by a column containing the event name, choose `Multi`. Hovering the selector explains the difference. The modal loads the available schemas from the configured data warehouse connection. Once loading finishes, select the schema containing the event table(s) you want to add. After you pick a schema, Mitzu loads every table name in it. You can then choose one or more tables to add, or pick the bold `Add all tables` option to select them all (where `` is the number of tables in the schema). Once the tables are selected, you can configure the fields for: - User ID column (mandatory) - Event time column (mandatory) - Date partition column (optional) - Event name column (visible and mandatory only for the `Multi` table type) For each column, type the column name or select it from the dropdown. If you're unsure what columns are available, open any of these dropdowns and pick `Fetch columns` at the top of the list. It loads the available columns for all selected tables and populates every column dropdown with the most common column names. > **WARNING** > > Fetching columns can take a long time if too many tables are selected. Click the `Add tables` button to close the modal and add the new tables with the selected fields. > **WARNING** > > If some tables are missing from the list and you recently updated the connection settings or the Mitzu permissions in your data warehouse, click the refresh button next to the tables dropdown to reload the list of tables in that schema. ## Configure event tables Toggle the checkboxes in the list to select one or more tables to configure, then click the `Configure tables` button to open a new modal. ![image](https://docs.mitzu.io/img/event-tables/image-2.png) For each column, type the column name and select it from the dropdown. If you're unsure what columns are available, click the `Fetch columns` button. It loads the available columns for all selected tables and populates the dropdown fields with the most common column names. > **WARNING** > > Fetching columns can take a long time if too many tables are selected. Click the `Configure` button to update the list of event tables. > **WARNING** > > Newly added and reconfigured event tables are not indexed automatically. You need to select them and click the `Index selected` button to index them. ### Display name prefix The **Display name prefix (optional)** field at the bottom of the modal adds a fixed label to the start of the display name of events that are newly indexed from the selected table(s). ![image](https://docs.mitzu.io/img/event-tables/display-name-prefix.png) For example, with a prefix of `Web` , a newly indexed `page_visit` event appears as `Web Page Visit` on the `Insights` and `Data catalog` pages. This is useful when several event tables produce events with the same names — prefixing keeps them distinguishable. The prefix is applied only while indexing, and only to events that don't already have a display name. Events that already exist or that you've manually renamed keep their names. The prefix is limited to 20 characters. Leave the field empty (the default) to keep the current display names. > **INFO** > > If two newly indexed events end up with the same prefixed display name, Mitzu automatically appends a number to keep them unique (for example `Web Page Visit`, `Web Page Visit (2)`). ## Enable / Disable You can disable a table if you don't want to use it as an event table. To do so, toggle the checkbox of an event table and click the `Enable / Disable` button. > **WARNING** > > When a table is disabled, all events and catalog records belonging to that table are removed. ## Re-indexing If the content of your table changes (for example, a new event in a multi-event table, new event property columns, etc.), you need to re-index it. First, select one or more event tables by toggling the checkboxes, then click the `Re-index selected` button to start indexing. You can track the progress and see the result below the table. You can read more about this process on the [indexing](https://docs.mitzu.io/indexing) page. ## Remove an event table You can remove an event table if you no longer need it. > **WARNING** > > All saved insights that use an event from the removed event table will break. --- # Workspace Settings: Dimension tables Source: https://docs.mitzu.io/dimension-tables ## Overview Dimensions are a common concept in data analytics. By dimensions, we usually mean a set of properties that a user, product, or session may have. Examples of user properties: - Country of origin - Email addresses - Primary email address - Phone number - Is paying - First event time - Last event time - Sign-up time - etc. In addition to user profiles, you can configure a dimension table for any entity you've added on the [Entities](https://docs.mitzu.io/entities) page. Most companies store these properties in their data warehouse in separate tables, where each row holds information about a single entity. Later, during analysis, they join these tables to the event tables for further filtering and segmentation. Mitzu supports joining one or more dimension tables to event tables. ## Add new dimension table(s) Click the `Add dimension table` button. ![image](https://docs.mitzu.io/img/dimension-tables/image.png) The modal loads the available schemas from the configured data warehouse connection. Once loading finishes, select the schema containing the table(s) you want to add. After you pick a schema, Mitzu loads every table name in it. You can then choose one or more tables to add, or pick the bold `Add all tables` option to select them all (where `` is the number of tables in the schema). Once the tables are selected, you can choose the entity and enter the `Primary key column`. For the `Primary key field`, set the column that can be used as a joining key when joining the event tables. For example, if you've selected the `User` entity, set the column that contains the user ID. Type the column name into the input and select it from the dropdown. If you're unsure what columns are available, open the `Primary key column` dropdown and pick `Fetch columns` at the top of the list. It loads the available columns for all selected tables and populates the dropdown with the most common column names. > **WARNING** > > Fetching columns can take a long time if too many tables are selected. Click the `Add tables` button to close the modal and add the new tables configured with the selected entity and primary key. ## Configure dimension tables ![image](https://docs.mitzu.io/img/dimension-tables/image-2.png) You can update the `Entity` and the `Primary key column` in the table. Optionally, you can set `Ignored fields` to list the columns you don't want indexed. The **Display name prefix (optional)** field adds a fixed label to the start of the display name of dimension properties that are newly indexed from this table. For example, with a prefix of `User` , a freshly indexed `country_code` property appears as `User Country Code`. Existing and manually renamed properties are left unchanged, and the prefix is limited to 20 characters. Leave it empty to keep the default display names. Changes are saved automatically. > **WARNING** > > Newly added and reconfigured event tables are not indexed automatically. You need to select them and click the `Index selected` button to index them. ## Table definition Every row in the list shows a small info icon to the left of the table name. Click it to open the **Table definition** modal, which shows the `CREATE` statement Mitzu read from your warehouse for that table, syntax highlighted and with a copy button. Mitzu stores the definition while indexing a table. If it has not read the definition yet, the modal says so and offers a `Fetch definition` button that queries the warehouse there and then and saves the result — no re-index needed. When a definition is already stored, the button reads `Refresh definition` and re-reads it, which is useful when the table changed since the last index. Not every warehouse exposes the `CREATE` statement of a table or a view. When Mitzu cannot read one, the modal says so — as text if nothing is stored yet, or as a notification if a definition is already stored, which is always left untouched. > **NOTE** > > Only workspace administrators can open the table definition or fetch it from the warehouse. ## Custom join condition By default, Mitzu joins a dimension table to an event table on the dimension table's `Primary key column`. For most dimension tables this is what you want. Some dimension tables, however, hold a separate row per entity **per date** (for example a `daily_user_state` table with `user_id` + `date`). Joining only on `user_id` duplicates the events. To handle these cases, the **Configure dimension table** modal exposes an optional `Custom join condition` text area: - Reference event-table columns as `__evt_` and dimension-table columns as `__dim_`. - Standard comparison and arithmetic operators are supported, as are SQL functions such as `date(...)`. - Both sides of the join must appear: at least one `__evt_*` and one `__dim_*` placeholder. - The expression is parsed and validated before saving — invalid syntax or unknown placeholders surface an error in the modal. The most common use is matching event timestamps against a dimension date column: ``` date(__evt_event_time) = __dim_date ``` Both `=` and `==` are accepted for equality — Mitzu normalizes them to the same operator internally. Leave the field empty to keep the default primary-key join. > **TIP** > > Custom join conditions are an advanced setting. Only use them when the dimension table contains time-varying rows that would otherwise duplicate events. ## Removing user profile tables If you decide to remove a dimension table, select it with the checkbox in the table and click the `Remove tables` button. This removes the table from the list of tables and from the user property catalog. All saved insights that use one of the removed tables will break. --- # Workspace Settings: Entities Source: https://docs.mitzu.io/entities In your data model, an event can be enriched with additional information — for example, properties about the user, the user's session, their team, their organization, and so on. These additional sets of properties are called entities. You can list the entities of your data model in the `Entities` tab. ![image](https://docs.mitzu.io/img/entities/image.png) ## Update entity The table contains all of the configured entities. You can update an entity's name or icon by entering a different name or selecting a different icon. Changes are saved automatically. ## Add new entity Click the `Add entity` button to create a new entity. The new entity is added to the table, where you can set its display name and select its icon. ## Remove an entity To remove one or more entities, toggle the checkboxes next to the entities you want to remove and click the `Remove entities` button. > **WARNING** > > The User entity cannot be removed. > **WARNING** > > Entities referenced by either an event data table or a dimension data table cannot be removed. ## Video tutorial A video showing how to set up your entities and dimension tables in 7 minutes. --- # Workspace Settings: Insight settings Source: https://docs.mitzu.io/insight-settings The **Insight settings** tab controls how new insights behave in this workspace — how dates are shown, how funnels and retention count events, and how Mitzu talks to your warehouse from the Insights page. Changes apply to every member of the workspace and are saved automatically. > **INFO** > > Performance-related options (sampling, resolution, "first period" filter) now live on the [Performance settings](https://docs.mitzu.io/performance-settings) tab. AI options live on the [AI settings](https://docs.mitzu.io/ai-settings) tab. ![image](https://docs.mitzu.io/img/application/insight-settings/image.png) ## Workspace display Presentation defaults applied to every insight, chart, and dashboard. - **Default entity**: The entity (for example User, Account, Session) that insights count by default. The Insights page uses this when an insight doesn't specify one. You can add or rename entities on the [Entities](https://docs.mitzu.io/entities) tab. ## Default date range Controls the **end date** that every new insight starts with. The start date is always expressed relative to this end date (for example "last 30 days"). - **End date mode**: How Mitzu picks the end date for new insights. | Mode | Use it when | | --- | --- | | **Start of the current day** | Your pipeline lands yesterday's events once per day. Picks today at 00:00. | | **End of the current day** | Events are loaded near real-time or in frequent batches. Picks today at 23:59:59. | | **Now** | Events are loaded near real-time **and** some events may be stamped with future timestamps that you want filtered out. | | **Custom date** | The dataset is frozen (for example a discontinued project). Use with `Fixed custom end date` below. | - **Fixed custom end date**: Pins every new insight to this exact date. Only enabled when **End date mode** is `Custom date`. ## Funnel & retention defaults How Mitzu matches a user's events to each step of a funnel or retention chart. - **Conversion attribution** (funnels): - `First`: only the user's first matching event at each step counts. Fast, conservative, recommended for most use cases. - `Every`: every matching event at every step counts. More permissive (and more expensive to compute). - **Retention attribution** (retention): - `First`: only the first retaining event per user in each period is counted. - `Every`: every retaining event is counted. - **Loose timestamp comparison** (formerly "Allow same-timestamp conversions"): allow a **1 minute grace period** when comparing the order of events, so a step can happen up to 1 minute before the previous step and the user is still counted as converted. Pick which insight types it is turned on for by default: - `Off`: no grace period anywhere. - `Funnels & Journey only`: on for funnels and journeys, off for retention. - `Retention only`: on for retention, off for funnels and journeys. This is the default for new workspaces. - `All`: on for funnels, journeys, and retention. This only sets the default. Every chart has its own **Loose timestamp comparison** checkbox in the conversion window menu, which overrides the workspace setting. Switching a chart to another insight type re-applies the workspace default for that type. > **WARNING** > > If the **same** event is used at every step of a funnel or retention chart, one event can satisfy every step at once, inflating conversion. On a retention chart whose two steps are identical this makes `Day 0` / `Week 0` / `Month 0` **100%**, because the initial event already counts as the return — see [what it does to period 0](https://docs.mitzu.io/retention#loose-timestamp-comparison). Keep this off for insight types whose steps use the same event. - **Retention base**: `Eligible users` (the default) counts a user towards a retention period only once that period has fully elapsed for them, so in 7-day retention a user who signed up two days ago is left out of the Day 7 base instead of counting as not returned. `All users` keeps every user in the base for every period. Each chart can override it in its Retention period menu. See [Retention base](https://docs.mitzu.io/retention#retention-base). - **Show incomplete periods**: retention periods that are still in progress are drawn dotted and marked with `*` by default. Turn this off to leave them out of new retention charts; each chart can override it in its More menu. See [Incomplete periods](https://docs.mitzu.io/retention#incomplete-periods). ## Filtering & chart defaults Small behavioral defaults applied to every new chart. - **Case insensitive filtering**: `Chrome`, `chrome`, and `CHROME` match the same events. When this is off, filters are case-sensitive. - **Fill missing values with zero**: shows a zero bar instead of an empty slot for categories that produced no events. **Applies to segmentation charts only.** - **Any event (experimental)**: adds a synthetic **"Any event"** entry to your event catalog that matches every event in the workspace. Useful for cross-event funnels like _"did anything after sign-up"_. Recommended only when you have a single event table — with many event tables, "Any event" expands to a large OR-query that can be slow. ## Querying & monitoring Controls how Mitzu runs queries against your warehouse from the Insights page. - **Gather cluster info**: collects cluster status alongside each query to help troubleshoot slow queries and visualize progress. Only has an effect on Snowflake, Databricks, BigQuery, and Trino. Changes are saved automatically. --- # Workspace Settings: Performance settings Source: https://docs.mitzu.io/performance-settings The **Performance settings** tab speeds up funnels, retention, and journey insights on high-volume projects by reducing how many events and entities Mitzu processes — and by applying query-friendly defaults to new charts. Use this tab when insights run slowly, your warehouse is under load, or you routinely hit query time limits. Changes apply workspace-wide and are saved automatically. ![image](https://docs.mitzu.io/img/application/performance-settings/image.png) ## Sampling & resolution Two knobs reduce event/user volume in very different ways. They are independent and can be combined. | Setting | What it reduces | Effect on results | | --- | --- | --- | | **Event resolution** | Collapses many events into one per user per time bucket (hour/day) | All users are still counted; event counts become "at least one" per bucket | | **Automatic entity sampling** | Drops a random subset of entities (users, accounts, sessions...) | Fewer entities counted; results are statistically scaled back up | ### Event resolution Groups high-frequency events into a single event per user per hour or per day. Funnels and retention read far fewer rows, so they calculate faster. Every user is still in the result — you only lose sub-hour or sub-day granularity on the event stream. When to use it: - Users generate many events of the same type in a short time (think scroll, heartbeat, tick events). - You don't need to distinguish "5 pageviews in a minute" from "1 pageview" in your funnel logic. Choose **hour** for the lightest compression that still preserves intraday analysis. Choose **day** for maximum speed on daily funnels and retention. ### Automatic entity sampling Samples entities — users, sessions, accounts, or whatever your default entity is — across **every** funnel, journey, and retention insight in the workspace. The label reads as a volume reduction, e.g. _"90% volume reduction"_ means Mitzu keeps roughly 10% of entities. Final aggregates are multiplied back up to approximate full-population numbers. Trade-off: faster queries at the cost of precision. Small segments may become invisible if the sample rate is aggressive. Recommended starting point on large warehouses: - First, try **50% volume reduction** and compare results with the non-sampled baseline. - Only go higher if the speed-up justifies the precision loss. ### Warehouse sampling ratio Use this **only** when your warehouse already holds a pre-sampled subset of production events — for example, a pipeline that writes 1 of every 5 events for cost reasons. It tells Mitzu what percentage of source events actually reached the warehouse so final counts can be reconstructed. - Enter a value between `0` and `100` (percent). - Mitzu multiplies every count by `100 / value` in supported final aggregations. - **Example:** the warehouse holds 20% of events → set to `20` → Mitzu multiplies counts by `5`. - Leave empty when the data is **not** pre-sampled. Most workspaces should leave this empty. > **NOTE** > > Unlike **Automatic entity sampling**, this setting does **not** add sampling to the queries Mitzu generates. It compensates for sampling that already happened upstream. ## Query optimization Defaults that reduce warehouse load for new charts. - **Apply first period filter by default**: turns on the "first period filter" for every new funnel and retention chart. The filter restricts the analysis to users whose **first** matching event falls inside the chosen date range, which is usually what you want and is dramatically cheaper to compute on high-frequency events. Strongly recommended for high-volume projects. Can be turned off per chart. Changes are saved automatically. ## Choosing the right lever | Symptom | First thing to try | | --- | --- | | Funnels scanning millions of identical events per user | **Event resolution: hour** | | Warehouse queue saturated, you need blanket speed-up | **Automatic entity sampling: 50%** | | You already pre-sample upstream and counts look too low | **Warehouse sampling ratio** | | New charts routinely time out or OOM | **Apply first period filter by default** | --- # Workspace Settings: AI settings Source: https://docs.mitzu.io/ai-settings The **AI settings** tab controls how the Mitzu AI assistant (the chat agent that answers questions, builds charts, and reads your catalog) behaves inside this workspace. There are two knobs: 1. A persistent **Custom instructions** entry that is included in every conversation — your workspace's "system prompt." 2. Whether the agent is allowed to **search the web** in real time while answering. Organizations that have the option enabled also get a third section, **Anthropic credentials**, for running the AI features on their own Anthropic account. Mitzu always picks the model that powers the agent, routing each request to the best-fit Claude model for the task, unless your organisation has set its own model id under **Anthropic credentials**. Only **Workspace Admins** can change these settings. The AI settings tab itself only appears when the AI feature is enabled for your organization — or, on a self-hosted deployment without a Mitzu-wide Anthropic key, when your organization is allowed to bring its own key (see **Anthropic credentials** below), so that the key can be entered in the first place. ![image](https://docs.mitzu.io/img/application/ai-settings/image.png) ## Custom instructions Standing context added to **every** AI conversation in this workspace. Use it to teach the agent domain language, reporting conventions, and business rules that aren't obvious from the catalog alone. ### What to put here Good custom instructions tend to cover: - **Terminology and acronyms.** _"Refer to monthly recurring revenue as MRR."_, _"In this workspace, 'deal' always means a closed-won opportunity."_ - **Calendar conventions.** _"Our fiscal year starts in April."_, _"The business week runs Monday–Sunday."_ - **Defaults for ambiguous filters.** _"Treat the `trial` property as `false` unless the user explicitly asks about trials."_, _"Exclude internal test accounts (user\_email ending in `@mitzu.io`) by default."_ - **Reporting style.** _"Prefer weekly granularity unless the user asks for daily."_, _"Always break down by country when a geographic cut is possible."_ - **Safety rails.** _"Never join raw payment tables into public dashboards."_ ### What **not** to put here - Secrets, API keys, or credentials — the prompt is visible to every workspace admin. - One-off questions — use a normal AI chat for those. - Giant rulebooks — the prompt is capped at **4,000 characters**. The counter under the box turns red when you go over, and the **Save instructions** button is disabled until you trim it. ### Saving Edits to the Custom instructions are **not** auto-saved. Click **Save instructions** to persist your changes; you'll see a success notification at the top right of the screen. Closing the tab with unsaved edits discards them. ### How it composes with other context The Custom instructions are one layer of context the agent receives. The full order is: 1. Mitzu's built-in system prompt (how the agent reasons, which tools it can call). 2. **Your workspace Custom instructions** (this setting). 3. The user's individual message in the chat. Instructions at lower layers can refine but not override the ones above. For example, if the Custom instructions say _"always exclude test accounts"_, a user can still ask _"include test accounts this time"_ — the workspace default is a default, not a hard rule. ## Web search Off by default. When enabled, the AI agent can use Anthropic's built-in **WebSearch** tool to look up information on the public internet while answering — useful for questions that depend on current external context (industry benchmarks, public company news, third-party documentation). Things to know before flipping it on: - The agent decides what to search for. To do its job it will send the user's question (and any context it considers relevant — including text from your catalog or chat history) to a third-party search provider. - Web results are untrusted content. Treat anything the agent quotes from the web the same way you'd treat a random page on the internet, not authoritative workspace data. - Responses become non-deterministic. The same question can return different answers as the underlying web pages change. - Only **Workspace Admins** can change this setting, and the toggle applies to every AI conversation in the workspace until it's turned off. If your workspace handles sensitive data or you need reproducible answers, leave it off. ## Anthropic credentials By default every AI and agentic feature runs on Mitzu's own Anthropic account, and your usage counts against the AI query allowance of your plan. If you would rather be billed by Anthropic directly, Mitzu can enable this for your organization — contact [support@mitzu.io](mailto:support@mitzu.io) to have it turned on. Until it is enabled, the **Anthropic credentials** section at the bottom of this tab shows a note telling you to contact support; the key, auth method, host and model fields only appear once it is on. Once enabled, the section takes four values, in this order: - **Host** — optional. The base URL requests are sent to, for an Anthropic-compatible gateway or proxy. It must be an `https://` URL and may include a path, e.g. `https://gateway.example.com/anthropic`. Mitzu appends `/v1/messages` itself, so do not include `/v1` or `/v1/messages`. The host must resolve to a globally routable address; loopback, private, carrier-grade NAT and other non-public hosts are rejected. Leave it empty to call the Anthropic API directly. - **API key** — an Anthropic API key from your own Anthropic account. It is never shown again after you save it; the field only tells you whether a key is currently saved. It is always stored encrypted at rest — a deployment without secret encryption configured refuses to store it at all. - **Auth method** — how the key is sent to the host. **API key header** sends it as `x-api-key`; it is the default and what `api.anthropic.com` expects. **Bearer token** sends it as `Authorization: Bearer`, for gateways that authenticate that way. Switching the method does not require retyping the key. - **Model** — by default Mitzu picks the model, and the field shows the exact id it prefers (`claude-sonnet-5`) greyed out so you know what to expect. Tick **Use a custom model id** to send your own id instead, for gateways that expose Claude under their own names, e.g. `eu.anthropic.claude-sonnet-5`. A custom id is used for every AI call of the organization, including the lightweight tasks Mitzu would normally run on Haiku. Untick the box to go back to Mitzu's default; the tooltip next to the field always names it. Things to know: - The credentials are **organization-wide**, not per workspace. Every workspace of the organization uses them. - They cover **every** AI call Mitzu makes for your organization: the chat agent, its subagents, the configuration agent, scheduled agent runs, and the summaries and trigger evaluations behind scheduled-agent emails. - While a key is set, the Mitzu AI query allowance is not enforced and the usage widget is hidden — you pay Anthropic for the tokens instead. Note that if the option is later switched off mid-period, the queries you ran on your own key do count towards the allowance again. - Only **Admin** users can view or change this section. - To save a new **Auth method**, **Host** or **Model** without retyping the key, leave the API key field empty and click **Save credentials**. The very first save must include a key. - **Remove key** deletes the stored credentials and moves every AI feature back onto Mitzu's account, with the plan allowance applying again. ### Test connection **Test connection** sends one tiny request (a single output token) to `/v1/messages` with the values currently in the form: the typed key, or the stored key when the field is blank, together with the auth method, host and model as entered. Nothing is saved by the test. The notification tells you whether the credentials, the host path and the model id were accepted, or which of them the host rejected, and the same result stays visible under the buttons until you dismiss it. On a failure, **Show gateway response** in that panel reveals the raw reply of the host (status and error message, with the key masked), which is what to paste into a support request. Redirects are not followed; enter the final URL as the host instead. The request is billed to the key it was sent with. If the key is rejected by Anthropic (revoked, out of credit, or wrong host), AI requests for the organization fail until you correct or remove it — Mitzu does not silently fall back to its own key. ## Tips - Keep the prompt short and declarative. One rule per line is easier for the model to follow than long prose. - When you add a new rule, re-run a few representative questions to make sure the agent honors it. - If the agent starts ignoring part of your prompt, check whether the catalog contradicts it (the catalog wins for factual questions). --- # Workspace Settings: Indexing settings Source: https://docs.mitzu.io/indexing-settings The Indexing settings tab contains all configuration related to event and property catalog creation. ![image](https://docs.mitzu.io/img/indexing-settings/image.png) ## Options - **Lookback window**: Mitzu only indexes the most recent events in your data warehouse. The lookback window setting defines the time window the indexing process looks at. - **Sample size**: Mitzu only picks a small sample of events for indexing. Increasing the sample size improves indexing precision but makes the indexing process longer. - **Bucketed column table indexing**: by default, Mitzu efficiently indexes any table using a single SQL query. However, this process takes longer if your data warehouse contains wide tables (tables with many columns). Processing the table in buckets of columns can improve performance, especially in data lakes with Parquet or ORC files. - **Bucketed event indexing**: by default, Mitzu efficiently indexes any table using a single SQL query. However, this process can run into limitations if your event tables contain too many events (1,000+). Indexing every event in these tables at once may hit the data warehouse's limits. Indexing the events in buckets can avoid these limits. This setting controls the bucket size used for indexing. - **Multi-step indexing**: by default, Mitzu efficiently indexes any table using a single SQL query that samples the table. However, this SQL can run into limitations if the selected sample has too many rows. This setting splits sample selection across multiple executions. The number of executions equals the value in the input box. - **Dimension table sample size**: Mitzu only picks a small sample of rows for indexing. Increasing the sample size improves indexing precision but makes the indexing process longer. - **Data scrambling**: by default, Mitzu indexing reads the data warehouse in its default order (no ordering), which may result in skewed data reads. Data scrambling randomizes the reading order. This setting randomizes the indexing but makes it slower. Changes are saved automatically. --- # Workspace Settings: Statistics Source: https://docs.mitzu.io/statistics The **Statistics** page shows how the current workspace is being used — which events and dashboards are active, and who is creating content. Use it to spot unused events, prioritize cleanup, and understand adoption across your team. ![image](https://docs.mitzu.io/img/application/statistics/image.png) ## Export dashboard events The **Export dashboard events** button downloads a CSV listing every dashboard in the workspace along with the events each one references. This is useful for auditing which events your dashboards depend on before removing or renaming them. ## Export usage report The **Export usage report** button downloads a CSV summarizing workspace activity — query volume, active members, and saved insight / dashboard counts — broken down over time. Use it to share adoption metrics with stakeholders or to audit how the workspace is being used. --- # Workspace Settings: Members Source: https://docs.mitzu.io/manage-members Invite colleagues and business partners to your Mitzu organization so they can share insights and dashboards, or analyze your company data themselves. ## Seat allocation Above the members table, the **Seat allocation** card shows how many editor seats are in use compared to your plan. Editor seats are consumed by `admin` and `member` users; `viewer` users do not count against the seat limit. If you exceed your purchased seats, Mitzu shows an **Editor seats exceeded** warning — reduce roles or click **Manage subscription** to increase your plan. ## Listing members Existing members are shown in a table with the following columns: - **User email** — the email address the member uses to sign in to Mitzu. - **Login** — either `basic authentication` or `private SSO`. `private SSO` means the member is authenticated by your configured identity provider (see [Single Sign-on](https://docs.mitzu.io/single-sign-on)). - **Role** — one of `admin`, `member`, or `viewer`. Only admins can change organization settings or invite new users. Viewers can read insights and dashboards but cannot edit them. Viewers also cannot run queries on the data warehouse: they see cached results, and a "You don't have permission to run queries" notice when a result is not cached yet. - **Invited** — time elapsed since the user was invited. - **Last login** — time elapsed since the user's most recent sign-in. - **Devices (7d)** — the number of distinct devices the member has signed in from over the last 7 days. Useful for spotting shared or unused accounts. ![image](https://docs.mitzu.io/img/application/manage-members/image.png) ## Invite new members To invite new members, click **Invite user**. A dialog opens where you can enter a list of email addresses and pick the role to assign. Fill in the fields and click **Invite user** to send the invitations — each address receives an invitation email. You can invite up to 10 email addresses at once. If SSO is enabled, you do not need to invite users that already exist in your identity provider — they can sign in directly. > **WARNING** > > Only admins can invite new members. ![image](https://docs.mitzu.io/img/application/manage-members/image-1.png) ## Update a member To change a member's role, select the member's row via its checkbox and click **Manage**. A dialog opens where you can pick the new role; click **Save** to apply it. You cannot change the role of the organization owner (the first user in the organization) or your own role. > **WARNING** > > Any admin can update member roles, but at least one member must always have the admin role. ![image](https://docs.mitzu.io/img/application/manage-members/image-2.png) ## Remove a member To remove a member, select the member's row via its checkbox and click **Remove**. A confirmation dialog appears — click **Delete** to proceed. All of the member's saved insights and dashboards are transferred to the organization owner (the first member of the organization). > **WARNING** > > You cannot remove the organization owner or your own user. > **WARNING** > > When SSO is enabled, members authenticated by your identity provider can be removed, but nothing stops them from signing in again and re-joining on their next login. ![image](https://docs.mitzu.io/img/application/manage-members/image-3.png) --- # Workspace Settings: API keys Source: https://docs.mitzu.io/api-keys API keys let you perform actions in your Mitzu organization through the [Mitzu API](https://docs.mitzu.io/api/v1/mitzu-api). Each key is tied to your organization, not an individual workspace. ## Viewing existing API keys Your existing API keys are shown in a table with the following columns: - **Name** — a label used to identify the API key. - **Expires at** — the date the key stops working. - **State** — the current status: `enabled`, `disabled`, or `expired`. ![image](https://docs.mitzu.io/img/application/api-keys/api-keys-table.png) ## Creating a new API key 1. Click **Add new API key**. 2. In the dialog, enter a **Name** and (optionally) an **Expiration Date**. Leave the expiration date empty if you want the key to never expire. 3. Click **Add** to generate the key. ![image](https://docs.mitzu.io/img/application/api-keys/api-keys-modal.png) The generated key is displayed once. **Copy it immediately** — Mitzu will not show it again after the dialog is closed. ![image](https://docs.mitzu.io/img/application/api-keys/api-keys-modal-success.png) ## Enabling or disabling an API key You can toggle a key between `enabled` and `disabled` without deleting it: 1. Select the key by checking the box in its row. 2. Click **Enable / Disable**. 3. The key's state updates immediately. ## Deleting an API key 1. Select the key by checking the box in its row. 2. Click **Remove**. 3. In the confirmation dialog, click **Delete** to permanently remove the key. ![image](https://docs.mitzu.io/img/application/api-keys/api-keys-delete-modal.png) --- # Workspace Settings: Single sign-on Source: https://docs.mitzu.io/single-sign-on SSO lets your team sign in to Mitzu through your company's identity provider instead of managing a separate password. SSO is configured once at the organization level and applies to every workspace. Mitzu supports: - [AWS Cognito](#aws-cognito) - [Google SSO](#google-sso) - Any [OIDC (OpenID Connect)](#oidc) compatible identity provider, such as Okta or OneLogin. ## AWS Cognito ### Create a new app client in AWS Cognito 1. Sign in to Mitzu and open the **Single Sign-on** tab in Workspace Settings. Once SSO is enabled, you can configure the integration details: ![image](https://docs.mitzu.io/img/application/aws-cognito/image.png) 2. Open the AWS Console and create a new app client in your AWS Cognito user pool with the following settings: - **Auth type:** Confidential client - **Allowed callback URLs:** copy the full value of the **Redirect URL** field from the Mitzu SSO settings - **OAuth 2.0 grant types:** Authorization code grant - **OpenID Connect scopes:** `email` must be selected ### Configure Mitzu with the Cognito app client 1. Fill in the client settings on the Mitzu SSO page: - **Client ID** and **Client Secret** — taken from the app client settings page in AWS. - **Pool ID**, **AWS Region**, and **AWS Cognito signing domain** — taken from the user pool settings page in AWS. 2. Click **Save**. ## Google SSO ### Create a new app client in Google 1. Sign in to Mitzu and open the **Single Sign-on** tab in Workspace Settings. Once SSO is enabled, you can configure the integration details: ![image](https://docs.mitzu.io/img/application/google-sso/image.png) 2. Open the Google Cloud Console and create a new OAuth 2.0 Client ID (**APIs & Services → Credentials**) with the following settings: - **Application type:** Web application - **Authorized redirect URIs:** copy the full value of the **Redirect URL** field from the Mitzu SSO settings ### Configure Mitzu with the Google app client 1. Fill in the client settings on the Mitzu SSO page: - **Client ID** and **Client Secret** — taken from the OAuth client settings page. - **Project ID** — shown on the **Cloud Overview → Dashboard** page in the project info box. 2. Click **Save**. ## OIDC ### Create a new app client in your identity provider 1. Sign in to Mitzu and open the **Single Sign-on** tab in Workspace Settings. Once SSO is enabled, you can configure the integration details: ![image](https://docs.mitzu.io/img/application/oidc/image.png) 2. Open the web console of your identity provider and create a new client application with the following settings: - **Application type:** Web application - **Grant type:** Authorization Code - **Sign-in redirect URIs:** copy the full value of the **Redirect URL** field from the Mitzu SSO settings - **Sign-out redirect URIs:** copy the full value of the **Home URL** field and append `/auth/unauthorized` - To let users start the login from the identity provider side, redirect them to the **Home URL** appended with `/auth/redirect-to-login` - **Client authentication:** client secret ### Configure Mitzu with the OIDC app client 1. Fill in the client settings on the Mitzu SSO page: - **Client ID** and **Client Secret** — taken from the OIDC app client's settings page. - **Authorize endpoint**, **Token endpoint**, and **JWKS URI** — configure these manually, or paste the `/.well-known/openid-configuration` URL and click **Fetch OIDC Settings** to fill them in automatically. 2. Click **Save**. > **VERIFY LOGIN FLOW** > > In a different browser (or in an incognito window) verify the login flow. If it is not working as expected then please supervise your settings or contact Mitzu Support. --- # Workspace Settings: Billing and Subscription Source: https://docs.mitzu.io/billing-and-subscription You can start, update, or cancel your Mitzu subscription at any time from the **Billing** tab in Workspace Settings. Billing applies to your entire Mitzu organization, not to a single workspace. ## New subscription Visit our [pricing page](https://www.mitzu.io/pricing) to pick the plan that fits your company best. If the Starter plan does not meet your requirements, contact us at [support@mitzu.io](mailto:support@mitzu.io). To start a new subscription on the **Starter** plan, select the billing period, enter the number of seats you need for your team, and click **Subscribe**. ![image](https://docs.mitzu.io/img/billing-and-subscription/image.png) You will be redirected to a secure payment page to enter your payment details. Payments are processed by a third-party provider — Mitzu does not store your payment details. Once the subscription is confirmed, you are returned to Mitzu. ## Manage subscription The **Billing** tab shows the details of your current subscription and lets you download recent invoices. Click **Manage subscription** to change the number of seats, switch the billing period, or cancel. ![image](https://docs.mitzu.io/img/billing-and-subscription/image-2.png) ### Update subscription To change your subscription details, click **Manage subscription** and follow the instructions on the payment page. ### Cancel subscription To cancel your Mitzu subscription, click **Manage subscription** and follow the instructions on the payment page. --- # Workspace Settings: Query Admin Source: https://docs.mitzu.io/query-admin The **Query Admin** tab lists recent and in-progress SQL queries that Mitzu has sent to your data warehouse on behalf of this workspace. Use it to spot slow queries, debug unexpected load, or cancel a runaway query before it finishes. ![image](https://docs.mitzu.io/img/application/query-admin/query-admin.png) ## Executed SQL queries The table shows the latest queries Mitzu executed for this workspace, with the following columns: - **Owner email** — the Mitzu user whose action triggered the query (e.g. opening an insight or refreshing a dashboard). - **Created** — how long ago Mitzu submitted the query to the warehouse. Badges turn red once the query has been running for more than a minute. - **Source** — the kind of action that produced the query (Insight, Dashboard, Public dashboard, Cohort, Query info, Indexing). Click the source button to open the originating page in a new tab. - **Statistics** — warehouse-reported metrics such as bytes processed, rows returned, or elapsed time. Contents depend on the adapter (Postgres, BigQuery, Snowflake, etc.). - **Status** — the current state reported by the warehouse (`running`, `done`, `cancelled`, or `error`). A red close icon appears next to queries that are still `running` — click it to cancel the query. Only the latest 30 queries are shown. Older queries are dropped from the list once newer ones are submitted. ## Refresh Click **Refresh** to re-fetch the latest queries from the warehouse. Mitzu does not poll automatically — you need to refresh the list to see newly started queries and updated states. ## Cancel a running query To stop a query that is still `running`, click the red `×` icon in the **Status** column. Mitzu sends a cancel request to the warehouse; once acknowledged, the status updates to `Cancelled`. > **WARNING** > > Cancelling a query only stops the warehouse-side execution. The Mitzu page that triggered the query may still show a loading state until it times out or is refreshed. --- # Workspace Settings: Slack Integration Source: https://docs.mitzu.io/slack-integration Connecting Slack to Mitzu lets your team: - Chat with **Mitzu AI** directly from Slack to ask product questions and get chart answers. - Receive **scheduled insight alerts** and **anomaly notifications** for this workspace in a Slack channel of your choice. ![image](https://docs.mitzu.io/img/application/slack-integration/slack-integration.png) ## Connect the Mitzu Slack app 1. Click **Connect Slack**. A new tab opens with the Slack OAuth consent screen. 2. Choose the Slack workspace you want to connect to Mitzu and review the requested permissions. 3. Click **Allow** to install the Mitzu Slack app. Slack redirects you back to Mitzu once the install succeeds. After installation, the **Mitzu** app appears in your Slack workspace's apps list. Each Mitzu workspace is linked to a single Slack workspace. > **NOTE** > > You need permission to install apps in the target Slack workspace. If your Slack admin restricts app installs, forward the OAuth link to them so they can complete the install on your behalf. ## Pick a notification channel Once the Slack app is connected, the **Notifications** section becomes active: 1. Click the **refresh** icon next to the channel dropdown to load the list of available channels from Slack. 2. Open the **Slack channel** dropdown and pick the channel where Mitzu should post alerts. The selection is saved automatically. 3. Click **Send test notification** to confirm the channel is reachable — Mitzu posts a short test message to the selected channel. > **WARNING** > > Mitzu can only post to channels the `@Mitzu` app has been added to. If the test message fails, open the target channel in Slack, type `/invite @Mitzu`, and try again. ## What gets posted to the channel The selected channel receives: - **Scheduled insight alerts** — insights saved with a schedule post a snapshot and a link back to Mitzu at each run. - **Anomaly notifications** — configured anomaly monitors post when a metric deviates from its expected range. - **Mitzu AI replies** — when a teammate mentions `@Mitzu` in a channel or sends a direct message to the app. All notifications include a link back to the originating insight or dashboard in Mitzu. --- # Workspace Settings: Appearance Source: https://docs.mitzu.io/appearance **Settings → Personal settings → Appearance** controls whether Mitzu renders in light or dark mode. Unlike the workspace and organisation tabs in Settings, this one is **personal, not shared**. It changes how Mitzu looks for you alone — nobody else in the workspace sees a difference — and it is available to every role, since it is not a workspace configuration. ## Choosing a mode Pick one of three options: | Option | What it does | | --- | --- | | **Light** | Always use light mode, whatever your device is set to. This is the default. | | **Dark** | Always use dark mode, whatever your device is set to. | | **System default** | Follow your operating system. If your Mac, Windows, or Linux desktop switches to dark in the evening, Mitzu follows it. | Mitzu starts in **Light** for everyone. Dark mode is opt-in: even if your computer is set to dark, Mitzu stays light until you pick **Dark** or **System default** here. The change applies the moment you click — there is no save button, and the page does not reload. ## Light and dark The same home page, in each mode: ![image](https://docs.mitzu.io/img/application/appearance/home-light.png) ![image](https://docs.mitzu.io/img/application/appearance/home-dark.png) ## Where the preference is stored Your choice is remembered **per browser, on the device you set it on**. It is not attached to your Mitzu account. In practice that means: - Setting dark mode on your laptop does not change anything on your phone, or in a different browser on the same laptop. - A private or incognito window starts from **Light** again, and forgets your choice when you close it. - Clearing your browser's site data resets it to **Light**. > **INFO** > > Because the preference is per browser, it also does not travel with anything you share. A dashboard or insight you send to a colleague renders in **their** chosen mode, not yours. ## What stays light A few things deliberately do not follow dark mode: - **Charts sent outside the app** — scheduled agent emails, alert notifications, and dashboard PDF reports. Email clients and PDF viewers vary too much to rely on a transparent background, so these are always rendered on white. - **Chart thumbnails saved before dark mode shipped.** Insight preview images generated earlier have a white background baked into the stored image, so they still show as white cards on a dark page until the insight is saved again.