# Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation This site has an agentic ask interface you may use to query the documentation dynamically by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.corraldata.com/kb/index.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. --- # Welcome Welcome to CorralData! Here you'll get an overview of all the amazing features CorralData offers to help you understand and act on your data. You'll see some of the best parts of CorralData in action — and find help on how you can turn your data into insights. ### Jump right in
Connect your dataLearn how to integrate your various sources of datavideoframe_844.pngConnect your data
Chat with your dataStart chatting with your data in natural languagevideoframe_2877.pngChat with your data
Explore your dataLearn the basics of CorralData reportingvideoframe_4666.pngExplore your data
# How CorralData Works You’re in! You’ve created your account and are ready to start making the most of the platform. CorralData takes the guesswork out of connecting your data sources, building reports, and gaining actionable insights.
### How it works: Your data belongs to you. That’s why **we don’t co-mingle data**. Instead, a unique data warehouse is generated just for your account so it’s safely and securely retained. After you connect out-of-the-box sources, **raw data is synced down** and dashboards are generated (where available, depending on source). Our reporting process, which uses Structured Query Language (SQL), lets you **directly interact with your data using plain English**. SQL is a powerful and widely recognized language for managing and querying databases. The combination of SQL and interacting with AskCorral using simple questions allows you to easily **pull the exact information** you need and **create custom reports** — any time. Your account's AI model is more than just a tool; it's an intelligent partner that grows with your data. This approach **ensures that the AI's understanding of your data landscape is always current**, comprehensive, and deeply integrated. This includes information such as table schemas, column names, data types, relationships between tables, and even contextual notes you might add. # Connect your data Here's how you can add any of your existing data sources (integrations) into CorralData. {% embed url="" %} Relevant insights start with having access to relevant data — and CorralData makes it easy to get started with any of your existing integrations. ## Connect CorralData supports over 600 integrations from many popular platforms and databases. If your data exists in the form of a file that needs to be integrated, we can also pull it in via our Google Sheet, Google Drive, or OneDrive integration.
{% hint style="info" %} Is there a missing integration? Drop a line to and we'll see if we can get it added for you. {% endhint %} ## Data syncs Depending on your plan, CorralData allows you to sync your data in almost real-time, but we default to a nightly sync to ensure all of your prior day's data is available in the morning. Your initial sync can take a few minutes to a few days, depending on how much data we are syncing. You'll receive a notification from the platform as soon as your data is done syncing. ### Connector statuses As each connector authenticates, it moves through three statuses: | Status | What it means | | --------- | --------------------------------------------------------------- | | Connect | Connector created, first sync not started yet | | Syncing | Data is being pulled from the source | | Connected | First sync is complete and your data is available in CorralData | > If a connector stays on Syncing for more than a few hours, or a connector card doesn't respond when you click it, reach out to . ## Reverse ETL CorralData also allows you to set up a bi-directional sync with an existing platform (i.e., your ad platform, email platform, Salesforce, or database). Setting up Reverse ETL via CorralData allows you and your team to write data to one of your existing platforms so you can leverage it to drive campaigns, emails, and generally keep your data in sync. # Reverse ETL Reverse ETL (or bi-directional sync) sends up-to-the-minute data from the CorralData platform back to your everyday systems like CRMs, marketing automation platforms, and support tools.
**Implementing Reverse ETL can help you and your team manage:** * Offline Conversions: (e.g., tracking lead-to-revenue impact for ad optimization) * Custom Audiences (e.g., refining audience targeting for ad platforms) * Marketing & Operational Automations (e.g., updating CRM fields, generating reports) * Other Applications (e.g., lead scoring, health scoring, weekly reporting) **Here’s an example of how Reverse ETL can give you a holistic view of your data:** A new customer converts from your paid Google ad and books an appointment — but did they actually show up? CorralData’s Reverse ETL connects the dots by sending visit and revenue data back to your CRM, helping sales and marketing know who showed up, how much they spent, and where to invest next. {% hint style="info" %} Want to add Reverse ETL to your account? Drop a line to and we'll get you set up. {% endhint %} # Add Board & widgets Now that you’ve connected your data sources, it’s time to start building. **Boards** allow you to organize, visualize, and play around with your data. You can add team members to Boards or manage them solo — or a combination of both. {% @arcade/embed url="" flowId="eTyee61ZnXtIiQqVu6cd" %} ### How it works: Open the lefthand navigation panel and click **Add Board**. Give your new Board a specific and unique name. To add widgets (data visualizations), type what you want to build into the **AskCorral bar** at the bottom of your Board — on mobile, tap the **AskCorral** button. Tell the AI exactly what you want to build, and you’ll have a new widget in no time. On a brand-new, empty Board, you can also click **Add Widget via AI** on the first-widget tile to get started. Add your new widget to the Board, then keep the conversation going to build another — or close AskCorral when you’re done. Besides creating new widgets, you can also [duplicate existing widgets](https://docs.corraldata.com/kb/organize-your-data/duplicate-widgets) from other boards into your new one. Be sure to [add any teammates](https://docs.corraldata.com/kb/getting-started/manage-users) you'd like to have access to your board, too! {% hint style="info" %} If you're having trouble and require technical assistance, feel free to reach out to . {% endhint %} # Add Board via AI Gone are the days of manually building dashboards. With **Add Board via AI**, you can build any Board you need, complete with relevant widgets that display your data clearly and simply. You’ll be building dashboards faster and more efficiently than ever before. ### How it works: #### Option 1: Ask AskCorral {% @arcade/embed url="" flowId="NOeX6cldbIfIpnYbU4Ik" %} Type your request into the **AskCorral bar** at the bottom of your screen — on mobile, tap the **AskCorral** button to open AskCorral. Be as specific as possible. It’s helpful to include the word *“build”* but not mandatory — our AI knows what to do. For example: *"Build a marketing performance dashboard that tracks spend across Meta, Instagram, and Google ads; focuses on MQLs; and shows purchase rates for new products"* Once generated, you can make follow-up requests, share updates with your team, or move on to your next build. View your new Board(s) any time by hovering over the **Boards icon** in the top left corner of the platform. #### Option 2: Add Board with AI-generated widgets {% @arcade/embed url="" flowId="DZ2eUokWN8hC56t1tkSc" %} Navigate to the left-hand side panel and click **Add Board** at the bottom of the list. Name your Board and click **Add**. Be sure to use a descriptive name so our AI can generate the appropriate widgets and deliver stronger results. Then, open the Board from the left-hand side panel. Your Board will be blank; this is normal. In the **Getting Started** modal, choose exactly what you want to achieve: * **Generate Dashboard** automatically creates a complete Board with relevant widgets. * Heads up: This button will generate a board based only on what you name it. Be sure to use a specific name to receive stronger results. * **Add via AI** lets you guide which individual widgets get created. Enjoy exploring clean, clear data visualizations. # Add widgets via AI Need a new metric? Just ask. Type what you want into the **AskCorral bar** at the bottom of any Board — on mobile, tap the **AskCorral** button — and the AskCorral Agent will build the widget and add it to your Board. On a brand-new, empty Board, the first-widget tile also offers **Add Widget via AI** to get you started. {% @arcade/embed url="" flowId="gWBBacfl25jx3yNgweqM" %} {% hint style="info" %} If you require custom widgets, feel free to reach out to . {% endhint %} # Add & manage users User management, at your fingertips: * Add new users to your account and decide which existing dashboards they'll have access to. * Manage board-level permissions. * Made a brand new dashboard? Enjoy the peace and solitude, or invite other users to come join you! ### User roles | Role | Invite users | Edit boards & widgets | AskCorral (AI) | Manage data sources | | ------------ | ------------ | --------------------- | -------------- | ------------------- | | Admin | Yes | Yes | Yes | Yes | | Editor | No | Yes | Yes | No | | Viewer | No | Read-only | Yes | No | | Reports Only | No | Read-only | No | No | {% @arcade/embed url="" flowId="BkwMPTFSdNWP2F6cOn79" %} {% @arcade/embed url="" flowId="O9wiR5nHqPCTLRqDxS6P" %} See all active users on a dashboard *(and easily add new ones)* in the top right corner:
**When to use each role** * **Admin** — your data lead or power user. Keep this to one or two people. Admins are the only role that can invite new users. * **Editor** — anyone who builds or edits dashboards. Most of your active users. * **Viewer** — people who only need to read reports, with AskCorral access. * **Reports Only** — same as Viewer, without AskCorral. Use this for seats on plans that don't include AI. #### Editing a user's role 1. Find the user in your user list. 2. Click **Manage** next to their name. 3. Select **Edit role**, choose the new role, and save. The change takes effect immediately — no page reload needed. #### Removing a user 1. Click **Manage** next to the user's name. 2. Select **Remove user**. 3. In the confirmation window, click **Confirm**. > Removing a user cannot be undone. To keep the user, click Cancel in the confirmation window. > Manage Data Sources and Connect Integrations only appear for users with the Admin role. If you can't see them, check that your account is an Admin. {% hint style="info" %} If you have users that need specific permissions, feel free to reach out to . {% endhint %} # Board Permissions Every Board now carries its own permissions, so the dashboards your team relies on can't be changed by accident. On top of your account role (Admin, Editor, Viewer — see [Add & manage users](https://docs.corraldata.com/kb/getting-started/manage-users)), each user can be granted a role on an individual Board. ### Board roles | Board role | What it allows | | ---------- | ----------------------------------------------------------------------------------------------- | | Owner | Full control: edit the Board and its widgets, and manage who has access and what role they hold | | Editor | Edit the Board and its widgets | | Viewer | Open and use the Board — filters, date ranges, exports — without changing it | A user's account role still sets their ceiling: someone who is a Viewer on the account can't be made an editor of a Board. ### Protecting a finished Board Boards built for you by the CorralData team (or by your own data lead) can be locked down so end users get view access only, unless explicitly granted more. Widgets on a protected Board are covered by the same rules — no more surprise edits to a number the whole company watches. If you open a Board you can't edit, you can still make your own version: choose **Duplicate to edit**, and work on the copy without touching the original. ### Managing access Board owners manage access from the Board itself — add a teammate, pick their role, or change it later. You can also keep a Board entirely to yourself while you're building ("Only me"), then share it when it's ready. {% hint style="info" %} If you're having trouble and require technical assistance, feel free to reach out to . {% endhint %} # Row-Level Security {% hint style="warning" %} Row-Level Security is available on **Enterprise plans**. Contact your CorralData team or to set it up for your account. {% endhint %} Row-Level Security (RLS) controls **which rows of data each user can see** — not just which Boards. A multi-location group can share one set of dashboards while each manager sees only their own location's numbers; a multi-brand organization can keep every brand's data walled off inside a single account. ### How it works RLS is enforced in the data warehouse itself, at query time. That means it applies everywhere a query runs, automatically: * **Boards and widgets** — the same widget shows each user only the rows they're permitted to see * **Board filters** — filter options are scoped to the user's permitted values, too * **AskCorral** — AI answers are computed only from the rows the asking user can access * **MCP (Claude / ChatGPT)** — queries run through the CorralData MCP server respect the same rules Because the filtering happens at the data layer, there's no separate setting to keep in sync per dashboard — one policy governs every path to the data. ### Access modes Each protected table can be governed in one of three ways: * **Value-based filtering** — every user's rows are filtered by their assigned values (for example, their location or brand). The most common setup. * **Specific users** — only individually designated users see the table's rows; everyone else sees none. * **Full access** — the table is explicitly open to all users on the account. Per-user overrides can be layered on top — for example, a manager scoped to one brand everywhere, except one shared company-wide Board where they're granted full visibility. ### Setting it up Your CorralData team configures RLS with you: together you define the mapping (which users see which locations, brands, or entities), and we apply and maintain the policies. Changes — new hires, new locations, role changes — are handled the same way. {% hint style="info" %} Want RLS on your account, or need a mapping updated? Reach out to your CSM or . {% endhint %} # Set up automated reports CorralData allows you to have automated emails come to your inbox (or your colleague's). Simply select which reports you want to distribute and when, and they'll start appearing in your inbox. {% @arcade/embed url="" flowId="8Ro8vvm0PtVfISZMOJMD" %} *Note:* Recipients of the report must be users on the account and have access permissions set up for the report's dashboard. {% hint style="info" %} You can also request custom reporting times by reaching out to our support team at {% endhint %} # Account Settings A handful of account-wide preferences – your display name, fiscal calendar, default currency, and account branding – are yours to set without waiting on your CorralData team. This is separate from Add & manage users, which controls who has access to your account and what they can do. Account Settings covers account-wide preferences, not permissions. {% hint style="warning" %} Changes here apply account-wide — every user, every board. Double-check with your team before changing the fiscal year start or beginning of week on an account that's already live, since it can shift how historical periods group on existing widgets. {% endhint %} *** ## Getting there Click your name in the bottom-left corner, then **Account Settings**. ## What you can change #### General Settings | Setting | What it controls | | ----------------- | ----------------------------------------------------------------------------------------------------------------------- | | Display Name | The name shown for your account throughout CorralData. | | Slug | Used in your account's URLs and integrations. Read-only here — contact if you need it changed. | | Fiscal Year Start | The month and day (MM-DD) your fiscal year begins, used anywhere CorralData reports on a fiscal basis. | | Beginning of Week | Which day your weekly date groupings start on. | | Default Currency | The currency symbol and formatting used across your boards. | #### Display Settings | Settings | What it controls | | ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Default Decimal Places | Rounds values shown on dashboards and in AI answers. Choose from 0, 1, or 2 decimal places. CSV exports keep full precision. Open dashboards may need a refresh. | #### Brand Settings Give your CorralData account its own look instead of the default blue. **Admin role required –** this is the one setting on this page gated by role; everything else above is open to any user who can reach Account Settings. | Settings | What it controls | | ----------------------- | --------------------------------------------------------------------------------------------------- | | Accent Color | The color used for buttons, highlights, and other accent elements across your CorralData interface. | | Logo (Light Background) | Your logo as shown on light backgrounds throughout the app. | | Logo (Dark Background) | Your logo as shown on dark backgrounds throughout the app. |
{% hint style="info" %} **Brand Settings** currently covers most of the interface, but not everything yet. A few elements (the AskCorral send button and Board Health among them) still use CorralData's default blue, your logo appears in the classic header only, and Data Apps don't pick up the accent color. We're expanding coverage over time. {% endhint %} # AskCorral Agent AskCorral Agent is your AI data team, available 24/7. Tell it what you need and it does the work: it can build dashboards, fix or debug widgets, provide insights and recommendations, and more–all from a single conversation. AskCorral Agent is **live** in your CorralData account! No setup required — just open the app and type your request into the **AskCorral bar** at the bottom of your screen (on mobile, tap the **AskCorral** button). AskCorral Agent mode is selected by default when you open AskCorral. {% @arcade/embed url="" flowId="fVDZXB6XXv5BKXaiHFIF" %} ### What can you do with AskCorral Agent? AskCorral Agent can handle three types of work: #### 🏗️ Build: acts like a data engineer AskCorral Agent can handle the full lifecycle of building and maintaining your CorralData environment. It can create things from scratch as well as modify, fix, and audit existing work. **What it can do:** {% columns %} {% column %} * **Create and manage datasets (data models):** Build reusable SQL datasets and data pipelines that power all reporting and widgets * **Build from scratch:** Create full multi-widget dashboards, individual boards, or standalone widgets from a single plain-English request * **Add to existing boards:** Add new widgets, filters, or sections to any board without rebuilding it * **Modify existing content:** Update a widget's SQL, change a chart type, rename a metric, adjust a date range, or restructure a board's layout {% endcolumn %} {% column %} * **Debug broken widgets:** Trace a broken or incorrect widget back through its SQL to the source table, identify the issue, and apply a fix * **Audit your boards:** Review all boards and widgets in parallel, flag broken queries and inconsistencies, and tell you what needs attention * **Maintain over time:** Ask it to keep dashboards current, rebuild after a schema change, or clean up outdated reports {% endcolumn %} {% endcolumns %} #### 🔍 Analyze: acts like a data analyst It can surface trends and anomalies and explain what the data actually means and why it looks the way it does, and model out scenarios so you can pressure-test decisions before making them. **What it can do:** {% columns %} {% column %} * **Diagnose metric changes:** When a number moves unexpectedly, it traces the cause–which segment, channel, time period, or data issue is responsible * **Surface trends and anomalies:** It can identify patterns, outliers, and changes across your data when prompted * **Validate numbers:** Trace a widget's output all the way back to the raw source table to confirm the number is correct or identify exactly where it diverges * **Run deep ad-hoc analysis:** Write and execute multi-table SQL for complex, one-off questions, and optionally save the result as a new widget {% endcolumn %} {% column %} * **Investigate data discrepancies:** When something looks off, it digs into the data pipeline, from widget to query to source, and explains the discrepancy * **Cross-segment and cross-period comparisons:** Compare performance across locations, teams, channels, customer tiers, or time periods in a single query * **Explain your dashboards:** Ask what a board is showing, what's notable, or what you should pay attention to and get a plain-English briefing, not a list of numbers {% endcolumn %} {% endcolumns %} #### 💡 Advise: acts like a strategist (with context) Brief it on your business (goals, priorities, targets, etc.) and AskCorral Agent moves from surfacing insights to advising action. Share context through [**Custom Instructions**](https://docs.corraldata.com/kb/chat-with-your-data/add-custom-instructions) or directly in the chat, and it will frame every insight around what actually matters to your business and tell you what to do next. {% hint style="success" %} ### Tips for Best Results with AskCorral Agent * **Give it clear, specific requests** * AskCorral Agent works best when your prompt is specific and describes the outcome. See more here in how to [**Build Prompts in AskCorral**](https://docs.corraldata.com/kb/chat-with-your-data/build-prompts-in-askcorral) * **Set up** [**Custom Instructions**](https://docs.corraldata.com/kb/chat-with-your-data/add-custom-instructions) * The more business context it has, the more strategic its outputs become. Once [**Custom Instructions**](https://docs.corraldata.com/kb/chat-with-your-data/add-custom-instructions) are set, the Agent uses this context in every session. * Examples of business context to include in your Custom Instructions: * Your business model and growth stage * Your 3–5 most important KPIs and how you define them * Your current strategic priorities (e.g., "We are focused on reducing churn this quarter") * Any targets or benchmarks (e.g., "Our retention target is 75%+") * Any terminology your team uses (e.g., "We call new patients guests") {% endhint %} ### What to expect when AskCorral Agent is working: AskCorral Agent works through multi-step tasks automatically. For complex requests like auditing all your boards or building a multi-widget dashboard, it may: * Spawn parallel subtasks to work faster * Show its reasoning and intermediate steps as it works {% hint style="info" %} **We want your feedback:** We're actively improving AskCorral Agent based on real usage. If you run into anything unexpected or have feedback on improvements, let us know at . We want to hear from you! {% endhint %} # AskCorral Copilot Understanding your data just got smarter and easier with AskCorral Copilot. AskCorral is “always on” and available across the platform — just look for the **AskCorral bar** at the bottom of your dashboard (on mobile, the **AskCorral** button). {% @arcade/embed url="" flowId="4o9ajZFB8oYNkxhrs8sZ" %} ### **How it works:** **Click AskCorral** on the bar (or just start typing your question) to open the tool. [Ask any question](https://docs.corraldata.com/kb/chat-with-your-data/build-prompts-in-askcorral). You can add results to your current Board and select or ask follow-up questions to keep the conversation going and the data flowing. #### Use AskCorral Copilot to: * **Build visualizations and dashboards** using natural language * **Modify existing reporting** without switching modes * This only works when AskCorral is open and Modify via AI is selected in a widget * **Summarize reporting** for easy insights, analysis, and sharing Ask and receive contextual answers directly within the part of the platform you’re using and drag them right in to your report. # Build Prompts in AskCorral Have questions about virtually anything in your data? AskCorral has answers. AskCorral trains our AI model on your account’s specific data such as existing schemas, tables, columns, and account-specific context so you get tailored results quickly. ### How it works: **Use full and well-spelled sentences:** AskCorral functions even if the prompt is low quality (incomplete sentences, spelling, or grammatical errors, etc.) but the results may not be as high quality. Ask simple questions (as if you’re talking to a human) to maximize the chances of getting strong results. * Worse Example: Show num of sesionns * Better Example: Show me the number of sessions our website received **Be specific:** AskCorral has a thorough understanding of your data sources and data points. Asking specific questions is key to ensuring strong and relevant results. Try to stay away from ambiguous questions that a human may have trouble understanding. * Worse Example: How many sessions? * Better Example: How many sessions did we get to the marketing website according to Google Analytics? **Include sources:** Strengthen your question by telling AskCorral which source(s) to pull from, especially when multiple similar sources are connected (i.e., Meta Ads + Google Ads) * If asking for blended data across multiple sources (i.e., ALL marketing spend), state this in the prompt, too. * If you’re asking across different systems, hint at the common key or relationship, if known. Example: *"Join Google Ads spend with Salesforce conversions by campaign ID"* **Include metrics and time frames:** Help AskCorral better understand "performance" and "growth" specific to you. Define it by adding metrics and time frames to your prompt. * Examples: * *"Calculate MoM change in net revenue from Stripe"* * *"Compare user churn rate before and after April 1, 2025"* * *"By 'engaged users', I mean users with >3 sessions in the last 30 days"* **Add internal lingo:** Train AskCorral on the nomenclatures and nuances of how your team “talks about data” by utilizing your [custom instructions](https://docs.corraldata.com/kb/chat-with-your-data/add-custom-instructions) in your prompts. Example: *“How many ‘newbie codes’ were distributed to ‘FTU’ compared to how many were redeemed?”* # Ask Multi-layered Questions Sometimes your business question is too complex for AskCorral to answer in one go — especially if it spans multiple sources, datasets, or stages in the funnel. AskCorral works best when you ask **smaller, focused questions first**, then combine them into a final, synthesized prompt. Example: *“What is the cost per SQL from paid LinkedIn campaigns targeting enterprise leads in Q2, and how does that compare to Q1?”* #### This question involves four different layers: 1. Spend from LinkedIn Ads 2. Leads filtered by campaign and segment 3. Funnel progression to SQL 4. Time-based comparison Trying to write this all at once may fail or return the wrong results. So, break it down. ### How it works: **Understand spend by asking:** “*What was the total LinkedIn Ads spend for Q1 and Q2?”* **Get lead counts by asking:** *“How many leads came from LinkedIn Ads in Q1 and Q2?”* **Filter to enterprise leads by asking**: *“How many of those LinkedIn leads were from enterprise accounts?”* **Funnel progression to SQL by asking:** *“Of those enterprise LinkedIn leads, how many became SQLs in Q1 vs Q2?”* **Synthesize all data with the prompt:** *“What was the cost per SQL for LinkedIn enterprise leads in Q1 and Q2?” (Use previous answers: divide spend by SQL count.)*
# Add custom instructions AskCorral, like any AI, thrives on training. We handle the bulk of it behind the scenes, of course, but you get to steer the ship a bit, too! No one knows your business better than you, and that means the things that make your business uniquely yours (think: insider acronyms, custom use cases, specialized language, etc.) might not be readily obvious to an outsider. Even one as smart as AskCorral. That's why we've added Custom Instructions where you can share these tidbits with your AI and make sure it's up to speed on what's most important to you. {% @arcade/embed flowId="V3sbgWPwMxKChvMJeSCD" url="" %} {% hint style="info" %} If you're having trouble and require technical assistance, feel free to reach out to . {% endhint %} # Conversation History AskCorral conversations are saved, so an analysis you started yesterday — or a build the Agent was midway through — is never lost when you close the panel. ### How it works Open the history list from the AskCorral panel to see your past conversations, each with an automatically generated title. From there you can: * **Resume** any conversation and pick up exactly where you left off — the full thread and context come back with it. Each conversation has its own link, so you can bookmark or share one with a teammate on the account. * **Pin** the conversations you return to often so they stay at the top of the list. * **Rename** a conversation when the auto-title isn't how you think of it. * **Delete** a conversation you're done with. Deleting also removes any files you attached to it. If the Agent is still working when you open your history or switch views, the run keeps going — you can jump back into the conversation and watch it finish. {% hint style="success" %} **Tip:** Long-running analyses make great pinned conversations — keep your weekly performance review thread pinned and just ask "same review for this week" each Monday. The Agent carries the context forward. {% endhint %} {% hint style="info" %} If you're having trouble and require technical assistance, feel free to reach out to . {% endhint %} # Attach Files to AskCorral Sometimes the context you need isn't in your connected data — meeting notes, a campaign brief, a vendor doc. You can attach files directly to an AskCorral conversation and the AI will read them and use them as context alongside your live data. {% hint style="warning" %} File attachments are rolling out gradually. If you don't see the attach option in your composer yet and want it enabled for your account, contact . {% endhint %} ### How it works **Click the attach button** in the AskCorral composer, or **drag a file** into it. Each attached file shows as a chip with its name and size — remove one with the × before sending. Then ask your question: *"Here are my notes from the ops meeting — which of these action items can you check against our actual numbers?"* * **Supported today:** plain text (`.txt`) and Markdown (`.md`) files. Unsupported types are rejected with a message naming the type; more formats are on the way. * **A few files per message,** with a per-file size limit — the composer will tell you if a file is too large to include. * **Session-scoped:** attachments live with that conversation. They're removed when you delete the conversation, and swept automatically after a retention window — they don't become part of your connected data. * **Private to your account:** files are isolated per customer and per user, enforced server-side. ### Good uses * Paste-averse context: a brief, a checklist, meeting notes, a KPI definition doc * "Compare this plan against our actuals" — attach the plan, let AskCorral pull the actuals * Terminology: attach a glossary so the AI uses your team's language for a session {% hint style="info" %} Want a file to become a permanent, queryable data source instead? That's an integration, not an attachment — see [Connect your data](https://docs.corraldata.com/kb/getting-started/quickstart) for the Google Sheet, Drive, and OneDrive paths. {% endhint %} # Governed Metrics in AskCorral When a metric or dataset in your account has been marked **governed** — reviewed and maintained by CorralData rather than built ad hoc — AskCorral prefers it over writing new SQL from scratch. You'll see a note like *"computed from governed metric ⟨name⟩"* under the answer, so you know exactly where the number came from and can trust it without having to check the underlying query yourself. *** ### How it works By default, AskCorral answers questions by writing SQL against your connected data on the fly. That's flexible, but for metrics your team relies on repeatedly — revenue, active patients, retention rate — you want the same number every time, computed the same way, not a fresh interpretation per question. Governed metrics and governed datasets solve that: * A **metric** can be marked governed once it's been defined and reviewed. When a question matches a governed metric, AskCorral answers directly from that metric's definition instead of writing new SQL. * A **dataset** can be flagged governed (CorralData-maintained) the same way. If a question could be answered from either a governed dataset or a non-governed one covering similar data, AskCorral prefers the governed one. * Either way, the response carries a provenance note — the metric or dataset name and its governed status — so it's clear the answer came from a reviewed source, not a one-off query. {% hint style="info" %} This only applies when a governed metric or dataset actually matches the question. Long-tail, exploratory questions with no governed match are answered exactly as before — AskCorral still writes SQL on the fly for anything outside your governed set. {% endhint %} *** ### What you'll see {% stepper %} {% step %} #### **Ask a metric question** Ask AskCorral something that matches a metric your team has already defined and governed — for example, "what was our retention rate last quarter?" {% endstep %} {% step %} #### **Get the answer with provenance** The response includes the number along with a note such as *"computed from governed metric Retention Rate"* — so you know it came from the reviewed definition, not a fresh query. {% endstep %} {% step %} #### **Reconcile with confidence** Because the same governed metric answers the same question the same way every time, you can compare answers across conversations, or against a board built on the same metric, and expect them to match. {% endstep %} {% endstepper %} *** ### Where this fits * Governed metrics and datasets are set up and maintained by your CorralData team — reach out if there's a number you'd like turned into a governed metric so it answers consistently everywhere it's asked. * This works alongside Row-Level Security: a governed metric still respects RLS, so two users asking the same governed question can get different (correctly scoped) numbers if their row-level access differs. * See AskCorral Agent for the broader picture of what the agent can do beyond metric questions — building, debugging, and analyzing across your account. # Instant Insights Save yourself hours of time analyzing data with Instant Insights. This powerful tool transforms your CorralData dashboards into immediate summaries that are easy to understand and made for real-world use. Think strategy reviews, team check-ins, board decks, or that last-minute email to your CEO. It’s like having a data analyst built into every report. {% @arcade/embed url="" flowId="RsLNeRa64yShzcIWEQNi" %} ### How it works: **Just click the Instant Insights button** in the lower-right corner on any Board. Watch as our AI scans your data and delivers trends, anomalies, performance highlights, and more. # Correlation Analysis Start exploring real relationships among your data with Correlation Analysis. Just AskCorral to spot the trends and connections. {% @arcade/embed flowId="iQT7fb5gdZ1TR94hrOkh" url="" %} ### How it works: **Ask a question:** Type a natural-language prompt into AskCorral. Be sure to include “correlation” in your question. Example: *“What’s the correlation between campaign spend and client rebookings last quarter?”* **Review the results:** Get a scatterplot and correlation coefficient with one click. **Refine on the fly:** Change your variables, adjust your date range, or ask a follow-up question. #### Correlation is one of the most powerful tools in exploratory analysis. It helps you: * **Spot trends** in marketing performance * **Identify factors** that may contribute to retention or churn * **Explore how spend** **is associated with outcomes** across channels or teams * **Make smarter, faster decisions** without waiting on BI teams # Modify widgets via AI You can modify any reporting by simply clicking on **Modify via AI** on any existing widget's menu and asking for any modification to it. Our AI understands both your request, as well as the underlying data to act on it. Happy with your update? Just click Save. It’s like having a team of data analysts on standby. {% @arcade/embed url="" flowId="ZpjPmhP4GjE5hGBUkFDn" %} {% hint style="info" %} If you're having trouble and require technical assistance, feel free to reach out to . {% endhint %} # Modify SQL via AI Want to get right under the data hood? You can modify any SQL on any existing widget using plain old English - no SQL bootcamps needed. Simply use AskCorral to modify the query. Our AI understands both your request, as well as the underlying data to act on it. {% @arcade/embed flowId="0vb3RD7ARB4JeaeGn7tY" url="" %} {% hint style="info" %} Need something more complex? Drop a line to and we'll see if we can get it added for you. {% endhint %} # Modify annotations Each report comes with a short, descriptive annotation. Don't like the default? Want to add additional details? No problem! Easily modify the annotation via **Edit Widget.** {% @arcade/embed flowId="3EyyMJnExpHrHJqPyClE" url="" %} {% hint style="info" %} If you're having trouble and require technical assistance, feel free to reach out to . {% endhint %} # Change chart type Need to change the Chart type on a widget? CorralData supports dozens of visualizations. Simply click ... and choose **Change chart to** on any widget. {% @arcade/embed flowId="ew46I59NtjwltKJY8kXk" url="" %} {% hint style="info" %} If you're having trouble and require technical assistance, feel free to reach out to . {% endhint %} # View a Widget Query Want to see what query is driving a particular widget? No need to go far: {% @arcade/embed flowId="rfgktOuIciQAwuLYLkst" url="" %} {% hint style="info" %} If you're having trouble and require technical assistance, feel free to reach out to . {% endhint %} # SQL Client Want to work with your warehouse directly? The built-in SQL Client gives you a full query workspace inside CorralData — no external tools, no separate credentials. ### How it works Open **SQL Client** from the left sidebar and start writing. As you work you get: * **A schema browser** in the sidebar — click through your schemas, tables, and columns, and insert table names straight into your query. * **Autocomplete** for table and column names as you type. * **Run selection** — highlight part of a query and run just that piece. * **A date picker for date-range substitution** — write queries with date tokens and control the period from the picker instead of editing the SQL each time. * **Optional auto-linting and formatting** — toggle it on to keep your SQL tidy, or off to keep every character exactly as you wrote it. * **Draft protection** — your in-progress query is kept if you navigate away and come back. ### Turn a query into something permanent A good query shouldn't die in the editor. From the SQL Client you can save your result as: * **A data model** — a reusable definition other widgets and AI answers can build on (see [Verified Data Models](https://docs.corraldata.com/kb/organize-your-data/verified-data-models)) * **A widget** — drop the result onto a Board as a chart or table {% hint style="success" %} **Tip:** You don't have to write the SQL yourself. Ask AskCorral to draft the query, then open it in the SQL Client to inspect, tweak, and save it. {% endhint %} {% hint style="info" %} If you're having trouble and require technical assistance, feel free to reach out to . {% endhint %} # Data Apps ## Data Apps Data apps are custom board tiles. Use them when you need a layout or interaction that goes beyond CorralData's standard widgets: an interactive table, a multi-panel view, a custom gauge, or any bespoke visualization specific to how your team works. You don't need to know any code – just describe what you want. *** ### Creating a Data App **The easiest way is to ask AskCorral.** Describe what you want in plain language, including the data you want to see, the layout, and any filters, then AskCorral builds it for you. You can also create a data app with Claude or ChatGPT if you have [CorralData MCP connected](https://docs.corraldata.com/kb/mcp/overview). Same idea: describe what you want and it builds it there instead. **Here's how it works:** {% stepper %} {% step %} #### **Describe it** Say what you want in plain language: the data, the layout, and any filters. For example, "a prep sheet for today's appointments, with each client's service, upsell opportunity, and rebooking window." That's enough to start. {% endstep %} {% step %} #### **Preview it** AskCorral builds it and shows you a live preview. Ask for changes in plain language until it's right. {% hint style="info" %} If a preview doesn't show up right away, just tell AskCorral to try again. {% endhint %} {% endstep %} {% step %} #### **Add it to your board** Once it looks good, say so, and AskCorral can add it to a new board or an existing one. {% hint style="info" %} You'll need edit access on the board to save it. If you're not sure what access you have, check with your CorralData admin or see [Add & manage users](https://docs.corraldata.com/kb/getting-started/manage-users). {% endhint %} {% endstep %} {% step %} #### **Use it** It's live from then on: open it like any other board, and the data updates every time you load it. {% hint style="info" %} From here, moving, resizing, or removing it works the same as any other widget. See [Manage Widgets](https://docs.corraldata.com/kb/organize-your-data/manage-widgets) if you need a refresher. {% endhint %} {% endstep %} {% endstepper %} *** ### Switch to a Full-Page Data App
Full Width Data App
By default, a board with a Data App shows it as a tile alongside your other widgets, same as any other board. **If a board has exactly one Data App, you can switch it to a full-page view instead** – no widget tile, just the app with the whole screen to work with. Good for wide tables, dense dashboards, or anything easier to read with more room. **To switch to full-page:** 1. You must be an **Editor** or **Admin to** make the switch 2. Find the board in the left nav 3. Click the board menu (···) 4. Choose **Switch to App.** Your Data App will convert to full-page and the board's name in the nav now carries an **App** badge. **To switch back to Classic:** 1. Open the same board menu 2. Choose **Switch to Board** {% hint style="info" %} **Full-page view only works for boards with a single Data App.** If a board has more than one, keep it on Classic — full-page will only show the first one and hide the rest. {% endhint %} ### What can you build as a Data App? Data apps give you full control and are endlessly customizable. They don't even have to be about numbers at all: a schedule, a service menu, a staff roster, a set of instructions can all become a data app. Here are a few use cases: * **Interactive tables:** Sortable, filterable views of your data that go beyond a static report.\ ***Try:*** *"Build me a data app with a table of today's schedule gaps next to anyone overdue for a follow-up, so I can fill open slots before end of day."*
* **Multi-panel views:** Several related views combined into a single tile.\ ***Try:*** *"Build me a data app where I can monitor revenue, appointment volume, and staffing by location, with each location as its own tab in the view"*
* **Custom gauges and scorecards:** A purpose-built visual for metrics your team watches most closely.\ ***Try:*** *"Build me a data app with a gauge showing this month's average appointment lead time against our 3-day target."*
* **Bespoke visualizations:** Anything a standard chart type can't do, built to match how you actually think about the data.\ ***Try:*** *"Build me a data app with a view of all my locations, color-coded by health status and grouped by region, so I can see who needs attention at a glance."*
* **Interactive modeling tools:** Sliders and scenario toggles that let your team change assumptions and watch the outcome update, live, not just view a static number.\ ***Try:*** *"Build me a data app of a what-if revenue simulator with sliders for members per site and monthly churn, showing where the projected uplift comes from."*
* **Reference tools, not tied to a number:** A table or list built from your data, with no metric involved.\ ***Try:*** *"Build me a data app of a lookup table of our current service menu, with pricing and duration, grouped by category."* {% hint style="info" %} Data Apps are now AskCorral's **default** for open-ended build requests — ask for a dashboard or report without naming a chart type and you'll get a Data App. If you ask for a specific widget type ("give me a bar chart"), AskCorral honors that instead; say **"build me a data app"** when you want to make sure you get one. {% endhint %} *** ### Data Apps stay in sync with your board Just like native widgets, data apps respond automatically to your board's filters and date range. Pick a location, a date window, or another filter at the top of the board, and any data app on it updates right along with everything else. You don't need to set this up: describe the filter behavior you want when you ask AskCorral to build it, and it handles the rest. A data app also stays live and org-wide once it's built. It queries your data on every load, so it's never a stale snapshot, and it lives on your board, visible to everyone whose permissions allow it, not buried in a chat history. {% hint style="success" %} **Tips for best results** * **Describe the outcome, not the mechanics.** Say what you want to see and why (for example, "a table of my top 10 locations by revenue this month, filterable by service line") and let AskCorral figure out the rest. * **Mention filters up front.** If you want the data app to respond to a board filter, such as location, date range, or provider, say so in your first request. * **Reference an example.** If you've seen a layout you like, on another board or in a screenshot, describe it or point to it. AskCorral can match an existing style. * **Got a regular widget instead of a data app?** Say "make this a data app" and AskCorral will rebuild it as one. {% endhint %} *** ### Rolling updates We're improving Data Apps continuously. As new capabilities land, we'll update this page. *** ### Getting help Tell AskCorral, Claude, or ChatGPT to build, fix, or modify a Data App in plain language. For help debugging an existing one, share what's not working and the AI will diagnose and fix it. # Data Apps (legacy) {% hint style="warning" %} **This page describes a superseded technical model.** Data Apps are now built by describing what you want in plain language — AskCorral (or Claude/ChatGPT via MCP) writes the SQL and wires up board filters automatically. See [Data Apps](https://docs.corraldata.com/kb/explore-your-data/data-apps) for the current workflow. This page is kept for reference on the underlying HTML/JS mechanics. {% endhint %} ## Data Apps Data apps are custom dashboard tiles built with HTML, CSS, and JavaScript. Use them when you need a layout or interaction that CorralData's native chart types can't deliver — interactive tables, multi-panel views, custom gauges, or any bespoke visualization. *** ### Creating a data app **The easiest way is to ask AskCorral.** Describe what you want in plain English — the data, the layout, any filters — and AskCorral will write the HTML/CSS/JS and wire up the SQL queries automatically. You can also create data apps through the Claude or ChatGPT MCP connector if you have `widget.edit` access. *** ### How data apps differ from standard widgets Native CorralData widgets (line charts, fuel gauges, tables) are configured through SQL and display settings. Data apps give you full control, with a few important constraints: | | Native widget | Data app | | ------------------------------------ | -------------------------------------- | ------------------------------------------------------------ | | **SQL** | Inline in widget settings | Named queries, called via JavaScript | | **Board filter tokens (`${param}`)** | Substituted into SQL automatically | **Not substituted** — filtering happens in JavaScript | | **Styling** | CorralData theme applied automatically | You write all CSS; use CSS variables for theme compatibility | | **Grid sizing** | Per-type defaults | Requires `grid_width: "4-full"` and `grid_height: "auto"` | *** ### The most important thing to know {% hint style="warning" %} **Board filter tokens do not work in data app SQL.** Tokens like `${brand}`, `${location}`, and `${date_start}` are substituted into SQL for standard widgets — but **not for data apps**. In a data app, `${brand}` arrives at the database as the literal text `${brand}` and returns no results. All filtering in a data app happens in JavaScript, after the data is loaded. When you ask AskCorral or Claude to build a data app with filters, this is handled automatically — just describe the filter behavior you want. {% endhint %} *** ### Running SQL queries in a data app SQL is registered as named queries and called from JavaScript at runtime: ```javascript const result = await corral.runNamedQuery('revenue_by_location'); // result = { columns: ['location', 'revenue'], rows: [['Main St', '12450.00'], ...] } // Rows are tuples — convert to objects before use const data = result.rows.map(r => Object.fromEntries(result.columns.map((c, i) => [c, r[i]])) ); ``` {% hint style="info" %} All query result values are strings, including numbers. Use `Number(val)` before doing any arithmetic. {% endhint %} *** ### Reading board filters in JavaScript ```javascript // Get current filter state const bf = corral.getBoardFilters(); // bf.filterParams is an ARRAY: [{ name: 'location', value: 'main_street' }, ...] // Find a filter value by name const location = bf.filterParams.find(p => p.name === 'location')?.value; // Re-render when filters change corral.on('filtersChanged', () => { // re-read filters and update the display }); ``` *** ### Common mistakes | Mistake | What happens | Fix | | -------------------------------------- | ----------------------------- | --------------------------------------------------------------------- | | `${param}` token in SQL | Query returns no results | Remove the token; apply the filter in JavaScript instead | | Using raw string values in arithmetic | Silent NaN or broken math | Coerce with `Number(val)` before calculations | | Fixed height on the iframe body | Layout gets clipped | Use `grid_height: "auto"` — never set `height: 100%` on the page body | | External JavaScript library from a CDN | Script blocked by the sandbox | Only CorralData's built-in chart toolkit is available | *** ### Getting help Ask AskCorral, Claude, or ChatGPT to build, fix, or modify a data app in plain English. For help debugging an existing one, share what's not working and the AI will diagnose and fix it. # Export Raw Data Every widget's standard **Export CSV** covers most needs, but it's capped at 3,000 rows. When you need the full result set behind a widget — up to 1,000,000 rows — use **Export Raw CSV** instead. *** ### How it works Export Raw runs asynchronously: instead of downloading immediately, CorralData generates the file in the background and notifies you when it's ready. This is what makes it possible to pull far more data than a normal export — the query isn't held open in your browser while it runs. {% hint style="info" %} If a widget's result set is larger than the standard export can handle, CorralData will route that export through Export Raw automatically. {% endhint %} *** ### Exporting {% stepper %} {% step %} #### **Open the widget menu** Click the **⋮** menu in the top corner of any widget. {% endstep %} {% step %} #### **Select Export Raw CSV** The export starts running in the background — you can keep working while it generates. {% endstep %} {% step %} #### **Check your notifications** You'll get a notification when the file is ready to download. {% hint style="info" %} If you don't see the notification right away, try refreshing the page — it may already be waiting for you in the notification panel. {% endhint %} {% endstep %} {% endstepper %} *** ### Where this fits * Use the regular **Export CSV** for anything under 3,000 rows — it's instant, with no need to wait for a notification. * See View a Widget Query if what you actually need is the SQL behind a widget, not the exported data itself. # Manage Widgets Now it’s even easier to see a full list of the widgets connected to your account. This function is especially useful when you know what you’re looking for but aren’t exactly sure where to find it. {% @arcade/embed flowId="ZdnKSxbNaj3ZQ6Ty1UhR" url="" %} ### How it works: **Just click Manage Widgets** in the **Settings** tab on the left sidebar. You can search for widgets by Title or keyword or filter widgets by Chart Type or Board. You don’t need to know the full title or to complete all three fields to return results. To see more (or fewer) results on the page, simply change the “Results per page” number in the lower-right corner.
# Data Dictionary When you import your data, we break down the information from every single table and column so our AI understands your data. The Data Dictionary (formerly Manage AI Metadata) collects all of this information into a simple database directly in your account. No more digging around when you need to make an edit. {% @arcade/embed url="" flowId="XPnbrovxmzYgRaEmrRJG" %} ### How it works: **Just click Data Dictionary** on the left sidebar. Filter results by typing in a Name or keyword and/or a Description. Click Edit to make changes to individual tables (description, name, and/or ID copy) and define whether or not the table (or columns) should be used in AI. {% hint style="info" %} When you select the “Use in AI” checkbox, the column and data within it will be included by the AI when responding to search requests. {% endhint %} # Verified Data Models Data models (reusable SQL definitions, formerly called data sets) can now be marked **verified** — a governance flag that tells both your team and our AI which definitions are the maintained, trusted source of truth. ### What the verified flag means A verified data model is one that CorralData (or your data lead) maintains as the approved definition of that data — your revenue model, your appointments model, your marketing-spend rollup. Unverified models are still useful for exploration, but they're someone's working copy, not the standard. ### Why it matters for AI answers AskCorral and the CorralData MCP server **prefer verified data models** when answering a question. If a question can be answered from a verified model, the AI grounds its answer there instead of hand-writing fresh SQL against raw tables — so two people asking the same question get the same number, computed the way your organization defined it. When an answer is grounded this way, AskCorral surfaces the provenance — which governed metric or data model the answer was computed from — so you can trust it and reconcile it. ### What this protects against Without the flag, an edited or experimental copy of a dataset could silently become the source for an AI answer. With it, unmaintained copies can't pollute your numbers: the verified definition wins. {% hint style="info" %} Want a data model verified, or a metric definition locked in as your organization's standard? Reach out to your CSM or . {% endhint %} # Edit Widgets Want to change your chart type? Title? Annotation? Size? Date settings? Or more? Widget editing is available right at your fingertips. Play around with the different settings to get a feel for this easy-to-use feature. {% @arcade/embed flowId="yVPNfnY1u2FuAR1GDEYS" url="" %} {% hint style="info" %} Have editing needs not available here? Reach out to our support team at {% endhint %} # Time Locking Do even more in widget-editing mode. Use **Widget Date Settings** when you want to see your metrics locked to specific reporting and comparison periods. We give you various intervals to choose from so you can zero in on the exact time frames without manually sifting through reports. **Examples:** * If you want to continuously track budget revenue year-to-date, set one revenue widget to show YTD instead of using the date picker to change the board each time. * If you want to show the same metric side-by-side in different intervals, set up multiple widgets, each with a locked time interval, then drag them next to each other in your dashboard. {% @arcade/embed flowId="zh1EI41Fx7kWnm1sfMtE" url="" %} ### How it works: **Just Click the three dots** in the upper-right corner of any Board. Then click Edit Widget to open up the editing panel. In Widget Date Settings, **select the checkbox** next to “Override date picker…” to enable the field. Choose your interval and/or comparison period to update your Board. # Duplicate widgets Because sometimes you want the same report across a multitude of dashboards. Not to fret, CorralData has *two* different ways for you to do this! Inside the widget menu you'll see ***Duplicate to*** as well as ***Create Linked Copy*****:**
So, what's the difference? ***Duplicate to*** creates a standalone copy of the selected widget to the selected dashboard. The two widgets have no ties back to one another after the creation and you can make changes to either widget without affecting the other. ***Create linked copy***, on the other hand, creates a *linked* copy of the selected widget to the selected dashboard so that any changes made to one widget affects all of its linked copies no matter the dashboard. So which do you choose? If you want to use a specific widget on another dashboard as a base for a new report (i.e. you anticipate making changes to this widget specific to its new dashboard) then select ***Duplicate to**.* If you want to see the same exact report across multiple dashboards with consistency and accounting for any future changes, then select ***Create linked copy****.*** {% hint style="info" %} If you're having trouble and require technical assistance, feel free to reach out to . {% endhint %} # Pivot Tables A regular table widget shows one row per record. A **pivot table** (Table V2) lets you group, summarize, and restructure that same data on the fly — rolling many rows into subtotals by category, location, or any column you choose, without writing new SQL. *** ### How it works Pivot tables work off the same underlying query as a regular table — you're changing how the results are grouped and displayed, not the data behind them. Columns can be dragged into roles: * **Row Groups** — columns to group rows by (for example, location, then provider). * **Column Labels** — columns whose values become their own columns across the top (for example, one column per month). * **Values** — the numbers being summarized (sum, average, count, etc.) for each group. You can freeze columns so they stay in view while scrolling a wide pivot, and rename columns from the same place you rename them on any table — Edit Widget → Column Settings. {% hint style="info" %} You don't have to build a pivot table by hand — you can ask AskCorral for one directly ("break this down by location and month") and it will set up the grouping for you. {% endhint %} *** ### Turning a table into a pivot table {% stepper %} {% step %} #### **Open the widget's column settings** From **Edit Widget**, open the Columns panel for a table widget. {% endstep %} {% step %} #### **Drag columns into place** Drag the columns you want into **Row Groups**, **Column Labels**, or **Values** to build the layout you want. {% endstep %} {% step %} #### **Freeze columns if needed** For a wide pivot, freeze one or more leading columns so they stay visible as you scroll. {% endstep %} {% step %} #### **Save** Save the widget. The board reflects the new layout for everyone who views it. {% endstep %} {% endstepper %} *** ### Where this fits * See Edit Widgets for the rest of what's available in a widget's settings beyond pivoting. * See Change chart type if you're deciding between a pivot table and a chart for the same data. # Board Filters Board filters let people narrow what a board shows — by date, location, provider, campaign, or any other dimension — without editing a single widget. ## Ask AskCorral to build one for you You don't need to build filters by hand. Just tell AskCorral (or Claude/ChatGPT, if you've connected the CorralData MCP server) what you want to filter by, and it'll set it up on the board for you: * "Add a location filter to the Sales board" * "Filter this board by campaign name, using the campaign column in the ad spend table" * "Update the date filter on this board to default to the last 30 days" * "Remove the provider filter from this board" AskCorral creates, updates, and removes board filters directly — no need to configure a query or pick options yourself. If you want a filter to apply to specific widgets only, mention that and AskCorral will scope it accordingly. {% hint style="info" %} Prefer to describe what you want in plain language rather than SQL — AskCorral will translate it into the right filter configuration. {% endhint %} ## How filters work * Filters can be **static** (a fixed list of options you provide) or **dynamic** (options pulled live from a column in your data). * A filter can apply to one board or several. * Once added, a filter shows up as a dropdown or control at the top of the board for anyone viewing it. ## Removing a filter Ask AskCorral to remove it, e.g. "Remove the region filter from this board" — or reach out to if you'd like help. # Google Sheet Connector Setup At CorralData, we leverage Google Sheets not as a place for styled dashboards or pre-aggregated reports, but as a lightweight, flexible tool to power ad hoc data sources and database tables for BI. This guide outlines best practices to ensure your synced Google Sheets function smoothly and scalably within our data pipelines. ### 1. Use a Single Tab for Your Data Source **Why:** This keeps your data structure clean and optimized as a single, reliable table.\ \ CorralData connects to one tab within a Google Sheet per connection. Avoid using multiple tabs for segmented information or calculations. Create additional Google Sheet connections to sync additional tabs. ### 2. Table Headings in Row 1 **Why:** CorralData expects headers in Row 1 to define column names in the resulting table.\ \ Ensure your column headings start at row 1 without any title, note, or spacing rows above. ### 3. No Skipped, Styled, or Merged Rows **Why:** Extra formatting or spacing can confuse the sync and schema generation process.\ \ Avoid inserting styled rows, merged cells, or leaving gaps. Keep the dataset tight and unstyled. ### 4. Avoid Aggregation, Subtotal, or Total Rows **Why:** These introduce semantic noise and may interfere with analysis or mislead downstream consumers.\ \ Maintain raw, atomic data only. Do not include subtotal rows, rollups, or summary calculations. All aggregations & calculations can be handled within CorralData. ### 5. Always Include a Date Column (Format: YYYY-MM-DD) **Why:** A date dimension is essential for time-based filtering in CorralData dashboards.\ \ Ensure at least one column contains clean ISO-formatted dates (yyyy-mm-dd). Do not mix text or ambiguous formats within date columns. ### 6. Appropriately Typed Columns **Why:** Ensures proper schema mapping and enables type-specific filters and aggregations.\ \ Numbers must be stored as numbers, text as text, and dates as dates in the sheet — not as formatted strings. ### 7. Use Column-Wide Named Ranges **Why:** Allows the sync to auto-expand with new rows of data as the sheet grows.\ \ Instead of defining named ranges like A1:A1000, use column-wide references like A:A. This ensures CorralData captures all present and future entries. ### 8. Use Full State Names for Geographic Fields **Why:** Supports compatibility with CorralData’s map visualizations.\ \ Use full names like "California" instead of abbreviations like "CA" when referencing U.S. states. ### 9. Avoid or Clean Up Formula Outputs **Why:** Sheets designed for BI ingestion should contain clean, flat data without #N/A, #VALUE!, or formula-based errors.\ \ If formulas are used, ensure all outputs are valid. Prefer pasting values using CTRL + SHIFT + V to remove formulas altogether. This prevents sync issues and ensures compatibility with downstream BI tools. ### 10. No Formatting Characters in Empty Values (i.e. N/A or -) **Why:** Sheets must handle empty cells / values in a consistent way to ensure that data can be properly aggregated. Don't use values like N/A or - to denote empty values. Corral will handle all cases of empty or NULL values. ### Summary These practices help ensure your Google Sheet behaves like a well-structured, scalable database table rather than a styled or pre-aggregated report. When done right, this setup enables faster insights, easier debugging, and smoother syncing across our analytics ecosystem. # Zenoti Connector Setup Follow the instructions below in order to generate the needed credentials & authorization to connect to Zenoti. **NOTE:** * Please note that CorralData will leverage the existing API credits of your Zenoti instance. ***Additional charges and fees may apply in Zenoti based on your account details***. * If you prefer for CorralData to sync Zenoti data during off hours or to only leverage a portion of your available API credits, please email and we'll adjust your sync settings. ### **In Zenoti, to generate a new API key:** 1. At the organization level, click the **Configuration** icon. 2. Search for and select the **Apps** setting from the **Integrations** section. 3. On the **Manage Applications** page, click **Add**. 4. Enter the following information: 1. **Name**: Enter the name of the application. This can be CorralData. 2. **URL**: Enter the URL of your Website or the application. In case of errors or issues in the app, URI information is used to contact the app developer. This can be . 3. **Description**: Enter a brief description of the app for which you are generating the API key. This can be “CorralData Integration”. 4. **Login User Type**: Select Employee 5. **Source App**: Select Client App from the drop-down list. 6. **Post Logout Redirect URL**: To redirect your users to a URL after they log out, click Add, and then enter as the URL. 7. **Post Login Redirect URL**: To redirect your users to a URL after they log in, click Add, and enter as the URL. 5. Click **Next**. 6. Manage the scope of your app by selecting the checkbox of data permissions under the appropriate API groups. For example, if you want to restrict access of the app to an employee module, then expand and select only the corresponding employee permissions under the relevant API group. Choose API keys (APIKEY GROUPS) as your authentication method 7. Click **Next**. 8. Zenoti generates a new **Application ID** and **Secrets** (secret key). These are used to generate a new API key. 9. Copy the **Application ID** and the **Secrets** on a notepad. 10. Click **Generate API Key**. 11. Zenoti generates a new API Key for your business and the app. 12. Click **Finish** ### **In CorralData:** 1. Copy the API keys to a notepad and enter them into the CorralData Connector form. 2. Click **Save**. 3. Once connected, CorralData will begin to sync your data and notify you as soon as this process has been completed and data is available for usage within the app.
# CorralData MCP Server The CorralData MCP Server is a [Model Context Protocol](https://modelcontextprotocol.io/) (MCP) integration that lets AI assistants interact with the CorralData analytics platform. It provides 40 tools for exploring data, building dashboards, and managing analytics content — all through natural conversation. ## What can it do? **Explore your data** * Browse database schemas, tables, and columns * Discover foreign key relationships between tables * Search for tables by keyword * Execute read-only SQL queries against your data warehouse **Build dashboards** * Create and update boards (dashboards) * Add and configure widgets (charts, tables, KPIs) * Set up board filters for interactive filtering * Bulk update widget layouts and properties **Manage datasets** * List and inspect reusable dataset definitions * Create and update datasets with SQL queries * Validate widget queries before saving **Build Data Apps** * Create custom HTML/JS widgets that run pre-registered SQL queries * Update a data app's content, queries, or sizing * Preview changes safely before persisting them **Work with connected services** * List upstream services connected for a customer's data warehouse * Search and call tools exposed by connected third-party services * Write actions require explicit user confirmation before running **Configure AI behavior** * List and read AskCorral's prompt templates * Set custom instructions that steer how AskCorral responds for a customer * List the customer accounts you have access to ## How it works The server runs as a stateless HTTP service exposing the MCP protocol. Claude, ChatGPT, Claude Code, Codex, and any other MCP-compatible client connect to the `/mcp` endpoint, discover available tools, and invoke them on behalf of the user. Authentication is handled via OAuth 2.0 (Authorization Code with PKCE, public client `corral-mcp-client`, no client secret). Users authenticate once, and the server enforces role-based access — read-only tools are available to all authenticated users, while write operations require specific roles like `board.edit` or `widget.edit`. ## Key features * **Role-based access control** — Write operations are restricted by role. Read operations are open to all authenticated users. * **Token-efficient responses** — Responses are designed for AI context windows with progressive disclosure (summaries for lists, details on demand). * **SQL safety** — Query execution is read-only with configurable row limits. * **Schema discovery** — AI assistants can explore your database schema to write accurate queries without prior knowledge of your data model. {% content-ref url="/pages/1GfB1zK4pr8bHFhaxE8w" %} [Getting Started](/kb/mcp/getting-started) {% endcontent-ref %} # Getting Started Once connected, you can ask your AI assistant things like "What were our top locations by revenue last month?" or "Build me a dashboard comparing provider performance across locations" — and it will pull directly from your CorralData account to answer. *** ## Choose Your Setup * [**Connecting to Claude**](#connecting-to-claude) * [**Connecting to ChatGPT**](#connecting-to-chatgpt) * [**Connecting to Claude Code**](#connecting-to-claude-code) * [**Connecting to Codex**](#connecting-to-codex) All setups use the same connection details: | Field | Value | | --------------- | -------------------------------- | | MCP Server URL | `https://mcp.corraldata.com/mcp` | | OAuth Client ID | `corral-mcp-client` | {% hint style="info" %} **No client secret is needed.** CorralData uses a public OAuth client with PKCE. If a form insists on a client secret, enter any value — it is not checked. Your CorralData login is what controls access to your data. {% endhint %} *** ## Connecting to Claude You'll add CorralData directly inside Claude.ai or the Claude Desktop app. #### Team and Enterprise plans {% hint style="info" %} On Team and Enterprise plans, a **Claude admin** enables CorralData for the organization first. Then each **member** connects with their own CorralData login. {% endhint %} **For Admins:** {% stepper %} {% step %} **Open your Claude Organization Settings** Click your organization name and select **Settings**. {% endstep %} {% step %} **Go to Connectors** In the left sidebar, click **Connectors**. Or, [click here](https://claude.ai/settings/connectors?modal=add-custom-connector) to go there directly. {% endstep %} {% step %} **Search for CorralData** Type it into the search field, then click on the listing. {% endstep %} {% step %} **Click 'Connect to Claude' Button** {% endstep %} {% step %} **Sign into your CorralData Account** Sign in with your CorralData credentials on the page that opens. You'll be redirected back to Claude once you login successfully and the connector will show **Connected.** {% hint style="success" %} **You're done!** CorralData will be available in Claude conversations. Claude will have access to all accounts your login can view. If your login has access to more than one account, confirm with Claude which one you're working in before running queries or creating widgets.
See what you can do [after you connect](#after-you-connect) or explore more [usage examples.](/kb/mcp/usage-examples) We also recommend installing the [CorralData skill](#add-the-corraldata-skill-recommended) after you've connected. {% endhint %} {% endstep %} {% endstepper %} **For Members:** The steps are the same as the [Personal plan steps](#personal-plans-pro-max). You may see **Request** instead of Connect in step 3 if CorralData hasn't been added as an organization connector yet by an admin. Click it to send the request to your Claude admin. Once they approve it and enabled the connector, you will be able to connect. #### Personal plans (Pro, Max) {% stepper %} {% step %} **Go to Customize and select Connectors** In the left sidebar, click **Customize**, then the **Connectors** tab. Or, [click here](https://claude.ai/customize/connectors) to go there direcly. {% endstep %} {% step %} **Search for CorralData** Type it into the search field, then click on the listing. {% endstep %} {% step %} **Click 'Connect to Claude' Button** {% endstep %} {% step %} **Sign into your CorralData Account** Sign in with your CorralData credentials on the page that opens. You'll be redirected back to Claude once you login successfully and the connector will show **Connected.** {% hint style="success" %} **You're done!** CorralData will be available in Claude conversations. Claude will have access to all accounts your login can view. If your login has access to more than one account, confirm with Claude which one you're working in before running queries or creating widgets.\ \ See what you can do [after you connect](#after-you-connect) or explore more [usage examples.](/kb/mcp/usage-examples) We also recommend installing the [CorralData skill](#add-the-corraldata-skill-recommended) after you've connected. {% endhint %} {% endstep %} {% endstepper %} ### Add the CorralData skill (recommended) The connector gives Claude access to your data. The CorralData skill teaches Claude how to use it well: how to explore your schemas, write correct SQL, and read your boards and widgets. Installing it leads to faster, more accurate answers with less back-and-forth. It is optional, and only available on Claude clients that support skills. **To install it: Download the file below**, then in Claude go to **Customize**, then **Skills,** and click **+Add** and choose **Upload skill**. Select the downloaded file. Claude applies it automatically whenever a conversation involves your CorralData data. {% file src="/files/MlLdHDZ7vsLjggu2mbfP" %} *** ## Connecting to ChatGPT You'll add CorralData directly inside the ChatGPT web app. {% hint style="info" %} You'll need a **paid ChatGPT subscription** (Plus, Pro, or Team) to use custom MCP connectors. {% endhint %} {% stepper %} {% step %} **Enable Developer Mode** Log in to [ChatGPT](https://chatgpt.com/), click your profile name in the left sidebar, and select **Settings**. Navigate to **Connectors**, then **Advanced Settings**, and toggle on **Developer mode**. {% endstep %} {% step %} **Create a new connector** Return to **Connectors**. You should now see a **Create** button — click it. {% endstep %} {% step %} **Fill in the connection details** Enter the following values exactly as shown: | Field | Value | | ------------------- | -------------------------------- | | Name | CorralData | | MCP Server URL | `https://mcp.corraldata.com/mcp` | | Authentication | OAuth | | OAuth Client ID | `corral-mcp-client` | | OAuth Client Secret | *(leave empty)* | | {% endstep %} | | {% step %} **Authorize** Check the **I trust this application** checkbox and click **Create**. Complete the OAuth consent screen by selecting your organization and clicking **Allow**. CorralData will now appear in your connectors list. {% endstep %} {% step %} **Enable CorralData in chat** Open a new chat. Click the **+** icon in the message bar, then **More → Developer Mode → Add Sources**, and toggle on CorralData. You'll need to do this step each time you start a new chat where you want to use CorralData. {% hint style="success" %} **You're done!** CorralData will be available once enabled in a chat. Remember to turn it on at the start of each new conversation (Step 5 above). ChatGPT will have access to all accounts your login can view. If your login has access to more than one account, confirm with ChatGPT which one you're working in before running queries or creating widgets.\ \ See what you can do [after you connect](#after-you-connect) or explore more [usage examples.](/kb/mcp/usage-examples) {% endhint %} {% endstep %} {% endstepper %} *** ## Connecting to Claude Code {% hint style="info" %} If you sign in to Claude Code with your **Claude.ai account** and your organization has already added the CorralData connector (see [Connecting to Claude](#connecting-to-claude)), it is available in Claude Code automatically. Nothing else to do. {% endhint %} If you use Claude Code with a **direct API key**, add the server yourself: {% stepper %} {% step %} **Add the server** Run in your terminal: ```bash claude mcp add --transport http corraldata https://mcp.corraldata.com/mcp \ --client-id corral-mcp-client ``` Add `--scope user` to make it available in every project. {% endstep %} {% step %} **Log in** Start Claude Code, run `/mcp`, select **corraldata**, and complete the CorralData login in the browser window that opens. {% endstep %} {% endstepper %} *** ## Connecting to Codex {% stepper %} {% step %} **Add the server to your Codex config** Open `~/.codex/config.toml` and add: ```toml [mcp_servers.corraldata] url = "https://mcp.corraldata.com/mcp" [mcp_servers.corraldata.oauth] client_id = "corral-mcp-client" ``` No client secret and no callback port are needed. Make sure Codex is up to date; older versions do not support the `oauth` section. {% endstep %} {% step %} **Log in** Run in your terminal: ```bash codex mcp login corraldata ``` Complete the CorralData login in the browser window that opens, then confirm with `codex mcp list`. {% endstep %} {% endstepper %} *** ## After you connect ### Your first conversation Try asking: > "What databases and schemas are available in my CorralData account?" Your assistant will use the `list_schemas` tool to discover your data. From there you can explore further: > "Show me the tables in the public schema" > "Describe the customers table — what columns does it have?" > "Write a SQL query to find the top 10 customers by revenue this month" ### Understanding permissions What you can do depends on your role in CorralData: | Permission level | What you can do | | --------------------------- | ----------------------------------------------------------------------------------------------------------------------- | | **All authenticated users** | Explore schemas, tables, and relationships. Execute read-only SQL queries. View boards, widgets, filters, and datasets. | | **board.edit role** | All of the above, plus create and update boards and board filters. | | **widget.edit role** | All of the above, plus create and update widgets and datasets. | If you try an action you don't have permission for, your assistant will let you know. Contact your CorralData administrator to request additional roles. ### Tips for effective use * **Start with schema exploration** — Ask your assistant to list schemas and describe tables before writing queries. This helps it understand your data model and write accurate SQL. * **Use progressive disclosure** — Ask for a list of boards first, then drill into a specific one. This keeps responses concise. * **Be specific with SQL** — When asking for data, mention the table names and columns you're interested in. * **Leverage filters** — When listing boards or widgets, mention the name or keyword you're looking for to narrow results. # Usage Examples ## Usage Examples These examples show real conversations you can have with Claude or ChatGPT once the CorralData integration is connected. *** #### Example 1: Explore your data and run a query **Goal**: Understand your database structure and pull a specific metric. > **You**: What schemas and tables do I have available? Claude/ChatGPT calls `list_schemas` and `list_tables` to map out your data model and returns a summary. > **You**: Describe the appointments and providers tables Claude/ChatGPT calls `describe_tables` to retrieve column names, types, and relationships for both tables at once. > **You**: How are those two tables related? Claude/ChatGPT calls `get_relationships` filtered to those tables and shows the foreign key connections. > **You**: Write a query to show total appointment revenue by provider for the last 30 days, ordered by highest first Claude/ChatGPT uses the schema context to write accurate SQL and executes it with `execute_sql`, returning the results in a table. *** #### Example 2: Build a location performance dashboard **Goal**: Create a new board with widgets to compare performance across locations. > **You**: Create a new board called "Location Performance" Claude/ChatGPT calls `create_board` and returns the new board with its URL. > **You**: Add a KPI widget showing total revenue this month across all locations Claude/ChatGPT writes the SQL, validates it with `validate_widget_query`, then calls `create_widget` with a KPI chart type. > **You**: Now add a bar chart showing revenue by location Claude/ChatGPT creates a bar chart widget, placing it below the KPI. > **You**: Add a location filter so users can drill into a specific practice Claude/ChatGPT calls `create_board_filter` to add an interactive filter that connects to all widgets on the board. *** #### Example 3: Analyze and improve an existing dashboard **Goal**: Review what's on an existing board and fix an issue. > **You**: Show me all my boards Claude/ChatGPT calls `list_boards` and presents a summary with names and URLs. > **You**: What widgets are on the "Monthly Operations" board? Claude/ChatGPT calls `get_board` then `list_widgets` to show all widgets with their types and queries. > **You**: The "Avg Ticket Value" widget looks off. Show me its query Claude/ChatGPT calls `get_widget` to retrieve the full widget configuration and SQL. > **You**: It's including voided appointments — fix the query to exclude those Claude/ChatGPT updates the SQL, validates it with `validate_widget_query`, then calls `update_widget` to save the fix. *** #### Example 4: Investigate a metric drop **Goal**: Use natural language to dig into a performance issue. > **You**: I need to understand why our botox revenue dropped last month. What tables do we have related to treatments or services? Claude/ChatGPT calls `search_tables` with relevant keywords and returns matching tables. > **You**: Describe those tables — I need to understand the columns Claude/ChatGPT calls `describe_tables`, showing columns, types, and relationships. > **You**: What are the possible values in the treatment\_category column? Claude/ChatGPT calls `get_column_values` to retrieve distinct values so filters will be accurate. > **You**: Write a query comparing botox appointment volume and revenue month-over-month for the last 6 months Claude/ChatGPT writes and executes the query with `execute_sql`, returning a table you can analyze directly in the conversation. # Tools Reference ## Tools Reference The CorralData MCP Server provides 40 tools organized into eleven categories. All tools accept a `customer_name` parameter for multi-tenant environments. ### Schema Discovery Tools for exploring your database structure. No special roles required. #### list\_schemas List all available database schemas with table counts. | Parameter | Type | Required | Default | Description | | ---------- | ------ | -------- | ------- | --------------------------------------- | | jq\_filter | string | No | — | jq expression to transform the response | #### list\_tables List tables with brief metadata (description, row count, column count). | Parameter | Type | Required | Default | Description | | ------------ | ------ | -------- | ------- | --------------------------------------- | | schema\_name | string | No | — | Filter tables by schema | | jq\_filter | string | No | — | jq expression to transform the response | #### describe\_table Get full column-level detail for a single table including types, keys, and descriptions. | Parameter | Type | Required | Default | Description | | ----------------------- | ------- | -------- | ------- | ---------------------------------------- | | schema\_name | string | Yes | — | Schema name (e.g., `public`) | | table\_name | string | Yes | — | Table name (e.g., `orders`) | | include\_enums | boolean | No | true | Include enum/category values | | include\_sample\_values | boolean | No | false | Include up to 3 sample values per column | | jq\_filter | string | No | — | jq expression to transform the response | #### describe\_tables Batch describe up to 10 tables in one call. More efficient than calling `describe_table` multiple times. | Parameter | Type | Required | Default | Description | | -------------- | ------------------------------------ | -------- | ------- | --------------------------------------- | | tables | array of {schema\_name, table\_name} | Yes | — | Tables to describe (max 10) | | include\_enums | boolean | No | true | Include enum/category values | | jq\_filter | string | No | — | jq expression to transform the response | #### get\_relationships Get foreign key relationships between tables as a join graph. | Parameter | Type | Required | Default | Description | | ------------ | ------- | -------- | ------- | ---------------------------------------- | | schema\_name | string | No | — | Filter by schema | | table\_name | string | No | — | Filter by table (requires schema\_name) | | max\_results | integer | No | 500 | Maximum relationships to return (1–1000) | | jq\_filter | string | No | — | jq expression to transform the response | #### search\_tables Search for tables relevant to a natural language query using semantic search. | Parameter | Type | Required | Default | Description | | ------------ | ------- | -------- | ------- | ---------------------- | | query | string | Yes | — | Natural language query | | max\_results | integer | No | 5 | Maximum results (1–10) | #### get\_column\_values Get distinct values for a specific column. Useful for building WHERE clauses. | Parameter | Type | Required | Default | Description | | ------------ | ------- | -------- | ------- | ------------------------------------------- | | schema\_name | string | Yes | — | Schema name | | table\_name | string | Yes | — | Table name | | column\_name | string | Yes | — | Column name | | limit | integer | No | 50 | Max distinct values (1–100) | | search | string | No | — | Filter values by pattern (case-insensitive) | #### get\_query\_context All-in-one context package for writing SQL. Given a question, returns relevant tables with pruned columns, join graph, and query hints. | Parameter | Type | Required | Default | Description | | ----------- | ------- | -------- | ------- | ---------------------------------------- | | question | string | Yes | — | Natural language question about the data | | max\_tables | integer | No | 5 | Max tables to include (1–10) | *** ### SQL Execution Tools for running and validating SQL queries. No special roles required. #### execute\_sql Execute a read-only SQL query against the data warehouse. | Parameter | Type | Required | Default | Description | | ----------- | ------- | -------- | ------- | -------------------------------------------------------------------- | | sql\_query | string | Yes | — | The SQL query to execute | | date\_range | object | No | — | Optional `{start, end}` in YYYY-MM-DD format | | max\_rows | integer | No | 1000 | Max rows to return (1–10,000). Results exceeding this are truncated. | #### lint\_sql Lint a SQL query and optionally auto-fix formatting issues. | Parameter | Type | Required | Default | Description | | --------- | ------- | -------- | ---------- | --------------------------------------------------------------------------------- | | query | string | Yes | — | The SQL query to lint | | dialect | string | No | PostgreSQL | SQL dialect (PostgreSQL, Snowflake, Redshift, Databricks, MSSQL, MySQL, BigQuery) | | auto\_fix | boolean | No | true | Auto-fix formatting issues | #### validate\_widget\_query Validate whether a SQL query result shape is compatible with a widget type. **Requires `widget.edit` role.** | Parameter | Type | Required | Default | Description | | ------------ | --------------------- | -------- | ------- | -------------------------------------------------------------------------- | | widget\_type | string | Yes | — | Target widget type (e.g., `line-chart`, `number-wo-comparison`) | | columns | array of {name, type} | Yes | — | Columns in the query result. Types: `date`, `numeric`, `string`, `unknown` | | row\_count | integer | Yes | — | Expected number of rows | | query | string | No | — | SQL query to check for date filter placeholders | *** ### Boards Tools for managing dashboards. #### list\_boards List all boards for a customer. Returns summaries by default. | Parameter | Type | Required | Default | Description | | ------------- | ------------ | -------- | ------- | --------------------------------------- | | show\_details | boolean | No | false | Include board filters and widget list | | board\_ids | array of int | No | — | Fetch specific boards by ID | | jq\_filter | string | No | — | jq expression to transform the response | #### get\_board Get detailed information about a single board. | Parameter | Type | Required | Default | Description | | ------------------------ | ------- | -------- | ------- | --------------------------------------- | | board\_id | integer | Yes | — | Board ID | | include\_widgets | boolean | No | false | Include widget details | | include\_widget\_queries | boolean | No | false | Include SQL queries in widget details | | jq\_filter | string | No | — | jq expression to transform the response | #### create\_board Create a new board. **Requires `board.edit` role.** | Parameter | Type | Required | Default | Description | | --------- | ------ | -------- | ------- | --------------------------- | | name | string | Yes | — | Board name (must be unique) | #### duplicate\_board Duplicate a board, optionally to a different customer. Clones the board including all widgets, queries, and settings. Datasets are NOT copied — widget queries keep their original dataset references. Board filters are NOT copied. **Requires `board.edit` role.** | Parameter | Type | Required | Default | Description | | -------------------- | ------- | -------- | ------- | ---------------------------------------------------------------------------------------- | | board\_id | integer | Yes | — | ID of the board to duplicate | | display\_name | string | No | — | Name for the new board (auto-generated if omitted) | | target\_customer\_id | integer | No | — | Numeric customer ID for cross-customer duplication (use `list_customers` to find the ID) | | nav\_only | boolean | No | — | If true, the duplicated board is navigation-only | | parent\_board\_id | integer | No | — | Parent board ID for nested hierarchy | #### update\_board Update an existing board. Only provide fields you want to change. **Requires `board.edit` role.** | Parameter | Type | Required | Default | Description | | ----------------- | ------- | -------- | ------- | ---------------------------------- | | board\_id | integer | Yes | — | Board ID | | display\_name | string | No | — | New board name | | position | integer | No | — | Position in navigation | | nav\_only | boolean | No | — | Navigation-only board (no widgets) | | parent\_board\_id | integer | No | — | Parent board for hierarchy | *** ### Widgets Tools for managing charts, tables, and other visualizations on boards. #### list\_widgets List all widgets, optionally filtered to a specific board. | Parameter | Type | Required | Default | Description | | ---------------- | ------- | -------- | ------- | --------------------------------------- | | board\_id | integer | No | — | Filter to a specific board | | include\_queries | boolean | No | false | Include SQL queries | | jq\_filter | string | No | — | jq expression to transform the response | #### get\_widget Get full details of a single widget including its SQL query. | Parameter | Type | Required | Default | Description | | ---------- | ------- | -------- | ------- | --------------------------------------- | | widget\_id | integer | Yes | — | Widget ID | | jq\_filter | string | No | — | jq expression to transform the response | #### create\_widget Create a new widget on a board. **Requires `widget.edit` role.** | Parameter | Type | Required | Default | Description | | ------------- | ------- | -------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------- | | board\_id | integer | Yes | — | Board to add the widget to | | title | string | Yes | — | Widget title | | widget\_type | string | Yes | — | Visualization type (e.g., `number-wo-comparison`, `wide-bar-chart-wo-comparison`, `n-series-line-chart`, `uni-table-wo-comparison`) | | query | string | No | — | SQL query (required for data widgets) | | metric\_name | string | No | — | Metric name (e.g., "Revenue") | | format\_type | string | No | — | Value format: `money`, `percentage`, `time`, `value`, `text` | | tooltip\_text | string | No | — | Tooltip explaining the metric | | sort\_order | integer | No | — | Position on board (0 = first) | | grid\_width | string | No | — | Width: `1` (quarter), `2` (half), `4` (full) | | grid\_height | string | No | — | Height: `1` (short) to `4` (tall) | | preview\_only | boolean | No | false | Preview without saving | | *...and more* | | | | See full parameter list in API | #### update\_widget Update an existing widget. Only provide fields you want to change. **Requires `widget.edit` role.** | Parameter | Type | Required | Default | Description | | ------------- | ------- | -------- | ------- | -------------------------------------------- | | widget\_id | integer | Yes | — | Widget ID | | title | string | No | — | New title | | widget\_type | string | No | — | Change visualization type | | board\_id | integer | No | — | Move to different board | | sort\_order | integer | No | — | New position on board | | widget\_query | object | No | — | Update query settings (SQL, format, tooltip) | | *...and more* | | | | See full parameter list in API | #### bulk\_update\_widgets Update multiple widgets in parallel (up to 100). **Requires `widget.edit` role.** | Parameter | Type | Required | Default | Description | | --------- | ----------------------- | -------- | ------- | -------------------------------------------------------------------------------------------- | | updates | array of widget updates | Yes | — | List of widget updates (1–100). Each update supports the same parameters as `update_widget`. | *** ### Board Filters Tools for managing interactive filters on boards. #### list\_board\_filters List all board filters with pagination. | Parameter | Type | Required | Default | Description | | ---------- | ------- | -------- | ------- | --------------------------------------- | | page | integer | No | 1 | Page number | | per\_page | integer | No | 50 | Results per page (1–250) | | jq\_filter | string | No | — | jq expression to transform the response | #### get\_board\_filter Get full details of a single board filter including its options. | Parameter | Type | Required | Default | Description | | ---------- | ------- | -------- | ------- | --------------------------------------- | | filter\_id | integer | Yes | — | Filter ID | | jq\_filter | string | No | — | jq expression to transform the response | #### create\_board\_filter Create a new board filter. **Requires `board.edit` role.** | Parameter | Type | Required | Default | Description | | ------------ | ------------ | -------- | ------- | ----------------------------- | | name | string | Yes | — | Filter name | | filter\_type | string | Yes | — | Filter type | | param\_name | string | No | — | URL parameter name | | board\_ids | array of int | No | — | Boards this filter applies to | | options | array | No | — | Static filter options | | query | object | No | — | Dynamic filter query | #### update\_board\_filter Update an existing board filter. **Requires `board.edit` role.** | Parameter | Type | Required | Default | Description | | ------------ | ------------ | -------- | ------- | ------------------------- | | filter\_id | integer | Yes | — | Filter ID | | name | string | No | — | New name | | filter\_type | string | No | — | New filter type | | board\_ids | array of int | No | — | Update board associations | | options | array | No | — | Update filter options | | query | object | No | — | Update dynamic query | #### delete\_board\_filter Permanently delete a board filter. **Requires `board.edit` role.** | Parameter | Type | Required | Default | Description | | ---------- | ------- | -------- | ------- | ------------------- | | filter\_id | integer | Yes | — | Filter ID to delete | *** ### Datasets Tools for managing reusable SQL query definitions. #### list\_datasets List all datasets for a customer. | Parameter | Type | Required | Default | Description | | ------------- | --------------- | -------- | ------- | --------------------------------------- | | limit | integer | No | 100 | Max datasets to return (1–1000) | | schema\_names | array of string | No | — | Filter by schema names | | include\_sql | boolean | No | false | Include SQL queries | | jq\_filter | string | No | — | jq expression to transform the response | #### create\_dataset Create a new dataset. **Requires `widget.edit` role.** | Parameter | Type | Required | Default | Description | | --------------------- | ------ | -------- | ----------------- | ---------------------------------------------------------------------- | | name | string | Yes | — | Dataset name (must be unique) | | description | string | Yes | — | Description of the dataset | | query | string | Yes | — | SQL query that defines the dataset | | materialization\_type | string | No | not\_materialized | `not_materialized`, `materialized_as_view`, or `materialized_as_table` | #### update\_dataset Update an existing dataset. **Requires `widget.edit` role.** | Parameter | Type | Required | Default | Description | | --------------------- | ------- | -------- | ------- | ------------------------ | | dataset\_id | integer | Yes | — | Dataset ID | | name | string | No | — | New name | | description | string | No | — | New description | | query | string | No | — | New SQL query | | materialization\_type | string | No | — | New materialization type | *** ### Board & Widget Utilities Additional tools for layout control and visual QA. #### reorder\_board Set the widget order on a board atomically. Pass the complete ordered list of visible widget IDs. Requires board.edit. * board\_id (integer, required): ID of the board to reorder * widget\_ids (array of integer, required): Full ordered list of visible widget IDs #### screenshot\_widget Render a widget as an image, useful for visual QA after creating or updating it. No special roles required. * widget\_id (integer, required): ID of the widget to capture ### Data Apps Custom HTML/JS widgets that run SQL only through named, pre-registered queries. Each query must select from a data model via `use_dataset(N)` — not a raw `schema.table` — and can opt into board filters with a commented WHERE clause keyed to the filter's `param_name` (substituted server-side, the same mechanism native widgets use). Requires widget.edit. #### create\_data\_app Create a Data App widget rendered in a sandboxed iframe. Always preview first, fix warnings, then get user confirmation before persisting. * board\_id (integer, required): ID of the board to add the widget to * title (string, required): Widget title * body\_html (string, required): HTML/JS body rendered in the sandboxed iframe * queries (array of {name, sql}, required): Named SQL queries the app can run via runNamedQuery * preview\_only (boolean, default false): Preview without saving #### update\_data\_app Update a Data App's content, queries, or sizing. Requires widget.edit. * widget\_id (integer, required): ID of the data app widget * body\_html / body\_edits (string / array, optional): Full body, or targeted find/replace patches for small tweaks * queries (array, optional): Declarative — the submitted list replaces the full query registry ### Connected Services Tools for working with upstream services connected to the customer's data warehouse (ad platforms, EMRs, CRMs, etc). No special roles required to read; write actions require confirmation. #### list\_services List the upstream services connected for this customer — the source of truth for what has live data, and whether write-back access is authenticated. #### search\_service\_tools Search tools provided by connected third-party services by natural language query. * query (string, required): Natural language search for a connected service's tools #### call\_service\_tool Execute a connected-service tool by its exact name. Write actions require user confirmation — the first call returns a confirmation\_required result and only runs after approval. * name (string, required): Exact service tool name (use search\_service\_tools first) * arguments (object, optional): Arguments to pass to the tool * confirmed (boolean, default false): Set by the client after the user approves a write action ### AI Configuration Tools for reading prompt templates and steering AskCorral's behavior for a customer. #### list\_prompts List all available prompt templates with metadata. #### get\_prompt Get a prompt by name with optional arguments, returned as a rendered messages array. * name (string, required): Prompt name * arguments (object, optional): Arguments for the prompt #### set\_customer\_prompt Create or update the customer's AI custom-instructions prompt that steers AskCorral. Requires ai\_metadata.edit. Passing an empty string removes the prompt entirely. * content (string, required): Full prompt text to save ### Account Management #### list\_customers List the customer accounts the authenticated user has access to. Single-company users see one row; multi-company users and administrators see their full set. Use this to find the slug to pass as customer\_name on other tools. * name\_filter (string, optional): Keyword filter by name * include\_demo (boolean, default false): Include demo customer accounts *** ### Permissions Summary | Role | Tools | | ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | *All authenticated users* | All read-only tools: list/get boards, widgets, filters, datasets, all schema tools, execute\_sql, lint\_sql, get\_query\_context, get\_relationships, list\_customers, list\_services, search\_service\_tools, list\_prompts, get\_prompt, call\_service\_tool (write actions require confirmation), screenshot\_widget | | `board.edit` | create\_board, duplicate\_board, update\_board, create\_board\_filter, update\_board\_filter, delete\_board\_filter, reorder\_board | | `widget.edit` | create\_widget, update\_widget, bulk\_update\_widgets, validate\_widget\_query, create\_dataset, update\_dataset, create\_data\_app, update\_data\_app | | ai\_metadata.edit | set\_customer\_prompt | # Authentication The CorralData MCP Server uses OAuth 2.0 for authentication. You sign in once through your organization's identity provider, and the server handles token management automatically. ## How authentication works When you connect to CorralData from Claude, ChatGPT, Claude Code, Codex, or any other MCP client, the following happens: 1. **Your assistant redirects you** to your organization's login page 2. **You sign in** with your existing CorralData credentials 3. **You grant permissions** for the assistant to access CorralData tools on your behalf 4. **The assistant receives a token** and uses it for all subsequent tool calls 5. **Tokens refresh automatically** — you won't need to sign in again unless your session expires ### Client ID and client secret Every MCP client identifies itself to CorralData with the public OAuth client ID `corral-mcp-client`. There is **no client secret**: the client is a public OAuth client protected by PKCE (Proof Key for Code Exchange), which is the standard for desktop tools and command-line clients that cannot keep a secret. If a setup form requires a client secret, enter any value; it is not checked. The client ID only tells CorralData which application is asking. Your own login is what decides what data you can see. ## Roles and permissions What you can do through your assistant depends on the roles assigned to your account in CorralData. | Role | Access level | | ------------------------ | --------------------------------------------------------------------------------------- | | **board.edit** | Create, update, duplicate, and reorder boards; create, update, and delete board filters | | **widget.edit** | Create and update widgets, Data Apps, and datasets, and validate widget queries | | **ai\_metadata.edit** | Set or update the customer's AI custom-instructions prompt | | *Any authenticated user* | All read-only tools: schema exploration, SQL execution, viewing boards/widgets/datasets | Roles are collected from **all companies** you belong to — if you have `board.edit` in any company, you can use board editing tools across CorralData. ### Tool-to-role mapping | Tools | Required role | | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------- | | list\_boards, get\_board, list\_widgets, get\_widget, list\_board\_filters, get\_board\_filter, list\_datasets, list\_schemas, list\_tables, describe\_table, describe\_tables, get\_relationships, search\_tables, get\_query\_context, get\_column\_values, execute\_sql, lint\_sql, screenshot\_widget, list\_customers, list\_services, search\_service\_tools, call\_service\_tool (write actions require confirmation), list\_prompts, get\_prompt | *None (any authenticated user)* | | create\_board, duplicate\_board, update\_board, reorder\_board, create\_board\_filter, update\_board\_filter, delete\_board\_filter | board.edit | | create\_widget, update\_widget, bulk\_update\_widgets, validate\_widget\_query, create\_dataset, update\_dataset, create\_data\_app, update\_data\_app | widget.edit | | set\_customer\_prompt | ai\_metadata.edit | If you try an action you don't have permission for, your assistant will let you know. Contact your CorralData administrator to request additional roles. ## Security * Authentication uses the OAuth 2.0 Authorization Code flow with PKCE (S256), enforced for every login * The OAuth client is public by design: there is no shared secret to leak, and a client ID alone grants no access * All communication is encrypted over HTTPS * Tokens are validated server-side and have a limited lifetime * Signing out invalidates your session — no data is stored server-side # Privacy Policy The CorralData MCP Server integration is governed by the [CorralData Privacy Policy](https://corraldata.com/privacy). ### How your data is handled When you use CorralData through Claude or ChatGPT, here's what happens with your data: * **Authentication tokens** are used to verify your identity and permissions. Tokens are validated server-side and are never stored persistently. * **Queries and tool calls** are processed in real time and forwarded to the CorralData API on your behalf. The MCP server does not store query history or results. * **Query results** are returned directly to your Claude or ChatGPT conversation. They are not logged or retained by the MCP server. * **The server is stateless** — no user data, session data, or conversation history is stored between requests. ### What data does Claude or ChatGPT see? When you use CorralData tools through Claude or ChatGPT, the tool responses (schema metadata, query results, board/widget details) become part of your conversation. This data is subject to [Anthropic's usage policy](https://www.anthropic.com/legal/aup) for Claude, or [OpenAI's usage policy](https://openai.com/policies/usage-policies/) for ChatGPT. ### HIPAA compliance and queries involving PHI Whether the MCP integration is HIPAA compliant depends on the type of question you ask and whether your organization holds a BAA. Operational and aggregate questions — production, recare rates, referral volume, and similar rollups — don't return individual patient information, so they're safe to ask in Claude or ChatGPT. Questions that return patient-level detail (PHI) are different. That data passes through Claude or ChatGPT as part of your conversation. For that to be HIPAA compliant, your organization must have its own Business Associate Agreement (BAA) with the AI provider — Anthropic for Claude, or OpenAI for ChatGPT. CorralData's BAAs cover the in-app AskCorral experience; they do not extend to a personal Claude or ChatGPT account you connect to the MCP server. **If your organization doesn't hold its own BAA with that provider, ask patient-level questions inside CorralData instead. AskCorral runs under CorralData's existing BAAs with Anthropic and OpenAI, so the same question stays covered.** **Rule of thumb:** aggregates anywhere; patient-level data in CorralData unless you hold your own BAA with the AI provider. ### Third-party services The MCP server connects to: * **CorralData API** — to execute tools on your behalf * **Keycloak** (your organization's instance) — for authentication and token validation No data is shared with any other third-party services. ### Questions? For privacy-related questions, refer to the full [CorralData Privacy Policy](https://corraldata.com/privacy) or contact your organization's CorralData administrator. # Support ### Contact us For help with the CorralData MCP integration, reach out to our support team: **Email**: ### Common issues #### "You don't have permission to use this tool" Your CorralData account doesn't have the required role for that action. Read-only tools (querying data, viewing dashboards) are available to all users. Creating or editing boards and widgets requires the `board.edit` or `widget.edit` role. Contact your CorralData administrator to request access. #### "Could not connect to CorralData" * Check that your organization's CorralData instance is online * Try disconnecting and reconnecting the integration from Claude or ChatGPT's settings * If the issue persists, contact your CorralData administrator to verify the MCP server is running #### "Authentication expired" or sign-in prompts Tokens refresh automatically, but long idle periods may require you to sign in again. Simply follow the authentication prompt — your conversation context in Claude or ChatGPT is preserved. #### Query returns no results * Verify the table and column names using `describe_table` * Check if a date range filter is needed — some data is time-scoped * Try a simpler query first (e.g., `SELECT * FROM table LIMIT 5`) to confirm the table has data #### Results are truncated SQL results are capped at 1,000 rows by default to keep responses manageable. Use `LIMIT` in your SQL for precise control, or ask Claude/ChatGPT to increase the `max_rows` parameter (up to 10,000). ### Feature requests Have an idea for a new tool or improvement? Email with the subject line "MCP Feature Request". # Automations & Integrations Once CorralData MCP is connected to your AI assistant, you can set up recurring automations — so your data comes to you, rather than you having to ask for it. ### Automate with Slack (Claude only) With Claude Cowork and the Slack connector, you can schedule CorralData to run a report on a recurring cadence and post the results to a Slack channel automatically. #### What you'll need * Claude Desktop app with Cowork (paid plan: Pro, Max, Team, or Enterprise) * CorralData MCP connected to Claude (see [Getting Started](/kb/mcp/getting-started)) * Slack connected to Claude (see [Claude's guide on connecting Slack](https://support.claude.com/en/articles/11506255-get-started-with-claude-in-slack)) Once CorralData MCP and Slack are connected to Claude, follow the steps below to set up your first scheduled brief. {% stepper %} {% step %} #### Create a scheduled CorralData task in Cowork * Open the **Claude Desktop app** and go to **Cowork**. * Click **Scheduled** in the left sidebar, then **+ New task**. * Select **Set up manually**. * Fill in the following fields: * **Task name** — a short label for the task (e.g., "Monday performance brief") * **Description** — what the task is for * **Prompt** — the exact instructions Claude will follow each time it runs (see example prompts below) * **Frequency** — how often it should run * Click **Save**. {% endstep %} {% step %} #### Review your scheduled task Go to **Scheduled** in the Cowork sidebar to see all your scheduled tasks. From here you can edit, pause, run on demand, or delete any task. {% hint style="info" %} **Important:** Scheduled tasks only run while your computer is awake and the Claude Desktop app is open. If the app is closed when a task is due, Cowork will run it automatically the next time you open the app. Toggle on **Keep awake** in the task settings to allow your computer to stay on when the task is scheduled to run to avoid task completion delays. {% endhint %} {% endstep %} {% endstepper %} *** #### Example scheduled tasks to get started > **Monday performance brief** > > *A weekly summary of location performance posted to Slack every Monday morning.* > > Prompt: "Every Monday at 8:00 AM, query CorralData for last week's revenue across all locations, flag any locations that are up or down significantly week over week, and post a summary to #leadership." > **Monday growth brief** > > *A weekly summary of CAC, ROAS, and new-customer mix posted to Slack every Monday morning.* > > Prompt: "Every Monday at 8:00 AM, query CorralData for last week's blended ROAS, CAC by channel, and new-customer mix. Flag any channels where efficiency dropped week over week and post a summary to #leadership." > **Daily location drop alert** > > *A conditional alert that only fires when a location misses its target — no noise on good days.* > > Prompt: "Every day at 7:00 AM, check CorralData for each location's revenue compared to the prior week. If any location is down more than 10% week over week, post an alert to #ops with the location name, the drop percentage, and any context on what's driving it (e.g. lower booking volume, utilization)." {% hint style="success" %} This page will update as we add more ways to automate CorralData across your tools. Check back for new workflows, or email with a use case you'd like to see. {% endhint %}