# Clarity Engine

The Clarity Engine is the backbone of Zenlytic's LLM-based agent, Zoë. It operates in two modes: **Exploratory Mode** (the default for new workspaces), which writes custom SQL directly against your warehouse, and **Default Mode** with Dynamic Fields, which stays within your semantic model's structure. Both modes enforce the same row- and column-level security.

## Just ask!

To start using the Clarity Engine in Zenlytic, navigate to Zoë (the chat interface in Zenlytic) and simply ask her a question. If you're unsure where to begin, ask what data she has access to, or request a good follow-up question based on your prior analysis within the conversation.

Note: Providing more context about the task you're trying to accomplish, your team, and job title will make Zoë even more helpful.

![Starting a new chat with Zoë](/files/HKLzTGXapA4uxy5GiW8E)

You can ask Zoë specific questions (e.g. "Show me sales YTD compared to the prior YTD, broken out by product type") or general ones (e.g. "I don't really know what I want to see, but tell me about channel and campaign performance"). The Clarity Engine handles both types of questions, and Zoë will ask follow-up questions when she is unable to make reasonable assumptions about your intent.

The chat interface includes several interactive elements:

* **Plus icon**: Add attachments to your message, including images (5MB limit), CSVs, and PDFs (maximum 5 files, 25MB total), and data via the query builder
* **Microphone icon**: Click to use voice input - Zoë will capture your prompt through real-time voice transcription via your web browser
* **Lightning icon**: Opens a panel to select and run a Proactive Agent
* **Model dropdown**: Located on the right side of the input area, this allows you to change the base LLM used for Zenlytic's LLM-based agent
* **Chat Options**: Toggle between Exploratory Mode (default) and Default Mode. When Exploratory Mode is active, a microscope icon appears in the chat input (shown below)
* **Submit**: Press "Enter" or click the up arrow button to send your message

![Starting a new chat with Zoë in Exploratory mode](/files/nkTxiN1SHLtMl450teho)

## Exploratory Mode

Exploratory Mode is the default for new workspaces. It lets the Clarity Engine write custom SQL directly against your data warehouse for advanced analysis that extends beyond your semantic model's current structure.

### How Exploratory Mode Works

When Exploratory Mode is active, the Clarity Engine operates with expanded capabilities:

1. **Writes custom SQL** - Creates queries directly against your tables and views, using full context about your existing semantic model
2. **Maintains security** - Enforces all row and column-level permissions, ensuring you only access data you're authorized to see
3. **Highlights reuse** - Identifies and shows you when the SQL leverages existing components from your semantic model
4. **Provides transparency** - Explains the approach in plain English, including which parts of your semantic model are being referenced

This mode gives you the flexibility to explore complex data relationships while staying within your organization's governance framework.

### Security in Exploratory Mode

Exploratory Mode maintains the same strict security standards as Default Mode:

* **Row-level security**: Your access filters are automatically applied to all SQL queries
* **Column-level security**: Only columns you have permission to view are included in the generated SQL queries
* **Semantic model integration**: Existing measures and dimensions from your semantic model are reused whenever possible, preserving their built-in governance

This approach ensures that expanded analytical capabilities never compromise your organization's data security and governance policies.

### Context Reuse Highlighting

When writing custom SQL in Exploratory Mode, the Clarity Engine identifies and highlights when it leverages components from your existing semantic model.

![The Clarity Engine highlighting re-use in exploratory mode](/files/tJn82bYQM6f8HKQbQeMg)

Zoë provides clear explanations of her analytical approach, showing you which parts of your semantic model she's reusing through interactive hover text. This transparency helps you understand how your established data definitions contribute to exploratory analysis, bridging the gap between governed and ad-hoc investigation.

## Default Mode with Dynamic Fields

Default Mode keeps Zoë's work within your semantic model. When the fields needed to answer a question don't exist yet, she creates **Dynamic Fields** by writing custom SQL on the fly, building on top of your already-defined fields. Dynamic Fields can be promoted into your semantic layer for reuse.

Use Default Mode when you want every answer to route through fields that have been (or can be) governed and reused across the platform.

### How Dynamic Fields Work

When you ask Zoë a question, the Clarity Engine first analyzes your semantic model to understand what fields, joins, and business logic are already available. If the specific fields needed to answer your question don't exist in your semantic model yet, here's what happens:

1. **Identifies existing components** - Reviews available measures, dimensions, and their underlying columns within relevant topics
2. **Leverages current structure** - Uses your existing joins, relationships, and business logic as building blocks
3. **Generates custom SQL** - Writes new field definitions on the fly that build on top of your established semantic layer
4. **Maintains governance** - Applies all security rules, including row and column-level permissions, to the dynamically created fields

