> ## Agent Instructions
> Orion is a collaborative analytics platform built by Gravity (bygravity.com). It connects to data warehouses, to Looker and dbt for existing business logic, and to a small set of external-context sources, and it lets teams ask questions in natural language to get shared analyses, dashboards, reports, and slide decks. The Connecting Data Sources page is the authoritative list of supported sources. When referencing Orion features, always link to the relevant documentation page. Orion is not open-source; it is a commercial SaaS product accessed at runorion.com.
# Basics & Navigation
Source: https://docs.runorion.com/chat/basics-navigation
Find your way around the Chat interface
The Chat interface is where you interact with Orion. Conversations are organized by [project](/core-concepts/projects), so each project maintains its own chat history and context. Start typing to ask a question, and Orion returns results inline.
## Chat Interface
The Chat interface is where you interact with Orion. Your conversations are organized by [project](/core-concepts/projects), so each project has its own chat history and context.
## Starting a Conversation
Simply start typing to begin a new conversation with Orion. Each conversation can reference previous conversations in the same project, and Orion will remember project-specific information and your preferences.
## Referencing Content with @
Type `@` in the chat input to reference something that already exists in the project. The reference inserts a chip with the item's exact name, so Orion does not have to guess which item you mean.
The `@` has to start the message or follow a space. With nothing typed after it, the menu opens on the category list:
| Category | What it offers |
| - | - |
| **Templates** | Saved slide and web page templates in this project |
| **Metrics** | Pinned metrics, plus metrics you created |
| **Views** | Pinned views, plus views you created |
| **Past chats** | Your earlier chats in this project |
| **Context** | Document pages in the project Context |
| **Workflows** | Workflows shared to the board, plus ones you created |
| **Google Sheets** | Spreadsheets attached to this project |
A category stays in the list even when it holds nothing, so opening an empty one shows "No matching references."
![The Chat screen with @ in the chat input. The menu lists Templates, Metrics, Views, Past chats, Context, Workflows, and Google Sheets. The reference menu is outlined in red above the input]()
Keep typing after the `@` to search every category at once. Matching is case-insensitive against the name, and results stay grouped by category, at most ten per category. The menu searches recent items, not the full history of the project.
Referencing a template tells Orion to build the deliverable with that template. Referencing a spreadsheet tells Orion to read it as data. Every tab loads unless you name one.
Attach spreadsheets on the **Connectors** tab of [Project Settings](/core-concepts/projects), after connecting Google under **Settings → Connectors**. Orion uses your Google access to read them. Attachments are read-only by default. To let Orion write to a sheet, switch its access to **Read/write**.
The menu is built for the keyboard:
* **Arrow Down** and **Arrow Up**: move the highlight
* **Arrow Right**: open the highlighted category
* **Arrow Left**: return to the category list, before you type anything
* **Enter** or **Tab**: take the highlighted entry
* **Escape**: close the category, then close the menu
Press **Backspace** once to remove a reference. The whole chip is deleted, not one character at a time.
In a room, the menu offers **Orion** as one more entry. That mention
addresses Orion rather than referencing content: see [Rooms](/chat/rooms).
## Chat History
Your chat history appears in the sidebar on the left side of the Chat interface. All your previous conversations are saved and easily accessible.
The chat history sidebar shows:
* A **+ New Chat** button at the top to start a new conversation
* Your recent conversations, organized chronologically with timestamps
* Conversation titles and related analysis tags
* The ability to hide or show the sidebar using the **← Hide** button
Your chat history is organized by project, so each project maintains its own separate conversation list. All conversations are private to your account.
![Chat history interface showing sidebar with list of conversations, new chat button, and navigation]()
## Sharing Conversations
Use the Share Chat button at the top of the chat interface to share conversations with your team. For more details, see our [Share Chat Conversations](/chat/share-conversations) guide.
![Share Chat button in the chat interface]()
# Best Practices
Source: https://docs.runorion.com/chat/best-practices
Habits that get better answers out of Orion
The most effective Orion users follow a consistent pattern: one project per use case, explicit prompts with context, 2-3 iterations per analysis, relative dates for anything scheduled, and active memory management. This guide covers each practice in detail.
## Overview
This guide covers:
* [Project setup and organization](#project-setup)
* [Crafting effective prompts](#crafting-effective-prompts)
* [Providing context for better results](#provide-context-for-document-uploads)
* [Iterating on analyses](#iterating-on-analyses)
* [Managing memory and conversations](#managing-memory)
* [Troubleshooting and debugging](#troubleshooting-and-debugging)
* [Performance optimization](#performance-optimization)
## Project Setup
### One Project Per Use Case
Create a separate project for each distinct use case or workflow. This keeps each project's context focused and prevents conflicting information. Think of each project as a dedicated analyst for that specific team or use case.
### Keep Context Consistent
Keep the context you give Orion clear and consistent. Conflicting information confuses Orion, and it can live in multiple places:
* [User profile settings](/profile-settings/profile-management)
* [Project settings](/core-concepts/projects)
* [Context pages](/core-concepts/knowledge-base)
* [Company information page](/configuration/company-information)
* [Memory](/chat/memory)
* Exploratory conversations
Review all these areas to ensure consistency.
### Memory Configuration
* **Private Project** - each project should have its own memory context
### Use Relative Dates
When creating a re-runnable or scheduled analysis, use relative date instructions instead of absolute dates. Include the word "evergreen" to ensure all instructions, queries, and generated code use relative dates that will work when rerun.
## Crafting Effective Prompts
### Be Explicit and Clear
Be explicit in your requests. Ambiguous prompts lead to assumptions, which can be incorrect, especially when working with a new project. Spell out exactly what you want rather than assuming Orion will infer your intent.
### Answer Clarifying Questions Consistently
When Orion asks clarifying questions, answer them in a consistent format (e.g., numbered points). If you want this format used every time, tell Orion to "remember this for next time."
### Provide Context for Document Uploads
When uploading documents or spreadsheets, provide supplemental context:
* What columns the document contains
* Where the data came from
* What the data represents
* Any relevant background information
For example: "I uploaded a spreadsheet. It has these following columns and it came from this source. It's a merge history from GitHub and contains details about team members."
### Explore Data First
Get Orion familiar with your data before diving in. Start by asking "tell me a little bit about the data that's available." This quick step helps Orion understand your data structure and confirms it has the access it needs, setting you up for more effective analysis down the road.
### Figure Out Your Assumptions
Identify the assumptions you make as a human analyst and explicitly state them to Orion. Don't assume Orion has background knowledge - provide that extra context upfront, even if it takes a few extra minutes.
Here are some questions to help surface assumptions in data analysis work:
**About the data itself**
* What do you believe is true about how this data was collected?
* What are you taking for granted about the completeness of this dataset?
* What do you assume the values in each field actually represent?
**About the problem and context**
* What do you believe caused the patterns you expect to find?
* What are you assuming about how this data relates to the real-world phenomenon you're studying?
* What do you take as given about the time period this data covers?
**About the analysis approach**
* What must be true about the data for your chosen method to be valid?
* What are you assuming about the relationships between variables?
* What do you believe about how representative this sample is of the broader population you care about?
**About stakeholders and use**
* What are you assuming about what the audience already knows or believes?
* What do you take for granted about how the results will be used?
* What do you assume the decision-maker actually needs from this analysis?
**About yourself**
* What prior beliefs might be shaping which patterns you notice or ignore?
* What are you assuming you understand correctly about the domain?
* Where might your expertise (or lack of it) create blind spots?
## Iterating on Analyses
### Expect Multiple Iterations
**Don't expect the first analysis to be perfect.** Plan for 2-3 iterations before you get a result you're happy with:
1. **First iteration**: Usually gets you to 80-90% - review and provide feedback
2. **Second iteration**: Refine based on feedback, adjust focus and formatting
3. **Third iteration**: This is typically the one you can share or re-use in the future
Think of Orion like a colleague who needs feedback to improve, not a superhuman that gets everything right immediately.
### Two Modes of Work
There are two distinct phases when working with Orion:
1. **Setup phase**: Creating projects and getting initial analyses running
2. **Refinement phase**: Editing insights, adjusting formatting, and fine-tuning outputs
The refinement phase typically takes about 10 minutes to go from 90% to 100% ready.
### Formatting and Editing
After an analysis runs, use chat to:
* Simplify content
* Change formatting
* Adjust specific sections
* Remove or add emojis (you can say "no emojis" if you don't want them)
* Specify chart preferences
You can also configure these preferences in project settings to influence default outputs.
## Managing Memory
### Explicitly Request Memory
**You must explicitly tell Orion to remember things.** Say "remember this" when you want something saved to memory. Orion won't automatically form memories from conversations to avoid saving hallucinations.
Orion may occasionally ask if something should be remembered, but it's more reliable to explicitly request it.
### When to Remember
Remember important information that:
* Applies to the project long-term
* Should influence future analyses
* Represents preferences or requirements
* Helps avoid repeating mistakes
## Organizing Conversations
### When to Start a New Chat
* **Start a new chat** when you want to explore something completely different
* **Use the same chat** for slight variations (e.g., "do this for November instead of October")
### Don't Delete Chats
Keep your chat history. Don't delete chats - let them accumulate. They serve as a record of your work and can be useful for reference.
### Sharing Chats
Use the share feature to share your chats and notebooks with others. Anyone you share a chat with can pick up where you left off in the conversation.
## Troubleshooting and Debugging
### Handling Skepticism
If Orion doesn't get something right the first time, don't lose confidence. It may need:
* More context
* Missing data
* Better instructions
Use the troubleshooting features to help Orion improve rather than assuming it can't handle the task.
## Performance Optimization
### Manage Data Volumes Carefully
**Start small, then expand.** If you eventually want to analyze years of data, don't start there:
1. Begin with a limited date range (e.g., "today and this day last year")
2. Get it working correctly with the smaller dataset
3. Once it's working, expand the date ranges
Starting with billions of rows and years of data is asking for trouble - it's slower, more expensive, and harder to debug.
### Check Data Availability
Before running full analyses, use chat to check data availability. Ask Orion to explore what data is available and identify any gaps or issues upfront rather than waiting for the entire analysis to run.
### Use Tools in the Right Order
Orion has access to exceptional tools, but they need to be used in the right order. Power users can guide Orion to be more efficient by:
* Coaxing out data details upfront
* Identifying missing information early
* Ensuring proper tool sequencing
## Project Settings Tips
### Visualization Preferences
![Visualization preferences settings showing different chart type options]()
In project settings, you can specify:
* Chart types and formats (e.g., "three to five columns of numeric and categorical optimized for waterfall")
* Emoji preferences (you can request no emojis)
* Output formatting preferences
These settings heavily influence insight output, so configure them based on your needs.
### Automation Features
When available, leverage automation features:
* **Calendar integration**: Reference Orion in calendar event descriptions (e.g., "Orion: I will need this data for this meeting")
* **Slack integration**: Orion can remember the last 10-20 messages in channels it's been invited to
* **Scheduled analyses**: Save re-runnable analyses to refresh on a recurring schedule
## Key Takeaways
1. **[One project per use case](#one-project-per-use-case)** - keep things focused
2. **[Expect 2-3 iterations](#expect-multiple-iterations)** - the first analysis won't be perfect
3. **[Be explicit](#be-explicit-and-clear)** - spell out assumptions and requirements
4. **[Use "remember this"](#explicitly-request-memory)** - explicitly request memory formation
5. **[Start small with data](#manage-data-volumes-carefully)** - expand date ranges after it's working
6. **[Use relative dates](#use-relative-dates)** - include "evergreen" for re-runnable or scheduled analyses
7. **[Explore data first](#explore-data-first)** - understand structure before diving in
8. **[Provide context for uploads](#provide-context-for-document-uploads)** - don't assume Orion will figure it out
# File Uploads
Source: https://docs.runorion.com/chat/file-uploads
Bring your own files into an analysis
Upload files to Chat to provide context to Orion or use as data sources in analyses.
## Upload Scope
You have two options for where to upload files:
* **Chat**: Upload a file directly in any chat conversation. The file is available to Orion within that conversation only.
* **Project**: Upload a file to the project itself so it's available as context across all chats in that project.
Use chat uploads for one-off files relevant to a specific question, and project uploads for reference material you want Orion to draw on consistently.
## How to Upload a File
1. Click the **plus icon (+)** in the chat text input area
2. Select **Attach File**
3. Choose one or more files from your computer
4. The files will appear in the chat before you send your message
5. Send your message to include the files in the conversation
You can upload multiple files at once. The maximum is 5 files per message.
## Supported File Types
Orion supports the following file formats for upload:
* **PDF** (.pdf) - PDFs and documents
* **Word Documents** (.doc, .docx) - Microsoft Word files
* **Excel Spreadsheets** (.xlsx) - Excel workbooks
* **CSV Files** (.csv) - Comma-separated values
* **Text Files** (.txt) - Plain text documents
## Two Ways Files Are Used
Orion intelligently determines how to use uploaded files based on context:
### 1. Context for Chat Conversations
Use files to provide context that Orion will read and reason with:
* **Company policies or SOPs** - Help Orion understand your processes
* **Meeting transcripts** - Reference discussions and decisions
* **Research documents** - Provide background information
* **Product specifications** - Share technical details
* **Data samples** - Show examples of data structure or format
* **Analysis guidelines** - Specify how to perform calculations or analysis
When files are used for context in Chat, Orion reads the file content to
inform its responses but doesn't create a separate data source.
### 2. Data Sources in Analysis
**Excel files (.xlsx only)** can be used as data sources for Orion to query directly:
* Upload one or multiple XLSX files
* Orion treats them as queryable data sources
* Each sheet in the XLSX becomes a table that Orion can analyze
* Multiple XLSX files create multiple data sources for the analysis
When you use an XLSX file as a data source, you'll see the file appear in the **right-hand "draft analysis" pane** under the **"Data Sources"** section. This indicates the file is being treated as a queryable dataset for your analysis.
Orion automatically detects whether you're providing a file for context or as
a data source based on your request. For analyses, structure your Excel files
as clean tables with clear column headers.
## Providing Context for File Uploads
When uploading files, especially new documents that Orion hasn't seen before, provide supplemental context about the file to help Orion interpret it correctly:
* **Describe the file contents** - Explain what the file contains and its purpose
* **List column names** (for spreadsheets) - Specify what columns are included
* **Indicate the source** - Mention where the file came from (e.g., "downloaded from GitHub", "exported from our CRM")
* **Explain the context** - Share relevant details about the data (e.g., "this contains merge history for my team members")
Orion can examine the first few rows of a file and make assumptions, but providing this additional context upfront makes a substantial difference in how Orion interprets and uses the file in your analysis.
## File Upload Tips
* **File size** - Keep files reasonably sized for faster uploads (typically under 10MB)
* **Multiple files** - Upload multiple XLSX files at once for complex analyses
* **Excel structure** - Use clear column headers and avoid merged cells for best results in analyses
* **Privacy** - Only upload files with appropriate data you're comfortable sharing with Orion
Be cautious when uploading files containing sensitive information. Ensure you
have appropriate permissions to use the data.
# Memory
Source: https://docs.runorion.com/chat/memory
Teach Orion preferences that persist across conversations
Orion's memory system lets it retain your preferences, project-specific context, and data requirements across conversations. Tell Orion to "remember this" explicitly, and it will apply that knowledge to every future analysis in the project, making results faster and more accurate over time.
## Overview
* [What is memory?](#what-is-memory)
* [How is memory isolated?](#how-is-memory-isolated)
* [What can be remembered?](#what-can-be-remembered)
* [How does memory work?](#how-does-memory-work)
* [What are best practices for memory?](#what-are-best-practices-for-memory)
* [FAQs](#faqs)
## What Is Memory?
Memory allows Orion to retain important information about your preferences, project specifics, and data requirements across conversations. The more context Orion has, the better it can build insights tailored to your needs.
## Quick Start
In [Chat](/chat/basics-navigation), you can ask Orion to remember something, check what it remembers, or update and remove memories.
**Ask Orion to remember something:**
> "Remember that we always use the Q4 filter for year-end reports"
**Check what Orion remembers:**
> "What do you remember about this project?"
**Update or remove a memory:**
> "Forget that I preferred pie charts - I now want bar charts instead"
You'll see a notification when Orion saves a memory. There's no dedicated memory page, but you can ask Orion what it remembers at any time.
## How Is Memory Isolated?
Memory is isolated to each project by default. The **Private Project** toggle controls this:
* **New projects:** Below the project description in the "New Project" menu
* **Existing projects:** Settings → Details tab (bottom of page)
This toggle is **on by default**. When enabled, Orion won't access memories from other projects, keeping your data and preferences organized.
## What Can Be Remembered?
Memory captures anything that helps Orion understand your needs: project-specific filters and data structures, format and visualization preferences, calculation methods, recurring workflows, and quality standards.
**Examples:**
* "We always run reports on the first of the month"
* "I prefer weekly summaries with three bullet points and clear action items"
* "Use the regional breakdown for all sales analyses"
If it's relevant to how you work with Orion, it's worth remembering.
## How Does Memory Work?
Orion creates memories through two paths:
**Automatic detection:** During conversations, Orion may flag important information and add it to memory. You'll see a notification when this happens.
**Explicit requests:** For critical information, tell Orion directly: "Remember that I prefer data tables over pie charts."
![Memory Saved notification]()
Be explicit for important information. Don't rely solely on automatic
detection for critical preferences.
## What Are Best Practices for Memory?
**Start early.** Set up memory when you begin a project to establish preferences from the start.
**Be specific:**
* ✅ "Remember that I prefer weekly summaries with three bullet points and clear action items"
* ❌ "Remember my preferences"
**Review periodically.** Ask Orion what it remembers and update as your needs evolve.
**Focus on patterns.** Memory is most valuable for information that applies across multiple conversations. Don't worry about one-off requests.
**Be project-aware.** Since memory is project-specific, set it up in each project where you need it.
## FAQs
**Q: Does memory transfer between projects?**
A: No. Memory is isolated to each project by default. Set up memory in each project where you want Orion to remember specific information.
**Q: How do I update or remove a memory?**
A: Tell Orion what changed: "Forget that I preferred pie charts - I now want bar charts instead."
**Q: How does memory improve my experience?**
A: Memory provides context that helps Orion build better insights. The more it understands about your preferences and requirements, the more accurate and useful its analyses become.
# Rooms
Source: https://docs.runorion.com/chat/rooms
Work with teammates and Orion in one shared chat
A room is a chat conversation with more than one person in it. Everyone in a room shares one
thread: the same history, the same analyses, and Orion's answers as they stream in. Rooms are how
a team investigates a question together instead of pasting results back and forth.
Everything on [Basics & Navigation](/chat/basics-navigation) still applies. A room is a normal
conversation that happens to have more than one participant.
## Rooms vs. Sharing a Copy
[Sharing a conversation](/chat/share-conversations) and starting a room are different things:
* **Send a copy.** The link is read only. The recipient reads the history, then continues it as
their own separate conversation. You never see what they do next.
* **Start a room.** Everyone stays in the same conversation. All participants post into it, see
each other's messages, and watch Orion work live.
Send a copy to hand work off. Start a room to do the work together.
Rooms cannot be copied. Once a conversation has more than one participant, the copy link is no
longer offered, because forking a room would hand one person a private duplicate of everyone
else's messages.
## Start a Room
The **+** sits in the **Rooms** header of the chat history sidebar.
![The Rooms header in the chat history sidebar, with the plus button outlined in red]()
Search by name or email. Each person you select moves up to the invite list. Nothing exists
yet at this point, so you can still remove anyone or cancel.
![The Start a room dialog, with two people staged on the invite list and the Create room button enabled]()
Orion creates the room and opens it for you.
## Turn an Existing Chat Into a Room
Any solo chat becomes a room the moment you add someone to it.
Go to the chat you want to work on together.
On a solo chat the control is labeled **Share**.
Search by name or email and select them.
They join this conversation, not a copy of it, and they see everything already in it from the
beginning. Once the conversation is a room, the same control is labeled **People** and shows the
participants' avatars.
Adding someone exposes the whole transcript to them, including anything discussed before they
joined. The dialog warns you before you add.
![The People dialog on an existing room, showing Add people with a search box, the In this room roster with the owner marked You and a remove control beside the other member, and the How Orion responds options]()
## Finding Your Rooms
The chat history sidebar splits into two sections, **Rooms** and **Chats**. Room rows carry a stack
of participant avatars, so you can tell at a glance who is in each one. Five rooms show by default,
and **Show all** expands the rest.
Rooms are not confined to the full-page chat. A room can also be open in the chat panel beside
a report, a dashboard, or a slide deck. That panel shows the participant avatars, the sender name
on each message, and `@orion`.
## Who Can Add and Remove People
* **The conversation owner** adds and removes participants. Orion enforces this server side, so the
controls do not appear for anyone else.
* **Any participant** can leave. Open the three-dot menu on the room's row in the sidebar and choose
**Leave room**.
* **Tenant admins** can read a room they are not in, but cannot post to it. They see a banner saying
so instead of the chat input.
Leaving does not erase history. Your earlier messages stay in the transcript, attributed to you.
## Addressing Orion and Teammates
In a room, Orion does not answer every message. You address it with `@orion`.
Type `@` in the chat input and pick **Orion** from the menu, or type `@orion` directly. The mention
renders as a chip in the sent message. Clicking a suggested follow-up or a recommendation inside a
room addresses Orion for you.
The `@` menu also lists the people in the room, next to content such as a metric or a wiki page.
Pick a teammate to mention them, and the mention renders as a chip with their name. If they have
the room open in a background tab, they hear a sound, and their browser shows a notification if
they have allowed notifications from Orion.
## How Orion Responds
Rooms have two response modes. Change them in the **People** dialog, under **How Orion responds**:
| Mode | What Orion does |
| - | - |
| **When mentioned** (default) | Replies only when you `@orion`. |
| **Listening** | Replies when a message looks meant for it, and whenever you `@orion`. |
A new room starts in **When mentioned**, including a solo chat you have just added someone to. In
either mode, `@orion` always gets a reply.
Any participant can change the mode, and the change applies to everyone in the room. Viewers are
the exception: a Viewer can change it only in a room they own.
Solo chats work differently: Orion replies to every message, and the setting is not offered.
Each change is recorded in the room's timeline, so the transcript shows a notice like
"Priya set Orion to listening" at the point it happened.
## Replying to a Specific Message
Rooms add a **Reply** action to messages. Select the reply arrow on a message, and it appears as a
quote card above the chat input. The card stays on your message after you send it, so a busy room
still reads in order.
You cannot reply to your own message, or to a message that is still streaming.
## What You See While Orion Works
* **Typing indicators.** Avatars appear above the chat input while a teammate is typing, and while
Orion is working on a turn.
* **Everyone watches the same answer.** Participants see Orion's response, including notebook cells,
as it is generated, not after it finishes.
* **Streams survive a reload.** If your connection drops or you refresh mid-answer, you rejoin the
stream in progress. Opening a room while a turn is already running catches you up on it.
## Room Activity
Rooms show light activity notices inline in the transcript:
* "You started this room"
* "Priya added Marcus"
* "Marcus left this room"
* "Priya set Orion to reply only when mentioned"
A run of similar notices collapses into one line, such as "You added Dana plus 9 others",
with the full list on hover. Inviting ten people costs one line, not ten.
## Important Notes
* **Rooms cannot be forked** - the read-only copy link is offered on solo chats only
* **Attribution comes from the server** - names and avatars are resolved from the room's participant
list, not from anything the browser sends
* **Response mode is per room** - it does not change the defaults for your other conversations
* **Leaving preserves history** - your past messages stay in the transcript after you leave
# Running Analyses
Source: https://docs.runorion.com/chat/running-analyses
Ask a question and get an analysis back
To run an analysis in Orion, open a project, type a question in plain language, and Orion writes the query, runs it against your connected data sources, and returns results (charts, tables, and code) directly in chat. Every analysis is captured as a reusable notebook you can re-run for fresh data, schedule on a recurring cadence, or turn into a report, dashboard, or slide deck.
## Quick Start
1. **Create or select a [Project](/core-concepts/projects)**: Click "New Project" or select an existing one. When creating a new project, you'll be prompted to select from the [data sources](/configuration/data-sources) your administrator has connected.
2. **Open Chat and ask your question**: Type your question in the Chat interface. Orion gets to work immediately, querying your data and returning results inline.
3. **Review and refine**: Ask follow-up questions, request edits, or adjust formatting. Your analysis stays in your chat history as a notebook you can return to and re-run any time.
## How Analysis Works
When you ask Orion to analyze something, it writes and runs code, queries your connected data sources, and returns results inline in your chat, with no waiting.
You can ask natural language questions like:
* "What were our top 10 customers by revenue last quarter?"
* "Show me a breakdown of churn by product line over the last 90 days"
* "Compare this month's signups to the same period last year"
Be specific and provide context. Clear questions and explicit guidance help
Orion understand your needs. The more context you provide upfront, the better
your results.
## What is a Notebook?
A notebook is Orion's record of an analysis: the instructions, the logic, and the code. Orion captures it automatically as the analysis runs and keeps it in your chat history, so there is no save step. Return to it any time to re-run it and get fresh results.
Notebooks are especially powerful when combined with [relative (evergreen) date ranges](/chat/best-practices#use-relative-dates). Because the analysis uses instructions like "last 30 days" rather than hardcoded dates, re-running a notebook always reflects the most current data.
## What You Can Do After an Analysis
Your analysis is automatically kept as a [notebook](#what-is-a-notebook) in your chat history, so there is no save step. From there you can:
* **Schedule it**: Set the notebook to run automatically on a daily, weekly, or custom schedule
* **Share or publish**: Share the results with teammates or publish as a dashboard
* **Pin metrics**: Pin key numbers from the analysis as metric tiles for at-a-glance tracking
* **Get a report**: Generate a formatted report from the analysis output
* **Get slides**: Turn the analysis into a presentation-ready slide deck
* **Ask follow-up questions**: Continue the conversation to dig deeper, refine results, or kick off a new related analysis
## How Orion Improves Over Time
Orion becomes a better analyst through three mechanisms:
* **[Memory](/chat/memory)**: Learns your preferences, project specifics, and data requirements
* **[Feedback Loops](/chat/best-practices#iterating-on-analyses)**: Each refinement helps Orion understand your expectations
* **[Context](/core-concepts/knowledge-base)**: Structured business context Orion applies across every analysis
Start early with context. Enable Context pages and use Memory from the
beginning. The more context you provide upfront, the faster Orion adapts.
## Next Steps
Tips for getting the most out of your analyses
Bring your own data into an analysis
Help Orion remember preferences and context across analyses
Organize your work and set project-level instructions
# Share Chat Conversations
Source: https://docs.runorion.com/chat/share-conversations
Hand a conversation to a teammate to continue
Share any Orion chat conversation with a teammate by copying a link. The recipient sees the full conversation history and can continue the analysis independently from where you left off.
To keep working in the same conversation instead of handing over a copy, start a [Room](/chat/rooms).
## How to Share a Conversation
When you find a conversation that would be helpful for someone else on your team, you can easily share it:
1. **Select Share** - The control sits at the top right of the conversation
2. **Copy the link** - In **Share this chat**, copy the link to your clipboard
3. **Share with your team** - Send that link to whoever needs access to the conversation
The same dialog also holds **Work on it together**, which adds someone to this conversation instead
of handing them a copy. That turns it into a [Room](/chat/rooms).
![Share Chat button in the chat interface]()
## What Happens When Someone Opens Your Shared Conversation
When a team member opens your shared conversation link, they'll see:
* A blue conversation box that displays the full conversation history
* A message indicating this conversation was shared with them
* The ability to continue the conversation as their own
![Recipient view of a shared chat, prompting the user to continue the conversation.]()
## Important Notes
* **Conversations are isolated** - All chat history is isolated to specific users and projects
* **Continue independently** - Once someone continues a shared conversation, the original user won't see their messages from that point forward
* **Great for onboarding** - Sharing conversations is a great way to help team members understand how conversations work and see examples of effective interactions with Orion
# Company Information
Source: https://docs.runorion.com/configuration/company-information
Company context Orion applies to every project
Company Information allows administrators to provide comprehensive context about your organization that Orion will reference across all [projects](/core-concepts/projects) and [conversations](/chat/basics-navigation).
## Accessing Company Information
1. Go to **Configuration** in the left-hand navigation menu
2. Select the **Company Information** tab
## What to Include
The Company Information section is where you store global company context. This is a large text field where you can provide:
### Data Context
* **Data sources** - Where your company data comes from
* **Data pipeline** - How data flows through your systems
* **Update frequency** - When and how often data is updated
* **Data quality notes** - Any important caveats or considerations
### Business Context
* **Company overview** - Your company mission, focus areas, and goals
* **Business terminology** - Industry-specific terms and definitions
* **Acronyms** - Common abbreviations used in your organization
* **Business rules** - Key processes and policies that affect data
### Domain Knowledge
* **Organizational structure** - How teams and departments relate
* **Key metrics** - Important KPIs and how they're calculated
* **Historical context** - Important events or changes that affect analysis
* **Industry nuances** - Sector-specific factors relevant to your data
## How Orion Uses Company Information
The information you provide in Company Information:
* **Applies globally** - Used across all projects and conversations for every user
* **Improves accuracy** - Helps Orion understand context and make better recommendations
* **Enhances insights** - Ensures analyses align with your business reality
* **Saves time** - Users don't need to repeat context in each project
## Best Practices
The more comprehensive and detailed your Company Information, the better Orion
can serve your entire organization. Update this section whenever significant
business changes occur.
# Data Sources Management
Source: https://docs.runorion.com/configuration/data-sources
Connect and manage the data sources your tenant queries
Orion connects to three kinds of source: your data warehouse, the tools holding your business logic, and a few services that add outside context. Administrators connect each one once, at the tenant level.
## Accessing Data Sources
1. Go to **Configuration** in the left-hand navigation menu
2. Select the **Data Sources** tab
![The Data Sources tab in Configuration, showing connected data source tiles]()
Once you've set up access on the source side (service accounts, API keys), this page is where you enter those connection details.
BigQuery needs one value from Orion as well. The connection form shows the Orion service account that you grant access to in Google Cloud. You never have to ask us for it. See [Connecting Data Sources](/connecting-data-sources#bigquery) for the full setup.
## How Data Sources Work
Data sources are configured at the tenant level and made globally available:
* **Tenant-level setup** - Administrators connect data sources once in Configuration
* **Tenant-wide by default** - Connected data sources are available across the tenant, subject to each user's role and group membership
* **Role limits** - What a user can do with a data source depends on their [role](/configuration/groups#roles-at-a-glance): Admins manage connections, Analysts query them, and Viewers query only where a project owner allows it
* **Group scoping** - [Groups](/configuration/groups) limit which data sources their members can use
* **Project-level selection** - Each [project](/core-concepts/projects) can choose which data sources to use
* **Multiple data sources** - A project can connect to multiple data sources simultaneously
## Supported Data Sources
Orion currently supports connections to:
* **BigQuery** - Google's data warehouse platform
* **Snowflake** - Cloud data platform
* **Databricks** - Lakehouse data platform
* **Redshift** - Amazon's cloud data warehouse
* **Amazon Athena** - Serverless SQL over data in S3, via the AWS Glue catalog
* **Microsoft Fabric** - Microsoft's analytics warehouse
* **PostgreSQL** - Open-source relational database
* **MySQL** - Open-source relational database
* **Delta Lake** - Delta tables on cloud storage (ADLS Gen2 or GCS)
* **MotherDuck** - Hosted DuckDB, queried with DuckDB SQL
* **Looker** - Dashboards, Looks, and LookML business logic
* **dbt** - Model metadata and lineage, used to enrich a warehouse connection
Two lightweight external-context sources round out the list:
* **News API** - News headlines pulled into analyses for external context (free newsapi.org key)
* **Weather** - Historical and forecast weather from Open-Meteo, no key required
For the credentials, grants, and step-by-step setup each source needs, see [Connecting Data Sources](/connecting-data-sources).
Beyond these tenant-level connections, users can also upload Excel files in chat and query them as ad hoc data sources for a single analysis. See [File Uploads](/chat/file-uploads).
## Adding a Data Source
As an administrator, you can:
1. Click the **Add Data Source** tile
2. Select the type of data source from the supported list
3. Provide the necessary connection credentials and configuration
4. Save the connection
![The Choose a data source modal. Source types appear as two columns of cards, each with an icon, a name and a one-line description, and the list scrolls to more types below the fold]()
The data source is now available for all users to select when setting up projects.
Each data source has its own access requirements. See [Connecting Data
Sources](/connecting-data-sources) for the credentials, grants, and network
access each one needs.
## Managing Data Sources
Administrators can:
* **Update credentials** - Change connection details if needed
* **Monitor status** - Check the health of data source connections
* **Remove data sources** - Disconnect data sources from the tenant
* **View usage** - See which projects are using each data source
Start with one or two data sources and expand as your team's analytical needs
grow.
# Global Configuration
Source: https://docs.runorion.com/configuration/global-configuration
The admin hub for tenant-wide settings
Global Configuration is the admin hub for tenant-wide settings (company information, data source connections, and user management) that apply to every user and project in your Orion instance.
This section is for tenant administrators. Configuration changes affect all
users in your Orion tenant.
## Accessing Global Configuration
As an administrator, access Global Configuration from the left-hand navigation menu by clicking on **Configuration**.
## Configuration Tabs
Global Configuration is organized into several tabs:
### Company Information
Store company-wide context and information that applies to all projects and conversations. See [Company Information](/configuration/company-information) for details.
### Data Sources
Connect and manage data sources for your entire tenant. See [Data Sources Management](/configuration/data-sources) for details.
### User Management
Manage tenant users and their permissions. See [User Management](/configuration/user-management) for details.
## Important Notes
Changes made in Global Configuration affect all users in your tenant. Ensure
you have the necessary permissions before making changes.
Configuration is still being enhanced with additional features and capabilities. Check back for updates.
# Groups
Source: https://docs.runorion.com/configuration/groups
Model teams and departments as shared-access units
Groups let you organize users into cohorts that share access to the same set of [projects](/core-concepts/projects), [data sources](/configuration/data-sources), [Context](/core-concepts/knowledge-base) pages, and [Integrations](/knowledge-base/wiki-integrations). Use them to model teams, departments, end customers, or any other grouping that maps to a set of people who should see the same resources.
## When to use Groups
Sales, Marketing, Finance, and Operations each get their own group with the
projects, data sources, and Context pages relevant to their work.
Agencies and consultancies can give each end customer their own group,
keeping their projects and data isolated from other customers in the same
tenant.
A user can belong to several groups at once, for example an executive who
needs visibility into Sales, Marketing, and Operations.
If you don't create any groups, Orion behaves exactly as before. Groups are an
additive feature: your existing users, projects, and permissions are
unaffected until you opt in by creating a group.
## Accessing Groups
Group management lives alongside user management in **Settings → Manage Users**. The page has two tabs: **Users** and **Groups**.
![Groups tab in Manage Users showing existing groups with member and project counts]()
## Creating a Group
From the Groups tab, click **+ New Group**. Give the group a clear name and an optional description.
![New Group dialog with Name and Description fields]()
If a non-admin user creates a group, they automatically become its first Group Admin. Tenant Admins who create groups manage them via their tenant role and are not added as members.
### Naming Groups with Prefixes
When creating a group, the modal offers the option to select a **prefix** or choose no prefix. Prefixes are a purely organizational label: they make related groups sort and display together, but confer no shared access or functional relationship between groups. A group named `Verizon / Sales` and one named `Verizon / Marketing` are completely independent; the prefix just keeps them visually adjacent.
The first group you create under a prefix acts as the **catch-all group** for that prefix, a landing zone you can add users to before their specific sub-group is ready. For example, you might create `Verizon` first, add new users there while you're still setting up sub-groups, then move them into `Verizon / Sales` or `Verizon / Marketing` once those are configured.
Use prefixes consistently from the start. It is significantly harder to
reorganize groups after members and projects have been added. A naming
convention like `[Customer] / [Team]` or `[Department] / [Sub-team]` works
well for most organizations.
## Group Roles
Each user has a role **within each group they belong to**. A group role only controls what someone can do inside that group: it is separate from and independent of their tenant role.
Manage everything in the group: add and remove members, add projects, data
sources, Context pages, and integrations, and delete the group.
Full working access to everything in the group. Can create new projects and
share them with others. Can also create new groups and automatically becomes
the Admin of any group they create.
Read-only access to the group's projects, data, Context pages, and
integrations. Cannot manage group settings or data source configuration, and
can query data only where a project owner allows it.
### Roles at a Glance
The table below covers the six roles you assign, across both levels, tenant and group. Tenant roles apply across the entire Orion instance; group roles apply only within the specific group.
| Capability | Admin | Analyst | Viewer | Group Admin | Group Analyst | Group Viewer |
| - | :-: | :-: | :-: | :-: | :-: | :-: |
| **Scope** | Full tenant | Projects they belong to | Approved projects | Own group(s) only | Own group(s) only | Group projects only |
| Invite users to tenant | ✓ | - | - | ✓³ | - | - |
| Manage tenant-wide settings & data sources | ✓ | - | - | -⁴ | - | - |
| See all users, groups & projects | ✓ | - | - | - | - | - |
| Create groups | ✓ | - | - | ✓ | ✓¹ | - |
| Manage group members | ✓ | - | - | ✓ | - | - |
| Manage group data sources, KB & integrations | ✓ | - | - | ✓ | - | - |
| Delete a group | ✓ | - | - | ✓ | - | - |
| Create & share projects | ✓ | ✓ | - | ✓ | ✓ | - |
| Run analyses & chat | ✓ | ✓ | - | ✓ | ✓ | - |
| View accessible projects | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| Query data sources | ✓ | ✓ | Per-project² | ✓ | ✓ | Per-project² |
1. A Group Analyst automatically becomes Group Admin of any group they create.
2. Project owners can extend Viewer access to allow data queries on a per-project basis in Project Settings.
3. Group Admins can invite new users to the tenant through the group's **Invite by email** flow, but not through Settings directly.
4. A Group Admin can still open **Configuration → Data Sources**, **Integrations**, and **Users**: an admin seat in any group admits them to those tabs. What they manage there is their own groups' resources, not the tenant's settings.
**Tenant roles and group roles are independent.** A tenant Viewer can be a
Group Admin. A tenant Analyst can be a Group Viewer in one group and a Group
Admin in another. Orion always evaluates the role that applies to the specific
resource someone is trying to access, so what a user can do in chat, sharing,
and editing may differ from one project to the next.
### Users with roles across multiple groups
Tenant Admins always have full visibility across every group. For everyone else (tenant Analysts and Viewers), group roles can vary between groups. A user can simultaneously be:
* A **Group Admin** in a group they created or were promoted in
* A **Group Analyst** in a colleague's group they were invited to contribute to
* A **Group Viewer** in a third group where they only need read access
This means two users with the same tenant role may have very different effective access depending on which groups they belong to and what roles they hold there. When troubleshooting unexpected access, check both the user's tenant role and their role within each relevant group.
## Onboarding new users
Whether you're adding an internal teammate or one of your customers, the safest default is the same: invite them as a tenant **Viewer**, then layer their real access on top through groups.
A tenant Viewer is a blank canvas: they cannot see any projects, data sources, or Context pages by default. From there, add them to the right group(s) with a group role that matches what they need to do:
* **Group Viewer**: read-only access to the group's projects, data, Context, and integrations
* **Group Analyst**: full working access; can create and share projects within the group
* **Group Admin**: full administrative control of the group, including adding members
This keeps tenant-wide settings and any unrelated projects off-limits while giving the user everything they need inside their group. The pattern works equally well for an internal employee joining a single team and for a customer who should only see their own group's projects.
The [**Invite by email**](#inviting-new-users-directly-into-a-group) flow from inside a group is the fastest way to apply this pattern:
From the group's detail page, click **Add member**, then **Invite by email**
at the bottom of the picker.
Choose **Viewer**. This is the user's baseline across the entire tenant and
keeps everything outside their group off-limits.
Choose **Group Admin**, **Group Analyst**, or **Group Viewer** based on what
they need to do inside this group.
The invitee receives an email and, on first login, lands in Orion with both
roles applied automatically.
Reserve tenant **Admin** and **Analyst** roles for people who genuinely need
tenant-wide reach. For everyone else (internal or external), "tenant Viewer +
Group \[role]" is the safest default.
## Managing a Group
Click any group from the Groups tab to open its detail view. From here you can manage everything the group has access to using the tabs along the top.
![Group detail view showing the Members tab with tabs for Projects, Data Sources, Context, and Integrations]()
The header shows who created the group and when. Click the group name or description to edit them inline.
### Members
The Members tab lists everyone in the group along with their group role.
#### Adding existing users to a group
Click **Add member** to open the member picker. The list shows users from your tenant who aren't already in the group. Pick the role they should have within the group, then add them.
![Add Members modal with a search field, a list of candidates, and a Join as role picker]()
#### Inviting new users directly into a group
If the person you want to add isn't in your tenant yet, click **Invite by email** at the bottom of the picker. You'll select their tenant role first (Admin, Analyst, or Viewer), then their group role. The invitee will receive an invitation email and, on first login, lands in Orion with both roles applied.
Inviting users directly into a group is the fastest way to onboard a new team
or customer cohort. They land in Orion already configured with the right
access, no second step required.
### Projects
The Projects tab lists the group's projects. Everyone in the group can access them with permissions matching their group role.
![Group detail view on the Projects tab showing the group's projects]()
Click **Add project** to add more projects to the group. The picker shows projects you have access to.
![Add Projects modal with a checkbox list of projects and a selection counter]()
A single project can belong to more than one group, useful for shared work that spans multiple teams.
Creating a new project does not automatically add it to a group. A project
belongs only to the user who created it until a Group Admin or Group Analyst
explicitly adds it to the group from this tab.
### Data Sources
When a project is added to a group, the [data sources](/configuration/data-sources) attached to that project automatically become available to everyone in the group, so you don't need to enable them separately. The Data Sources tab is **additive**: use it to expose data sources to the group *beyond* what its projects already provide.
![Group detail view on the Data Sources tab with a checkbox list of available data sources]()
### Context
The Context tab controls which [Context](/core-concepts/knowledge-base) pages and folders the group can use. You can select individual pages or whole folders.
Each linked page also has an **Auto-inject** switch: when on, the page is automatically included in chat context for everyone in the group, with no per-project enablement needed. See [Default Pages (Auto-Inject)](/knowledge-base/creating-pages#default-pages-auto-inject).
![Group detail view on the Context tab showing a folder tree with checkboxes]()
Selecting a **whole folder** means any new pages added to that folder later
are automatically available to the group. This is the easiest way to keep a
department's reference material in sync as it grows.
### Integrations
The Integrations tab controls which [integrations](/profile-settings/integrations) the group has access to.
![Group detail view on the Integrations tab showing connected integrations]()
## How users get access to a project
A user can be given access to a project in two ways:
1. **Through a group**: they're a member of a group that the project belongs to. Their permissions match their role in the group.
2. **Directly**: they were invited to the project individually from the project's Share menu, independent of any group.
The two methods work side by side. Removing someone from a group doesn't cancel any direct invite they have, and removing a direct invite doesn't remove them from the group.
The Project Settings modal shows which groups currently have access to the project, alongside its other settings.
## Deleting a Group
To delete a group, open it, select the **Settings** tab, then click **Delete Group**. The group card's **...** menu offers the same action.
![The Analytics group's Settings tab in Admin Settings, with Delete Group outlined in red below the Danger zone heading]()
The confirmation dialog summarizes what will happen:
![Delete group dialog showing confirmation steps]()
* **Members** lose access to anything they only had through this group. They keep any direct project access they were granted individually.
* **Projects** that are only used by this group can either be transferred to the group's Admins (who keep access individually) or deleted along with the group.
* **Data Sources, Context pages, and Integrations** are not deleted, they simply leave the group.
Type the group's name to confirm, whether or not you also delete its projects.
Deleting a group is permanent. The group and its membership are gone for good.
Members who had no other way to access projects will be left as Viewers with
no projects to see until someone adds them again.
# SSO
Source: https://docs.runorion.com/configuration/sso
Allow users to sign in with their identity provider
Single sign-on (SSO) allows users to sign in to Orion through your identity provider instead of using an Orion password. Invitations from [User Management](/configuration/user-management) create accounts one at a time. An SSO provider authenticates users and creates an account when no matching Orion account exists. Allowed domains and optional group mappings determine who can complete sign-in.
Orion supports compatible identity providers that publish an OpenID Connect discovery document, issue RS256-signed ID tokens, and support an authorization code exchange with a client secret. Register Orion as an application with your provider, then enter its issuer, client ID, and client secret in Orion. You also choose the provider name shown on the login page. Orion uses the issuer to discover the authorization endpoint, token endpoint, and signing keys.
## Before you start
Create an OAuth application in your identity provider first. Orion uses the authorization code flow and requests the `openid`, `email`, and `profile` scopes.
Register this redirect URI on that application:
```
https://g.runorion.com/oidc/callback
```
Identity providers name that field differently. Look for a redirect URI, a callback URL, or a sign-in redirect URI.
Save these three values for the setup in Orion:
| Value | What Orion requires |
| - | - |
| **OIDC Issuer URL** | Starts with `https://`, and serves a discovery document |
| **OAuth Client ID** | The client ID of the application you just created |
| **OAuth Client Secret** | At least 24 characters |
Your identity provider must report the user's email address as verified. Orion rejects a sign-in when the token does not confirm this, because an unverified address could belong to another user.
Create any [Groups](/configuration/groups) you plan to assign through SSO before you configure the provider. The mapping editor only lists groups that already exist.
## Accessing SSO Configuration
Only tenant Admins can access **SSO Configuration**. A group administrator without the tenant Admin role cannot open it.
1. Open **Configuration** in the left-hand navigation menu
2. Select **SSO Configuration** in the **Admin Settings** sidebar
When no providers exist, the page shows **No SSO Providers Configured** and one button: **Add Your First OIDC Provider**.
On a shared trial tenant the **SSO Configuration** entry appears but stays
disabled. Sign-in providers are configured per tenant, and a trial tenant is
shared with other companies.
## Adding an OIDC provider
1. Click **Add OIDC Provider**, or **Add Your First OIDC Provider** for the first one
2. Enter a **Provider Name**. The login page displays it after **Continue with**, so choose a name users will recognize
3. Enter the **OIDC Issuer URL**, **OAuth Client ID**, and **OAuth Client Secret**
4. List the domains you admit under **Allowed Email Domains**, pressing Enter, Tab, or comma after each one
5. Click **Create Provider**
![The Add OIDC Provider dialog, showing the Provider Name, OIDC Issuer URL, OAuth Client ID and OAuth Client Secret fields in order, then a blue OAuth Application Setup panel carrying the redirect URI, above the Cancel and Create Provider buttons]()
A new provider is enabled as soon as you create it. Its sign-in button can take up to five minutes to appear on the login page. Once it appears, users who meet the allowed-domain and group-mapping rules can sign in.
Leaving **Allowed Email Domains** empty admits every domain your identity
provider will authenticate. Add the domains you own before you create the
provider, not afterwards.
**Portal Visitor Domains** and **Enable Provider** are available only in the **Configure** dialog. Create the provider, then open **Configure** to set them.
## Restricting who can sign in
**Allowed Email Domains** controls which email domains are eligible to sign in. Orion rejects other domains before creating or reusing an account and tells the user to contact their administrator.
Users at an allowed domain can sign in without an invitation if they also satisfy any group mappings. Only add domains you control.
Orion highlights allowed domains that are not also portal visitor domains in an amber notice. Review this notice for domains that should have portal-only access.
## Portal visitor domains
A portal visitor can only open pages shared with them. To give external users portal-only access, add their domain to both **Allowed Email Domains** and **Portal Visitor Domains** in **Configure**. If **Allowed Email Domains** is empty, add the domain only to **Portal Visitor Domains**, but remember that every domain your provider authenticates remains eligible to sign in.
New users from allowed domains that are not on the visitor list receive **Viewer** accounts. Existing Orion accounts keep their current tenant role.
## Mapping domains or claims to groups
Open **Configure** for the provider. The **Group Assignment** section offers two options: **Map domains to groups** and **Map claims to groups**. Both create a table where each row defines a value, **Group**, and **Role**.
**Map domains to groups** uses the `hd` claim. When a provider omits `hd`, Orion derives the value from the user's verified email domain. For other values, use **Map claims to groups** and enter a **Claim Name** the provider sends, such as `groups` or `department`.
![The Claim-to-Group Mapping card with Claim Name set to groups, then two rows: claim value analytics mapped to the Analytics group as Analyst, and finance mapped to the Finance group as Viewer, with an Add mapping button below]()
**Role** controls what the user can do inside that group: **Admin**, **Analyst**, or **Viewer**. It does not change their tenant role. See [Groups](/configuration/groups#roles-at-a-glance) for a comparison of all six roles.
Orion checks the mappings at every sign-in. If a user's claim value no longer matches, Orion removes the membership created by that mapping. It never changes or removes memberships added manually by an administrator.
Once mappings exist, every user's token must match at least one row. Orion
rejects the sign-in when no row matches. Add a row for every expected claim
value, or remove the mapping.
## What happens when a user signs in
When no matching Orion account exists, the first sign-in creates one. New users from a portal visitor domain receive the **Visitor** tenant role. All other new users receive the **Viewer** tenant role. Later sign-ins never change that tenant role. Change tenant roles from **Manage Users** when users need more access. Group memberships managed through SSO are refreshed at every sign-in.
If the email address matches an existing Orion account, Orion reuses that account and keeps its current role. Email matching ignores letter case.
Password sign-in stays available alongside your SSO buttons. Ask your Gravity
contact if you want the login page to offer single sign-on only.
## Enabling, testing, and deleting a provider
Each provider row includes **Configure**, a **Details** accordion, and an **Enabled** or **Disabled** badge. Expand **Details** to view the issuer, a truncated client ID, and two actions.
* **Configure** edits everything, including the **Enable Provider** switch. Leave **OAuth Client Secret** empty to keep the secret you already stored.
* **Test Connection** confirms that the provider record exists and is enabled. It does not perform a sign-in or validate credentials. The button is unavailable while a provider is disabled.
* **Delete Provider** asks for confirmation, then removes the provider.
![The SSO Configuration screen reached from the Admin Settings sidebar, with one provider named Company SSO carrying an Enabled badge, a Configure button, and an expanded Details panel showing its issuer and a truncated client ID. Test Connection is outlined in red, beside a red Delete Provider button]()
Turning **Enable Provider** off preserves the configuration and removes the provider's button from the login page.
Deleting a provider cannot be undone. Its allowed domains, portal visitor
domains, and group mappings go with it, and users cannot sign in through it
again. Accounts and group memberships created through it stay exactly as they
are.
## When a change takes effect
Provider changes can take up to five minutes to appear on the login page, because it caches the list of enabled providers for five minutes. This delay applies when you add, rename, enable, or disable a provider.
Domain rules and group mappings apply at the next sign-in. They do not affect existing sessions.
## Troubleshooting
When Orion rejects a sign-in, it displays the reason and tells the user to contact their administrator:
| What the user sees | What to change |
| - | - |
| "Your email domain is not permitted for this sign-in method" | Add their domain to **Allowed Email Domains** in **Configure** |
| "Your account does not match any access group configured for this workspace" | Add a mapping row for their claim value, or remove the mapping |
| "Your sign-in token is missing information this workspace requires" | The claim named in **Claim Name** is absent from their token. Check that your provider sends it, or switch mapping mode |
| "Your identity provider did not report your email address as verified" | Mark the address as verified in your identity provider |
| "This sign-in method is disabled" | Turn **Enable Provider** back on |
| "This sign-in method is misconfigured" | Check the issuer, client ID, and client secret in **Configure** |
If sign-in fails after **Test Connection** passes, check the redirect URI, client secret, and scopes on the OAuth application.
If a change locks every administrator out of your tenant, contact Gravity support.
## Next Steps
Create the groups your claim mappings assign, and see what each group role
can reach
Set tenant roles, invite the users your provider does not cover, and audit
who has access
# Sudo
Source: https://docs.runorion.com/configuration/sudo
Act as another user, or let Gravity support do it
Sudo lets an admin temporarily act as another user, useful when a teammate reports a bug you can't reproduce, or when Gravity support needs to investigate something specific to your tenant. A banner sits across the top of every page during a sudo session so you always know you're acting on someone else's behalf, and every session is recorded in your tenant's activity log.
## Two ways to use Sudo
A tenant admin opens **Manage Users**, finds a user in their tenant, and
clicks **Sudo**. No invitation needed: admins already have full authority
in the tenant.
A tenant admin invites a Gravity support engineer by email and sets how long
the access lasts. The engineer signs in through a dedicated Gravity-only
entry point and can then sudo as a user in the tenant.
## Sudoing as a teammate
1. Open **Settings → Manage Users**.
2. Find the user you want to act as.
3. Click the **Sudo** icon on their row.
You'll be redirected to the home page, now acting as that user. An amber banner appears across the top with the target user's name and an **Exit sudo** button.
The Sudo button is only available to tenant admins, and only for active users
in your own tenant.
## Granting Gravity support access
If a Gravity support engineer needs to investigate something in your tenant, you can grant them temporary access from the **Support Access** section of **Manage Users**.
1. Open **Settings → Manage Users → Support Access**.
2. Click **Grant access**.
3. Enter the Gravity engineer's email address.
4. Choose how long the grant lasts: **8 hours**, **24 hours**, **7 days**, or **30 days**.
5. Add a short note describing the reason (e.g. a support ticket number). The note is required so the access is traceable.
The Gravity engineer can then sign in through Gravity's dedicated support entry point. Once signed in, they pick a user to sudo as and a red banner appears across every page they visit, showing your tenant name, the note you wrote, and when the grant expires.
Granting access lets a Gravity engineer sign in to your tenant and act as one
of your users. Only grant access in response to a request you initiated (a
support ticket, an incident, or a scheduled investigation) and pick the
shortest TTL that covers the work.
### Revoking access
You can revoke a grant at any time. From the **Support Access** section, find the grant and click **Revoke**. Any sudo session running under that grant ends within 15 minutes: Gravity's session is rechecked on a short timer, and a revoked grant fails the next check.
## What changes during a sudo session
* **A banner is always visible**: amber for intra-tenant sudo, red for Gravity support sudo. The banner shows who you're acting as and an **Exit sudo** button.
* **Your normal session is preserved.** Exiting sudo (or letting the session expire) drops you back into your own account, not the login screen.
* **A sudo session can do anything the target can do.** This is intentional: the point is to reproduce what the target sees, including saving forms, running analyses, and editing settings. Be deliberate about destructive actions.
* **Everything is logged.** Every action taken during a sudo session is recorded in your tenant's activity log, along with the identity of the real driver, so "what did Drew do while signed in as Alice" is fully attributable.
## FAQ
No notification is sent. Sudo activity is recorded in your tenant's activity
log, which admins can review.
A session lasts 15 minutes and refreshes silently every 12 minutes as long
as you're active. Exiting sudo or closing the tab ends the session
immediately. For Gravity-support sudo, the underlying grant also has its own
TTL (8 hours to 30 days), and once that expires, no new sessions can start,
even if the engineer is mid-investigation.
Only tenant admins. Analysts and viewers do not see the Sudo button on the
Manage Users page and cannot start a sudo session through the API.
Yes. Sudo events (`session started`, `session ended`, `grant created`,
`grant revoked`) flow through the same activity stream as the rest of Orion.
Contact your Gravity account team if you need a custom report.
# User Management
Source: https://docs.runorion.com/configuration/user-management
Invite people and set what they can reach
Orion has three tenant-level roles (Admin, Analyst, and Viewer) that control baseline permissions. Admins invite users, assign roles, and manage group membership from **Settings > Manage Users**. Users and [Groups](/configuration/groups) are managed from the same page.
## Accessing User Management
User Management is available to tenant Admins. To access it:
1. Click your **username** in the bottom-left corner
2. Select **Manage Users**
The page has two tabs: **Users** (everyone in the tenant) and **Groups** (groups of users that share access to projects, data, and knowledge).
![Manage Users page on the Users tab, with columns for User, Role, Project Access, and Groups]()
The Users table shows each user's tenant role, the number of projects they can access, and the groups they belong to. Use the search box to filter by name, email, role, or project.
## Inviting New Users
To invite a new team member to your Orion tenant:
1. Navigate to **Settings → Manage Users**
2. From the **Users** tab, click **Invite user**
3. Enter the new user's email address
4. Choose the appropriate role
5. Send the invitation
The new user will receive an email with instructions to complete their account setup. See [User Onboarding & Invitations](/profile-settings/user-onboarding) for more details.
To onboard a new user **directly into a group**, invite them from inside that
group instead. Open the group, click **Add member**, then **Invite by email**
and the invitee is automatically added to the group with the role you pick on
first login. See
[Groups](/configuration/groups#inviting-new-users-directly-into-a-group) for
details.
## Tenant Roles
Every user has a tenant role that defines their baseline permissions across the entire tenant.
Full control of the tenant. Can invite users, create and manage groups,
connect data sources, and assign users to projects.
Can do just about anything within a project: chat, run analyses, and share
projects. Cannot add existing users to other projects directly.
Read-only access to approved projects and content. Cannot run analyses or
make changes.
Carefully consider permission levels when inviting users, especially for
administrative roles.
### Tenant roles vs. group roles
If you use [Groups](/configuration/groups), each user also has a **group role** in every group they belong to (Group Admin, Group Analyst, or Group Viewer). Group roles are independent of tenant roles and only apply inside that group, so a tenant Viewer can still be a Group Admin in a group they manage.
For a side-by-side comparison of all six roles, see [Groups → Roles at a Glance](/configuration/groups#roles-at-a-glance).
## User Management Tasks
Administrators can:
* **Invite new users**: add team members to the tenant
* **Assign tenant roles**: control each user's baseline permissions
* **Manage group membership**: see which groups a user belongs to and their role in each
* **Modify permissions**: update existing user roles
* **Deactivate users**: remove user access while preserving history
* **Remove users**: completely delete user accounts
* **[Sudo as a user](/configuration/sudo)**: temporarily act as another user to troubleshoot issues from their point of view
## Best Practices
Follow the principle of least privilege: grant users the minimum permissions
they need to do their job. For tenants using Groups, prefer group membership
over direct project access: it's easier to audit and easier to revoke when
someone's role changes.
# Connecting Data Sources
Source: https://docs.runorion.com/connecting-data-sources
What each data source needs: credentials, grants, and network access
These guides walk through what Orion needs to connect to each supported data source, and how to grant that access. Most connections are configured once at the tenant level by an administrator.
Every guide ends the same way: take the connection details you produced and enter them in Orion under **Configuration → Data Sources → Add Data Source**. See [Data Sources Management](/configuration/data-sources) for a tour of that page. If you'd rather not enter them yourself, share the details with your Gravity contact and we'll configure the connection for you.
## How Orion connects
A few principles apply to every connection:
Orion only ever issues read queries (`SELECT` and metadata introspection).
It never runs DDL, DML, or stored procedures against your systems.
We recommend a dedicated service user or service account scoped to just the
data you want Orion to analyze.
Any credentials you share (passwords, keys, secrets) are encrypted at rest
in our database.
For private databases that aren't publicly reachable (behind a VPC, private
subnet, firewall, or VPN), allowlist Orion's egress IPs so we can reach them.
All Orion services egress through the same set of IPs, so a single allowlist
entry covers everything. Your production egress IP range is provided by your
Gravity contact during onboarding.
## Choose your data source
***
## BigQuery
Orion connects to BigQuery using **service account impersonation**. You create a service account in your project and grant Orion's service account permission to impersonate it. No credentials or keys are ever shared.
For every Google Cloud Console step below, make sure you are in the correct
GCP project. Most setups use a single project for both the service account and
the source data. If your datasets live in a different project from the one
that runs Orion's queries, see [Querying datasets in another
project](#querying-datasets-in-another-project).
1. Go to **Google Cloud Console → IAM & Admin → Service Accounts**
2. Click **Create Service Account**
3. **Name:** `external-orion-data-access` (or your preferred naming)
4. **Description:** "Service account for Orion data access"
5. Click **Create and Continue**
6. Skip role assignment for now → click **Done**
We'll refer to this as the **BigQuery Service Account** going forward.
Orion queries BigQuery by impersonating the service account you just created. To allow that, grant Orion's own service account the **Service Account Token Creator** role on it.
Orion shows you the address to use. Go to **Configuration → Data Sources**, click **Add Data Source**, and choose **BigQuery**. The **Orion Service Account** sits under the Service Account Email field, with a button to copy it.
Then, in Google Cloud Console:
1. Navigate to **IAM & Admin → Service Accounts**
2. Find the BigQuery Service Account you just created
3. Select the **Principals With Access** tab and click **Grant Access**
4. **Add principal:** the Orion Service Account address you copied
5. **Assign role:** **Service Account Token Creator**
6. Click **Save**
1. Navigate to **BigQuery**
2. Create a new dataset, a dedicated dataset reserved for Orion's use (we recommend a descriptive name like `orion_scratch`)
3. Grant the BigQuery Service Account **Data Editor** access to this dataset
The scratch dataset **must be in the same region** (or multi-region) as the
datasets you wish to query via Orion.
Orion uses this dataset to efficiently stream query results to a binary format optimized for quick analysis. Temp tables created here are automatically cleaned up.
In **BigQuery**, for each dataset or table you want to share:
1. Select the dataset → click **Share Dataset**
2. Add the BigQuery Service Account email
3. **Assign role:** **BigQuery Data Viewer**
4. Click **Add**, then **Done**
1. Navigate to **IAM**
2. Locate your BigQuery Service Account and click **Edit**
3. Assign these roles:
* **BigQuery Job User**
* **BigQuery Connection User**
* **BigQuery Read Session User**
* **BigQuery Resource Viewer**
4. Click **Save**
These roles let Orion run queries, use BigQuery connections, stream results,
and read project query history. Query history powers Orion's usage
intelligence. **BigQuery Resource Viewer** provides `bigquery.jobs.listAll`,
while **BigQuery Job User** provides `bigquery.jobs.create`.
Grant **BigQuery Resource Viewer** on every project whose query history
Orion collects. A basic connection test can pass without this role because
it does not read project-wide job history. Regular queries can therefore
work while usage intelligence remains unavailable.
In Orion, go to **Configuration → Data Sources**, click **Add Data Source**, and choose **BigQuery**. The form asks for exactly what the steps above produced:
| Field | From |
| - | - |
| **Project ID** | The GCP project that runs Orion's queries: where the service account, scratch dataset, and query jobs live |
| **Service Account Email** | The BigQuery Service Account from step 1 |
| **Scratch Dataset** | The dataset from step 3 |
| **Data Project ID** *(optional)* | The GCP project where your source datasets live, if it differs from **Project ID**. Leave blank when everything is in one project |
| **Location** | The GCP location of your datasets (defaults to the `US` multi-region) |
![The Configure BigQuery Connection form in Orion, with the Orion Service Account shown under the Service Account Email field]()
The **Orion Service Account** shown on this form is Orion's own address, the one you granted access to in step 2. You do not enter it anywhere. Your instance has its own address, so copy it from your own screen rather than from the picture above.
No credentials need to be shared.
**One project or two?** Most customers keep the service account, scratch
dataset, and source data in a single project and leave **Data Project ID**
blank. Fill it in only when your datasets live in a different project from
the one running Orion's queries. See [Querying datasets in another
project](#querying-datasets-in-another-project).
### Querying datasets in another project
Orion separates the project that **runs** your queries from the project that **stores** your data. The two roles map to the two form fields:
* **Project ID** is the compute and billing project. The service account, the scratch dataset, and every query job live here. Grant **BigQuery Job User**, **BigQuery Connection User**, **BigQuery Read Session User**, and **BigQuery Resource Viewer** on this project (step 5), plus **Data Editor** on the scratch dataset (step 3).
* **Data Project ID** is where your source datasets live. Grant the service account **BigQuery Data Viewer** on those datasets (step 4).
When both are the same project, leave **Data Project ID** blank and Orion uses **Project ID** for everything. When your data lives elsewhere, set **Data Project ID** to that project. Orion then qualifies your tables against it while still running jobs and writing scratch results in **Project ID**. The service account still only needs impersonation set up once, in the project where it was created.
### Usage intelligence permissions
Orion reads BigQuery job metadata to learn which tables, columns, and joins are
commonly used. It does not read query results as part of this collection.
Grant the BigQuery Service Account **BigQuery Job User** and **BigQuery Resource
Viewer** on every project where the query jobs run. Granting Resource Viewer only
on the project that stores the tables does not expose jobs billed through a
different execution project. If you use per-user OAuth, these grants are still
required on the shared service account because scheduled collection is
unattended.
If Orion reports that usage intelligence needs additional access:
1. Grant the missing roles to the BigQuery Service Account shown in Orion.
2. In Orion, open the data source's **Refresh Data** tab.
3. Select **Full Resync** to retry immediately. Orion will also retry during the
next nightly refresh.
For a custom role, include `bigquery.jobs.create` and
`bigquery.jobs.listAll`.
### Per-user OAuth (optional)
By default, Orion queries BigQuery through the shared service account above. With **per-user OAuth**, Orion instead runs each person's BigQuery queries under their own Google identity, so what each user can see in Orion follows the BigQuery permissions they already have, rather than a single shared service account.
Per-user OAuth builds on the service account setup above, so complete that
first. The service account is still used for unattended work such as scheduled
refreshes with no individual owner and schema introspection.
Use it when you want each person's data access in Orion to match their existing BigQuery roles.
1. In **APIs & Services → OAuth consent screen**, set the **User type** to **Internal** so only your Google Workspace users can sign in
2. In **APIs & Services → Credentials**, click **Create Credentials → OAuth client ID**
3. **Application type:** Web application
4. Add the **Authorized redirect URI** provided by your Gravity contact. It points at Orion's OAuth callback, for example `https://g.runorion.com/datasource/bq-oauth/callback`
5. Click **Create**, then copy the **Client ID** and **Client Secret**
On the BigQuery data source (**Configuration → Data Sources**), open the **Connection** tab, click **Edit**, and set:
| Field | Value |
| - | - |
| **Authentication Mode** | Per-user OAuth |
| **OAuth Client Reference** | A short name for this client (e.g. `acme-bigquery`) |
| **OAuth Client ID** | From the previous step |
| **OAuth Client Secret** | From the previous step |
Save. The client ID and secret are sent to Orion's gateway and stored encrypted; they are never written to Orion's database. To rotate the secret later, enter the new values and save again. Leave them blank to keep the current ones.
The first time someone opens a project that uses this data source, Orion prompts them to connect. They click **Connect BigQuery**, sign in with Google, and consent once. From then on their queries run under their own identity.
Each person must sign in with the Google account whose email matches their
Orion sign-in. If your team signs in to Orion with Google (SSO), this
matches automatically.
A couple of things to know:
* **Scheduled work runs as its creator.** A metric or workflow that someone schedules runs under that person's connected account. Work with no individual owner uses the service account.
* **If a user disconnects or loses BigQuery access**, their scheduled work pauses until they reconnect. This is deliberate: Orion never falls back to broader access than the user has.
[↑ Back to all data sources](#choose-your-data-source)
***
## Snowflake
Orion connects to Snowflake using **key pair authentication**. You create a dedicated service user, grant it read-only access to the data you want analyzed, and associate a public key with it. Orion holds the matching private key to authenticate.
**Connection information**
| Field | Description |
| - | - |
| **Account** | Your Snowflake [account identifier](https://docs.snowflake.com/en/user-guide/admin-account-identifier) (e.g. `orgname-account_name` → `orgname-account_name.snowflakecomputing.com`) |
| **User / Role / Warehouse / Database / Schema** | Standard [connection context](https://docs.snowflake.com/en/user-guide/gen-conn-config) values used by Snowflake clients and drivers |
**Required grants** (on the role you configure for the connection)
```sql theme={null}
GRANT USAGE ON WAREHOUSE TO ROLE ;
GRANT USAGE ON DATABASE TO ROLE ;
GRANT USAGE ON SCHEMA . TO ROLE ;
GRANT SELECT ON ALL TABLES IN SCHEMA . TO ROLE ;
-- Usage intelligence. Described under Usage intelligence permissions below.
GRANT DATABASE ROLE SNOWFLAKE.GOVERNANCE_VIEWER TO ROLE ;
```
**Key pair authentication setup**
Generate an encrypted private-public key pair (RSA 2048 or 3072 recommended).
```bash theme={null}
# Encrypted private key (an optional passphrase is recommended)
openssl genrsa 2048 | openssl pkcs8 -topk8 -v2 des3 -inform PEM -out rsa_key.p8
# Associated public key
openssl rsa -in rsa_key.p8 -pubout -out rsa_key.pub
```
The private key stays on your system. The public key (`rsa_key.pub`) is added to the Snowflake user.
```sql theme={null}
CREATE USER orion_svc
DEFAULT_ROLE =
MUST_CHANGE_PASSWORD = FALSE;
```
Assign the relevant role with the grants listed above.
```sql theme={null}
ALTER USER orion_svc SET RSA_PUBLIC_KEY='';
```
In Orion, go to **Configuration → Data Sources**, click **Add Data Source**, and choose **Snowflake**. Enter the connection information from the table above (account, user, warehouse, role; database and schema are optional) and upload the **private key** file. Provide the passphrase if the key is encrypted.
### Snowflake usage intelligence permissions
Orion reads Snowflake query metadata to learn which tables, columns, and joins your team uses most. It does not read query results as part of this collection.
The grant is the last line of the block above. Run it as a role that can grant Snowflake database roles, such as `ACCOUNTADMIN`. That database role gives Orion `SNOWFLAKE.ACCOUNT_USAGE.QUERY_HISTORY` and `SNOWFLAKE.ACCOUNT_USAGE.ACCESS_HISTORY`. Query history records which statements ran. Access history records which objects and columns each statement touched.
`ACCESS_HISTORY` requires Enterprise Edition or higher. On a lower edition the grant succeeds and the view stays unavailable, so Orion reads the query text instead and reports the reduced evidence in the data source's usage status.
A connection test passes without this grant, because it does not read account
usage. Your queries and dashboards keep working while usage intelligence stays
unavailable.
Orion reports two different gaps here, and they take different fixes.
**Usage intelligence needs additional Snowflake access.** Orion cannot read account query history. Grant `SNOWFLAKE.GOVERNANCE_VIEWER` to the role shown in Orion, open the data source's **Refresh Data** tab, and select **Full Resync**.
**Usage intelligence found no tables to analyze.** The role cannot read the configured database's metadata, so Orion has nothing to attribute usage to. Grant usage on the database and schema, and select on its tables, then use **Refresh Now** on the same tab. Orion skips the collection in this state rather than failing the refresh.
A large account can need more than one **Full Resync** to finish its first 90 days. Each run continues from the progress the last one saved, so partial coverage after one run is expected rather than a failure.
Snowflake fills the Account Usage views on a delay, so Orion collects complete days that are at least four hours old. Activity from the last few hours appears in the next collection.
**What we store:** Orion uses the private key to authenticate connections. We store the encrypted key and passphrases in our database, and we encrypt your encrypted key. See the [Snowflake key pair documentation](https://docs.snowflake.com/en/user-guide/key-pair-auth).
[↑ Back to all data sources](#choose-your-data-source)
***
## Databricks
Orion connects to Databricks using a dedicated **Service Principal** and a **SQL Warehouse** for compute. We strongly recommend OAuth M2M authentication.
We recommend a dedicated Service Principal for Orion. Follow the [official documentation](https://docs.databricks.com/en/admin/users-groups/service-principals.html) to create one.
Follow the [official documentation](https://docs.databricks.com/en/dev-tools/auth/oauth-m2m.html)
to create a **Client ID** and **Client Secret**. Copy the Client Secret
immediately; you only get one chance to see it.
Follow the [official documentation](https://docs.databricks.com/en/dev-tools/auth/pat.html).
PATs are legacy and being phased out by Databricks, so prefer OAuth M2M.
SQL Warehouses are the compute resources used to execute queries. Either identify an existing warehouse, or create a dedicated one following the [official documentation](https://docs.databricks.com/en/compute/sql-warehouse/create.html). Make note of the warehouse's **HTTP Path**.
Assign the Service Principal to your workspace with the **Databricks SQL
access** entitlement. Grant **CAN USE** on the SQL Warehouse.
For business data queries, grant `USE CATALOG`, `USE SCHEMA`, and `SELECT`
only on the catalogs, schemas, and tables Orion should query. Warehouse usage
intelligence needs the [additional system-table grants](#databricks-usage-intelligence-permissions)
below. Orion does not need admin, ownership, or write permissions.
In Orion, go to **Configuration → Data Sources**, click **Add Data Source**, and choose **Databricks**. Give the connection a name and optional description, then fill in:
| Field | Description | Example |
| - | - | - |
| **Host** | The host URL for your Databricks | `abc-123.cloud.databricks.com` |
| **Warehouse HTTP Path** | The HTTP path to your chosen SQL Warehouse | `/sql/1.0/warehouses/abc123` |
| **Client ID** & **Client Secret** | OAuth M2M credentials | |
Set **Catalog** and at least one **Included schemas** entry for usage
intelligence. Enter schema names on separate lines or separate them with
commas. New schemas are not added automatically.
Use separate Orion data sources for separate catalogs or schema groups.
Each schema should belong to one Orion data source within the workspace.
The scope also limits schema sync. Tables outside your selection may
disappear from Orion and affect existing metrics or mappings. The scope
does not change the Service Principal's Databricks permissions.
### Databricks usage intelligence permissions
Orion's nightly job reads query history and lineage to learn which tables and columns your team uses. Optional SQL-text access adds query patterns, filters, and explicit joins. This collection does not read business table rows or historical query results.
Your workspace must support Unity Catalog, with the `system.query` and `system.access` tables available. The existing read grants provide metadata visibility for your selected business catalog and schemas. Usage collection does not need additional `SELECT` grants on business tables.
Ask an administrator authorized to grant access to these objects to run the following SQL. Replace `ORION_SERVICE_PRINCIPAL_APPLICATION_ID` with your Service Principal's application ID, keeping the backticks.
```sql theme={null}
GRANT USE CATALOG ON CATALOG system TO `ORION_SERVICE_PRINCIPAL_APPLICATION_ID`;
GRANT USE SCHEMA ON SCHEMA system.query TO `ORION_SERVICE_PRINCIPAL_APPLICATION_ID`;
GRANT USE SCHEMA ON SCHEMA system.access TO `ORION_SERVICE_PRINCIPAL_APPLICATION_ID`;
GRANT SELECT ON TABLE system.query.history TO `ORION_SERVICE_PRINCIPAL_APPLICATION_ID`;
GRANT SELECT ON TABLE system.access.table_lineage TO `ORION_SERVICE_PRINCIPAL_APPLICATION_ID`;
GRANT SELECT ON TABLE system.access.column_lineage TO `ORION_SERVICE_PRINCIPAL_APPLICATION_ID`;
```
| System table | What Orion uses it for |
| - | - |
| `system.query.history` | Query activity, status, timing, and available SQL text |
| `system.access.table_lineage` | Evidence of which tables a query reads or writes |
| `system.access.column_lineage` | Evidence of which columns a query touches |
`USE CATALOG` and `USE SCHEMA` allow access to the containing namespaces. `SELECT` allows reads of only the three named system tables. These grants do not include billing tables, audit logs, or write access. See [Databricks system-table access](https://docs.databricks.com/aws/en/admin/system-tables#grant-access-to-system-tables).
These tables can expose activity across your account's workspaces in the same
region. Orion limits collection to the connected workspace and attributes
object usage to the selected catalog and schemas. These application filters
do not narrow the underlying Databricks grants. Review this access with your
security team before approval.
### Optional access to SQL text
For SQL-derived query patterns and joins, ask an account administrator to add Orion's Service Principal to the account-level `databricks_pii_access` group. The name is case-sensitive. If the group does not exist, the account administrator must create it through the account console or identity provider.
This membership allows unmasked query text on supported Databricks surfaces where the principal also has access. SQL text can contain sensitive literals, such as names or email addresses. Membership does not replace the system-table grants above, and Orion does not need an account admin role. See [Databricks group setup](https://docs.databricks.com/aws/en/admin/users-groups/manage-groups#create-and-manage-the-databricks_pii_access-group).
Orion processes readable SQL during collection and stores derived usage evidence with literal values removed. The warehouse-usage workflow does not persist raw SQL or query parameter values in Redis or cloud storage.
If you decline this access and Databricks redacts SQL text, Orion still publishes a usage summary when readable lineage provides table evidence:
| Available evidence | What Orion can include |
| - | - |
| Table and column lineage | Observed usage counts, table rankings, and last-used times |
| Readable, supported SQL text | Additional query patterns, filter shapes, and explicit join keys |
| Redacted SQL text | No SQL-derived enrichment for those statements |
The cached summary records coverage limits because lineage may miss queries or columns. Tables used together do not prove an explicit SQL join. If lineage is also unavailable, Orion cannot attribute usage to tables from redacted statements.
Removing group membership later does not erase earlier usage summaries.
Previously collected data can remain in cloud storage and the cache. Orion
can retain a higher-quality cached snapshot when a later scan has less
coverage. Contact Gravity if you need previously collected data removed.
### Verify usage access
Verify access with the same Service Principal Orion uses. A successful connection test does not prove access to query history, lineage, or unmasked SQL text.
After the grants take effect, open the data source's **Refresh Data** tab and select **Full Resync**. Review the usage status for missing permissions and coverage limits. Existing connections without a scope must first set **Catalog** and **Included schemas**. Open the **Connection** tab, click **Edit**, fill both fields, then save.
The first collection builds up to 90 complete UTC days of history. Later runs reuse saved history and refresh the newest two days, with at least two hours for system tables to settle. Large workspaces may need multiple runs to complete the initial history.
If SQL text stays unavailable after group membership changes, ask your administrator to check encryption settings. Workspaces with customer-managed keys may need [additional system-catalog configuration](https://docs.databricks.com/aws/en/admin/system-tables/query-history#reading-encrypted-fields).
[↑ Back to all data sources](#choose-your-data-source)
***
## Looker
Orion connects to Looker using a dedicated user account with analyst-level (read-only) permissions plus API credentials. You'll also grant the account access to the Spaces (folders) that hold your dashboards and Looks.
**Standard deployment:** We request a Looker account for the email **`orion@gravity.foundation`**, with permissions matching those of a typical analyst at your organization. Orion only needs **read** access.
**Required permissions** (in addition to analyst-level access)
* **Models** ([docs](https://cloud.google.com/looker/docs/admin-panel-users-roles)): can be scoped to necessary models via model sets; includes the `explore` permission
* **`see_system_activity`**, **`see_lookml`**, **`see_sql`**
* **`see_user_dashboards`** (or provide PDFs of sample dashboards instead)
* **`create_custom_fields`**: enables building custom fields via **+ Add**
* **`login_special_email`**: only if using non-email (third-party) authentication
**Content access (Spaces / folders)**
Model permissions and content access are configured separately in Looker. The Orion user also needs **view access** to the Spaces where your dashboards and Looks are stored:
Navigate to the folder(s) containing your key dashboards.
Click **Manage Access** on the folder.
Add the Orion user (or a group it belongs to) with **View** access.
Without this step, the Orion user will have model and query permissions but
won't be able to see any saved dashboard content. See [Managing access to
folders](https://cloud.google.com/looker/docs/managing-spaces-and-folders).
**API credentials:** Generate API keys for `orion@gravity.foundation` ([docs](https://cloud.google.com/looker/docs/api-auth)). Then, in Orion, go to **Configuration → Data Sources**, click **Add Data Source**, choose **Looker**, and enter your Looker **base URL**, the **`client_id`**, and the **`client_secret`**.
**Third-party authentication:** If you use Okta or another third-party provider, add the **`login_special_email`** permission. Navigate to the **Roles** section of the Admin panel (`https://[organization].cloud.looker.com/admin/roles`) and, if you don't already have external users, create a new permission set. See the [Looker documentation](https://cloud.google.com/looker/docs/admin-panel-users-roles#login_special_email).
### LookML augmentation (optional)
Beyond querying dashboards and Looks, Orion can read your LookML business logic directly from its GitHub repository, reusing the dimensions, measures, and joins you have already defined to write better SQL. Setup takes about 10 minutes and needs a GitHub repository admin for one step.
The GitHub account that owns the token you create must have **Read** access to
the LookML repository (see Step 9). A valid token from an account without repo
access fails with a "repository not found" error. If you are not a repo admin,
loop one in for Step 9.
On the **Configuration → Data Sources** page, open the Looker datasource and select the **Augmentation** tab.
![The Coffee Rush Looker datasource in Orion Configuration, with the Connection, Refresh Data, Augmentation, Schema, and Migration tabs]()
Click the **Create token** link to open GitHub.
![The Create token link beneath the Personal Access Token field on the Augmentation tab]()
On GitHub, begin creating a **fine-grained personal access token**.
![GitHub's fine-grained personal access tokens page with the Generate new token button]()
* **Resource owner:** select the organization or account where the Looker GitHub repository lives.
* **Expiration (TTL):** set the token expiration. We recommend the longest your security policy allows; GitHub's maximum for fine-grained tokens is 1 year (366 days).
![The new fine-grained token form with token name, resource owner, and expiration fields]()
When this token expires, Orion can no longer pull your LookML repo. Schema sync and the nightly enrichment that reads your LookML will fail with an authentication error, and any insights that depend on that business logic go stale until you issue a new token and update the connection. Set a reminder to rotate the token before it expires.
Choose the Looker repository from the dropdown.
Grant read-only access, nothing more:
* **Contents:** Read-only
* **Metadata:** Read-only
![Repository access set to the LookML repo, with Contents and Metadata permissions set to Read-only]()
Generate the token and copy it. You will not be able to view it again.
Back in Orion, enter the repository URL, the PAT, and the rest of the configuration (see the **Augmentation** tab in Step 2), then save.
The account that owns the token must have at least **Read** access to the LookML repo, or Orion authenticates but cannot see the repo and the connection fails with "repository not found."
A repository admin:
1. In GitHub, open the LookML repository → **Settings → Collaborators and teams** (under **Access**).
2. Under **Manage access**, click **Add people** (or **Add teams** if you manage access by team).
3. Enter the username of the account tied to the token, or the service account created for Orion.
4. Set the role to **Read**. No write or admin access is required.
5. Send the invitation.
6. The account owner **accepts the invite**. Until they do, access does not take effect and the connection will still fail.
7. Return to the Orion connection and reconnect.
![The LookML repository's Collaborators and teams page in GitHub, under Settings, with the Add people option]()
Use a shared service account rather than an individual's personal account. If a person leaves or loses access, a personal-account token breaks the connection.
On the **Augmentation** tab, click **Test Connection**. This verifies that Orion can reach the repository with the token and branch you configured, without running a full sync.
* **Success:** the connection is valid. Orion can authenticate and see the repo. Click **Sync Now** to pull the LookML files. When it finishes, **Status** shows **Synced**, along with the file count and the latest commit.
* **Failure:** read the error message:
* **"Repository or branch not found"** usually means the token's account lacks Read access to the repo (revisit Step 9), or the branch name is wrong. Leave **Branch** blank to use the repo default, or enter the correct branch.
* **"Authentication failed"** means the token is invalid or expired. Generate a new one (Steps 3-7) and re-enter it.
* **"Access forbidden"** means the token is missing a permission or, if your org enforces SSO, has not been SSO-authorized for the organization.
Once the test passes and the first sync completes, Orion is reading your LookML.
### Migrating dashboards into Orion (optional)
LookML augmentation teaches Orion the business logic behind your models. Migration ports the dashboards themselves into Orion projects, each with its own metrics and workflows. The two are independent, and either one runs on its own.
The **Migration** tab appears on Looker data sources only, and only
administrators can start or roll back a migration.
**Before you start:** Orion extracts the SQL behind your dashboards and runs it against a database data source, the **Target Database**. The target must be the same database your Looker connection queries. Connect that data source first. Snowflake, BigQuery, Postgres, and Databricks connections qualify.
Go to **Configuration → Data Sources**, open the Looker data source, and select the **Migration** tab. Then click **Migrate to Orion**.
![The Looker data source page with the Migration tab selected among Connection, Refresh Data, Augmentation, Schema, and Migration. Under Available, a Migrate to Orion card describes porting Looker dashboards into Orion projects]()
Choose the **Target Database**, then click **Choose Dashboards**. The button stays disabled until a target is set and Looker reads as **Connected**.
Orion reads your Looker usage history, proposes dashboards to migrate, and groups them into projects. Each card shows the title, tile count, user count, and query count. Every dashboard starts selected: clear what you do not want, and confirm the selection.
Paste a Looker dashboard URL into **Add Dashboard by URL** to include one the list missed.
![The Select Dashboards to Migrate step on the Looker Migration screen. A Corporate Finance and Cash Flow project group holds one selected dashboard with tile, user, and query counts, above Add Dashboard by URL and a Migrate 1 Dashboard button]()
The status view updates itself while the run works, so you can leave and come back. The summary then counts the projects, metrics, and workflows created and links to each one. Dashboards Orion could not port appear under **Excluded Dashboards**, each with a reason.
**Rollback Migration** deletes every project and resource the run created.
That cannot be undone. **Start New Migration** clears the record instead and
leaves the created projects in place.
A data source runs one migration at a time. Start the next one once the current run has completed or failed.
[↑ Back to all data sources](#choose-your-data-source)
***
## PostgreSQL
Orion connects to PostgreSQL with username/password authentication. Create a dedicated read-only user and grant it `SELECT` on the schemas and tables you want analyzed.
**Connection information**
| Field | Description |
| - | - |
| **Host** | PostgreSQL server hostname / IP address |
| **Port** | PostgreSQL server port (default: `5432`) |
| **Database** | Target database name |
| **User** | PostgreSQL username for authentication |
| **Password** | User password for authentication |
| **SSL Mode** | `disable` / `allow` / `prefer` / `require` / `verify-ca` / `verify-full` |
**Required grants**
```sql theme={null}
GRANT CONNECT ON DATABASE TO ;
GRANT USAGE ON SCHEMA TO ;
GRANT SELECT ON ALL TABLES IN SCHEMA TO ;
-- So future tables are visible automatically:
ALTER DEFAULT PRIVILEGES IN SCHEMA GRANT SELECT ON TABLES TO ;
```
**Setup**
```sql theme={null}
CREATE USER orion_svc WITH PASSWORD '';
```
In `postgresql.conf`: set `listen_addresses = '*'` so PostgreSQL accepts connections, and `ssl = on` for SSL connections.
In `pg_hba.conf`:
```text theme={null}
host orion_svc md5
hostssl orion_svc md5 # SSL-only
```
Restart the PostgreSQL service, then assign the grants listed above to the service user.
In Orion, go to **Configuration → Data Sources**, click **Add Data Source**, and choose **Postgres**. Enter the connection information from the table above (host, port, database, user, password, SSL mode).
**What we store:** username/password authentication; we encrypt your plain-text password in our database. See the PostgreSQL docs on [connection parameters](https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-PARAMKEYWORDS), [access control](https://www.postgresql.org/docs/current/ddl-priv.html), and [client authentication](https://www.postgresql.org/docs/current/client-authentication.html).
[↑ Back to all data sources](#choose-your-data-source)
***
## MySQL
Orion connects to MySQL with username/password authentication. Create a dedicated user and grant it read-only access to the target database.
**Connection information**
| Field | Description |
| - | - |
| **Host** | MySQL server hostname / IP address |
| **Port** | MySQL server port (default: `3306`) |
| **Database** | Target database (schema) name |
| **User** | MySQL username for authentication |
| **Password** | User password for authentication |
| **SSL Mode** | `disabled` / `preferred` / `required` / `verify-ca` / `verify-identity` |
| **SSL CA Certificate** (optional) | PEM-encoded CA bundle, required for `verify-ca` / `verify-identity` when the server certificate is not signed by a publicly trusted CA |
In MySQL, a "database" and a "schema" are the same thing. The **Database**
value above is the schema Orion will read from.
**Required grants**
```sql theme={null}
-- Read-only access to all current and future tables/views in
GRANT SELECT, SHOW VIEW ON .* TO ''@'';
FLUSH PRIVILEGES;
```
**Setup**
```sql theme={null}
CREATE USER 'orion_svc'@'' IDENTIFIED BY '';
```
Replace `` with the IP/CIDR Orion will connect from (e.g. `'orion_svc'@'10.0.0.0/8'`), or use `'%'` to allow any source.
Ensure MySQL accepts remote connections in `my.cnf` (or `mysqld.cnf`):
```ini theme={null}
[mysqld]
bind-address = 0.0.0.0
# For SSL:
require_secure_transport = ON
ssl-ca = /path/to/ca.pem
ssl-cert = /path/to/server-cert.pem
ssl-key = /path/to/server-key.pem
```
Optionally require SSL for this user only: `ALTER USER 'orion_svc'@'' REQUIRE SSL;`
Restart the MySQL service, then assign the grants listed above to the service user.
In Orion, go to **Configuration → Data Sources**, click **Add Data Source**, and choose **MySQL**. Enter the connection information from the table above (host, port, database, user, password, SSL mode, and the CA certificate if applicable).
**What we store:** username/password authentication; we encrypt your plain-text password at rest. If you provide an SSL CA certificate, we encrypt the PEM contents alongside it. See the MySQL docs on [access control](https://dev.mysql.com/doc/refman/8.0/en/access-control.html) and [encrypted connections](https://dev.mysql.com/doc/refman/8.0/en/encrypted-connections.html).
[↑ Back to all data sources](#choose-your-data-source)
***
## Redshift
Orion connects to Amazon Redshift (cluster or Serverless workgroup) over the standard PostgreSQL wire protocol (port `5439`) using username/password authentication. Orion only ever issues read (`SELECT`) queries.
**Connection details**
| Field | Description |
| - | - |
| **Host** | Your cluster endpoint, e.g. `my-cluster.abc123xyz.us-east-1.redshift.amazonaws.com`. For Serverless: `my-workgroup.123456789012.us-east-1.redshift-serverless.amazonaws.com` |
| **Port** | Defaults to `5439` |
| **Database** | The database name to connect to, e.g. `analytics` or `dev` |
| **User** | The read-only user created for Orion (we suggest `orion`) |
| **Password** | The password for that user |
| **SSL Mode** | `require` (default; Redshift clusters always terminate TLS) |
**Database user & permissions**
On Redshift, a user can only see a table in `information_schema` if it has
been granted access, so these grants also determine what Orion can discover.
```sql theme={null}
CREATE USER orion PASSWORD '';
-- For each schema you want Orion to access:
GRANT USAGE ON SCHEMA TO orion;
GRANT SELECT ON ALL TABLES IN SCHEMA TO orion;
-- So future tables are visible automatically:
ALTER DEFAULT PRIVILEGES IN SCHEMA GRANT SELECT ON TABLES TO orion;
```
Orion does not need `INSERT` / `UPDATE` / `DELETE` / `CREATE`, so please do
not grant write access.
**Network access:** Orion connects from our infrastructure, so the endpoint must be reachable on the Redshift port. Allow inbound traffic on port `5439` from Orion's egress IP range in the cluster's VPC security group. See the docs on [managing Redshift security groups](https://docs.aws.amazon.com/redshift/latest/mgmt/working-with-security-groups.html).
**Enter the connection in Orion:** go to **Configuration → Data Sources**, click **Add Data Source**, choose **Amazon Redshift**, and enter the connection details from the table above.
[↑ Back to all data sources](#choose-your-data-source)
***
## Amazon Athena
Orion connects to Amazon Athena to run serverless SQL over data in S3. Table and column metadata comes from your **AWS Glue Data Catalog**; queries run through Athena and write their results to an S3 **output location** you control. Orion only ever issues read (`SELECT`) queries against your tables.
Authentication uses an **IAM access key** for a dedicated user. You create the user, attach a least-privilege policy, and enter the access key ID and secret in Orion.
Every Athena query must write its results somewhere in S3. This is an Athena
requirement, not an Orion one: the output location (or a workgroup that
enforces one) is where Athena stages query output before Orion reads it. The
IAM user therefore needs **write** access to that one output prefix, even
though it only reads your actual data.
**Connection details**
| Field | Description | Example |
| - | - | - |
| **AWS Access Key ID** | Access key ID for the dedicated IAM user | `AKIA...` |
| **AWS Secret Access Key** | Secret access key for that user | *(sensitive)* |
| **Region** | AWS region where Athena and your Glue catalog live | `us-east-1` |
| **S3 Output Location** | S3 URI where Athena stages query results (must end in `/`) | `s3://my-bucket/athena-results/` |
| **Workgroup** | Athena workgroup to run queries under (defaults to `primary`) | `primary` |
| **Data Catalog** | Athena data catalog name (defaults to `AwsDataCatalog`) | `AwsDataCatalog` |
| **Database** *(optional)* | Scope schema exploration to a single Glue database | `analytics` |
If you grant the optional query-history permissions below, Orion reads the
chosen workgroup's query history to learn which tables and columns your team
queries most. That history includes the **SQL text** of every query run in
the workgroup. Use a dedicated workgroup if it may contain sensitive queries.
**IAM setup**
In the AWS IAM console, create a user for Orion (we suggest `orion-athena`) with **programmatic access**, then create an access key for it. Copy the **Access Key ID** and **Secret Access Key**; the secret is only shown once.
Attach a policy for one Athena workgroup, one Glue database, the S3 prefix holding your data, and the S3 prefix for query results. Replace the placeholders with your AWS account, region, workgroup, database, bucket, and prefix values. Prefix values should not start or end with `/`. Ask your Gravity contact for Orion's egress IPs if you use the final, optional deny statement.
```json theme={null}
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "AthenaQuery",
"Effect": "Allow",
"Action": [
"athena:StartQueryExecution",
"athena:StopQueryExecution",
"athena:GetQueryExecution",
"athena:GetQueryResults",
"athena:GetWorkGroup"
],
"Resource": "arn:aws:athena:::workgroup/"
},
{
"Sid": "AthenaUsageHistory",
"Effect": "Allow",
"Action": [
"athena:ListQueryExecutions",
"athena:BatchGetQueryExecution",
"athena:GetQueryRuntimeStatistics"
],
"Resource": "arn:aws:athena:::workgroup/"
},
{
"Sid": "GlueCatalogRead",
"Effect": "Allow",
"Action": [
"glue:GetDatabase",
"glue:GetTable",
"glue:GetTables",
"glue:GetPartitions"
],
"Resource": [
"arn:aws:glue:::catalog",
"arn:aws:glue:::database/",
"arn:aws:glue:::table//*"
]
},
{
"Sid": "S3BucketLocation",
"Effect": "Allow",
"Action": "s3:GetBucketLocation",
"Resource": [
"arn:aws:s3:::",
"arn:aws:s3:::"
]
},
{
"Sid": "S3ListData",
"Effect": "Allow",
"Action": "s3:ListBucket",
"Resource": "arn:aws:s3:::",
"Condition": {
"StringLike": { "s3:prefix": ["/", "/*"] }
}
},
{
"Sid": "S3ReadData",
"Effect": "Allow",
"Action": "s3:GetObject",
"Resource": "arn:aws:s3::://*"
},
{
"Sid": "S3ListResults",
"Effect": "Allow",
"Action": "s3:ListBucket",
"Resource": "arn:aws:s3:::",
"Condition": {
"StringLike": { "s3:prefix": ["/", "/*"] }
}
},
{
"Sid": "S3ReadWriteResults",
"Effect": "Allow",
"Action": ["s3:GetObject", "s3:PutObject", "s3:AbortMultipartUpload"],
"Resource": "arn:aws:s3::://*"
},
{
"Sid": "DenyOutsideOrionEgress",
"Effect": "Deny",
"Action": "*",
"Resource": "*",
"Condition": {
"NotIpAddress": {
"aws:SourceIp": ["/32", "/32"]
},
"Bool": { "aws:ViaAWSService": "false" }
}
}
]
}
```
Set **Database** in Orion to the database named in the policy. Orion then reads that database without listing the whole catalog.
`AthenaUsageHistory` is optional. Remove that statement if you do not want Orion to read the workgroup's query history. `DenyOutsideOrionEgress` is also optional; remove it if you do not want to restrict direct use of the access key to Orion's egress IPs.
Keep `aws:ViaAWSService` in the condition. Athena accesses other AWS
services on your behalf, and those requests do not originate from Orion's
IPs. [AWS cautions against source-IP denies on S3 actions used by Athena](https://docs.aws.amazon.com/athena/latest/ug/s3-permissions.html).
Test a query with the pilot workgroup and buckets before using this deny
in production.
Orion tenants share these egress IPs. The IP condition does not identify a tenant; the dedicated access key and its permissions control access to your resources.
Make sure the workgroup you name exists in the chosen region, and that either the workgroup enforces an output location or the **S3 Output Location** you enter is writable by the IAM user. If the workgroup enforces its own output location, that setting wins over the value you enter in Orion.
In Orion, go to **Configuration → Data Sources**, click **Add Data Source**, and choose **Amazon Athena**. Enter the connection details from the table above. Use the **Workgroup** and **Database** named in the policy. Leave **Data Catalog** at `AwsDataCatalog`.
**Network access:** Orion reaches Athena and Glue over public AWS API endpoints, so the connection needs no VPC allowlist. Athena accesses S3 from AWS, not from Orion's egress IPs. If your bucket policies restrict source IPs or VPC endpoints, account for [Athena's S3 access](https://docs.aws.amazon.com/athena/latest/ug/s3-permissions.html) when configuring them. The optional deny statement above restricts direct use of the access key by source IP.
**What we store:** the IAM access key ID and secret access key, encrypted at rest in our database. To rotate the key later, open the data source's **Connection** tab, click **Edit**, enter the new values, and save. Leave the secret blank to keep the current one.
**Known limitations**
* **IAM access key only.** Cross-account IAM role assumption is a planned fast-follow; today the connection uses a long-lived access key, so rotate it on your normal cadence.
* **Output location is mandatory.** Athena cannot run a query without a place to write results, so the workgroup must enforce one or you must supply the **S3 Output Location**.
* **dbt enrichment** is supported on Athena connections (see [dbt](#dbt)); semantic enrichment from a Looker connection can also be projected onto Athena schemas.
[↑ Back to all data sources](#choose-your-data-source)
***
## Microsoft Fabric
Orion connects to a Microsoft Fabric Warehouse using a **Service Principal** (App Registration) in your Microsoft Entra ID tenant. Orion connects over TDS (the SQL endpoint) using ODBC Driver 18 with Service Principal authentication, with no interactive login required.
**Azure App Registration**
1. Create an App Registration in your Entra ID tenant ([docs](https://learn.microsoft.com/en-us/entra/identity-platform/quickstart-register-app))
2. Note the **Application (client) ID** and **Directory (tenant) ID**
3. Create a **Client Secret** under **Certificates & secrets** ([docs](https://learn.microsoft.com/en-us/entra/identity-platform/quickstart-register-app#add-credentials)) and note the secret **value** (not the Secret ID). Recommended expiry: 12 months
**Fabric Admin Portal settings** (must be enabled by a Fabric Administrator)
1. Navigate to **Fabric Admin Portal → Tenant settings → Developer settings**
2. Enable **Service principals can use Fabric APIs**
3. Scope to a security group containing the Orion Service Principal (recommended), or enable for the entire organization
**Workspace access:** Open the workspace containing your Warehouse, click **Manage access → Add people or groups**, search for the App Registration name, and assign the **Viewer** role (minimum). Contributor is recommended for full metadata access.
**Warehouse SQL endpoint:** Open the Warehouse in Fabric, click **Settings → SQL connection string**. The hostname looks like `xxxxxxxx.datawarehouse.fabric.microsoft.com`. Note the **Database** name (the Warehouse name).
**Credentials summary**
| Field | Description | Example |
| - | - | - |
| **Server Hostname** | SQL connection string from Warehouse settings | `xyz.datawarehouse.fabric.microsoft.com` |
| **Database** | Warehouse name | `my-warehouse` |
| **Tenant ID** | Entra ID Directory (tenant) ID | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` |
| **Client ID** | App Registration Application (client) ID | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` |
| **Client Secret** | App Registration client secret value | *(sensitive)* |
**Enter the connection in Orion:** go to **Configuration → Data Sources**, click **Add Data Source**, choose **Microsoft Fabric Warehouse**, and enter the credentials from the table above.
Orion uses read-only SQL (`SELECT` only) to discover your schema via
`INFORMATION_SCHEMA`, run agent-generated queries, and stream results into its
analysis pipeline. It never executes DDL, DML, or stored procedures. If you
use dbt with Fabric, Orion can enrich metadata with dbt models and lineage;
see [dbt](#dbt).
[↑ Back to all data sources](#choose-your-data-source)
***
## Delta Lake
Orion connects to Delta Lake tables on **Azure Data Lake Storage Gen2** (`abfss://`) or **Google Cloud Storage** (`gs://`). Orion reads the Delta table directly via its transaction log. There is no warehouse, cluster, or notebook to provision.
You provide two things: the **Delta table or table root URI**, and credentials with read access to that location. The URI points at a Delta table folder, or at a parent folder holding many Delta tables. Set **Object storage** to the provider that holds them: Orion refuses a URI whose scheme does not match that selection.
Orion only performs read-only scans against your storage account / bucket: no
writes, no vacuums, no schema changes.
**Storage account access**
* The Table URI looks like `abfss://@.dfs.core.windows.net/`
* `` can point to a single Delta table folder (containing a `_delta_log/` subdirectory) or a parent folder; in the parent case, Orion exposes every Delta table found underneath
* Confirm **hierarchical namespace** is enabled on the storage account (required for `abfss://`)
**Credentials (pick one)**
Read-only and time-bounded ([docs](https://learn.microsoft.com/en-us/azure/storage/common/storage-sas-overview)).
Scope to the container, permissions read + list (`sp=rl`), expiry 90 days
or longer. Send the token query string (with or without a leading `?`).
Read/write, full access, only if SAS is not viable. Either the raw account
key, or the full connection string.
**What you enter in Orion** (under **Configuration → Data Sources → Add Data Source → Delta Lake**): the full `abfss://...` URI, the **Azure storage account** name, and your credential. **Storage authentication** is where you pick **SAS token** or **Account key**. The account name is required with either one.
**Bucket access**
* The Table URI looks like `gs:///`
* As with Azure, `` can be a single Delta table folder or a parent folder containing many Delta tables
**Credentials (pick one)**
Create HMAC keys for a service account that has `roles/storage.objectViewer`
(or finer-grained access) on the target bucket.
No secret to share. Grant the Orion workload identity your contact
provides `roles/storage.objectViewer` on the bucket.
**What you enter in Orion** (under **Configuration → Data Sources → Add Data Source → Delta Lake**): the full `gs://...` URI, and your choice in **Google Cloud credentials**. **HMAC key** asks for an **HMAC access key ID** and an **HMAC secret**. **Workspace identity** asks for neither: confirm with your Gravity contact that it is configured.
**Parent-folder mode:** point the Table URI at a parent directory (e.g.
`abfss://.../silver/`) and Orion discovers every Delta table underneath on
schema sync. Partition columns need no setup; Orion reads them from the Delta
log for query pruning automatically.
[↑ Back to all data sources](#choose-your-data-source)
***
## MotherDuck
Orion connects to MotherDuck using **access token authentication**. You create an access token in your MotherDuck account, and Orion uses it to run read-only (`SELECT`) queries against a single database. There is no service user, warehouse, or cluster to configure.
**Connection information**
| Field | Description |
| - | - |
| **MotherDuck Token** | Access token created in MotherDuck under **Settings → Access Tokens** |
| **Database** | The database Orion queries: the bare name, without the `md:` prefix |
**Setup**
1. In MotherDuck, go to **Settings → Access Tokens**
2. Create a token. A **Read Scaling** token is recommended
3. Copy the token
The token is a JWT: one long three-part string, like `eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyIjoi...`.
A **Read Scaling** token is read-only on MotherDuck's side and spreads
Orion's queries across replicas. Replicas are eventually consistent, so a
result can trail the latest writes by a few minutes.
In Orion, go to **Configuration → Data Sources**, click **Add Data Source**, and choose **MotherDuck**. Paste the token and enter the database name.
Enter the bare database name (`analytics`), not the `md:analytics` form a
MotherDuck connection string uses. Names accept letters, digits,
underscores, and hyphens, up to 128 characters, starting with a letter,
digit, or underscore.
On connect, Orion discovers every table, view, and column in the database you named.
A database holding more than 5,000 tables and views is refused rather than
trimmed, because a partial schema looks complete to everything downstream.
Set comments on your MotherDuck tables and columns. Orion reads them and shows
them as descriptions on the **Schema** tab.
**What we store:** the MotherDuck token, encrypted at rest in our database. To rotate it, open the data source's **Connection** tab, click **Edit**, enter the new token, and save. Leave the field blank to keep the current token.
dbt enrichment is supported on MotherDuck connections: see [dbt](#dbt).
[↑ Back to all data sources](#choose-your-data-source)
***
## dbt
If you use dbt, Orion can enrich an existing warehouse connection with your dbt model descriptions and lineage. You connect Orion to your dbt project's GitHub repository with a read-only fine-grained access token.
1. Navigate to **Settings → Developer Settings → Personal access tokens → Fine-grained tokens**
2. Click **Generate new token**
3. Set your organization as the resource owner (if required)
4. Configure permissions: **Contents** → Read access (**Metadata** is auto-added)
5. Under **Repository access**, select **Only select repositories** and add your dbt project repo only
6. Click **Generate token**, then copy and save it immediately; it won't be shown again
1. In Orion, go to **Configuration → Data Sources**
2. Click the data source tile you want to enrich, then select the **Augmentation** tab
3. On the **dbt project** card, open **Add a dbt project**
4. Set **dbt Source Type** to **GitHub Repository**
5. Enter the **Repository URL** (your dbt project's GitHub URL) and **Personal Access Token**
6. Click **Connect dbt Project**
![The Augmentation tab of a data source, selected among Connection, Refresh Data and Schema. Below it, the dbt project card explains what a dbt project adds, and its Add a dbt project row is outlined in red]()
Once connected, the card shows the sync status, the model count, and when it last refreshed, next to a **Refresh** button. To change the configuration later, open **dbt project settings**, click **Edit**, and the footer offers **Save Changes** and **Disconnect**.
Make sure there's no trailing slash at the end of the Repository URL.
**dbt Source Type** also supports **dbt Cloud** (account ID, API token,
and environment ID) and **Upload manifest.json** if you would rather not
connect the GitHub repository.
Standard dbt projects only require these two fields, **Repository URL** and
**Personal Access Token**. Additional fields are optional.
[↑ Back to all data sources](#choose-your-data-source)
***
## News API
Orion can search news headlines and fold them into an analysis as a dataset, useful for explaining external context behind a change in your numbers ("did coverage spike the week signups jumped?").
Register for a free API key at [newsapi.org](https://newsapi.org/register).
1. In Orion, go to **Configuration → Data Sources** and click **Add Data Source**
2. Select **News API**
3. Enter the key in **NewsAPI.org API Key** and click **Connect Data Source**
Enable News API on a project like any other data source, and users there can ask Orion to pull articles by keyword from the last 1 to 30 days. Results come back with date, title, source, and summary, as a dataset the analysis can correlate against your own data.
News API is a single tenant-wide connection; once added, the tile shows
**Already connected**.
[↑ Back to all data sources](#choose-your-data-source)
***
## Weather
The Weather source pulls daily weather from Open-Meteo. No account or API key is needed: add it from **Configuration → Data Sources → Add Data Source → Weather** and click **Connect Data Source**.
Enable it on a project and users can ask for weather by location and date range: historical actuals back to 1940 and forecasts up to about 16 days out, with conditions, high and low temperatures, and precipitation. The data lands as a dataset the analysis can join against your business data, which is what you want for questions like "do cancellations track with bad weather?"
[↑ Back to all data sources](#choose-your-data-source)
# Context
Source: https://docs.runorion.com/core-concepts/knowledge-base
Give Orion the business context it needs to be right
Context is where you manage the business knowledge Orion uses in its work. It brings together written pages and the **Metrics Catalog**.
This page covers written Context pages: company information, definitions, and procedures that help Orion understand your business. Think of them as the information you would give a new employee during onboarding.
![Context page with editor]()
## What Are Context Pages?
Context pages use a wiki-style file and folder structure. They provide a single source of truth for:
* **Company Context** - Information about your organization, industry, and business rules
* **Metrics & Definitions** - How your company defines key metrics and terminology
* **Standard Operating Procedures (SOPs)** - Step-by-step processes and workflows
* **Analytical Methods** - How to perform certain analyses, calculations, and methodologies
* **Product Documentation** - Details about your products, services, and features
* **Guidelines & Best Practices** - Standards and recommendations for your team
## How Orion Uses Your Context Pages
When you enable Context pages for a project, Orion will:
* **In Chat** - Use that context for better answers and analysis throughout your conversation
* **In Deliverables** - Include small in-line source citations in reports, slide decks, and dashboards for wiki pages that were referenced
* **In Updates** - Accept suggestions to update wiki pages with new information
The more comprehensive and well-organized your Context pages, the better Orion can tailor its analysis to your specific needs and processes.
## Organization
It's recommended that you create folders based on how your company normally organizes information, such as by department, and then within that, by certain use cases, activities, or scopes.
**Example structure:**
```
Sales/
├── Pricing
├── Contracts
└── Customer Stories
Operations/
├── Payroll Process
├── Returns Policy
└── Escalation Procedures
Product/
├── Features
├── API Documentation
└── Release Process
```
Name folders and files in a way that is as easy to understand for Orion as it would be for a new hire.
## Key Features
Organize content in nested folders (up to 3 levels deep) that mirror your
company structure
Create and edit pages using a markdown editor with live preview
Upload spreadsheets, text files, and documents that automatically convert to
pages
Reorganize pages and folders by dragging them around
Track changes and see who updated pages and when
Enable specific pages for projects to keep Orion focused on relevant context
## Getting Started
To get started with Context pages:
1. Go to **Context** in the left-hand navigation menu, then open **Pages Overview**
2. Create your first folder or page
3. Organize your content into folders that match your company structure
4. Enable pages for projects that should have access to them
Start with essential documentation like company information, key processes,
and business definitions. You can expand your Context pages over time.
## Context Pages vs. Project Files
The key difference between Context pages and project file uploads:
* **Context pages** - Designed for structured, concise context (metrics, definitions, procedures, guidelines) that Orion uses throughout chat and analysis
* **Project file uploads** - Designed for long-form, unstructured documents like dense PDFs with images, charts, and complex text
## Next Steps
Learn how to create and manage Context pages
Tips for writing effective Context pages
Connect Context pages to your projects
Learn when to use file uploads vs. Context pages
# Portals
Source: https://docs.runorion.com/core-concepts/portals
Share Orion content with people outside your workspace
Portals let you share Orion content outside your workspace. Choose a public link, a protected link, or an embed according to who should be able to open it.
Use [dashboard sharing](/dashboards/publish) for people in your project. A portal gives external readers access to selected content without project membership.
Portals requires tenant administrator access and must be enabled for your
workspace. You open it from **Portals** in the left-hand navigation menu.
![The left-hand navigation menu has Portals selected. The Portals screen shows a search field, Create portal, Public links, and a list of protected portals]()
## Choosing a Portal Type
Choose the sharing method according to who should be able to open the content.
| Kind | Choose it when | What readers need |
| - | - | - |
| **A public link** | Anyone receiving the URL may read the content | The link alone |
| **A protected link** | Readers must sign in or enter a shared password | Your SSO, or the password you give them |
| **An embed in their site** | Another site will display the content inside its own page | A token signed by that site's server |
![The New portal dialog offers A public link, A protected link, and An embed in their site. Each option explains its audience and access method]()
Choose SSO when access depends on each reader's identity. Configure your [SSO provider](/configuration/sso#portal-visitor-domains) first, then add rules for the people, domains, or groups you allow. A domain rule cannot admit someone your provider refuses.
Choose a shared password when readers will open the page directly. Password pages cannot be framed inside another site, so use an embed for that task.
## Publishing a Public Link
1. Select **Public links** in **Portals**, then click **Publish public link**
2. Click **Choose an artifact**, select the content, and set **Expires after**
3. Click **Publish**, then copy the link
![The public-link publishing form has Choose an artifact and Expires after controls, an explanation that anyone with the URL can read, and Cancel and Publish buttons]()
Anyone holding a public link can read the content, including anyone it was forwarded to.
## Creating a Protected Portal or Embed
For protected links and embeds, click **Create portal**, then work through the dialog:
1. Choose **A protected link** or **An embed in their site**
2. Name the portal after the audience it serves, such as a customer or a site
3. For an embed, add the origins allowed to frame it
4. Choose how a reader gets in, and for SSO add at least one rule saying who is allowed
5. Confirm
A new portal serves nothing until you add content and publish a link. For password access, set a password of at least twelve characters on **Access**. Until then, nobody can open it. Orion never shows the password again, so keep a copy to give your readers.
![The New portal dialog shows People sign in with your SSO and One shared password. The selected password option explains setup after creation and direct browser access]()
## Adding an Artifact and Publishing a Link
A protected portal or embed can serve dashboards, reports, and slide decks. Add the content first, then publish a link to it.
1. Open the portal and its **Artifacts** tab
2. Click **Add artifact**, then search by artifact or project name
3. Set **Link expiry**, then click **Publish link** on the artifact's row
The link appears under **Links**. Use **Copy** on its row to get the same URL again.
Readers see the current content. Editing or re-running it changes what everyone holding the link sees.
### Starting From the Artifact
On a project page, open the artifact's **...** actions menu and choose **Share externally**. With the artifact open, choose **More → Make Public** to open the same dialog.
![The P&L slide deck's top bar shows Shared, Ask Orion, Download, and an expanded More menu with Make Public. Slide thumbnails sit beside an Executive Summary of monthly and year-to-date figures]()
Use **Public link** to publish directly. Use **Protected** or **Embed in a site** to add the content to a portal you already created.
![The Share externally dialog has Public link, Protected, and Embed in a site tabs. Public link shows expiry, Copy link, Stop public access, and Create another link]()
## Embedding in Another Site
An embed portal is framed inside a page you do not control, so it needs two things the other kinds do not.
* **Origins**: list the site origins allowed to frame the content, such as `https://acme.example`. Include any port, but no path
* **Signing keys**: **Create key** shows the key once. Keep it securely, because Orion cannot show it again
Open **Embed code** on a live link's row for setup checks and iframe, Node, and Python snippets. Give the other site's engineers those instructions. Their server signs a new token on each load, because Orion does not refresh expired tokens.
An allowed origin still needs a valid signed token. An origin outside your list cannot frame the content.
## Expiry, Revoking and Disabling
Choose an expiry before publishing. Use **Never** only for content intended to stay available indefinitely.
**Revoke** stops one URL immediately. Its row stays as history. **Disable** stops a whole portal, and **Enable** brings it back.
**Stop public access** revokes every portal link to that artifact, including
protected and embed links. Deleting a portal stops every link under it. Use
**Disable** when you expect to restore access later.
## What a Reader Sees
* **Public link**: the page opens, with no sign-in
* **Password**: a prompt headed "This page is password protected". The unlock covers that one link, so opening one page does not unlock the next you send
* **SSO**: a prompt headed "Sign in to open this page", with a button for each provider. A reader who signs in and matches no rule is told "You do not have access to this page"
* **Embed**: the artifact renders inside the other site's page
* **Revoked, expired, or under a disabled portal**: a page not found
![A public portal shows the P&L slide deck's Executive Summary, with monthly figures, a year-to-date summary, and slide thumbnails. The header offers Download and slide navigation without project editing controls]()
## Who Can Use Portals
Only tenant administrators manage portals. Analysts and viewers cannot use **Portals** or **Share externally**. See [Groups](/configuration/groups#roles-at-a-glance) for workspace roles.
## Next Steps
Set up the provider and the portal visitor domains a protected link checks
Share a dashboard with teammates who do sign in to Orion
# Projects
Source: https://docs.runorion.com/core-concepts/projects
The workspace holding a team's chats, data, and context
Projects serve as the primary organizational mechanism in Orion. Each project brings together your [Chat Conversations](/chat/basics-navigation) and [Analyses](/chat/running-analyses), along with all the context that supports them: [Context](/core-concepts/knowledge-base) pages, [data sources](/configuration/data-sources), [uploaded files](/chat/file-uploads), [memories](/chat/memory), and other project-specific details.
## Personal vs Shared Projects
When you create a new project in Orion, it is automatically ***private*** by default until you share it with other team members.
* **Personal (Private) Projects:** Any analyses, insights, or conversations within the project are only accessible by you (aside from admins).
* **Shared Projects:** Projects shared with 1 or more team members. Only those with access to the project can view the contents.
## Creating a Project
![Create new project dialog in Orion]()
### Project Name
Give your project a descriptive name that reflects its purpose (e.g., "Marketing Strategy", "Q4 Sales Analysis", "Customer Churn Research").
### Project Description
The project description helps you and your team quickly understand what the project is about. This short description (up to 500 characters) appears in the project list and is intended for human readers. To give Orion richer context for its analysis, use [Context](/core-concepts/knowledge-base) pages.
## Next Steps After Creating a Project
Once you have created a new project, it will appear in the left-hand navigation menu and on the main projects page.
Click into your new project to complete the setup. A dialog will appear prompting you to select a data source for the project. A project must always be connected to at least one data source to work.
![Get started with new project dialog showing data source selection]()
### Selecting a Data Source
The next modal displays a list of available [data sources](/configuration/data-sources) that have been connected by your Admin. Select one by enabling the toggle switch.
![Select data source modal with available data sources]()
### Accessing Project Settings
The Project Settings modal is always accessible by:
* Clicking the **Settings** button in the top right corner of your screen, or
* Clicking the three dots on the project item in the left-hand navigation menu and selecting **Project Settings**
From Project Settings, you can:
* Update the project name and description
* Change the selected data source at any time
## Opening a Project
A project opens on a new chat. Until you send the first message, the project's recent content sits below the chat input.
**All Content** opens the project's **Content** page, with its reports, [dashboards](/dashboards/overview), slide decks, and [workflows](/core-concepts/workflows). A project with no reports, dashboards, or slide decks yet offers **Create Content** instead. It starts a chat asking Orion to pick a first question from what it knows about you, the project, and its data. Orion then decides whether the answer becomes a report, a dashboard, or a slide deck.
On a wide screen, a side panel sits to the right of the chat input. **Quick Actions** holds **Create a Room**, which starts a [room](/chat/rooms), and **View Metrics**, which opens the project's [metrics](/metrics/overview). Below it, **Your Recent Chats** and **Recent Workflows** reopen recent work. A narrower window hides the panel.
## Memory Isolation
Memory isolation is enabled by default for all new projects.
When memory isolation is enabled, any memories formed by Orion within this project remain contained to the project itself. These memories will not be accessible in other chat conversations or analyses outside the project.
**Disabling memory isolation** allows memories formed within this project to be accessible across other projects. This is useful when you want Orion to recall memories from one project in order to inform work in another.
## Warp Drive
[Warp Drive](/core-concepts/warp-drive) limits a project to answers drawn from content your team has already approved. A question that needs more can be escalated, if the project's access policy allows it. It has its own **Warp Drive** tab in Project Settings, and it becomes available once the project has a small foundation of approved content.
## Enabling Context Pages
Context is the recommended way to provide your project with structured, organized context. By enabling [Context](/core-concepts/knowledge-base) pages for your project, Orion gains access to your organization's centralized documentation.
From the Project Settings modal, click on the **Context** tab to enable pages for this project.
![Context tab in project settings modal]()
### How to Enable Pages
1. Browse or search for Context pages in the catalog
2. Enable the pages you want Orion to have access to for this project
3. Save your changes
**By default**, Orion has no access to any Context pages until you explicitly enable them.
### Best Practices for Context in Projects
* **Keep it focused** - Enable 8-10 pages maximum per project to keep Orion focused on relevant context
* **Enable strategically** - Only enable pages that are directly relevant to this project's analysis
* **Stay organized** - Use your Context pages folder structure to find related pages
When you enable Context pages, Orion will:
* Include them throughout its analysis workflow
* Cite them with inline references in your reports, dashboards, and other deliverables
* Reference them throughout your chat conversations
* Use them to inform analytical decisions and methodology
Context pages provide the foundation of structured context that Orion
uses across chat and analysis. Combine them with file uploads for
comprehensive context coverage.
## Uploading Files to a Project
In addition to Context pages, you can upload files to provide Orion with detailed reference materials and long-form documentation. From the Project Settings modal, click on the **File Uploads** tab.
![File uploads tab in project settings modal]()
### When to Use File Uploads
Project file uploads are ideal for **long-form, unstructured documents**, especially:
* **Dense PDFs** - Research reports, whitepapers, or detailed analyses
* **Documents with images and charts** - Anything with visual content or complex formatting
* **Transcripts and notes** - Meeting recordings, interview transcripts, or detailed notes
* **Complex layouts** - Documents that are difficult to structure into Context pages
File uploads are primarily used within chat conversations for specific reference and research, rather than being integrated throughout your analysis workflow like Context pages.
### Supported File Types
Orion currently supports the following file formats for project document uploads:
* **Markdown** (.md, .markdown)
* **PDF** (.pdf)
* **Word Documents** (.docx)
* **Plain Text** (.txt)
Excel spreadsheets are not currently supported for file uploads, but we're
actively working on adding Excel support in an upcoming release. For
spreadsheet data, consider uploading to Context as structured pages
instead.
#### Common Examples of Project Files:
* Research reports and whitepapers
* PDF analyses and detailed documentation
* Meeting transcripts and interview recordings
* Competitor analysis documents with images
* Industry reports and market research
Use file uploads for dense, reference-heavy documents. Use Context
pages for structured, reusable context that Orion should consistently apply to
your project.
## Comparing Context Pages and File Uploads
Both provide context to Orion, but serve different purposes:
Structured context (metrics, definitions, procedures) used throughout chat
and analysis workflow
Long-form documents (PDFs, transcripts, historical reports) used for
specific reference in chat
## Cloning Projects
Within shared projects, you have the ability to clone projects. This is useful when you want to reuse the same project settings, data sources, and file uploads from an existing project.
For example, if you're using a project for customer-facing analytics reporting and want to use the same project configuration for a new use case, you can simply clone everything from the original project.
![Clone project option in project dropdown menu]()
Memories from an isolated project will not automatically copy into a cloned
project. Each cloned project starts with its own isolated memory.
## Sharing Projects
You can share projects two ways: directly with individual users, or by sharing them with a [Group](/configuration/groups).
### Sharing with individuals
To share a project with one or more users, click the share button in the upper right-hand corner of the project interface.
![Share button in upper right corner of project interface]()
Shared projects enable collaboration and allow you to work together with your team members on analyses.
### Sharing with a Group
If your tenant uses [Groups](/configuration/groups), you can give access to a project by sharing it with a group. Everyone in the group can access the project, with permissions matching their role in the group, so there is no need to invite members individually.
If a group has been given access to the project, Project Settings lists it on the **Details** tab. Administrators see every group with access; everyone else sees only the groups they belong to.
![Project Settings modal showing the Groups with access section listing groups that share the project]()
Direct invites and group access work side by side. Removing someone from a group doesn't cancel any direct invite they have on the project, and removing a direct invite doesn't remove them from the group.
## Project Permissions
Orion supports three tenant roles with varying levels of access. If your tenant uses [Groups](/configuration/groups), users also have a group role that may further shape what they can do within a specific project. See [Groups → Roles at a Glance](/configuration/groups#roles-at-a-glance) for a full breakdown.
Can control who has access to projects. Admins can assign users to projects
from the Manage Users tab and have full control over project access.
Can do just about anything within a project, including chatting with the
project and sharing projects. The only limitation is that analysts cannot
add existing users to other projects.
Can view projects that have been approved and view insights that have been
approved. Viewers have read-only access to approved content.
# Search
Source: https://docs.runorion.com/core-concepts/search
Find anything in your workspace with Cmd+K
Global search lets you find anything in your Orion workspace from a single input. Open it from the sidebar or with a keyboard shortcut.
## Opening Search
* Click **Search** in the left sidebar, or
* Press **⌘K** (Mac) / **Ctrl+K** (Windows/Linux)
Press **Esc** to close.
![Global search showing results for 'cost' across Projects, Artifacts, and Conversations]()
## Filtering Results
By default, search returns results across all content types. Use the filter tabs at the top of the panel to narrow to a specific type:
| Filter | What it searches |
| - | - |
| All | Everything below, combined |
| Projects | Project names |
| Artifacts | Reports, slides, and dashboards |
| Conversations | Chat messages within projects |
| Context | Wiki pages |
| Metrics | Tracked metrics |
| Workflows | Scheduled workflows |
## Reading Results
Results are grouped by content type. Each result shows:
* **Name**: the title of the item
* **Type badge** (artifacts only): Report, Slides, or Dashboard
* **Date**: when the item was last updated or created
* **Match count** (conversations only): number of matching messages within that conversation
When no query is typed, search shows recent items for the active filter.
## Keyboard Navigation
| Key | Action |
| - | - |
| ↑ / ↓ | Move between results |
| Enter | Open the selected result |
| Esc | Close search |
# Warp Drive
Source: https://docs.runorion.com/core-concepts/warp-drive
Answers drawn only from content your team already approved
Warp Drive is a project mode where Orion quickly returns governed answers from approved material like metrics, scheduled deliverables, and Context pages. Ordinary chat can reach past those sources into your warehouse. Warp Drive does not.
Turn it on for projects where business users ask well-understood questions and expect immediate responses. A finance project holding a handful of signed-off metrics is a good fit. An exploratory project where analysts are still shaping the data is not.
## What Orion Can Answer
The name describes the speed, but Warp Drive is also a governance policy. The speed follows from the smaller boundary, because Orion retrieves from approved material instead of exploring your data sources.
These sources sit inside the boundary:
| Source | What it covers |
| - | - |
| **Context pages** | Pages enabled for the project |
| **Project documents** | Files uploaded to the project |
| **Catalog metrics** | Metric definitions published to the Metrics Catalog |
| **Project metrics** | Metrics saved on the project |
| **Reports and dashboards** | Deliverables already built in the project, read from saved output |
| **Workflow outputs** | Output from a completed run of a project workflow |
| **Project memory** | What Orion has been asked to remember |
| **Conversation history** | Earlier chats in the project |
Orion can still run a query in this mode, as long as somebody defined it first. Executing a saved metric or a catalog metric is allowed, because its definition was already reviewed. Writing new queries is not.
Everything else sits outside the boundary: warehouse queries, Looker Explores, notebooks and Python, and the creation of dashboards, reports, and slide decks. Warp Drive is read-only, so it cannot edit a Context page, a metric, or a workflow either.
## Turning Warp Drive On
Warp Drive has its own tab in [Project Settings](/core-concepts/projects#accessing-project-settings).
An empty project cannot turn it on. Orion needs a foundation of approved content first.
**Readiness checks** lists the three requirements. Each row shows how many sources the project has against how many it needs, under the line "Checked automatically from project content." Until all three pass, the tab shows **Locked** instead of the on and off control.
Once the project is ready:
1. Switch **Warp Drive** on
2. Choose a **Full Analysis access** policy
3. Click **Save Changes**
## Full Analysis Access
Full Analysis is the way out of the boundary. It reruns the question with the tools and the model ordinary chat uses, and it stays selected for the rest of the chat.
**Full Analysis access** decides who is allowed to do that. The tab puts the choice as "Choose who can ask questions with Full Analysis when Warp Drive isn't enough."
| Option | Who can run Full Analysis |
| - | - |
| **No one** | Nobody. Orion names a project owner instead |
| **Project owners, analysts, and admins** | The project team. This is the default |
| **Anyone with project access** | Everyone who can open the project |
Choose according to how far you trust the approved content to cover what people will actually ask.
## What You See in Chat
When Orion cannot answer from approved content, it replies with one of the following information cards:
| Card | What happened |
| - | - |
| **Deeper analysis needed** | The request needs tools outside Warp Drive |
| **Not enough approved information** | Orion checked the approved sources and could not support an answer |
| **Answer requires deeper analysis** | Orion drafted an answer, but some claims in it need a deeper check |
Where Orion read something before giving up, the card carries **Sources checked**, listing what it read. Named deliverables, metrics, and Context pages link out so they can be inspected.
Where a draft was written and then rejected, the card also shows the draft. Orion keeps it so you can see what it nearly said and which claims it wanted to test. It is not an approved answer, and Orion does not treat it as context in later chats.
If your access policy allows it, the card offers **Run Full Analysis**. Where it does not, the card names the project owners, so you know who to ask for help.
## Who Can Change These Settings
Changing the mode or the access policy needs one of the following:
* A tenant admin or analyst with access to the project
* A project owner
* An admin of a group that has the project
Roles are covered in full under [Groups](/configuration/groups#roles-at-a-glance).
## Next Steps
Build the approved context Warp Drive reads from
Define the numbers Orion is allowed to execute
Where the Warp Drive tab lives
Turn a recurring answer into a scheduled deliverable
# Workflows
Source: https://docs.runorion.com/core-concepts/workflows
Automate a recurring analysis and the delivery of its results
A Workflow is an automation. It takes an analysis you have already validated, re-runs it on a schedule, and delivers the result to whoever needs it, without anyone opening Orion to make it happen.
They scale with the job. The simplest is one analysis, one schedule, one email. A larger one queries several sources, produces a slide deck and a CSV, decides for itself whether the numbers are worth flagging, and mails different people depending on the answer. Between those two extremes sits most of what a data team currently does by hand every Monday morning.
The recipe is fixed, and that is the point. A Workflow re-runs the notebook you already checked rather than working the analysis out from scratch each time, so the same queries and the same transformations produce this week's numbers. You are not asking a question twice and hoping the answers are comparable.
Workflows are in beta, marked **v2 Beta** in the product. Existing Workflows
keep running, but expect the interface to keep moving.
## Notebook vs Workflow
A Workflow starts from work you have already done in [Chat](/chat/basics-navigation). Get the analysis right there first, then automate it.
| | Notebook | Workflow |
| - | - | - |
| How it is created | Captured automatically as an analysis runs | Built from a notebook you choose to save |
| When it runs | When you ask Orion to re-run it in chat | On a schedule, or on demand |
| Output | Results inline in your conversation | Reports, exports, or both, refreshed in place each run |
| Who sees it | You, and anyone you share the conversation with | Anyone with project access, plus whoever the Workflow emails |
## What a Workflow is Made Of
Open a Workflow and it lays itself out as a graph of steps, running top to bottom.
![Workflow view showing a graph of connected steps: a Scheduled Run trigger, the analysis it runs, slide deck and podcast outputs, a CSV export, and an email notification step]()
* **Trigger**: when the Workflow runs. A schedule, or you pressing Run Now.
* **Analysis**: the notebook that does the work. This is the recipe, frozen at the version you validated.
* **Outputs**: what gets produced. A report, a slide deck, a dashboard, an audio briefing.
* **Exports**: data rather than narrative, such as a CSV of the underlying rows.
* **Notification**: who hears about it, and what gets attached.
Click any step to configure it. The set of steps is not fixed either, so a Workflow can grow new outputs and notifications as the need appears.
Opening a Workflow requires Analyst or Admin on the project. Viewers cannot
open one at all, not even read-only. Your level can come from a group, so
being a Viewer elsewhere in Orion does not necessarily mean you are one here.
See [Project Permissions](/core-concepts/projects#project-permissions).
## Finding Your Workflows
Each project has a dedicated **Workflows** page listing everything in one place. You get to it from the project page: scroll to the **Workflows** strip below Shared Metrics and Published Content, and click **View all**. The strip itself shows only the six most recently run, and it is the way in, so it is worth knowing where it sits.
![A project page with the Shared and Yours toggle near the top and the Workflows section highlighted at the bottom, below Shared Metrics and Published Content. The section carries a v2 Beta badge, a View all link, and one entry listing a weekly schedule, a succeeded status, and a last run two days ago]()
The Workflows page is where you actually work with them. **Shared** and **Yours** tabs separate the project's Workflows from your own, and you get search, card and list views, and sorting by name, creation date, or most recently run.
![The dedicated Workflows page with Shared and Yours tabs, card and list view toggles, a sort control set to Created, and a search field. Four workflow cards each show a preview of the workflow's graph, its name, creator, schedule, and last run]()
Each card previews the Workflow's graph, so you can tell a one-step report from a branching automation before opening anything, alongside its name, who created it, its schedule, the outcome of the last run, and when that run happened. A Workflow that has never run says so.
Workflows are also indexed in [Search](/core-concepts/search) under the Workflows filter.
A Workflow starts out private to its creator, which is why a new one appears under **Yours** rather than **Shared**. See [Sharing and Permissions](/workflows/manage#sharing-and-permissions) for how to change that.
## Next Steps
Turn a finished analysis into an automation, in the dialog or by asking
Formats, templates, publish URLs, and who gets emailed
Schedules, run history, change history, and editing
Decision steps and using metrics as the source
How to build automations that keep working
# Edit a Dashboard
Source: https://docs.runorion.com/dashboards/edit
Change a dashboard by pointing at what is wrong
Dashboards are edited by telling Orion what to change, aimed at the exact element you mean. There are two surfaces for it.
## Editing from chat
With the dashboard open in its panel beside the chat, click **Edit**. The cursor becomes a crosshair, and clicking any card, heading, or text element selects it and offers a **Comment** button.
Your comments collect in a panel, so you can send them together. Click more elements and write what to change about each one. For example, "make this a bar chart", or "this title should say Q3". Then click **Send**. Orion applies the whole batch, the canvas refreshes itself, and edit mode exits. If the result is not correct, send a follow-up reply in the same thread.
Edit mode is off by default, so filters and charts stay interactive until you ask for it.
You can also skip the pointing entirely and just ask in chat: "change the dashboard title to Q1 2026 Report".
## The dashboard editor
A dashboard also has its own editor. From the project page, open the dashboard card's menu and choose **Edit Dashboard**. The **Edit** button on a published dashboard's page opens the same editor.
You cannot drag a card to a new position, and you cannot resize or delete one by hand. Orion builds each dashboard on a layout it writes itself, so the layout is not a grid you rearrange. A banner at the top of the editor says the same thing.
What the editor gives you instead is a way to aim an instruction. Click a card to select it, then describe the change. Every structural change goes through the chat panel, including moving a card, removing one, or reordering a section.
The editor header holds **Save** and **Discard**, an unsaved-changes indicator, and a **Chat** button that docks Orion beside the canvas.
Highlight any text on the dashboard and an **Ask Orion** pill appears, attaching your selection to the next chat message. It is the fastest way to say "this number looks wrong" about the number itself.
Save before asking the chat for an edit. Orion works from the saved version
of the dashboard, and the editor warns you if there are unsaved changes.
## Who can edit
Editing requires edit access on the project: Analysts, Admins, and the project owner. Viewers can [explore](/dashboards/explore) but not change.
# Filter and Explore
Source: https://docs.runorion.com/dashboards/explore
Narrow a dashboard to the slice you care about
Everything on this page works for every project member, including Viewers. No edit access is needed to explore a dashboard.
## Filters
When a dashboard defines filters, a filter bar sits at the top:
* **Date range**: opens a calendar bounded to the dates actually present in the data, with the available range shown underneath. Coarser data swaps the day calendar for From and To pickers at its own grain, month or year.
* **Multiselect**: a checkbox list of the values in the data. The button reads **All** or **N selected**.
* **Numeric range**: **Min** and **Max** inputs, with the data's real range as a guide.
Those three are the whole set. There is no free-text search, and no relative-date preset such as "last 30 days". A dashboard filters on dates, categories, and numeric ranges only.
A **Clear** button appears at the end of the bar whenever any filter is active. A dashboard can also open with a filter already applied, which is why **Clear** sometimes shows before you have touched anything.
![A dashboard with its filter bar outlined in red, holding three controls: Date Range reading All months, Region reading All, and Office Status reading 2 selected, followed by a Clear button. The Region dropdown is open below the bar, listing an unchecked checkbox for each value in the data, from Metro Central through Rural West]()
A date filter over month-grain data, showing the From and To pickers and the range actually available:
![A dashboard with its Date Range filter open and the contents of the dropdown outlined in red: empty From and To month inputs side by side, each with a calendar button, above a line reading Data: Jul 2024 to Jun 2026]()
Filters recompute the dashboard. They do not only hide rows. KPI values, charts, and aggregated tables are recalculated exactly over the filtered dataset. Two caveats show up as labels on the dashboard itself:
* A card that ignores the filters carries a **Not filtered** badge. Hover it to read why that card was left out.
* Narrative and headline text is written from the full dataset, and says so, rather than silently pretending to match your filter.
A **Not filtered** badge is always deliberate. The author must declare each unfiltered card and give a reason for it. The badge never means that someone missed a card. The tooltip gives that reason. Usually the card answers a question that the filters would distort. Examples are a year-to-date total, a benchmark, or a figure from a different source.
![A dashboard where one card, titled Backlog Build vs. Identity Review Rate, carries a small Not filtered badge in its top left corner, outlined in red. The neighbouring cards carry no such badge]()
## Charts and tables
Charts support hover tooltips and clickable legends for isolating series. Tables sort by column, resize, and scroll smoothly at any row count.
Clicking a mark rather than hovering it starts an [investigation](/dashboards/investigate) into that specific number.
## Sharing a filtered view
On a dashboard's own page, active filters are written into the page URL. Copy the browser URL and the recipient opens the dashboard with your exact filter state applied.
# Investigate
Source: https://docs.runorion.com/dashboards/investigate
Click a number to find out why it moved
Filters narrow a dashboard. Investigate explains it.
Click a single value. Orion recomputes that number from the source data. It compares the number with the period before, if one exists. It also breaks the number into its parts. The answer opens in a rail beside the dashboard.
This is not the chat panel. Investigate returns a fixed set of computed facts with their provenance, and declines when the math will not hold up rather than guessing.
## Starting an investigation
Click any mark on a card:
* A point on a line or combination chart
* A bar, including a single segment of a grouped or stacked bar
* A pie segment
* A row in a table
* A KPI tile
The rail opens on the right. The dashboard stays live behind it, so filters and other cards keep working while an answer loads.
![A dashboard with the Investigate rail open over its right edge and the whole rail outlined in red. The rail is headed Applications in Queue and shows the clicked value, how the latest month compares with the one before, and a breakdown by region. The dashboard behind it stays fully rendered rather than shrinking to make room]()
Scatter plots, heat maps, waterfall charts, and box plots are not clickable.
Their marks have no mapping back to a measure, so Investigate is unavailable
on those cards.
## What the answer contains
The rail shows the clicked value immediately, then fills in each computed part as it arrives:
* **The value**: the number recomputed from the source data, not read off the chart
* **Change**: the same measure for the previous period, with the delta and percent change. An incomplete period is compared against the prior period truncated to the same elapsed point, labeled "vs same point in"
* **Signal**: whether the change is a real shift or ordinary variation, judged against the measure's recent history. A sustained shift also reports when it began
* **Breakdown**: which members the number is made of, or which ones moved it. The two are different, and the rail says which one you are looking at
* **Provenance**: the snapshot it was computed from, when it was computed, and which filters were in scope
Color follows the measure, not the arrow. A fall in churn reads as good, a fall in revenue does not.
Where a card offers more than one breakdown dimension, each appears as a chip under the heading. Selecting one reshapes the breakdown in place, without starting a new investigation.
![A dashboard with the Investigate rail open for a KPI called Applications in Queue, and the breakdown portion of the rail outlined in red. Under a heading reading What makes up this number, Region name and Office status are offered as chips with Region name selected, followed by six rows from Metro South down to an Other row, each carrying a count and a percent share. The clicked KPI tile on the dashboard behind is ringed to show where the answer came from]()
## Scope is frozen at the click
An investigation captures the dashboard's filters at the moment you click, so the answer cannot drift while you read it. Chips at the top of the rail show that frozen scope and where each part of it came from.
Change the dashboard filters while the rail is open and a **Filters changed** marker appears. The answer on screen still describes the scope you originally clicked.
## Following the thread
Each answer suggests its own next questions as chips, either a further breakdown or a trend over time. A chip is named for what it will do, like **By Region**. Click a chip to run a new investigation in the same rail. A trail across the top shows where you have been, such as `Actual › Acute`. The **X** at the top right closes the investigation.
For any other question, use the footer. It asks **How was this number made?** and offers **Ask Orion why**. That button sends the current scope to chat.
## When Orion declines
Investigate withholds an answer rather than produce a number it cannot stand behind. The reason is always specific:
| What you see | What it means |
| - | - |
| No data for the preceding period under these filters. | Your filters leave nothing in the prior period |
| This slice is too small to break down safely. | Splitting it further would rest on too few rows |
| Averages, ratios, and distinct counts can't be split into parts that add up. Ask Orion to compare segments. | The measure is not additive, so a contribution breakdown would be false |
| There is nothing interesting to explore here. | The recomputed value did not reconcile with the displayed one |
| The breakdown is temporarily unavailable. | A transient failure. This one offers **Retry** |
More than one can appear at once, each in its own card. **Ask Orion why** remains available underneath in every case.
![A dashboard with the Investigate rail open and outlined in red. The rail is headed Avg Review Rate and shows the value and a line comparing the latest month against the one before, but in place of a breakdown it carries a single card reading that averages, ratios, and distinct counts cannot be split into parts that add up, suggesting Ask Orion to compare segments]()
The example above is an average. Its value and its movement both resolve, and only the breakdown declines, because a share-of-total split of an average would not add up. Parts of an answer fail independently.
## Who can use it
Anyone who can open the dashboard, including Viewers. Investigate only reads data, it never changes the dashboard. See [Filter and Explore](/dashboards/explore) for the other controls that need no edit access.
# Dashboards
Source: https://docs.runorion.com/dashboards/overview
Build an interactive, filterable view of an analysis
A dashboard is an interactive layout of KPI tiles, charts, tables, and narrative text built from one of your analyses. A report or a slide deck fixes its numbers in place. A dashboard does not. You can filter it, [investigate any number on it](/dashboards/investigate), and every card recalculates.
A dashboard is the product of one analysis, so it carries that analysis's results until the analysis runs again. To keep it current on a recurring basis, make it a [Workflow](/workflows/create) output, and every scheduled run updates it in place.
Reach for a dashboard when people will come back to the same numbers repeatedly. Reach for a report or deck when the finding is the point. See [Workflow Outputs](/workflows/outputs) for that comparison in full.
![A published dashboard titled Regional Service Centers, opening with a dark header that carries the reporting period, duration, office count and headline totals, and a filter row with Date Range, Region, and Office Status dropdowns. Below it, three highlighted KPI tiles for median wait, applications in queue, and worst-case wait, then four more KPI tiles, then a Turnaround and Backlog Trends section holding a line chart of median turnaround by month beside a combination chart of backlog against review rate]()
## Creating a Dashboard
There are three ways to get one:
### From the output picker
Ask for something to share, but do not say what kind. Orion runs the analysis. Then it offers **Choose an output format**, with **Report**, **Slides**, **Dashboard**, and **Pinned Metrics**. Pick **Dashboard**, and Orion builds one from the analysis it just ran.
The picker is not automatic. A question answered in chat does not raise it on its own. It appears when Orion has a result to package and no format has a name yet.
![A finished analysis in chat, ending with Orion asking which format works best. Below it, outlined in red, a card headed Choose an output format offers four illustrated tiles: Report, Slides, Dashboard, and Pinned Metrics]()
### By asking
Ask in chat: "make me a dashboard of this", or "build a dashboard showing revenue by region with a date filter". If you ask before running an analysis, Orion runs the analysis first, so generation takes longer. A placeholder grid with a progress bar shows while the dashboard is assembled.
### As a Workflow output
Choose **Dashboard** as the output format when [creating a Workflow](/workflows/create). The Workflow keeps one dashboard at one URL. Each scheduled run refreshes the data and rewrites the narrative text from the new numbers. The layout and the filters stay the same. Until the first run completes, the dashboard's card on the project page shows **Result pending**.
## Working with the result in chat
The finished dashboard appears in the chat as a thumbnail card. Click the card, or its **Expand dashboard** button. The dashboard opens in a panel beside the chat. There you can use the [filters](/dashboards/explore), [investigate a number](/dashboards/investigate), publish the dashboard, or [edit it](/dashboards/edit).
If you iterate on the same dashboard across a conversation, Orion marks the older thumbnails as superseded, so you always know which card is current. When the dashboard is already open next to the chat, edits confirm with a compact **Dashboard updated** chip and the canvas refreshes on its own.
Every dashboard appears on the project page as soon as it is created, visible
**Only You** until you share it. Publishing and visibility are covered in
[Publish and Share](/dashboards/publish).
# Publish and Share
Source: https://docs.runorion.com/dashboards/publish
Give a dashboard a stable link and decide who sees it
A new dashboard is visible **Only You** until you publish or share it. Publishing gives it a stable link. Visibility controls whether it sits on the project's shared board.
## Publishing
Click **Publish** in the dashboard panel or editor. The dialog asks for:
* **Name**: the name of the dashboard in the list
* **Custom URL**: the link slug, `/share/` plus a name auto-suggested from the title. Edit it to something recognizable, like `revenue-overview`
Publishing copies the link to your clipboard, and the button becomes **Share Link** for grabbing it again later.
Share links require an Orion login and project access. They are for
teammates, not the open internet.
Anyone who opens the link gets the full interactive dashboard. This includes the [filters](/dashboards/explore), [Investigate](/dashboards/investigate), and an **Ask Orion** chat toggle. A project member with edit access also gets an **Edit** button.
## Visibility
Independently of the link, a dashboard is either **Only You** or on the **Shared Board**, where every project member sees it on the project page. Change it from the publish dialog or the dashboard card's menu on the project page.
## Managing from the project page
Published dashboards appear as cards on the project page with a live thumbnail and a **Dashboard** label. A dashboard that a Workflow maintains also carries a **Workflow** badge. Each card's menu offers **Open**, **Edit Dashboard**, **View Workflow** where one applies, **Visibility**, and **Delete**.
Deleting a published dashboard cannot be undone.
## Permissions
* **Viewers**: open shared dashboards and share links, use every filter. No publishing, editing, visibility changes, or deleting
* **Analysts**: create, edit, and publish dashboards. They also set the visibility of the dashboards they created
* **Admins and project owners**: manage visibility and deletion for anyone's dashboards
# Welcome to Orion
Source: https://docs.runorion.com/index
Ask your data questions in plain language, as a team
Orion is a collaborative analytics platform built by [Gravity](https://bygravity.com). Connect your data warehouse, ask questions in plain language, and share the resulting analyses, dashboards, reports, and slide decks across your team, all without writing SQL. Orion stores feedback through [Memory](/chat/memory) and learns your preferences over time, so each analysis gets faster and more accurate.
## Get Started
New to Orion? Start here to learn the fundamentals.
Organize your work with Projects - the primary organizational structure in Orion.
Learn the Chat interface and how to navigate Orion's conversation system.
Learn how to run analyses and get reports, dashboards, and other deliverables from Orion.
## Core Features
Explore Orion's powerful capabilities for data analysis and insights.
Orion captures each analysis as a notebook you can re-run any time for fresh results.
How Orion remembers project information and learns from your interactions.
Share chats and analyses with teammates so they can pick up where you left off.
Give Orion the business context it needs to produce more accurate, relevant results.
## Configuration & Setup
Customize Orion to work the way you do.
Connect and manage your data sources for analysis.
Set your personal preferences to tailor how Orion presents data and insights.
Configure company-wide settings and information.
Learn best practices for effective Chat conversations and analysis workflows.
## Need Help?
Reach out to our support team for assistance.
# Best Practices
Source: https://docs.runorion.com/knowledge-base/best-practices
How to write pages Orion actually uses well
## Keep Pages Short and Concise
Rather than creating one super long page, break your content into shorter, more focused pages. This helps Orion navigate and use your Context pages more effectively.
**Better approach:**
* One page on metrics and definitions
* One page on a standard procedure for a specific analysis
* One page for additional context on a topic
* Separate pages for different processes or guidelines
Shorter, focused pages are easier for both humans and Orion to understand and
reference.
## Start With a Clear Summary
It's recommended that at the very top of each page, you provide a description or summary of what the page contains. The first 250 characters of your page are especially important because:
* Orion uses this text to quickly glance at what the page contains
* It helps determine whether the page is relevant for your analysis
* It acts like an executive summary for the page
**Example:**
```
# Sales Metrics Definitions
Our sales team uses these key metrics to measure performance and health. Updated monthly.
## ARR (Annual Recurring Revenue)
Total committed recurring revenue normalized to an annual value...
```
## Write for Clarity
**Do:**
* Use clear, plain language
* Use headers and formatting to break up content
* Include concrete examples
* Define acronyms and industry terms
* Name folders and files in a way that's easy to understand
**Don't:**
* Use dense paragraphs without structure
* Assume Orion knows your internal terminology
* Mix different types of content on a single page
* Leave pages incomplete or outdated
## Keep Content Current
Your Context pages are only as valuable as the quality and accuracy of their content:
* Review your Context pages quarterly
* Update pages when processes change
* Remove outdated or incorrect information
* Use revision history to track important changes
## Recommended Structure
Organize your folders around your company's natural structure and functions:
**Example organization:**
```
Company Information/
├── Mission & Values
├── Industry & Competitive Landscape
└── Key Contacts
Operations/
├── Sales Process
├── Contracts & Pricing
├── Customer Onboarding
└── Returns & Escalations
Finance/
├── Metrics & KPIs
├── Forecasting Methodology
└── Accounting Practices
Product/
├── Feature Definitions
├── Technical Specifications
└── API Documentation
```
## What to Document First
Start with the essentials that most affect Orion's analysis quality:
1. **Company Information** - Industry, size, geography, business model
2. **Key Definitions** - Important metrics, terminology, product names
3. **Core Processes** - How you operate, key workflows, decision criteria
4. **Data Definitions** - What your data represents, how it's calculated
5. **Guidelines** - Preferences for analysis, communication style, reporting format
## What to Add Later
As your Context pages grow, expand with:
* Competitive intelligence
* Industry trends and context
* Historical decisions and reasons
* Standard templates and formats
* Advanced processes and edge cases
## Per-Project Context Management
When enabling Context pages for a project, it's recommended to keep this between **8-10 pages maximum** per project. This approach:
* Keeps Orion focused on relevant context only
* Improves analysis quality by reducing noise
* Makes the system more effective at navigating your company's context
**Example per-project enablement:**
* **Sales Project** - Enable pages on: Pricing, Sales Process, Key Metrics, Contracts, Customer Definitions
* **Product Project** - Enable pages on: Feature Definitions, Technical Specs, API Documentation, Product Roadmap
* **Finance Project** - Enable pages on: Metrics & KPIs, Forecasting Methodology, Accounting Practices, Budget Guidelines
## Where Project Context Lives
Use Context as the home for company-wide context instead of pasting it into free-text boxes:
* Store your company-wide context in Context
* Enable relevant pages for each project
* Reuse the same pages across projects rather than re-typing context
This creates a more maintainable, reusable system where your context is documented once and enabled where needed.
# Creating & Managing Pages
Source: https://docs.runorion.com/knowledge-base/creating-pages
Write, upload, and organize Context pages
## Creating a New Page or Folder
Go to **Context** in the left-hand navigation menu, then open **Pages Overview**. Use the page tree on the left to create folders and pages.
**To create content:**
1. Right-click on the root or any folder to see options
2. Select **Create Page** or **Create Folder**
3. Enter a name for your content
4. Start editing (if creating a page)
## Folder Structure
You can create a hierarchical folder structure with a **maximum of 3 folder levels deep**. Within folders you can create as many pages as you want.
**Important naming rules:**
* ❌ You cannot have multiple folders with the same name in the root directory
* ❌ You cannot have multiple pages with the same name within a folder
This organizational approach keeps your Context pages clean and prevents naming conflicts.
## Creating Pages
When you create a new page, you have two options:
1. **Write manually** - Use the markdown editor to type and format your content
2. **Upload a file** - Import existing documentation (see supported formats below)
### Supported File Formats for Upload
Context supports uploading:
* Text files (.txt)
* Markdown files (.md)
* Excel spreadsheets (.xlsx)
* CSV spreadsheets (.csv)
PDFs and images are not currently supported file types. For PDFs and complex
documents with images, use project file uploads instead.
When you upload a file, it will automatically be named with the name of the file you uploaded and converted to markdown format.
## Markdown Editor
The page editor provides a markdown editor with live preview. You can:
* Write your content in markdown
* See a live preview of your changes
* Format text, create lists, add headers, and more
* Save your changes when ready
## Key Information About Pages
The **first 250 characters** of your page are especially important. Orion uses this text to quickly understand what the page contains, so it's recommended to:
* Place a summary or description at the very top of the page
* Provide the most important context in those first 250 characters
* Think of it like an executive summary
## Editing & Managing Pages
### To edit a page:
* Click on the page in the left navigation to open it
* Click the **Edit** button in the top right corner
* Make your changes and save
### To rename or delete:
* Right-click on a page or folder
* Select **Rename** or **Delete**
If you try to delete a folder that contains pages, you'll get a warning. You
must first move the files out of that folder before it can be deleted. This is
a safety precaution to prevent accidentally deleting entire folders of
content.
## Organizing Your Context Pages
You can reorganize your Context pages by **dragging and dropping** pages or folders into one another. This makes it easy to reorganize your wiki pages without having to recreate them.
## Revision History
We store the revision history of all your pages. In the top left corner above the editor, you can see who updated the page last and when. This helps track changes to your Context pages over time.
## Locking Pages and the Change Request Flow
Pages can be **locked** to control who can make direct edits. Locking a page enables the change request workflow for that page.
![Context page view showing the Unlocked button in the top right corner next to the Edit button]()
### Who Can Lock a Page
Only the **page creator** or an **admin** can lock or unlock a page. Use the lock toggle in the top right of the page view (next to the Edit button).
### What Happens When a Page Is Locked
* **Admins** can always edit and delete directly
* **Non-admins** (analysts, viewers) who edit a locked page submit a **change request** instead of saving directly
* The page creator and admins are notified of pending change requests
* The page's content is unchanged until the change request is approved
### Reviewing Change Requests
Admins and page creators can review pending change requests:
1. Open the page. A banner appears when there are pending requests
2. Click **Review** to see the proposed changes
3. **Approve** to apply the changes, or **Reject** to decline them
4. Optionally add a review note explaining the decision
![Review Changes screen showing a pending edit with a unified diff view, risk level badge, and Approve / Reject buttons]()
The review screen shows:
* **Pending / History** tabs: active requests and past decisions
* **Risk level**: Minor, Careful review, or No risk, based on how much content changed
* **Unified / Split diff**: toggle between views of what changed
* **Edit proposed changes**: modify the submission before approving
* **Show full content**: see the entire page in context
Change requests can also be **bulk approved** from the Change Requests panel in the admin settings.
### Change Request Statuses
| Status | Meaning |
| - | - |
| Pending | Awaiting review |
| Approved | Changes applied to the page |
| Rejected | Changes declined |
| Auto-approved | Applied automatically (low-risk or unlocked page) |
If you are the creator of a page, your own edits bypass the change request
flow even when the page is locked.
## Enabling Pages for Projects
To use Context pages in a project:
1. Go to your project settings
2. Navigate to the **Context** tab
3. Search for and select the pages you want to enable
4. Orion will have access to these pages when working on the project
By default, Orion has no access to Context folders and files until you
explicitly provide access by enabling them within the project. This keeps
Orion focused on only the context needed for that specific project.
## Default Pages (Auto-Inject)
Administrators can mark a small set of pages as defaults that Orion includes automatically, without anyone enabling them per project. This is an opt-in setting made page by page; nothing is auto-injected until an admin selects it. There are two scopes:
* **Tenant-wide**: on the page itself, open the **...** actions menu and switch on **Project Default** (admins only). The page is included in every project in the tenant, and the sidebar marks it with a globe icon.
* **Per group**: in a [group's](/configuration/groups) **Context** tab, each linked page has an **Auto-inject** switch. When on, the page is included in chat context for everyone in that group. Group admins and group analysts can manage this alongside tenant admins.
In a project's **Context** tab, default pages appear pre-checked with a **Global Default** or **Group Default** badge. Projects can add more pages on top but can't opt out of defaults, so keep the set small: defaults ride along in every conversation in scope. Company-wide definitions and business rules belong here; everything else is better enabled per project.
# Metrics Catalog
Source: https://docs.runorion.com/knowledge-base/metrics-catalog
Reuse shared metric definitions across your projects
Use the **Metrics Catalog** to share a metric definition across projects.
Promote a metric, place it in a project, and control who can see it
# Context Pages
Source: https://docs.runorion.com/knowledge-base/overview
A wiki Orion reads from and cites during analyses
Context pages hold the written business knowledge Orion reads and cites during analysis. Organize them into folders for company information, definitions, procedures, and other shared documentation.
Go to **Context** in the left-hand navigation menu, then open **Pages Overview**. The Context area also contains the **Metrics Catalog**. This guide covers written pages.
## What Are Context Pages?
Think of Context pages as the information you would give a new employee during onboarding. They provide a single source of truth for:
* **Company Context** - Information about your organization, industry, and business rules
* **Standard Operating Procedures (SOPs)** - Step-by-step processes and workflows
* **Metrics & Definitions** - How your company defines key metrics and terminology
* **Product Documentation** - Details about your products, services, and features
* **Analytical Methods** - How to perform certain analyses, calculations, and methodologies
* **Guidelines & Best Practices** - Standards and recommendations for your team
When you enable Context pages for a project, Orion will have access to this context and can reference it to provide more accurate and relevant insights.
## Organization Structure
It's recommended that you create folders based on how your company normally organizes information, such as by department, and then within that, by certain use cases, activities, or scopes.
**Example structure:**
```
Sales/
├── Pricing
├── Contracts
└── Customer Stories
Operations/
├── Payroll Process
├── Returns Policy
└── Escalation Procedures
Product/
├── Features
├── API Documentation
└── Release Process
```
There's no specific methodology that Orion prefers, but organize folders and files in a way that is as easy to understand for Orion as it would be for a new hire.
## Key Features
Structure your documentation with nested folders (up to 3 levels deep) and
unlimited pages
Create and edit pages using a markdown editor with live preview
Upload spreadsheets, text files, and documents that automatically convert to
pages (supports .txt, .md, .xlsx, .csv)
Reorganize pages and folders by dragging them around
Selectively enable pages for specific projects to keep Orion focused on
relevant context
Orion searches and references your Context pages during analysis and chat
conversations
## Getting Started
To get started with Context pages:
1. Go to **Context** in the left-hand navigation menu, then open **Pages Overview**
2. Create your first folder or page
3. Organize your content into folders that match your company structure
4. Enable pages for projects that should have access to them
Start with essential documentation like company information, key processes,
and business definitions. You can expand your Context pages over time.
## How Orion Uses Your Context Pages
When you enable Context pages for a project:
* **Chat & Analysis** - Orion uses that context for better answers and more accurate analysis throughout your conversation
* **Citations** - In your deliverables (reports, slide decks, dashboards), you'll see small in-line source citations for wiki pages that were referenced
* **Knowledge Updates** - You can ask Orion to update wiki pages with new information or changes
The more comprehensive and well-organized your Context pages, the better Orion can tailor its analysis to your specific needs and processes.
## Context Pages vs. Project Files
The key difference between Context pages and project file uploads:
* **Context pages** - Designed for structured, concise context (metrics, definitions, procedures, guidelines) that Orion uses throughout chat and analysis
* **Project file uploads** - Designed for long-form, unstructured documents like dense PDFs with images, charts, and complex text
# External Wiki Integrations
Source: https://docs.runorion.com/knowledge-base/wiki-integrations
Import pages from Notion, Confluence, and GitHub
Connect external documentation sources to pull content directly into your Context pages.
![]()
Notion
Import pages and databases using a Notion integration token
![]()
Confluence
Browse spaces and pages using your Atlassian email and API token
![]()
GitHub
Import markdown, text, and Word files from any accessible repository
## Adding an Integration
Admins manage integrations at the tenant level under **Admin Settings**.
1. Go to **Admin Settings → Integrations**
2. Open **Knowledge sources**
3. Find the integration type (GitHub, Confluence, or Notion)
4. Click **Add connection** and enter your credentials
5. Save. Orion validates the connection before storing it
![Configuration > Integrations > Knowledge sources page showing GitHub, Confluence, and Notion integrations with existing connections and Add connection buttons]()
Once connected, the integration appears in the list with the connection name and date. Each connection can be renamed (pencil icon), browsed (link icon), or deleted (trash icon).
Only admins can add integrations. Connected integrations are available to all
users for browsing and importing content.
***
## ![]()
Notion
### Setup
Create a [Notion internal integration](https://www.notion.so/my-integrations) for your workspace, then click **Add connection** next to Notion in **Admin Settings → Integrations → Knowledge sources**:
1. Enter your **Integration Token** (starts with `secret_`)
2. Give the connection a name
3. Save. Orion validates the token before storing it
You must explicitly share each Notion page or database with the integration inside Notion before Orion can access it (**Share** → **Connections** → select your integration).
### What You Can Import
* **Pages**: Imported as markdown with full formatting preserved
* **Databases**: Rendered as markdown tables with all visible properties
* **Child pages**: Browse into a page to see nested child pages and sub-databases
### Browsing
The root level shows all pages and databases shared with your integration. Click into a database to see its rows, or into a page to see child pages.
If a page isn't showing up, check that you've shared it with the integration
in Notion's **Connections** settings.
***
## ![]()
Confluence
### Setup
Generate a [Confluence API token](https://id.atlassian.com/manage-profile/security/api-tokens) from your Atlassian account, then click **Add connection** next to Confluence in **Admin Settings → Integrations → Knowledge sources**:
1. Enter your **Base URL** (e.g. `https://yourcompany.atlassian.net`)
2. Enter the **Email** associated with your Atlassian account
3. Enter your **API Token**
4. Give the connection a name and save
### What You Can Import
* **Spaces**: Browse all available Confluence spaces
* **Pages**: Navigate root pages in a space, then drill into child pages
* **Page content**: HTML is automatically converted to markdown on import
### Browsing
The root level lists all spaces your token can access. Navigate into a space to see its root pages, then into each page to see children.
Use a dedicated service account token rather than a personal token so the
integration doesn't break if a user leaves the organization.
***
## ![]()
GitHub
### Setup
Create a [personal access token](https://github.com/settings/tokens) with `repo` scope (or `read:org` for organization repositories), then click **Add connection** next to GitHub in **Admin Settings → Integrations → Knowledge sources**:
1. Enter your **Personal Access Token** (classic `ghp_` or fine-grained `github_pat_`)
2. Give the connection a name and save
### What You Can Import
Supported file types: `.md`, `.txt`, `.docx`
* **Repositories**: Browse all repos accessible to your token
* **Directories**: Navigate folder structures within a repo
* **Files**: Import individual markdown, text, or Word documents
### Browsing
The root level lists all repositories the token can access. Navigate into a repo to browse its directory structure and select files to import.
Fine-grained personal access tokens (`github_pat_`) scoped to specific
repositories are recommended over classic tokens for tighter security.
***
## Importing Content
Import from an external source when creating a new page in Context:
1. In Context, click **+** to create a new page
2. Select the **GitHub**, **Confluence**, or **Notion** tab at the top of the panel
3. Choose a connection from the dropdown (or click **+** to add a new one)
4. Browse the list of pages and select one. A preview loads on the right
5. Choose an import mode and click to import
![Import panel showing the Notion tab selected with a connection picker, page list, and markdown preview with Read & Write and Sync Only options]()
### Import Modes
When importing, you choose how Orion handles the page going forward:
| Mode | Behavior |
| - | - |
| **Read & Write** | Imports the content as a normal Context page. You can edit it freely, and manually sync from the source at any time. |
| **Sync Only** | Keeps the page locked to the external source. Content updates automatically on a daily schedule. Manual edits are not allowed. |
Use **Sync Only** when the source is the authoritative version and you want Context to always reflect it. Use **Read & Write** when you want to import once and then own the content in Orion.
## Syncing Pages
To refresh a **Read & Write** page with the latest content from its source:
1. Open the page in the Context editor
2. Click **Sync** in the top toolbar
3. The page content is overwritten with the current version from the source
**Sync Only** pages update automatically, with no manual action required.
Syncing overwrites the page content entirely. Any manual edits made since the
last sync will be lost.
## Managing Integrations
From **Admin Settings → Integrations → Knowledge sources**, each connection has three actions:
* **Rename** (pencil icon): change the display name of the connection
* **Browse** (link icon): open the integration browser to import more content
* **Delete** (trash icon): remove the connection. Pages already imported are kept, but they can no longer be synced.
# Gemini Enterprise
Source: https://docs.runorion.com/mcp/gemini-enterprise
Add Orion as a custom MCP server data store in Gemini Enterprise
Gemini Enterprise connects to Orion through a [custom MCP server data store](https://docs.cloud.google.com/gemini/enterprise/docs/connectors/custom-mcp-server/set-up-custom-mcp-server). Once connected, your Gemini Enterprise agents can ask Orion data questions, check metrics, run workflows, and search your Context pages alongside your other connected data stores.
An official Orion connector for Gemini Enterprise is in the works with
Google. Until it ships, the custom MCP server setup below is the supported
way to connect.
## Prerequisites
* An Orion account with login credentials
* A Gemini Enterprise app in your Google Cloud project
* The **Discovery Engine Editor** role (`roles/discoveryengine.editor`) on that project
* An organization policy that permits custom MCP data stores. Google Cloud blocks them by default, so an Organization Policy Administrator must [turn the constraint off](https://docs.cloud.google.com/gemini/enterprise/docs/connectors/custom-mcp-server/override-constraint-for-custom-mcp-data-stores). If your organization also restricts [data sources](https://docs.cloud.google.com/gemini/enterprise/docs/connectors/configure-allowed-data-sources) or [egress domains](https://docs.cloud.google.com/gemini/enterprise/docs/connectors/configure-allowed-egress-fqdns), that administrator adds `custom_mcp` to `allowedDataSources` and `g.runorion.com` to `allowedEgressFqdns`
## Get OAuth Client Credentials
Gemini Enterprise authenticates to MCP servers with OAuth 2.0 and asks for a client ID and client secret. Reach out to your Gravity Solution Consultant, who will provide credentials registered for Gemini Enterprise. Store them somewhere safe; you will enter both in the next step.
## Create the Data Store
In the Google Cloud console, go to [Gemini Enterprise](https://console.cloud.google.com/gemini-enterprise), select your app, and open **Connected data stores**.
![The Connected data stores page in the Google Cloud console with the New data store button highlighted]()
1. Click **New data store**
2. Search for and select **Custom MCP Server**
3. Click **Add MCP server**
Choose **OAuth 2.0** as the authentication method and fill in the form:
| Field | Value |
| - | - |
| **MCP Server URL** | `https://g.runorion.com/mcp` |
| **Authorization URL** | `https://g.runorion.com/mcp/authorize` |
| **Authorization URL Parameters** | Leave blank |
| **Token URL** | `https://g.runorion.com/mcp/token` |
| **Client ID** | Provided by your Gravity Solution Consultant |
| **Client Secret** | Provided by your Gravity Solution Consultant |
| **Scopes** | `orion:full` |
![The MCP Server Configuration form in the Create data store flow, with Enable PKCE Support checked and Use HTTP Basic Authentication unchecked]()
Two checkboxes decide whether the connection works:
* Check **Enable PKCE Support**. Orion's authorization endpoint rejects requests without a PKCE code challenge.
* Uncheck **Use HTTP Basic Authentication**. Orion's token endpoint only accepts client credentials in the request body, so Basic authentication fails with a `401 invalid_client` error.
Click **Verify Auth** and sign in with your Orion credentials in the window that opens. If your email domain maps to more than one Orion organization, pick the organization Gemini Enterprise should access. Then click **Continue**.
The location defaults to **global (Global)**. Enter a **Data connector name** (for example, `Orion`); the ID Google generates from it cannot be changed later. Leave the optional tag and sensitive data protection policy fields blank unless your organization uses them, then click **Create**.
Gemini Enterprise takes you to the new connector's page, where **Connector state** shows **Active**. The next section turns Orion's tools on.
## Enable Orion Tools
Orion's tools appear on the connector's **Actions** screen, where you choose which ones your agents can use.
1. Open the connector from **Connected data stores**, then open **Actions** in the left-hand menu
2. If the list is empty, click **Reload custom actions**
3. Select the tools your agents should use. Start with **Ask Orion**, **List Projects** and **Get Conversation History**, or use the header checkbox to select all of them
4. Click **Enable actions** in the selection bar, and check that the **Status** column reads **Enabled**
Orion marks its read-only tools with the MCP `readOnlyHint` annotation, which Gemini Enterprise uses to run those calls without a user confirmation step. `ask_orion` carries no such annotation, because it starts an analysis rather than reading a stored value. The [Tools Reference](/mcp/tools) lists every tool by its identifier, so **Get Conversation History** appears there as `get_conversation_history`.
## Verify the Connection
In your Gemini Enterprise app, ask the agent to list your Orion projects:
> "List my Orion projects"
If the connection is working, the agent returns the projects your Orion account can access. Each user needs an existing Orion account and signs in with their own credentials the first time they use an Orion tool, so results always respect that user's Orion permissions. The authorization lasts four weeks and refreshes automatically.
Gemini Enterprise only supports the StreamableHTTP transport, which is what
Orion's MCP server uses. If the connection fails, see
[Troubleshooting](/mcp/troubleshooting).
# MCP Server
Source: https://docs.runorion.com/mcp/overview
Let an AI assistant work with your Orion projects directly
The Orion MCP server lets AI assistants such as ChatGPT, Claude, and Cursor work directly with your Orion projects, metrics, workflows, and Context. It uses the open [Model Context Protocol](https://modelcontextprotocol.io/). Add Orion to [ChatGPT](https://chatgpt.com/plugins/plugin_asdk_app_6aa9bc6e67e08191b93ea9e5219d824a) or [Claude](https://claude.com/connectors/orion) from their directories, or point any MCP client at `https://g.runorion.com/mcp`. You sign in with your Orion credentials, and there is nothing to install.
## What You Can Do
Ask your assistant in your own words. It chooses the Orion tools that fit, and Orion does the analysis.
* **Ask why a number moved**: "Why did weekly signups drop in the Growth project?" Orion runs the analysis in that project and answers with its reasoning. A full analysis takes a minute or two.
* **Check a KPI**: "How is net revenue retention trending this quarter?" Your assistant can list a project's metrics, read their latest values, and see the changes and anomalies Orion detected.
* **Run a workflow and read its report**: "Run the weekly pipeline review and bring me the report." Orion starts the run, and your assistant reads the report once it is ready. Runs take minutes.
* **Read a dashboard, slide deck, or report**: "Summarize the Q3 board deck." Your assistant reads it as text, so it can quote, compare, or build on it.
* **Work with your Context pages**: "What does our wiki say about how we count an active customer?" Your assistant can search, read, create, and edit pages. Writes use your own Orion permissions, so only Admins, Analysts, and Group Analysts can make them.
* **Pick up an Orion chat**: "Continue my churn analysis from yesterday." Your assistant can list your Orion chats, read their history, start new ones, and continue them.
* **Find what to look at next**: "What should I look into in the Marketing project this week?" Orion's recommendations come back with suggested questions to ask.
In a project with [Warp Drive](/core-concepts/warp-drive) on, a question that approved content cannot answer comes back declined. Your assistant can then offer to continue in Full Analysis, which takes longer, if the project's access policy allows it.
## Supported Clients
The Orion MCP server works with any MCP-compatible client, including:
* [ChatGPT](https://chatgpt.com/plugins/plugin_asdk_app_6aa9bc6e67e08191b93ea9e5219d824a)
* [Claude Code](https://docs.anthropic.com/en/docs/claude-code) (CLI)
* [Claude Desktop](https://claude.ai/download)
* [Cursor](https://cursor.com)
* [Windsurf](https://windsurf.com)
* [Gemini Enterprise](https://cloud.google.com/gemini-enterprise)
## Next Steps
Use [Orion Guide](/mcp/setup#add-the-orion-guide-skill) to bring relevant context from your AI assistant into Orion and create your first analysis, metric, dashboard, slide deck, or workflow.
Connect your AI assistant to Orion in under a minute.
Browse the full list of available tools.
# Setup
Source: https://docs.runorion.com/mcp/setup
Point your AI client at Orion's remote MCP server
## Prerequisites
* An Orion account with login credentials
Orion runs a remote MCP server; you do not need to install a server locally. Connect your client below, then optionally [add Orion Guide](#add-the-orion-guide-skill) to help your assistant use it.
## Server URL
```
https://g.runorion.com/mcp
```
## Connecting to Claude Code
Run the following command in your terminal:
```bash theme={null}
claude mcp add orion --scope user --transport http https://g.runorion.com/mcp
```
`--scope user` makes Orion available in every directory. Without it, Claude Code adds the server only for the directory you ran the command in.
Claude Code loads servers when a session starts, so open a new session, then authenticate:
1. Type `/mcp` in Claude Code
2. Select the **orion** server
3. Choose **Authenticate**
4. Sign in with your Orion credentials in the browser window that opens
## Connecting to Claude
Open [Orion by Gravity](https://claude.com/connectors/orion) in Claude's connector directory and choose **Add to Claude**. To add it from inside Claude instead:
1. Go to **Settings > Customize > Connectors**
2. Search for **Orion** in the Connectors search bar
3. Click to add the Orion connector
4. Authenticate with your Orion credentials when prompted
## Connecting to ChatGPT
Open the [Orion plugin](https://chatgpt.com/plugins/plugin_asdk_app_6aa9bc6e67e08191b93ea9e5219d824a) in ChatGPT's plugin directory and add it. Sign in with your Orion credentials when prompted.
## Connecting to Cursor
1. Open Cursor Settings
2. Go to **MCP Servers**
3. Click **Add Server**
4. Set **Type** to `http`
5. Set **URL** to `https://g.runorion.com/mcp`
6. Authenticate with your Orion credentials when prompted
## Connecting to Gemini Enterprise
Gemini Enterprise connects through a custom MCP server data store in the Google Cloud console, which needs OAuth client credentials from your Gravity Solution Consultant and an organization policy override. See [Gemini Enterprise](/mcp/gemini-enterprise) for the full walkthrough.
## Verifying the Connection
Once connected, ask your AI assistant to list your Orion projects:
> "List my Orion projects"
If the connection is working, you should see a list of projects you have access to.
## Add the Orion Guide skill
Orion Guide helps your assistant use relevant context and work with Orion. Add it to your assistant alongside the MCP connection.
Download the skill from the [Orion examples repository](https://github.com/Gravity-Foundation/orion-examples/tree/main/skills):
For Codex, ChatGPT, and other assistants.
Packaged skill for Claude.
Download the ZIP without unzipping it. In **Customize → Skills**, choose
**+ → Create skill → Upload a skill**, upload the ZIP, and enable it.
Skills require code execution; your organization may also need to enable
them. See Claude's [skill installation guide](https://support.claude.com/en/articles/12512180-use-skills-in-claude).
Download `SKILL.md` and add it to a project for your Orion work. Add this
project instruction: **"Read the attached SKILL.md and follow Orion Guide
when helping me with Orion."**
To use Orion from ChatGPT, your workspace also needs
[the Orion plugin](#connecting-to-chatgpt).
Download `SKILL.md` and save it at
`~/.agents/skills/orion-guide/SKILL.md` for personal use, or
`.agents/skills/orion-guide/SKILL.md` in your repository for project use.
See the [Codex skill locations](https://learn.chatgpt.com/docs/build-skills#where-codex-loads-local-skills).
Mention **`$orion-guide`** with your request.
Download `SKILL.md`, attach it or paste its contents into your assistant's
instructions, and ask it to follow Orion Guide.
## Get started
After connecting Orion and adding the skill, try:
```text theme={null}
Use Orion Guide to help me get started with Orion.
```
Already have a task in mind?
```text theme={null}
Use Orion Guide to help me [describe your task].
```
# Tools Reference
Source: https://docs.runorion.com/mcp/tools
Reference for every tool the MCP server exposes
The Orion MCP server exposes 27 tools organized into read-only and action categories. Each tool includes annotations so your AI assistant knows which tools are safe to call without confirmation.
## Action Tools
These tools create, modify, or trigger operations in Orion.
### ask\_orion
Send a natural language question to Orion and get an AI-powered data analysis response. This is the primary tool for interacting with Orion.
| Parameter | Type | Required | Description |
| - | - | - | - |
| `message` | string | Yes | The question or analysis request |
| `user_id` | string | Yes | The user ID sending the message |
| `project_id` | string | No | Project ID to scope the analysis |
| `conversation_id` | string | No | Existing conversation ID to continue |
Orion performs multi-step analyses that take 1-2 minutes. After calling
`ask_orion`, use `get_conversation_history` to poll for the final response.
Wait at least 30 seconds between polls.
### create\_conversation
Start a new Orion conversation.
| Parameter | Type | Required | Description |
| - | - | - | - |
| `user_id` | string | Yes | The user ID creating the conversation |
| `project_id` | string | No | Project ID to scope the conversation |
| `title` | string | No | Title for the conversation |
### execute\_metric
Trigger execution of a metric to refresh its current value.
| Parameter | Type | Required | Description |
| - | - | - | - |
| `metric_id` | string | Yes | The metric ID to execute |
### run\_workflow
Trigger a workflow run. Returns the created run, including its id. Runs take minutes, so poll [get\_workflow\_run\_reports](#get_workflow_run_reports) with that id to see outputs as they land.
| Parameter | Type | Required | Description |
| - | - | - | - |
| `workflow_id` | string | Yes | The workflow ID to run |
`create_wiki_page` and `update_wiki_page` write to your Context pages. An
assistant connected over MCP can add and edit pages. Writes carry your own
permissions: the backend rejects anyone who is not an Admin, Analyst, or Group
Analyst.
### create\_wiki\_page
Create a Context page or folder. The page is created immediately, with no review step.
| Parameter | Type | Required | Description |
| - | - | - | - |
| `title` | string | Yes | The page title, 1 to 200 characters |
| `content` | string | No | The page content in markdown. Empty for a folder |
| `parent_id` | string | No | Parent page ID to nest the new page under |
| `summary` | string | No | Short description, up to 500 characters |
| `tags` | array | No | Tags for categorization |
| `page_type` | string | No | Either `document` or `folder` (default `document`) |
### update\_wiki\_page
Update an existing Context page. Only the fields you pass change.
An edit to an unlocked page applies immediately, with no review. On a locked page, only the page creator edits directly. For every other caller the change is submitted as a change request. See [Locking Pages and the Change Request Flow](/knowledge-base/creating-pages#locking-pages-and-the-change-request-flow).
| Parameter | Type | Required | Description |
| - | - | - | - |
| `page_id` | string | Yes | The page ID to update |
| `title` | string | No | New page title, 1 to 200 characters |
| `content` | string | No | New page content in markdown |
| `summary` | string | No | New short description, up to 500 characters |
| `tags` | array | No | New list of tags |
| `edit_summary` | string | No | Short description of the change, for revision history |
### delete\_artifact
Delete a slide deck, dashboard, or report artifact. This is a destructive action.
| Parameter | Type | Required | Description |
| - | - | - | - |
| `artifact_id` | string | Yes | The artifact ID to delete |
## Read-Only Tools
These tools only read data and are safe to call without confirmation.
### list\_projects
List Orion projects the user has access to.
| Parameter | Type | Required | Description |
| - | - | - | - |
| `search` | string | No | Search text to filter projects by name |
| `limit` | integer | No | Maximum results (default 20) |
### list\_users
List all users in the Orion organization. Returns user ID, name, and role.
### list\_conversations
List chat conversations for a user.
| Parameter | Type | Required | Description |
| - | - | - | - |
| `user_id` | string | Yes | The user ID |
| `project_id` | string | No | Filter by project |
| `limit` | integer | No | Maximum results (default 20) |
### get\_conversation\_history
Read messages from an existing Orion conversation. Use this to poll for results after calling `ask_orion`.
| Parameter | Type | Required | Description |
| - | - | - | - |
| `conversation_id` | string | Yes | The conversation ID |
| `limit` | integer | No | Maximum messages (default 50) |
### list\_metrics
List metrics (KPIs) and views for a project. A view is a dataset metric Orion does not display whole, because it exists as a checkpoint for further analysis. A table metric is the same shape at a size you can read.
| Parameter | Type | Required | Description |
| - | - | - | - |
| `project_id` | string | Yes | The project ID |
| `pinned` | boolean | No | Filter to pinned/unpinned metrics |
### get\_metric
Get full metric detail including definition, Python code, data sources, and latest result.
| Parameter | Type | Required | Description |
| - | - | - | - |
| `metric_id` | string | Yes | The metric ID |
### get\_metric\_results
Get historical execution results for a metric, newest first.
| Parameter | Type | Required | Description |
| - | - | - | - |
| `metric_id` | string | Yes | The metric ID |
| `limit` | integer | No | Maximum results (default 20) |
### get\_metric\_insights
Get auto-detected metric insights showing significant changes and anomalies for a project.
| Parameter | Type | Required | Description |
| - | - | - | - |
| `project_id` | string | Yes | The project ID |
| `change_threshold` | float | No | Minimum change to flag, 0.0-1.0 (default 0.2 = 20%) |
### list\_workflows
List the workflows for a project.
| Parameter | Type | Required | Description |
| - | - | - | - |
| `project_id` | string | Yes | The project ID |
| `search` | string | No | Filter by text in the workflow name |
| `limit` | integer | No | Maximum results (default 50) |
### get\_workflow
Get workflow detail, including its definition (steps and outputs) and its schedule.
| Parameter | Type | Required | Description |
| - | - | - | - |
| `workflow_id` | string | Yes | The workflow ID |
`get_workflow_results` was replaced by the three tools below. Calling it now
returns an error. Reading a run's outputs takes three steps:
`get_workflow_runs` for the run id, `get_workflow_run_reports` for that run's
artifacts, then `get_workflow_report_content` for the content.
### get\_workflow\_runs
List a workflow's runs, newest first. Each run carries an id: pass it to [get\_workflow\_run\_reports](#get_workflow_run_reports) to see what that run produced.
| Parameter | Type | Required | Description |
| - | - | - | - |
| `workflow_id` | string | Yes | The workflow ID |
| `limit` | integer | No | Maximum runs (default 10) |
### get\_workflow\_run\_reports
List the report artifacts one workflow run produced. Markdown reports, slide decks, podcasts, and CSV exports each appear as one item with a format and an id. When an item carries a `share_url`, that is its full public link: share that exact URL rather than assembling one.
| Parameter | Type | Required | Description |
| - | - | - | - |
| `run_id` | string | Yes | The workflow run ID |
### get\_workflow\_report\_content
Read one report artifact's content. Markdown reports, slide decks, and dashboards return their content as markdown. Podcast audio is not readable inline, so this returns a short-lived signed download URL instead.
| Parameter | Type | Required | Description |
| - | - | - | - |
| `artifact_id` | string | Yes | A report artifact ID from `get_workflow_run_reports` |
### list\_artifacts
List slide decks, dashboards, or reports for a project.
| Parameter | Type | Required | Description |
| - | - | - | - |
| `project_id` | string | Yes | The project ID |
| `artifact_type` | string | No | Filter by type: `html_slides`, `html_dashboard`, or `markdown_report` |
| `limit` | integer | No | Maximum results (default 20) |
| `offset` | integer | No | Number of artifacts to skip for pagination (default 0) |
| `visibility` | string | No | Filter by visibility: `user_board` or `shared_board` |
| `created_by` | string | No | Filter by creator user ID |
| `has_workflow` | boolean | No | `true` for workflow artifacts, `false` for static ones |
### get\_artifact
Get the content of a slide deck, dashboard, or report as markdown.
| Parameter | Type | Required | Description |
| - | - | - | - |
| `artifact_id` | string | Yes | The artifact ID |
### search\_wiki
Search Context pages.
| Parameter | Type | Required | Description |
| - | - | - | - |
| `text` | string | Yes | Search text |
| `project_id` | string | No | Scope the search to a project |
| `limit` | integer | No | Maximum results (default 20) |
### get\_wiki\_page
Get one Context page with its full markdown content.
| Parameter | Type | Required | Description |
| - | - | - | - |
| `page_id` | string | Yes | The page ID, from `search_wiki` or `list_wiki_pages` |
### get\_wiki\_page\_by\_path
Get a Context page by its hierarchical path, for example `/internal/icp`.
| Parameter | Type | Required | Description |
| - | - | - | - |
| `path` | string | Yes | The full hierarchical path to the page |
### list\_wiki\_pages
Browse Context pages and folders to navigate the hierarchy.
| Parameter | Type | Required | Description |
| - | - | - | - |
| `parent_id` | string | No | Filter to children of this parent page |
| `page_type` | string | No | Filter by type: `document` or `folder` |
| `search` | string | No | Filter by text in the title or content |
| `limit` | integer | No | Maximum results (default 50) |
| `offset` | integer | No | Number of pages to skip for pagination (default 0) |
### list\_recommendations
Get AI-generated recommendations for a project with suggested analysis prompts.
| Parameter | Type | Required | Description |
| - | - | - | - |
| `project_id` | string | Yes | The project ID |
| `limit` | integer | No | Maximum recommendations (default 10) |
# Troubleshooting
Source: https://docs.runorion.com/mcp/troubleshooting
Fix the common MCP connection and result problems
## Connection Issues
### Authentication Fails
* Verify you are using valid Orion login credentials
* Try logging in to Orion directly at your organization's URL to confirm your account is active
* Clear your browser cookies and try authenticating again
### Client Cannot Reach the Server
* Confirm the server URL is `https://g.runorion.com/mcp`
* Check that there are no firewall or VPN restrictions blocking access
* Ensure your MCP client supports the `http` transport
## Tool-Specific Issues
### ask\_orion Returns Only an Acknowledgment
This is expected behavior. Orion's analyses are multi-step operations that take 1-2 minutes. The initial response is an acknowledgment. Your AI assistant should automatically poll `get_conversation_history` to retrieve the final analysis.
If the analysis never completes:
* Check that the `project_id` is valid and has connected data sources
* Verify the user has access to the specified project
* Try a simpler question to confirm the pipeline is working
### list\_artifacts Returns Empty
* Verify the project has published artifacts (dashboards, slides, or reports)
* Check that you are using the correct `project_id`
### Metric or Workflow Execution Fails
* Ensure the metric or workflow has valid data source connections
* Check that the underlying data source is accessible
* Try retrieving the metric or workflow details first with `get_metric` or `get_workflow` to inspect its configuration
# Metrics Catalog
Source: https://docs.runorion.com/metrics/catalog
One shared definition, reused in every project that needs it
The Metrics Catalog is a workspace-wide list of metric definitions that any project can use. A [project metric](/metrics/overview) belongs to the project that created it. A catalog metric is defined once and placed wherever it is needed, so revenue means the same thing on every board that reports it.
Use the catalog when more than one team tracks the same number. Instead of four projects each carrying their own revenue metric, one definition sits in the catalog and each project draws from it.
## Finding the catalog
Open **Metrics Catalog** in the **Context** section of the left sidebar. It is available to admins, analysts, Group Admins, and Group Analysts.
## Metric status
A catalog metric can store a definition before it can run.
Each entry carries a status:
* **Live**: has run successfully, or is scheduled to run
* **Not run yet**: has not run successfully yet
* **Paused**: the schedule is paused
* **Error**: the last run failed
* **Cannot run**: there is no definition Orion can execute
**Cannot run** means Orion cannot execute the metric yet. Add a metric created from SQL to a project to make it runnable. For an imported metric, try importing it again.
## Adding a metric to the catalog
Most catalog metrics start in a project. Create a project metric, then promote it so other projects can use the same definition and results. Tenant admins can also create a catalog metric from SQL.
**Import / export** opens four choices:
* **Import from a project**: promote metrics that already exist in a project
* **Import from dbt**: import governed metrics, which dbt keeps and runs
* **Import an Apache Ossie document**: upload a document, review what it contains, and pick where the metrics land
* **Export to Apache Ossie**: export catalog metrics as an Ossie document
Admins, and analysts who are also Group Admins, see **Manage connections**, which opens the dbt integration settings.
To promote one metric on its own, open it from the project's **Metrics** page and use **Add to catalog** in its detail sheet.
### Creating a metric from SQL
Tenant admins also see **New**, which creates a table metric from a SQL query:
1. Click **New**
2. Enter a **Name**, choose a **Data source** with your query's tables, and write the **SQL query**
3. Click **Create metric**
The query must be a single `SELECT`. Creating the metric does not run it, so check the SQL before you save. Add it to a project before running or scheduling it. Until its first placement, only admins can manage it.
## The inventory
Open a metric from **Inventory** to place it in a project or change its definition. Use the **Cannot run** card to find entries that need attention.
The catalog loads up to 5,000 metrics. Past that, the page says how many
loaded, and search and filters cover only the loaded ones.
## Projects and Sources
Use **Projects** to find where catalog metrics are used, then **Manage metrics** to open a project.
Use **Sources** to check where a definition is managed before you change it.
## Placing a metric in a project
A catalog metric reaches a project as one of two kinds, shown under **Project Usage** on the metric page:
* **Shared**: the project reads the catalog definition. Every shared project updates together
* **Project copy**: the project gets its own copy, which runs on its own and keeps its own results
**Shared** is the default. Use it when projects should read the same result from the same run. Choose **Project copy** for separate schedules, data sources, and run histories. Catalog definition changes still apply to every project copy, which keeps its own data-source choices.
Some metrics support only **Shared value**. If Orion says a metric runs on an external integration, choose **Shared value**. A metric already placed in a project cannot be switched from one kind to the other.
To place a metric:
1. Open the catalog metric and click **Add to project** under **Project Usage**
2. Choose a project and select **Shared value** or **Project copy**
3. If data-source choices appear, point each query at a data source in the selected project
4. If **Test** appears, run it and check the result
5. Click **Add** after any required test passes
Adding another placement requires permission to change the metric in every project that already uses it, plus membership in the target project.
Removing a project copy from **Project Usage** keeps it as an independent project metric. Choose **Also delete this project's copy** to delete it instead.
## The metric page
**What Orion Understands** draws the metric's neighborhood from your written Context pages. A solid line means a page states the relationship. A dashed line means Orion concluded it. Click a line to read the sentence it came from and open the page that carries it.
**Generate** draws the picture the first time, and **Refresh** redraws it. Both require permission to change the metric. You can read an existing diagram without that permission. A **Changes since last refresh** badge appears when a cited page has changed.
**Metric Owners** records who owns the metric. **Where this Metric is used** lists the reports and workflows that read it, and counts anything sitting in a project you cannot open.
**Source and Definition** holds the query and the transformation. A metric that Orion can run will not save until a test run passes. Each save goes into the edit history, with an optional change summary. For writing and visualizing a metric, see [Managing Metrics](/metrics/manage).
If the metric feeds published reports, Orion names them and asks once before saving, because the next build of each one uses the new numbers.
The **...** actions menu carries **Run now**, **Schedule runs**, a lock switch, and **Delete**. Locking blocks edits to a metric's name and definition until somebody unlocks it.
**Delete** removes the catalog entry permanently. Project copies remain as
independent metrics unless you select **Also delete each project's copy**,
which permanently deletes them too.
## Restricting a metric to a group
Catalog metrics are visible across the workspace by default. To narrow one:
1. Open the group in **Configuration**
2. Choose its **Metrics Catalog** tab
3. Use **Add metric** to name the metrics or folders that group may see
A restriction is an allow list, and it outranks placement. Once a metric is restricted, only members of that group see it, even in projects they share with everybody else. Admins and analysts are not affected.
Restricting a metric removes it from viewers who could previously see it
through a project, and they are not told. Check who relies on a metric before
you restrict it.
## Permissions
* **Viewers**: see a catalog metric placed in a project they can reach, restricted to their group, or created by them. They open the metric page and read its value, owners, usage, definition, and project copies
* **Group Analysts and Group Admins**: also open the catalog from the sidebar, which lists the metrics they can read. Group Admins also manage which catalog metrics their group can see
* **Analysts**: see every catalog metric, and can promote and import. Changes to an existing metric require membership in every project that uses it
* **Admins**: do all of that for every metric, create metrics from SQL, restrict metrics to groups, and manage metrics that are in no project
A viewer with no group seat has no **Metrics Catalog** row in the sidebar,
and reaches a metric through the project that uses it.
# Managing Metrics
Source: https://docs.runorion.com/metrics/manage
Run, reschedule, and inspect a metric you already saved
Click any metric card to open its detail sheet. This is where a metric is run, scheduled, visualized, and retired. Opening a metric from the project board also puts its ID in the page URL, so you can share a link that opens straight to the metric.
## The Detail Sheet
From top to bottom:
* **State and visibility** - The state pill (Active, Paused, Error, Draft) and the Shared/Private toggle
* **Name and description** - Click the name to rename it inline
* **Run Now** - Executes the metric immediately. Most runs finish within a minute; slow ones keep running in the background
* **Current Value** - The latest result, rendered per the metric's visualization
* **Schedule** - When the metric refreshes automatically
* **Historical Results** - Up to 20 recent runs, expandable for table results
* **Query & Code** - The sources and transformation behind the value
* **Delete Metric** - Removes the metric and its entire run history
Viewers see a reduced sheet: the current value and history, without the run, schedule, code, or delete controls.
## Visualizing results
What you can adjust depends on the value type:
* **Numbers, percentages, currency** - Render as a large formatted value
* **Tables** - Get a chart-type toggle (table, bar, line, grouped bar, stacked bar, pie, scatter, combo, heatmap, waterfall, boxplot, offered when the data suits them) plus X and Y column selectors. A **Save Visualization** button appears once you change something
* **Field sets** - Render as a tile layout; a layout editor picks which fields show, their labels, and their format
Table results also have a **Download CSV** button that exports the full result set.
For anything beyond chart type and axes, ask Orion in chat: colors, titles, decimal places, prefixes and suffixes, and threshold lines (a marker line on the chart at a value you name, for example a red line at your SLA limit).
## Scheduling
The Schedule section offers **None**, **Hourly**, **Daily**, **Weekly**, **Monthly**, and **At times**:
* **Hourly** - Every 1, 2, 3, 4, 6, 8, or 12 hours, on the quarter hour you pick
* **Daily** - Choose days of the week, including presets for every day, weekdays, or weekends
* **Monthly** - A day of the month, 1st through 28th
* **At times** - Up to five specific times per day
Times are shown in your local timezone and converted automatically. The next scheduled run shows at the top of the section.
## Run history
**Historical Results** lists recent runs with their values; failed runs carry an error icon, and table results expand inline. **Select** enters a selection mode for deleting runs you don't want to keep.
Deleting run history is permanent, and so is deleting the metric itself.
## Query & Code
The **Query & Code** section shows each data source with its variable name. SQL sources render with syntax highlighting, a plain-language summary of what the query does, and a diagram of how data flows through it. Looker sources show the query structure and link back to Looker.
Sources and transformation code are read-only here. To change them, ask Orion in chat:
* "Update the metric to exclude internal accounts"
* "Fix this metric" (after a failed run, Orion repairs the code)
* "Change the metric's schedule to weekdays at 7am"
Orion dry-runs every change against real data before saving it.
## Metrics in chat
* **@-mention** a metric in any chat to bring it into the conversation
* Ask "how is this metric calculated?" for its lineage: sources, transformation, and how data flows between them
* Ask Orion to load a metric's history into an analysis to chart it over time or build it into a deliverable
When Orion discusses a metric, it renders the live metric card in the chat. Click the card to open the full detail sheet.
## Deleting a metric
**Delete Metric** removes the metric and all of its run history, permanently. If a Workflow or notebook references the metric, deletion is blocked and Orion lists the dependents, so you can't silently break a scheduled Workflow. See [Metrics as a source](/workflows/advanced#using-metrics-as-the-source) for how Workflows consume metrics.
## Permissions
* **Viewers** - See shared metrics, open the sheet, browse history
* **Analysts** - Everything: run, rename, schedule, visualize, delete. Sharing to the board is limited to metrics they created
* **Admins and project owners** - Can also change visibility on anyone's metric
# Metrics
Source: https://docs.runorion.com/metrics/overview
Track a number from an analysis over time
A metric is a value Orion tracks over time: revenue this week, active users, churn rate, or a whole table of results. Once created, a metric re-runs on its own schedule, keeps every result as history, and renders as a live card on the project board.
Where a chat analysis answers a question once, a metric keeps answering it. That makes metrics the building block for everything recurring in Orion: project boards your team checks daily, and [Workflows](/workflows/advanced#using-metrics-as-the-source) that read metric values on a schedule.
## What a metric contains
* **Data sources** - One or more queries, SQL or Looker, that pull the raw data
* **A transformation** - Python code that turns the query results into the tracked value
* **A value type** - A number, percentage, currency, string, table, or a small set of fields
* **A visualization** - How the card renders: big number, chart type, colors, labels
* **A schedule** - How often the metric refreshes on its own
* **Run history** - Every execution result, kept so you can see the value over time
Each metric shows a state pill: **Active**, **Paused**, **Error**, or **Draft**.
## Creating a Metric
Metrics are created in chat. Ask Orion to track something, and it builds the metric for you:
* "Track daily active users from BigQuery"
* "Create a metric from this SQL query"
* "Turn the revenue number from this analysis into a metric"
Before anything is saved, Orion validates the metric with a dry run against your real data and shows you the result. The metric is only created after you confirm.
The easiest path: run an analysis in chat first, then ask Orion to track the
number you care about. The metric inherits the validated logic from the
analysis.
### Orion Suggested metrics
Orion can also propose metrics proactively based on your project data. These carry an **Orion Suggested** badge and a banner explaining where they came from, with a **Hide from Shared Board** button if the suggestion misses.
## Shared and personal metrics
The project home page has two tabs:
* **Shared** - The shared board. **Shared Metrics** are visible to every project member.
* **Yours** - **Your Metrics**, everything you created, shared or not.
Every metric card has a visibility button: a single-person icon means **Private**, a multi-person icon means **Shared**. Click it to move a metric on or off the shared board; a confirmation dialog (**Add to Shared Board?**) makes the change explicit.
Visibility can be changed by admins, the project owner, or the metric's creator. Everyone else sees a lock explaining who can.
Sharing a metric is how it becomes a tile on the project board for the whole
team. If the board looks empty, check the **Yours** tab: metrics start out
visible only to their creator.
## Arranging the board
Shared metrics render in a four-column grid on the project page:
* **Reorder** - Drag a card to a new position
* **Resize** - Drag the handle in a card's bottom-right corner to change its footprint
* Layout changes save automatically
## Next steps
* [Managing Metrics](/metrics/manage) - The metric detail sheet: run, schedule, visualize, and delete
* [Metrics as a Workflow source](/workflows/advanced#using-metrics-as-the-source) - Drive scheduled Workflows from tracked metrics
* Metrics are indexed in [Search](/core-concepts/search) under the Metrics filter
# Email Digest
Source: https://docs.runorion.com/profile-settings/email-digest
Get a weekly summary of your projects by email
The Email Digest is a weekly automated email that summarizes the latest insights and activity from your selected Orion projects. Orion personalizes each digest to your role using your profile bio and any additional instructions you provide, so no manual report writing is required.
You can create multiple digests (one per project, say, or one for different audiences), each with its own schedule.
![Email Digest list view]()
## Create a Digest
![Email Digest create form]()
1. Go to **Settings → Email Digest**.
2. Click **Add New Digest**.
3. Fill in the form:
* **Digest Name**: a label for this digest (e.g. "Weekly Marketing Summary").
* **Your Bio**: Orion uses your profile bio to personalize the digest content to your role and preferences. You can edit it inline from this page, or update it in [Profile Management](/profile-settings/profile-management).
* **Additional Instructions** *(optional)*: free-text guidance Orion follows when writing the digest. Use this to focus on specific metrics, highlight anomalies, or set a preferred tone (e.g. "Prioritize conversion metrics and flag any week-over-week drops greater than 10%").
* **Selected Projects**: choose one or more projects. Orion draws insights from all selected projects when composing the digest.
* **Schedule**: pick a day of the week, delivery time, and timezone. Digests are sent weekly.
4. Click **Save Changes**.
At least one project must be selected and a name must be provided before you
can save. The digest will not send until it is enabled.
## Enable or Disable a Digest
Each digest has an **Enabled** toggle visible in the list view. Disable a digest to pause delivery without deleting your configuration. Re-enable it at any time to resume on the existing schedule.
## Edit a Digest
1. Go to **Settings → Email Digest**.
2. Click the icon next to the digest.
3. Update any fields, including the enabled state, schedule, projects, or instructions.
4. Click **Save Changes**.
## Send a Test Digest
Send yourself a one-off digest email at any time to preview the content before the next scheduled delivery.
1. Go to **Settings → Email Digest**.
2. Click the icon next to the digest.
3. Check your inbox. The test email arrives within a few minutes.
You must save your preferences before sending a test digest.
## View Digest History
1. Go to **Settings → Email Digest**.
2. Click the icon next to a digest to open the history drawer.
3. The drawer lists all previously sent digests with their sent timestamps.
## Delete a Digest
1. Go to **Settings → Email Digest**.
2. Click the icon next to the digest.
3. Confirm the deletion in the dialog.
Deleting a digest permanently removes it and stops all future scheduled deliveries immediately.
## How the Digest Content is Generated
When a digest is due, Orion:
1. Fetches recent insights and activity from your selected projects.
2. Uses your profile bio to understand your role, focus areas, and communication preferences.
3. Applies any additional instructions you've set to shape the content.
4. Generates a curated email summary and delivers it to the email address on your account.
The more context you provide in your bio and instructions, the more relevant and personalized the digest will be.
# Integrations & Connectors
Source: https://docs.runorion.com/profile-settings/integrations
Connect Slack, Google, and Fireflies to your account
Orion integrates with Slack (ask questions and start analyses from any channel), Google Calendar (share schedule context), Google Slides (auto-generate presentations from analyses), and Fireflies.ai (bring meeting transcripts into analyses). Connect them from **Settings > Connectors**.
## Accessing Integrations
To connect integrations to your account:
1. Go to **Settings**
2. Select the **Connectors** tab
This is where you can manage connections to external apps and services.
## Slack Integration
### What You Can Do
Connect Orion to Slack to:
* **Message Orion directly** - Type questions and requests in Slack
* **Use @ mentions** - Reference Orion with `@orion` in channels
* **Start analyses** - Kick off analyses and ask questions without leaving Slack
* **Stay in your workflow** - Get insights without switching applications
### Setup
The Slack integration requires two connections:
1. **Workspace Slack** - Connects your Slack workspace to Orion
2. **Individual account** - Links your personal Slack account to your Orion profile
Once connected, you can reference Orion in any channel or direct message to
ask questions or request analyses.
## Google Calendar Integration
### What You Can Do
Connect Orion to your Google Calendar to:
* **Share schedule context** - Allow Orion to see your upcoming and past events
* **Control privacy** - Specify which calendar events Orion can access
* **Enable automation** - Support for future calendar-based automations
### Permissions
When you connect Google Calendar, you can:
* Grant Orion access to specific calendars
* Choose which events to make visible
* Update permissions at any time
Orion respects your privacy settings. You control exactly which calendar
events are visible to Orion.
## Google Slides Integration
### What You Can Do
Connect Orion to Google Slides to:
* **Create presentations** - Have Orion generate slides directly
* **Publish automatically** - Push new slides to your Google Workspace
* **Access existing presentations** - Pull presentations from your workspace
* **Edit content** - View and edit presentations directly through Orion
### Requirements
The Google Slides integration requires:
* Access to your Google Workspace account
* Permission to create and edit presentations in your workspace
Use Google Slides integration to quickly generate reports, presentations, and
shareable insights from your analyses.
## Fireflies.ai Integration
### What You Can Do
Connect Orion to Fireflies.ai to bring your meeting record into chat:
* **Recall meetings** - "What did we discuss in the last meeting?" or "Show me my recent meetings"
* **Pull out decisions** - Action items, summaries, and outlines from any recorded meeting
* **Find the right meeting** - Search by title, check who attended, get the full transcript with speakers and timestamps
* **Feed analyses** - Fold meeting notes into an analysis as context
Orion uses your own Fireflies credentials, so it only sees meetings your Fireflies account can access.
### Setup
1. Go to **Settings > Connectors** and find **Fireflies.ai**
2. Click **Connect**
3. Paste your **Fireflies API Key** and click **Connect Fireflies**
Your API key is in your [Fireflies settings](https://app.fireflies.ai/settings#api). Once connected, the card shows the linked Fireflies account name and email.
# Profile Management
Source: https://docs.runorion.com/profile-settings/profile-management
Keep your account details and bio current
Update your profile information and customize how Orion knows you.
## Accessing Your Profile
To access your profile settings:
1. Click on your **user account icon** in the bottom left corner of the left-hand navigation menu
2. Select **Profile**
This will take you to `Settings > Profile`.
## Editing Your Profile
In your profile settings, you can update:
* **Name** - Your first and last name
* **Username** - Your unique username
* **Email** - Your email address associated with the account
## Profile Bio - Tell Orion About Yourself
The **profile bio** (also called "About Me" section) is one of the most important parts of your profile. This is where you tell Orion:
* **Who you are** - Your role and background
* **What you do** - Your responsibilities and focus areas
* **Your preferences** - Your communication style and analysis preferences
The more detailed your profile bio, the better Orion can personalize your
experience. Include information about your communication preferences and what
types of analysis you typically need.
## Why Your Profile Matters
Your profile information helps Orion:
* **Enhance the [chat](/chat/basics-navigation) experience** - Provide responses tailored to your role and communication style
* **Personalize analyses** - Create insights that align with your specific needs and preferences
* **Improve accuracy** - Better understand context and nuances relevant to your work
# User Onboarding & Invitations
Source: https://docs.runorion.com/profile-settings/user-onboarding
Bring a new teammate into your tenant
Learn how to invite new team members to your Orion tenant and guide them through the account creation process.
## Inviting a New User
To add a new user to your Orion tenant:
1. Navigate to **Settings** in your tenant
2. Select **Manage Users**
3. Enter the new user's email address
4. Choose the permission level to assign them
5. Send the invitation
Only tenant administrators can invite new users.
## Account Creation Process
Once you send an invitation, the new user will receive an email with instructions. Account creation is a two-step process.
### Step 1: Account Details
The new user clicks the invitation link and enters:
* First name
* Last name
* Username
* Password
The email address is pre-filled from the invitation and cannot be changed. If they need a different email, they must request a new invite from an admin.
### Step 2: LinkedIn Profile (Optional)
After setting up their account details, the new user is prompted to add a bio. Orion uses the bio to personalize insights and analysis.
They can either:
* **Paste a LinkedIn profile URL**: Orion will automatically research the profile and generate a bio, including their current role, company, and key interests.
* **Write a bio manually**: Enter a short description of their role and focus areas directly.
* **Skip for now**: Proceed without a bio and add one later via [Profile Management](/profile-settings/profile-management).
Adding a LinkedIn URL is optional but recommended. It allows Orion to tailor
analysis to the user's role and context without any manual writing.
## Getting Started
After account creation, the new user is automatically redirected to `runorion.com`. They can then:
1. Log in with their new credentials
2. Access the tenant
3. Start exploring projects and using Orion
# User Preferences
Source: https://docs.runorion.com/profile-settings/user-preferences
Set the default chart type for your analyses
Set your personal preferences to tailor how Orion presents data and insights to you.
## Accessing User Preferences
To access your preferences:
1. Go to **Settings**
2. Select the **Preferences** tab
## Visualization Preferences
Your visualization preferences determine how Orion formats data when creating tables and charts in your insights and chat conversations.
![Visualization preferences settings showing different chart type options]()
### Available Visualization Options
Choose your preferred visualization type from:
* **Table View** - Standard tabular format
* **Bar Chart** - Simple bar chart visualization
* **Grouped Bar Chart** - Multiple series displayed as grouped bars
* **Stacked Bar Chart** - Stacked bar format for comparative analysis
* **Pie Chart** - Pie chart format for part-to-whole relationships
* **Scatter Plot** - Scatter plot for correlation analysis
* **Combo Chart** - Combined chart with multiple chart types
* **Heat Map** - Color-coded heat map visualization
### How Preferences Affect Your Experience
Your selected visualization preference will influence:
* **Chat insights** - The types of charts you see when asking Orion questions
* **Analysis results** - Default visualization formats for Orion's analyses
* **Data presentations** - How Orion presents data in responses (subject to underlying data compatibility)
Your visualization preference is a default setting. Individual analyses may
use different visualizations when appropriate for the specific data and
analysis type.
# Quickstart
Source: https://docs.runorion.com/quickstart
From first login to your first analysis in about 15 minutes
Orion is an AI-powered analyst: you ask questions in plain language and it queries your data and returns results inline. This guide takes you from logging in to your first analysis in about 15 minutes, then shows what you can do with the result.
If you have joined a shared test or demo workspace, it may already include
example projects, pinned metrics, and dashboards. Open them to see finished
output, then run your own analysis using the steps below.
## Step 1: Open a project
A [Project](/core-concepts/projects) is the primary unit of work in Orion. It bundles your chats, analyses, data sources, and context together.
Pick an existing project from the left-hand navigation, or create a new one.
A project must be connected to at least one [data source](/configuration/data-sources) to run an analysis. New projects prompt you to select from the sources your administrator has connected.
## Step 2: Ask your first question
Open [Chat](/chat/basics-navigation) inside the project and ask a question in plain language. Orion writes and runs the query, returns results inline, and captures the analysis as a [notebook](/chat/running-analyses#what-is-a-notebook) you can re-run any time.
Not sure what is in your data yet? You do not need to know the tables behind it. Start by asking Orion to [explore what is available](/chat/best-practices#explore-data-first), for example:
* "What data can you see?"
* "Tell me a little about the data that's available."
Once you know what is there, ask a specific question:
* "What were our top 10 customers by revenue last quarter?"
* "Show churn by product line over the last 90 days."
* "Compare this month's signups to the same period last year."
Be specific and give context. Clear questions and explicit guidance produce
better results. The more context you provide upfront, the less you have to
correct later.
## Step 3: Refine the result
Your first pass usually gets you most of the way. Ask follow-up questions, request edits, or adjust formatting until the result is right. Each correction also teaches Orion through [Memory](/chat/memory), so it gets faster over time. See [Best Practices](/chat/best-practices) for getting sharper results with less back-and-forth.
## Step 4: Put the result to work
Once an analysis is right, reuse it or turn it into a [deliverable](/chat/running-analyses#what-you-can-do-after-an-analysis):
* **Refresh the numbers** by simply asking Orion in chat to re-run the notebook. It pulls the latest data, no rebuilding required.
* **Turn the notebook into a workflow** to run it on a schedule or trigger an alert when a value crosses a threshold.
* **Generate a report or slide deck** to package the findings for stakeholders.
* **Pin a metric** to surface a key number as a tile on your project page, then publish it as a shared pinned metric.
* **Publish a dashboard** to hand a finished result to a business user.
* **Share it** with a teammate so they can pick up where you left off. See [Sharing conversations](/chat/share-conversations).
* **Set up an email digest** for a weekly AI-generated summary of the project's insights. See [Email digest](/profile-settings/email-digest).
## Next steps
The full analysis lifecycle and what you can produce from it
Get sharper results with less back-and-forth
Give Orion the business context it needs
Organize work and set project-level context
# Export a Project
Source: https://docs.runorion.com/version-control/export
Download a project's definition as one TOML file
Any project can be exported as a single TOML file with its definition: settings, data source selections, Context pages, metrics, notebooks, and Workflows. The file is plain text, and two exports of an unchanged project are identical, so a diff shows only real changes. Use it to keep projects under [version control](/version-control/sync-to-git) or to [import](/version-control/import) a project into another tenant.
## What the File Contains
| Section | Contents |
| - | - |
| `[project]` | Name, description, slug, and project settings |
| `[[groups]]` | The groups that have access to the project, by name. Grants only, not members |
| `[[datasource_selections]]` | Each connected data source by name and type, and which tables and fields the project uses. No connection details |
| `[[catalog_metrics]]` | Which tenant-level catalog metrics the project uses, and in which mode. The metric definitions themselves stay in the catalog |
| `[[wiki_pages]]` | Context pages linked to the project: title, path, parent, tags, and full content |
| `[[metrics]]` | Metric definitions: description, visibility, value type, Python code, SQL sources with their data source, schedule, and dashboard card layout |
| `[[insight_makers]]` | Saved notebooks: cells, sources, parameters, metric references, schedule, and context instructions |
| `[[workflows]]` | Each Workflow's name, schedule, and its step definition, verbatim |
References between exported items use slugs derived from names. Workflow bodies retain embedded IDs and include reference maps used during import. Groups and catalog metrics also retain their IDs as external references. Cross-tenant imports depend on matching data sources and other existing dependencies; review the [import requirements](/version-control/import#what-must-already-exist) and warnings.
## What Is Not Included
* Outputs: run results, reports, slide decks, CSV exports, and podcasts
* Chat conversations, memories, and uploaded files
* Data source connections and credentials. A source is named by data source name and type only
* User identities, ownership, timestamps, and other audit fields
* Private and draft content. The file includes shared, published, or pinned metrics, published or template notebooks, and shared Workflows. A draft that a shared Workflow depends on is included so the Workflow can be re-imported in working order
## Who Can Export
Export needs admin capability on the project: a tenant Admin, the project owner, or a Group Admin of a group with access to the project. Analysts and Viewers do not see the option. See [Roles at a Glance](/configuration/groups#roles-at-a-glance).
## From the App
Go to **Projects**, hover over the project, and click the three-dot menu.
The same menu is available next to each project in the left-hand
navigation menu.
![The Projects page with one project's actions menu open. The menu lists Settings, Members, Clone Project, Export Project Data, and Delete. Export Project Data is outlined in red]()
A dialog summarizes what the file will contain. Leave **Include run
history** off for a file meant for version control. Click **Export**. The
browser downloads `.dsl.toml`.
![The Export project dialog over the Projects page. It says the download holds the project's definition as a TOML file and that deliverables are not included. Below that are an Include run history switch, turned off, and Cancel and Export buttons]()
### Include run history
Turn this on to append what ran and whether it failed, for each metric, notebook, and Workflow. The file gains a `[meta]` block with the export time and a `history` list per item: run times, status, and error messages, no payloads. **Runs per item** caps each list, 50 by default and 500 at most.
The timestamp makes every export unique, so keep history off for version control. Files with history are for incident review and audit sampling. Import accepts them but drops the history.
## From the API
The export endpoint is the same one the app uses. Authenticate with a bearer token, then request the file.
### Get a token
Exchange a username and password for a token at the login endpoint. The token is valid for four weeks.
```bash theme={null}
export ORION_URL="https://your-tenant.runorion.com"
TOKEN=$(curl -sf -X POST "$ORION_URL/api/auth/login" \
--data-urlencode "username=$ORION_USER" \
--data-urlencode "password=$ORION_PASSWORD" | jq -r .access_token)
```
The password login endpoint requires a stored Orion password. An SSO-only
account without one cannot use this endpoint. Run this example as a
dedicated account with an Orion password. See [Export Orion Snapshots to
Git](/version-control/sync-to-git#prerequisites).
### Download the file
```bash theme={null}
curl -sf -H "Authorization: Bearer $TOKEN" \
"$ORION_URL/api/projects//dsl-export/" \
-o finance-kpis.dsl.toml
```
The project ID is the last segment of the project's URL in the app, `/projects/`.
Keep the trailing slash on `/dsl-export/`. A different path can return a
redirect instead of the TOML file; `curl -f` alone does not reject redirects.
| Query parameter | Default | Meaning |
| - | - | - |
| `include_history` | `false` | Also export run history. Adds a `[meta]` block with a timestamp |
| `history_limit` | `50` | Most recent runs kept per item when history is on. Between 1 and 500 |
The response body is the TOML document with content type `application/toml`. Two response headers are set:
* `Content-Disposition` gives the filename: the project name as a slug, plus `.dsl.toml`
* `X-Dsl-Export-Summary` counts what was left out or could not be resolved, for example `excluded_metrics=3` when three private metrics were skipped
| Status | Meaning |
| - | - |
| `401` | Missing, invalid, or expired token |
| `403` | The account does not have admin capability on this project |
| `404` | No project with that ID |
| `422` | `history_limit` outside 1 to 500 |
## Sample Export
An abridged export. SQL and Python are stored as multi-line strings, exactly as written, so a diff of this file shows query changes line by line.
```toml theme={null}
[project]
slug = "finance-kpis"
name = "Finance KPIs"
description = "Monthly close metrics for the finance team"
[[datasource_selections]]
datasource = "Snowflake Production"
datasource_type = "snowflake"
snapshot_version = 3
[[metrics]]
slug = "net-revenue"
name = "Net Revenue"
description = "Net revenue for the trailing 30 days"
visibility = "shared"
state = "active"
is_pinned = true
value_type = "number"
schedule_enabled = true
schedule_cron = "0 6 * * *"
python_code = """
result = round(float(df["net_revenue"].iloc[0]), 2)
"""
[[metrics.sources]]
variable_name = "df"
source_type = "query"
execution_order = 0
datasource = "Snowflake Production"
datasource_type = "snowflake"
[metrics.sources.query_config]
query = """
SELECT SUM(amount) AS net_revenue
FROM finance.revenue
WHERE booked_at >= DATEADD(day, -30, CURRENT_DATE)
"""
[[workflows]]
slug = "monthly-close-digest"
name = "Monthly Close Digest"
visibility = "shared_board"
schedule_enabled = true
schedule_cron = "0 8 1 * *"
schema_version = "1.0"
toml = """
schema_version = "1.0"
[[steps.metrics]]
id = "net-revenue"
metric_id = "2f1c9c2e-3b6d-4d7a-9a1e-6c1f4d2b8e10"
[[steps.reports]]
id = "close-summary"
format = "markdown"
[steps.reports.recipe]
metric_ids = ["2f1c9c2e-3b6d-4d7a-9a1e-6c1f4d2b8e10"]
"""
[workflows.refs.metrics]
"2f1c9c2e-3b6d-4d7a-9a1e-6c1f4d2b8e10" = "net-revenue"
```
The Workflow body keeps the IDs it was saved with, and the `refs` table maps each one to a slug in the same file. Import uses that map to connect the Workflow to the metrics it recreates.
## Next Steps
Schedule snapshots and review exported differences in pull requests
Create a project from a committed file
# Import a Project
Source: https://docs.runorion.com/version-control/import
Create a project from an exported TOML file
The create endpoint documented here imports a new project from a file produced by [Export](/version-control/export). Use it to reconstruct an exported definition as a new project, move a project between tenants, or create a copy for review. This create operation does not update an existing project or automatically apply Git commits to Orion.
## Who Can Import
A tenant Admin or a Group Admin can use preview and create. Project ownership alone does not grant import permission. Import creates tenant-level Context pages and binds existing catalog metrics.
## What Must Already Exist
Import recreates supported project content, including exported Context pages. The following dependencies must already exist:
* **Data sources**: Every data source the file names must exist in the tenant with the same name and type. A missing one is an error and nothing is written. Connections and credentials are set up in [Data Sources](/configuration/data-sources).
* **Groups**: Matched by name. An unknown group is skipped with a warning. Access grants are applied only when the request sets `include_access=true`, so a file alone cannot share a project with a group.
* **Catalog metrics**: Matched by ID first, then by name if the ID does not resolve to a non-deleted metric. An unresolved placement is skipped with a warning.
A file exported with run history is accepted, but the history is dropped with a warning. Export without history when the file is meant for import.
## Preview First
The preview validates the file and reports what a create would do, without writing anything. It also lists the members of each group an access grant would apply to.
```bash theme={null}
curl -sf -X POST -H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/toml" \
--data-binary @projects/finance-kpis.dsl.toml \
"$ORION_URL/api/projects/create/preview/" | jq
```
The response contains:
* `project_name`: the name the new project would get
* `counts`: how many items per section would be created
* `access_grants`: each group in the file that exists in this tenant, with its members and their roles
* `unresolved_groups`: groups in the file that do not exist in this tenant
* `warnings`: anything skipped or ignored
An invalid file returns `422` with a `detail.errors` list. Each error has a `code`, a `path` into the document such as `metrics[2].sources[0]`, and a `message`. Fix the file and preview again.
## Create
```bash theme={null}
curl -sf -X POST -H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/toml" \
--data-binary @projects/finance-kpis.dsl.toml \
"$ORION_URL/api/projects/create/?name=Finance%20KPIs%20(review)" | jq
```
| Query parameter | Default | Meaning |
| - | - | - |
| `name` | The file's project name | Name for the new project. Set it when a project with the file's name already exists in the tenant |
| `include_access` | `false` | Apply the file's `[[groups]]` grants |
A `201` response reports the new `project_id`, counts of what was `created` and `skipped` per section, and any warnings. Newly created items get fresh IDs; existing data sources, groups, and catalog metrics retain theirs. The importer maps references onto the new IDs. Imported Context slugs can receive suffixes to avoid collisions with existing pages.
## What the Validator Checks
Preview and create share document validation:
* The document parses as TOML and each section has the required keys
* Every data source named exists in this tenant, by name and type
* Declared slug references resolve within the file: Workflow reference maps, notebook metric and Context references, and page parents
* Slugs are unique within each section, and the Context tree has no cycles
* Embedded Workflow TOML parses, and enabled Workflows supply a schedule string
Create performs additional work after validation. It rewrites Workflow references and validates the resulting bodies; a Workflow that fails this validation is skipped with a warning. Scheduling errors can also produce warnings and leave the next run unset. A successful preview is not a guarantee that every item will be created or run successfully. Inspect the create response's `skipped` counts and `warnings`.
Create strips Workflow `vanity_url` claims so the copy does not claim the original public URLs. Enabled schedules are preserved and next runs are computed during import.
## Testing an Exported Project
Use a separate project to inspect an exported definition and record test results alongside the [snapshot review](/version-control/sync-to-git#review-snapshots). Changes captured by a scheduled export have already occurred in Orion. Testing or approving this copy does not gate those changes, and merging the PR does not deploy the copy.
Check out the branch under review, or download the changed file from the
pull request.
Before importing, set `schedule_enabled = false` on exported metrics,
notebooks, and Workflows so the review copy does not start scheduled runs.
Review Workflow delivery destinations before any manual run. Create with
`name= (review)` and leave `include_access` off to avoid applying
group grants from the file. Inspect import warnings and the new project's access.
Open the review project in the app and run the changed metric or Workflow.
Compare the result to the source system or to the current production
project.
Note the result on the pull request, approve or request changes, then
delete the review project. Imported Context pages are tenant-level
records; review and clean up those copies separately if no longer needed.
## Limits
* The create endpoint in this guide always creates a new project. This guide does not configure updates to existing projects or Git-triggered reconciliation.
* Import can create Context pages, but does not create data sources, groups, users, or catalog metrics. Review existing dependencies and import warnings; this is not a complete tenant restore.
* Run history in a file is not imported.
## Next Steps
The scheduled export and review procedure this page supports
Download the TOML file that import reads
# Export Orion Snapshots to Git
Source: https://docs.runorion.com/version-control/sync-to-git
Keep exported definitions in Git and review changes through pull requests
Export Orion project definitions and selected tenant configuration to Git for version history and pull-request review. This guide includes a [shell script](#set-up-the-export) that creates snapshots and a [GitHub Actions configuration](#run-on-a-schedule) that schedules exports and opens pull requests. You host the job and manage its credentials, repository access, and failure alerts.
This is a one-way export
from Orion to Git. Pull requests review changes that have already occurred in
Orion; merging or reverting a commit does not update Orion.
To bring GitHub documentation into Orion, use the separate [knowledge source integrations](/knowledge-base/wiki-integrations).
## What gets versioned
The script writes the following files under `orion-snapshots/`. It exports selected fields, not a complete tenant backup. IDs in filenames distinguish objects with the same name.
| Content | Output |
| - | - |
| Project definitions: metrics, notebooks, Orion Workflows, linked Context pages, data source selections, and group grants | `projects/.dsl.toml` |
| Looker governance rules from **Always Filter Rules** in the project's Schema Explorer | `governance/.json` |
| Context document titles, paths, and content, including pages linked to no project | `knowledge-base/.md` |
| Catalog metric definitions | `catalog-metrics/.toml` |
| Company name, context, and profile | `company.md` |
| Data source IDs, names, types, descriptions, and active status | `datasources.json` |
| Users, tenant roles, account status, groups, group project assignments, and memberships | `access/` |
Chat conversations, memories, uploaded files, and generated outputs such as reports and CSV exports are excluded. Project definitions follow the [project export rules](/version-control/export#what-is-not-included), which exclude most private and draft content. This script does not request run history.
Connection credentials are omitted from the data source inventory. Secrets written into exported text, SQL, Python, or Context content are **not automatically redacted**.
## Prerequisites
* **An Orion export account:** Use a dedicated user with the **Admin** role and an Orion password set during [onboarding](/profile-settings/user-onboarding). The script uses password authentication, not an interactive SSO login. See [User Management](/configuration/user-management).
* **A Git repository:** Restrict access to people authorized to read the exported definitions and user information. Reserve `orion-snapshots/` for generated files and start from a clean checkout.
* **A runner:** Install Bash, `curl`, `jq`, and `git`. The GitHub Actions example below supplies the runtime and commit identity; another runner needs its own Git identity and push credentials.
## Set up the export
Download [orion-export.sh](https://gist.githubusercontent.com/noahgcook/6a55a32a090a133c10b4aad1ff98a0d1/raw/d4c7aa05c7fe85775edb7a47899a949c2d13bcd9/orion-export.sh), save it as `scripts/orion-export.sh`, and commit it. Both examples are maintained in [orion-examples](https://github.com/Gravity-Foundation/orion-examples/tree/main/git-snapshots).
Supply these environment variables through your runner. Store the password in its secret manager, never in the repository.
| Variable | Value |
| - | - |
| `ORION_URL` | Your tenant's base URL, such as `https://your-tenant.runorion.com` |
| `ORION_USER` | Export account email |
| `ORION_PASSWORD` | Export account password |
| `PROJECT_IDS` | Optional space-separated project IDs; see [Limit project exports](#limit-project-exports) |
Run `bash scripts/orion-export.sh` from a clean checkout. The script authenticates on each run, stages the exports in a temporary directory, replaces its generated files, and commits any differences. If nothing changed, it makes no commit. Pushing and opening a pull request are handled by the scheduled job below.
[Open the script Gist](https://gist.github.com/noahgcook/6a55a32a090a133c10b4aad1ff98a0d1/d4c7aa05c7fe85775edb7a47899a949c2d13bcd9) if the preview does not load.
API errors, redirects, or failed response checks stop the export before it replaces the previous snapshot. A catalog metric without a TOML definition also stops the export. If adapting the script, preserve endpoint paths and trailing slashes: redirects are rejected.
### Limit project exports
Set `PROJECT_IDS` to limit project definitions and governance rules. Find each ID in its app URL: `/projects/`. Other exports remain tenant-wide, so this setting does not remove the Admin requirement.
Without `PROJECT_IDS`, the script requests the account's project list, which can include accessible personal projects. Before scheduling, compare the exported objects with Orion to confirm the intended scope. A successful run alone does not prove coverage.
## Run on a schedule
The [GitHub Actions example](https://github.com/Gravity-Foundation/orion-examples/blob/541b041/git-snapshots/orion-export.yml) schedules a daily export at 06:00 UTC and supports manual runs.
1. Download [orion-export.yml](https://gist.githubusercontent.com/noahgcook/370eb8fd810f48de98f8843bcc01de00/raw/02fb79d7b4a9fb2ce2258371dddbdb2014513c3f/orion-export.yml) and save it as `.github/workflows/orion-export.yml`.
2. Set `ORION_URL` to your tenant URL. The example assumes the default branch is `main`; replace each reference if yours differs. Add `PROJECT_IDS` to the `env` block if needed.
3. Add `ORION_USER` and `ORION_PASSWORD` as repository secrets. Enable [Allow GitHub Actions to create and approve pull requests](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-github-actions-settings-for-your-repository), subject to organization policy. The example creates PRs; it does not approve them.
4. Commit the script and YAML to the default branch. In GitHub, select **Actions → Orion export → Run workflow** to check the first export. Configure failure alerts and retain job logs.
[Open the GitHub Actions workflow Gist](https://gist.github.com/noahgcook/370eb8fd810f48de98f8843bcc01de00/02fb79d7b4a9fb2ce2258371dddbdb2014513c3f) if the preview does not load.
Each run starts from `main`. If the exports differ, the job force-pushes a new commit to `orion-export`, **replacing any unmerged snapshot**. Reserve that branch for the job. Protect the default branch and require renewed approval after updates if your review policy calls for it. If Orion returns to the snapshot on `main`, close any stale export PR; the job does not close it automatically.
To retain every changed snapshot without a PR, replace the final step with `git push origin HEAD:main`, if branch policy permits.
## Review snapshots
Use the diff to review:
* **Metric SQL and Python:** Reconcile changed calculations with source data using Orion or your testing tools.
* **Company information and Context pages:** Check changes to definitions and instructions used in analysis.
* **Looker governance rules:** Check whether changes expand access to rows.
* **Orion Workflows:** Review definitions, schedules, and recipients.
* **Access:** Review role changes, account reactivation, group project assignments, and memberships.
Files disappear from the snapshot when objects are deleted, become inaccessible, or fall outside the selected scope. Investigate the cause before accepting a deletion.
For review evidence, link the change request and test results in the PR and record the required approvals. You can [import an exported project for testing](/version-control/import#testing-an-exported-project); import creates a new project and does not restore every tenant-level surface. If approval is required before production changes, enforce it in your Orion change process. The export PR happens afterward.
## Limits
* **Snapshot history:** Changes between runs can be missed. An empty diff means only that the exported fields match the snapshot in the checkout.
* **Consistency:** Exports read multiple endpoints; changes during a run can produce a mix of states.
* **Attribution:** Git records the configured commit identity and commit time, not each original editor or edit time. The job does not enforce independent review.
* **Coverage:** The exports do not capture every setting, permission, or access event. For example, standalone Context files contain titles, paths, and content, not page settings.
## Next steps
Project export contents, options, and API reference
Reconstruct an exported definition as a new project
# Advanced Workflows
Source: https://docs.runorion.com/workflows/advanced
Decision steps and using metrics as the source
Most Workflows are a straight line: run the analysis, produce the output, email it. These two features are for the ones that are not.
## Decision Steps
A decision step is a point where the Workflow judges the results and decides what happens next. It is what turns a Workflow from something that always does the same thing into something that responds to what it found.
The mechanics are simple. Steps can be marked **conditional**, which means they do not run on their own. A decision step then reads the run's results and decides whether to release them. Nothing meaningful happened this week, and the report is written but the email never goes out. Churn crossed the line you care about, and it does.
You write the criteria in plain language, the same way you write a notification preference. The difference is scope: a notification preference gates one email, while a decision step can gate several steps at once, including reports and exports rather than just notifications.
A decision runs at one of two points:
* **After dependencies**, before the outputs are generated. Use this to skip producing something entirely when it is not warranted.
* **After reports**, once the artifacts exist. Use this when the judgment depends on reading the finished output.
You control what the decision gets to look at: metric values, notebook outputs, and for late decisions the finished reports and exports. Give it the context the judgment actually needs and no more, since a decision reading everything is slower and no sharper.
If all you want is "email me only when something changed", write it as a
notification preference instead. See [Notification
Preference](/workflows/outputs#notification-preference). Reach for a decision
step when the condition has to gate more than one thing.
## Using Metrics as the Source
A Workflow normally runs a notebook. That is the recommended default and what you get from the Create Workflow dialog.
There is a second option. If you have a set of tracked metrics and what you want is recurring reporting on those specific numbers, a Workflow can read the metrics directly instead of re-deriving them in a notebook. The Workflow becomes a reporting layer over numbers Orion already tracks, rather than an analysis of its own.
Each metric in the Workflow has a **refresh** setting, and it is off by
default. With refresh off, the run uses the metric's last known value rather
than querying for a current one, which means a daily Workflow can email
yesterday's number without anything appearing to be wrong. Turn refresh on
for any metric whose freshness matters.
This is the main thing to get right when using metrics as a source. A notebook-sourced Workflow queries your data on every run by definition. A metric-sourced one only does if you tell it to.
# Workflow Best Practices
Source: https://docs.runorion.com/workflows/best-practices
How to build automations that keep working
A Workflow runs unattended, often for months, in front of people who will not check whether it still makes sense. That changes what "good" means compared to a one-off analysis.
## Get the Analysis Right First
Automating a wrong analysis produces the wrong answer on a schedule, and now it has an audience. Run it in chat, read the numbers, sanity-check a total you already know, and only then save it.
The dry run Orion does before saving proves the recipe executes. It does not prove the recipe is correct. That part is yours.
## Write It Evergreen
Orion rewrites hardcoded dates during [the evergreen check](/workflows/create#the-evergreen-check), but it is cheaper to write them that way from the start. Ask for "the last 30 days" rather than a specific window, and say the word "evergreen" in your original request. See [Use Relative Dates](/chat/best-practices#use-relative-dates).
The same applies to anything else pinned to the moment you happened to run it: a specific customer ID you were investigating, a file you uploaded once, a region you filtered to because it was the one with the problem that day.
## Match the Format to the Reader
The format is not decoration, it is who the thing is for.
* A **dashboard** suits a number someone checks between meetings.
* A **slide deck** suits a recurring meeting where the analysis gets presented.
* A **markdown report** suits findings that need an argument rather than a chart.
* A **podcast** suits people who will genuinely listen and would never open the deck.
* A **CSV export** suits anyone who is going to do their own work with the rows.
If you cannot name the person who reads it, the Workflow probably should not exist yet.
## Be Deliberate About Notifications
The fastest way to make a Workflow ignored is to email everyone every run. Once people learn the email rarely matters, they stop opening it, including the week it does.
Set a notification preference so a run only lands in someone's inbox when it is worth their attention. Send different things to different people rather than one email to everybody: a summary to leadership, the full deck and the data to the team who has to act.
Reserve the whole-project distribution list for the ones that genuinely warrant it.
## Name It for Someone Else
The person who most needs to understand a Workflow six months from now is not you. "Weekly Executive P\&L Analysis" survives a handover. "Untitled report" and "P\&L v3 final" do not.
The same goes for publish URLs. `weekly-revenue` is a link someone can recognize in a bookmark bar. Set it once, early, because [changing it later breaks every link already shared](/workflows/outputs).
## Check In Occasionally
Automations fail quietly. A data source loses reachability, a schema changes underneath, credentials expire, and the Workflow keeps its schedule while producing nothing useful.
Worth a periodic look:
* Runs marked **Partial**, which succeed loudly and fail quietly at the same time.
* Metric-sourced Workflows with **refresh** off, which report stale numbers without erroring. See [Using Metrics as the Source](/workflows/advanced#using-metrics-as-the-source).
* Schedules still running for meetings that no longer happen.
Setting a schedule to **None** stops the runs and the emails while keeping the recipe and its history, which is almost always better than deleting.
## Let It Grow
Start with one analysis, one schedule, one recipient. Add the CSV when someone asks for the rows, the second notification when a different audience appears, a decision step when you notice you only care in certain weeks.
Workflows built that way tend to reflect how the work is actually done. Workflows designed in full up front tend to reflect how someone once imagined it might be.
# Create a Workflow
Source: https://docs.runorion.com/workflows/create
Turn a finished analysis into a scheduled automation
Every Workflow starts from an analysis that already works. Run it in [Chat](/chat/running-analyses), check the numbers, then automate it. Automating a wrong analysis just produces the wrong answer on a schedule.
## Two Ways In
Click **Create Workflow** in the notebook panel, or ask Orion in chat. Both call the same thing underneath, so pick whichever is faster in the moment.
**Asking** is quickest when you already know what you want. In the chat where the analysis ran: "save this as a workflow that runs every Monday at 8am and outputs a dashboard." It also handles schedules the dialog cannot express, like running at several specific times a day.
**The dialog** is the guided version. Open the notebook panel in Chat. At the top you will find **Save as a Workflow**. Click **Create Workflow**.
![A chat with the Analysis Notebook panel open on the right. The Save as a Workflow section and its Create Workflow button sit at the very top of that panel, highlighted, above the notebook's variables, referenced metrics, data extractions, and executed cells]()
## The Dialog
It asks for three things.
Pick Hour, Day, Week, or Month. Week adds a day picker, Month adds a day of
the month, and Hour asks only for the minute it should fire on. Your local
timezone is preselected.
Choose **Markdown Report**, **Slide Deck**, or **Dashboard**. This is the
format the Workflow starts with, not a permanent choice. See [Outputs and
Delivery](/workflows/outputs).
Describe in plain language what makes a run worth an email, for example
"only notify me if revenue changes by more than 10%". Leave it blank to
decide later.
![Create Workflow dialog showing the run frequency, time and timezone pickers, the Markdown Report, Slide Deck and Dashboard format choice, and a plain language notification preference field]()
## What Orion Builds
Submitting the dialog writes exactly the kind of request you would have typed and sends it to Orion, which is why the two routes behave the same.
From there Orion assembles the recipe. Only cells that ran cleanly make it in, so anything that errored is left behind. It then does a full dry run end to end before saving. If that dry run fails nothing is saved and Orion tells you what broke, which is the point: a Workflow that cannot complete once will not complete on a schedule either.
Workflows normally take a notebook as their source, which is what the dialog
produces. If what you actually want is recurring reporting on a set of
tracked metrics, a Workflow can read those directly instead. See [Using
Metrics as the Source](/workflows/advanced#using-metrics-as-the-source).
## The Evergreen Check
A Workflow that hardcodes last quarter's dates would keep reporting last quarter forever, so Orion reviews the analysis for that before saving. You do not have to ask.
The check looks for hardcoded dates and date ranges, filter values and IDs that came from your specific session, and hardcoded file paths, and rewrites them to relative equivalents: a fixed `2026-01-01` cutoff becomes a rolling window.
Writing the analysis that way from the start is still cheaper than having it corrected. See [Use Relative Dates](/chat/best-practices#use-relative-dates).
## Next Steps
Choose formats, set a publish URL, and decide who gets emailed
Schedules, run history, and editing what you built
# Manage Workflows
Source: https://docs.runorion.com/workflows/manage
Schedules, run history, change history, and editing a Workflow after it exists
Once a Workflow is running, most of your time with it is spent on four things: making it run, checking that it did, seeing what someone changed, and changing it yourself.
## Running and Scheduling
The **Scheduled Run** step at the top of the graph is the trigger. It shows the cadence, the time, and the timezone the Workflow runs in, along with the date of the next run. Open it to change any of them.
The schedule offers None, Hourly, Daily, Weekly, Monthly, and At times. A few details worth knowing:
* **Daily** lets you restrict which days actually run, so weekdays-only is a daily schedule with the weekend deselected.
* **Hourly** runs on an interval, from every hour up to every 12 hours, on a minute you pick.
* **At times** runs at several specific times in the same day rather than on an interval.
* **None** disables the schedule without deleting the Workflow or its history. Run Now still works.
* Times display in your local timezone and are stored converted, so a schedule set in New York does not drift for a teammate in London.
* Schedule changes are not saved until you confirm them.
**Run Now** in the header triggers an immediate run without touching the schedule. Use it to confirm a change worked, or to refresh a number ahead of a meeting. Runs happen in the background, so the result appears once it completes rather than instantly.
## Run History
The status in the header opens the run history. Each entry shows the outcome, **Succeeded**, **Failed**, **Partial**, or **Running**, and whether it was scheduled or a manual run, so you can tell an automated result from one someone triggered by hand.
![The Workflow header with its run status highlighted, and the Run History panel it opens listing eleven runs, each showing a succeeded status, how the run was triggered, and how long ago it happened]()
Open a run to see its steps. Each step reports whether it completed and how long it took, and steps that produced something carry a **View** link straight to that artifact.
![Run Details panel showing a succeeded scheduled run that took three minutes and forty-eight seconds, broken into three completed steps with per-step durations and a View link on the step that produced slides]()
When a run fails, the failure surfaces on the Workflow entry in the list. Open the failed step to see the error that stopped it. Common causes are a data source that went unreachable, a schema change, or credentials that expired. See [Troubleshooting](/mcp/troubleshooting#metric-or-workflow-execution-fails).
**Partial** means some steps finished and others did not, so it is always worth opening to see which.
## Change History
Run history tells you what the Workflow did. **Revision History** tells you what people did to it.
Every save writes a revision recording who made it, a summary of what changed, and when. Changing a notification's recipients, switching an output format, or adjusting the schedule each leave a trace. On a Workflow that several people maintain, this is how you answer "why is this suddenly emailing the whole company" without guessing.
## Editing a Workflow
Click any step to open its configuration. The trigger holds the schedule, each output step holds a format and its latest result, and the notification step holds the message and its recipients. You can add steps too, so a Workflow that only writes a report today can gain a CSV export or a second notification later.
The analysis step in the middle is the recipe. It shows the notebook name, how many cells run, and a badge for each kind of data source the cells query, which is the fastest way to see what a run touches without opening the code.
### In Chat
Some things are easier to describe than to click. **Open in Chat**, at the bottom right of the graph, drops you into the project chat with the Workflow already referenced and a prompt started for you.
![Project chat input prefilled with a request to change a workflow, the workflow itself shown as a reference chip inside the message]()
You can do the same from scratch in any project chat by typing `@` and picking the Workflow, the same way you reference a metric or a Context page.
Chat is not only for changes. Referencing a Workflow and asking about it works too: what it queries, why last Tuesday's run looked different, what would happen if you changed the window to 90 days. You get an answer without editing anything.
## Sharing and Permissions
A Workflow starts out private to its creator and appears under **Yours**. **Move to Shared Board** hands it to the rest of the project, **Make Private** pulls it back. Either one is on the entry's actions menu, and admins can do it to any Workflow while everyone else can only do it to their own.
Editing anything at all requires Analyst or Admin on the project. See [Workflows](/core-concepts/workflows#what-a-workflow-is-made-of) for what Viewers can and cannot reach.
## Working With Workflows Elsewhere
The [MCP server](/mcp/overview) exposes Workflows to AI assistants like Claude Code and Cursor. You can list them, read their configuration, trigger runs, and pull execution results. See [MCP Tools](/mcp/tools#run_workflow).
## Deleting a Workflow
Delete removes the Workflow and its entire run history, and cannot be undone. If your goal is only to stop the emails and the scheduled runs, set the schedule to **None** and clear the notification's recipients instead. That keeps the recipe and its history intact so you can start it again later.
# Outputs and Delivery
Source: https://docs.runorion.com/workflows/outputs
What a Workflow produces and how it reaches people
A Workflow run produces artifacts and then delivers them. Those are two separate decisions: what gets made, and who ends up looking at it.
A Workflow can carry several outputs at once. The same run can write a slide deck for the meeting, an audio briefing for the commute, and a CSV for whoever wants the underlying rows. Each is its own step on the graph with its own settings.
## Formats
A written report. Best for narrative findings someone will read top to
bottom.
A styled web page of charts and tables. Best for numbers people check at a
glance.
A presentation. Best for recurring meetings where the analysis gets
presented rather than read.
An audio briefing of the same analysis. Best for people who will listen on
the way to work but never open the deck.
You can change an output's format later. The next run regenerates it from scratch in the new format.
## Data Exports
An export is data rather than narrative. Where a report interprets the numbers, an export hands over the rows.
An export step points at a DataFrame your notebook produced, by variable name, and writes it out under a filename you choose. Each export gets its own publish URL, and can be attached to a notification alongside the reports, so the same email can carry the narrative and the raw data behind it.
Reach for one when the recipient is going to do their own work with the numbers: a finance team that wants the line items in a spreadsheet, or a downstream process that reads the file on a schedule.
## Report Configuration
Opening an output step gives you its **Report Configuration**, which controls how the result is written and where it lands.
* **Report Style**: formatting, structure, length, tone, and emphasis, in plain language. This is the main lever for what the output reads like. "Executive summary, one page max" and "five slides for a board meeting" both belong here.
* **Publish URL**: the address the result is published at, `/share/` plus a slug you choose. Set it to something recognizable like `weekly-revenue`.
* **Report Visibility**: who inside the project can view the result.
* **Context Sources**: the notebooks behind the report, plus any [Context](/core-concepts/knowledge-base) pages you attach as ground truth.
Because the Publish URL is stable and every run republishes to it, one link stays current forever. That is what makes a Workflow worth handing to someone who will never open Orion.
Changing the slug moves the report. Links you have already shared point at
the old address and will stop working.
### Templates
Report Style controls how the writing reads. A **template** controls how a slide deck looks. Attach one and every run comes back in the same layout and theming, which matters once the same deck goes to the same meeting every week and people navigate it from memory.
Templates are optional and are saved per project. Set one from **Artifact Template** in an output step's Report Configuration. You get them two ways: upload an HTML file, or generate a deck you like in chat and use **Save as template** to keep it.
## Notifications
When a run finishes, a Workflow can email the result out. Open the **Notification** step to control what gets sent and who gets it:
* **Message**: the body of the email that goes out, which you write yourself.
* **Artifacts**: which of the Workflow's outputs and exports get attached. Each report and export is a checkbox, so a Workflow that produces three things can send all three or just one.
* **Recipients**: who receives it, chosen as **Users**, **Groups**, or **Emails**. Users covers people already on the project, searchable by name or email, and Groups covers the project's groups. Emails takes any address you type, which is how you reach someone outside the project.
![Notification Configuration panel showing the message body, three artifact checkboxes for two reports and one export, and recipient tabs for Users, Groups, and Emails with a member search field]()
A Workflow can have more than one notification step, which is how you send a short summary to executives and the full deck plus data to the team that has to act on it.
### Notification Preference
Recipients control who gets email. A **notification preference** controls when. Write it in plain language when you create the Workflow and Orion turns it into a condition evaluated on each run:
* "Only notify me when there is a significant change"
* "Only if churn goes above 5% or a new anomaly shows up"
* "Always notify me"
A Workflow with no condition set notifies on every run. For conditions that gate more than a single email, see [Decision Steps](/workflows/advanced#decision-steps).
Delivery is email only. Workflows do not post to Slack, Teams, or SMS. For a
broader summary of a project's activity, see [Email
digest](/profile-settings/email-digest).