Sessions and tools in Maia

A session is an ongoing, structured interaction between you and Maia. A session includes your full conversation history, relevant context, and any tool based actions Maia has performed on your behalf, all within the current Designer workspace.

Sessions are designed to help you work more efficiently and offer the following benefits:

Context-awareness: Maia builds on prior messages within the same session, allowing for more coherent, informed responses across multiple prompts.
Session-scoped: Your chat with Maia remains active and visible in the Maia panel as long as you're working in the same Designer project and branch.
Resettable: If you'd like to start fresh or you're seeing unexpected behavior, click the New Chat icon in the top-right of the Maia panel to clear the current session and begin a new conversation.

Note

You can switch between pipelines in the same branch without losing session context. However, switching branches will automatically reset the session and clear your chat history.

If Maia appears to misunderstand your intent or loses context, use New Chat to reset and start a clean conversation. If you have a long conversation with Maia, it may summarize your chat so far, and then continue. If this happens, we recommend starting a new chat the next time you start to discuss a new topic with Maia.

Plan mode

You can chat with Maia about your pipeline without making any changes to it using Maia's plan mode. Plan mode provides you with extra visibility and control over Maia's suggested actions, which can be useful when working on complex pipelines, and enables you to suggest changes to Maia's approach before any work is performed on your pipelines. To use plan mode, switch on the Plan mode toggle at the bottom of Maia's chat interface.

When plan mode is active, Maia can analyze your pipeline and explore your data warehouse, then present a multi-step plan to achieve your goal without making any changes to your pipeline. You can then suggest changes to the plan if needed, or accept Maia's suggestion. Maia will only make changes to your pipeline after you have approved its suggested plan.

Visualizing data

Maia can now visualize the data it samples in a component directly in the chat interface. These visualizations enable you to discover key insights and identify trends. To visualize your data in the Maia interface, prompt Maia to create a chart or graph representing the data in a specific component.

The visualizations that Maia creates are based on the data that Maia can sample, so the visualizations will include between 10 and 20 rows of data, not the entire data set. For more information about how Maia samples data, read Sampling data.

Conversation history

Maia automatically saves your recent conversations, making it easy to continue where you left off or revisit previous work. This ensures that important context and progress aren't lost when you need to step away or switch tasks. Conversation history is tied to your current branch. Switching to a different branch will show conversations specific to that branch's context.

Note

For the best results, we recommend starting a new chat for each distinct task or pipeline project. This helps Maia provide more focused, relevant assistance while still allowing you to return to previous conversations when needed.

When you open the Maia chat panel, you'll see your two most recent conversations from the past three days displayed in the Branch conversations section, as shown in the image below. To view more of your most recent conversations with Maia and resume any of these conversations:

Click See more above the two most recent conversations when you first open the Maia chat interface.
While chatting with Maia, click Chat history in the top right of the chat interface.

When you select a previous conversation, Maia loads the complete chat history and you can continue exactly where you left off. To start a completely new conversation instead, type a message in the chat input field when it opens.

Renaming and deleting conversations

You can rename and delete your previous conversations with Maia. Renaming a conversation makes it easier to find useful pipeline information or data analysis, while deleting conversations lets you clear conversations you no longer need.

To rename or delete a previous conversation, click the three dots ... next to the conversation name, and then click Rename or Delete as shown in the image below. If the conversation you want to rename or delete is not one of your two most recent conversations, click See more above the recent conversations to open your conversation history.

File exploration

Maia can search through and explore files in your project, making it easier to understand existing work, find specific configurations, or perform project-wide updates.

Maia's file search capabilities help you:

Locate specific files: Find pipeline files, scripts, or documentation by name or pattern.
Discover existing components: Find configured components to copy or reference.
Validate project-wide changes: Ensure parameters or configurations are updated everywhere they're used.
Understand your project structure: Get an overview of what files and pipelines exist in your project.

For example, you could prompt Maia as follows:

"Find all transformation pipelines that connect to the "product-orders" table."
"Show me any existing Salesforce load components I can copy."
"Find every time the database name 'PROD_DB' is mentioned."
"Summarize the content of the pipeline files in the analytics folder."

Search performance

For larger projects with many files, searches may take longer to complete. Maia will let you know when it's working on your search request. Using file search is much more efficient than having Maia view each file individually, especially when you need to:

Perform large-scale refactors across multiple pipelines.
Check whether changes were applied consistently throughout your project.
Find specific patterns or configurations across many files.

Slash commands

Slash commands are a command-line interface (CLI) style method of interacting with Maia. These commands simplify complex prompts into a one-word command to standardize common tasks. The table below explains what Maia will do as a response to each slash command.

To use a slash command, type a forward slash / in the Maia chat interface, followed by the command you want to give. After you type /, an autocomplete list of available slash commands will appear. After typing the command, enter the name of the object that you want Maia to process—you can use the @ symbol here to mention a specific file in your project. For example, you could prompt Maia "/document the customer_data folder", "/explain this pipeline" or "/fix @weekly_orders".

Command	Maia's task
`/document`	Generate a Markdown file containing information about a specified pipeline, file or directory. The information Maia provides will include a summary of the file, the components used (when documenting a pipeline), how to use the file, and important information like dependencies and performance considerations.
`/explain`	Generate a brief explanation of a specified pipeline or concept. The information Maia provides will include a short explanation of the pipeline's purpose, data flow, and key components.
`/fix`	Identify issues in a specified pipeline and suggest ways to fix them. Maia will determine the cause of any errors or configuration problems in the pipeline and present you with options to resolve the issues. Maia will not take any action until you approve one of the options presented.
`/notes`	Add notes to a specified pipeline. Maia will add notes to the Designer canvas with information about the purpose of components, the data flow in the pipeline, any potential issues, and opportunities for optimization.
`/optimize`	Analyze a specified pipeline and suggest opportunities for optimization. The suggestions Maia provides can include information about generic SQL that could use specialized components, opportunities for parallelization, and performance bottlenecks. Maia will not make any changes to your pipeline until you approve one or more of its suggestions.

Tools

Maia uses tools to perform tasks in your Designer workspace based on your prompts. These tools let Maia go beyond chat and perform real, interactive actions.

Maia tools allow it to:

Create and modify orchestration or transformation pipelines.
Add and configure pipeline components.
Search for tables in your data warehouse.
Preview or sample table data.
Run pipelines and monitor their status.

Note

Tools let Maia take real actions in the Designer, not just respond with suggestions for you to take yourself. These actions include building pipelines, configuring components, and running tasks directly in your workspace.

Tool permissions

For security and transparency, Maia requires explicit permission before using tools that can affect your workspace.

When a prompt requires tool access, Maia displays a Tool Permissions dialog. You can:

Accept once: Approve the action for a one-time use.
Accept for session: Allow Maia to repeat this action without asking again during the current session.
Decline Deny the request and optionally adjust your prompt.

This permission-based model ensures that you stay in control while enabling Maia to act confidently on your behalf.

Got feedback or spotted something we can improve?

We'd love to hear from you. Join the conversation in the Documentation forum!