Building a Dashboard with Charts

Aggregate your storage data, render it live on a page, and keep it fast. The dashboard pattern end to end.

A dashboard is a page backed by a few well-chosen queries: counts, sums, recent items, and grouped stats. This tutorial assembles one: data first, then rendering, then keeping it fast.

Step 1, Get the Data

Dashboards read. Never write. Build a function per metric (or one function returning an object with all of them):

  1. Counts: function_search with the hits out-pin (total matching documents), one per filtered query: open tasks, shipped orders, this week's signups.
  2. Recent items: function_search + query_sort_field on _meta.created descending + limit 10. See search tips.
  3. Grouped stats: aggregations where the storage supports them; for anything heavy, precompute counters on write instead (see performance below).

Return everything from one function as an object built with object_new_fields. One call, one payload for the page.

Step 2, Render the Page

  1. A state_page for the dashboard URL, scoped for your team (*loggedin or a custom scope).
  2. On load, run the metrics function from the render flow and pass results into state elements: number tiles (styled elements), a recent-items list (iterate the array), and your chart component.
  3. For real charts, mount a custom React component in the page and feed it the metrics object. See Components and RUAL Library for passing data to components.
  4. Want it live? Real-time search updates the metrics as documents change: worth it on shared boards, overkill on quiet data (see real-time vs polling).

Step 3, Keep It Fast

  • Cache the metrics function with a cache_key on function_search and a short TTL via Redis. The dashboard loads instantly even with thousands of documents. See caching patterns.
  • Precompute counters on write: increment a stats document on each create (mutations_increment_by_field) instead of counting at read time; reads become a single function_get_document.
  • Avoid dashboard-side loops. If the page needs per-item computation, do it in the function with array_map, not in the render.
  • Watch out for the aggregation traps in Common Pitfalls.

    • Checklist

    • One metrics function returning one object.
    • Sort + limit on every "recent" list.
    • Cache key on expensive searches; counters for hot stats.
    • Scope set intentionally (no accidental *public dashboards).

    Next Steps

    Components Mounting custom React components in RUAL pages. Common Blueprint Patterns Caching and transformation recipes for the metrics function. Storage Examples Data models that aggregate well.

    Frequently asked

    How do I build a dashboard page in RUAL?

    Build one function that gathers every metric, counts via the hits out-pin of function_search, recent items via a sort on _meta.created with a limit, grouped stats via aggregations, and return everything as one object built with object_new_fields. The page runs that function on load and passes the results into state elements or a chart component.

    How do I show charts on a RUAL page?

    Mount a custom React component in the page and feed it the metrics object. Number tiles and recent-items lists can be plain state elements; real charts go through the component.

    How do I keep a RUAL dashboard fast?

    Cache the metrics function with a cache_key on function_search and a short TTL in Redis, precompute counters on write with mutations_increment_by_field instead of counting at read time, and do per-item computation in the function with array_map rather than in the render.

    Was this page helpful? Tell us what to improve · RUAL Docs is an integral component of the RUAL ecosystem