Data App developer guide

These guides cover free form Data App layouts, filters, charts, detail panels, and light and dark themes across desktop and mobile screens.

These pages apply to any code-built app that mounts Astrato visualizations against a semantic layer: a Data App hosted by Astrato, or an app you host yourself. Start from the Data App quickstart or the externally hosted app quickstart. Where something applies to only one of them, the page says so. Workbooks, built in the Workbook editor, are not covered here.

For machine-readable page links, start at /llms.txt. Use the task table below and reuse documents already read in this task.

Start with your task

For a timed demo with prepared data and app setup, use the Demo quick track. It targets a small app in one pass and defines how to measure the under-one-minute goal. Use the full sequence below when preparation is still needed.

For an existing app, reuse its hosting setup, verified data bindings and presentation decisions. Read the guide for the part you are changing. For a new app, follow this order:

1. Explore the data. Inspect the semantic layer and execute bounded queries before deciding what the dashboard should show. Check metric meaning, grain, date coverage, category values, missing data and joins. Use the exploration checklist.
2. Reuse or save Business Questions. Read and execute existing questions that match your findings. Every required analysis needs a useful saved question; create missing questions during exploration and validation. Save them in the semantic layer through the Business questions guide. Retain the query evidence and identify any model changes that still need publication.
3. Use semantic and chart capabilities. Follow the capability checklist for every build. Use time intelligence, grouped dimensions and other advanced features where the task and verified data support them; record omissions and blockers in the brief.
4. Choose the presentation. Select a layout and style at the start of the dashboard design, then add components that support its reading and interaction flow. Consult an expert guide where useful. Start from Lead with a business story. Compose a dashboard page owns these choices; Choose a chart matches each question to a chart form.
5. Set up the app. Follow the matching quickstart above. If hosting is undecided, use Getting started with Data Apps before scaffolding.
6. Render a representative object. Follow Mounting objects and the Visualizations reference. Read the definition reference for creation and the operation reference for each type you need to change.
7. Extend the page. Use Layout and responsiveness and Theming, then add the filters, menus or exports your app needs from the table below. Use Querying the engine for custom queries.
8. Verify and build. Use Verifying an app and your chosen quickstart’s build instructions. For Astrato-hosted delivery, building and publishing are separate actions; see Data App publications for availability and publication.

Find an implementation guide

Page	Read it for
Compose a dashboard page	Question coverage, semantic/chart capabilities and page composition
Demo quick track	Preparing and timing a small app built in one pass
Business questions guide	Reusing or saving questions from exploration
Choose a chart	Matching questions and data to familiar and less common chart forms
Layout and responsiveness	Size, reflow, breakpoints, scrolling, grid behavior
Theming	Dark and light, colour tokens, chart palettes, fonts
Motion and texture	Optional ambient layer, navigation motion, backdrops, logo and favicon
Mounting objects	Definitions, operations, mount lifecycle, tables and charts
Querying the engine	Queries you build yourself, response shapes, model defects
Filters and selections	Selection groups, an apply bar, filter objects
Object menu	Context menus and available actions
Data dialogs and exports	Show as table, CSV, Excel, image capture
Rebuilding a Workbook	Carrying an existing Workbook’s settings across
Verifying an app	Checking rendering, queries and interactions
App limitations	What an app cannot do yet with the documented packages
Governed objects	Objects from stored questions; no figures computed in the app
Account review	A complete app built around one decision
Examples	Blueprints for whole dashboards, such as affordability and lending decisions

Decide the responsive strategy first

When the brief leaves page sizing open, start from the overview dashboard defaults.

Choose how the layout should adapt to the available space before writing the CSS. Use one strategy for the main layout so fixed proportions and reflow rules do not conflict.

Scale one composition. Define a reference size and scale lengths together to preserve the layout’s proportions. Use this for compositions such as a stage or roster.

Reflow in tiers. Reduce the number of columns and allow scrolling as space decreases. This keeps text and charts readable on smaller screens.

Layout and responsiveness has both in full.

Implementation requirements

Show only governed figures. Build each object from a stored business question and take every number from a governed measure. Do not compute figures in the app from query results; add the missing measure, flag or question to the layer. See Governed objects.

Use live model metadata. Resolve field keys from metadata and read category values and figures from query results. Keep field keys opaque. If a field is missing, fail only the object that needs it and list the available names; an empty chart could be mistaken for a valid result with no data. You can author headings and control labels separately.

One selection group. Charts, tables, your own queries and filter objects share a single group unless you are deliberately building a comparison. See Filters and selections.

Unmount hidden objects. display: none hides a chart that keeps querying on every filter change. Unmount it instead. See Mounting objects.

Give each chart host a non-zero size before mounting. height: 100% requires a parent with a resolved height. See Container sizing.

Decide what scrolls. When one object fills the window, such as a table, a list or a statement, the page must not scroll as well. When sections stack, the page scrolls and an object may scroll only inside a frame clearly shorter than the window. See Choose what scrolls.

Document omissions. When reproducing a Workbook, reference design or specification, list omitted parts and their reasons in the README and handoff message. For Workbooks, use the handoff checklist.

Common problems

• A zero-size chart host can prevent rendering. — Mounting objects
• A hidden but mounted object keeps querying on applied-selection changes. — Mounting objects
• A mounted object may still fail to render. Check ready for errors and timeouts outside the panel’s show/hide lifecycle chain. — Mounting objects
• A table frame that fills the window inside a page that also scrolls gives two scrollbars side by side, and the wheel moves whichever is under the pointer. — Layout and responsiveness
• A media query adds no selector specificity; later declarations of equal specificity can override it. — Layout and responsiveness
• An author display on a <dialog> beats the user-agent dialog:not([open]) rule, leaving closed dialogs visible and able to intercept clicks. — Layout and responsiveness
• A stored calculation goes in calculations, not measures; a stored dimension is an itemKey and a raw column is a fieldKey. An incorrect query can return HTTP 400. — Querying the engine
• An operation batch is not transactional; check each operation’s result for failures. — Mounting objects
• Local-development query responses omit engine SQL, query IDs and execution timings. — Querying the engine