This process allows Zoë to answer complex questions that go beyond your current semantic model while staying within the governance framework you've established.

### Permissions in Dynamic Fields Mode

The Clarity Engine follows a **component accessibility** model for security: when you have access to a measure or dimension, Zoë can use any underlying column referenced in that field's definition to create Dynamic Fields.

**How this works:**

Consider this measure in your semantic model:

```yaml
- name: count_unique_emails
  field_type: measure
  type: count_distinct
  sql: ${TABLE}.email
  required_access_grants: [marketing_team]
```

If you have access to `count_unique_emails` through the `marketing_team` access grant, the Clarity Engine can use the underlying `email` column in multiple ways:

* **Counting**: "How many customers have Gmail addresses?"
* **Filtering**: "Show me customers who signed up with work emails"
* **Grouping**: "Break down results by email domain"
* **Custom logic**: Create new measures that reference the email column

This approach maintains strict access controls while giving Zoë maximum flexibility to answer your questions using the data components you're already authorized to access.

### Querying with Dynamic Fields

When you ask Zoë a question, she analyzes your semantic model to find existing fields that can answer your question and creates new Dynamic Fields when needed. Her responses include clear visual indicators to help you understand what she's using:

![The Clarity Engine analyzing your request](/files/bU42s4oy4pyyJTck1glH)

**Visual Indicators:**

* **Green checkmark**: Indicates a verified field from your semantic model that's governed and reusable across the platform
* **No checkmark**: Indicates a Dynamic Field created within the context of the current question

The Clarity Engine uses an intelligent agent-based architecture that allows Zoë to plan approaches to complex problems, use multiple tools to gather information, maintain context throughout your conversation, and update her memory to provide increasingly relevant answers.

### Promoting Dynamic Fields

When Zoë creates Dynamic Fields to answer your questions, you can promote these fields into your semantic model for reuse across the platform. Dynamic Fields appear without a green checkmark, indicating they were generated in the context of your current question and haven't yet been validated by the data team.

Note: Promoting Dynamic Fields requires developer-level permissions or above.

**To promote a Dynamic Field:**

1. Click on the Dynamic Field in your results
2. Click the three-dot menu on the right side of the field
3. Select "Promote"

![The Clarity Engine promoting a metric](/files/VNt7jHCCBpkzAnDYDuxa)

This promotion workflow transforms ad-hoc analysis into governed, reusable components that become available in [Artifacts](/using-zenlytic/artifacts.md), explores, [Proactive Agents](/proactive-agents/getting-started.md), and future conversations with Zoë. By building your semantic model this way, you create measures and dimensions based on real analytical needs rather than trying to anticipate every possible field upfront.

## Artifacts

Both Exploratory Mode and Default Mode produce rich, interactive outputs called [Artifacts](/using-zenlytic/artifacts.md): apps, documents, spreadsheets, presentations, charts, and more. When Zoë's analysis goes beyond a single table or chart — merging results from multiple queries, applying external assumptions, building custom visualizations, or running statistical analysis like clustering, correlation, regression, or forecasting — the result is delivered as an Artifact you can save, share, refresh on a schedule, and publish.

See [Artifacts](/using-zenlytic/artifacts.md) for the full feature set: saving and organizing artifacts, update history and versioning, auto refresh, scheduled delivery to email or Slack, sharing and permissions, and web publishing.

## Choosing Between Modes

The Clarity Engine's two modes handle different analytical scenarios. Most new workspaces default to **Exploratory Mode** because it's the most flexible surface. Switch to Default Mode (Dynamic Fields) when you want every answer to flow through your governed semantic model.

**Exploratory Mode** (default) is best for:

* **Custom analysis beyond semantic constraints** - Handles questions that cannot be answered within the structured relationships of any semantic model, requiring complete flexibility to redefine how data connects and flows
* **Advanced ad-hoc investigations** - Enables complex analytical techniques that extend beyond traditional BI platforms, and even beyond Default Mode

**Default Mode with Dynamic Fields** is best for:

* **Flexible semantic model expansion** - Leverages your existing data structure while dynamically creating new fields that extend far beyond traditional BI platforms' capabilities, allowing complex analysis while maintaining governance
* **Platform integration and reusability** - Creates analysis components that integrate natively with [Artifacts](/using-zenlytic/artifacts.md), explores, [Proactive Agents](/proactive-agents/getting-started.md), and can be promoted into your permanent semantic model for team-wide use

Both modes maintain the same high standards for security, governance, and transparency.


---

# Agent Instructions: Querying This Documentation

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

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.zenlytic.com/using-zenlytic/clarity_engine.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

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