> For the complete documentation index, see [llms.txt](https://docs.corraldata.com/kb/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.corraldata.com/kb/explore-your-data/data-apps.md).

# Data Apps

## 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.


---

# 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
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

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

```
GET https://docs.corraldata.com/kb/explore-your-data/data-apps.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

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