> ## Documentation Index
> Fetch the complete documentation index at: https://tinyanalytics.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Custom Analytics Dashboards

> Build site or organization dashboards from reusable templates and read-only SQL cards, with a shared date range and drag-and-drop layout.

Custom dashboards turn read-only SQL queries into reusable charts. Build one for a single site or compare selected sites across an organization, then use one date picker to update every card.

## Choose a dashboard scope

<Tabs>
  <Tab title="Site dashboard">
    A site dashboard queries one site's analytics. Its cards use the same site-scoped virtual tables as the [SQL query builder](/docs/sql-analytics-query-builder), so you do not add a `site_id` filter.

    Start from a blank dashboard or use a template:

    * **Traffic overview** — 6 cards
    * **Content** — 4 cards
    * **Engagement** — 5 cards
  </Tab>

  <Tab title="Organization dashboard">
    An organization dashboard compares sites you can access in the active organization. Each card can use **All accessible sites** or an explicit subset of up to 50 sites.

    Start from a blank dashboard or use a template:

    * **Portfolio traffic** — 8 cards
    * **Content across sites** — 5 cards
    * **Live & engagement** — 5 cards

    The SQL editor scopes `scoped_events` to the selected sites. Add `site_id` to `SELECT` and `GROUP BY` when you want one series or row per site; the dashboard maps those IDs to site names in the visualization.
  </Tab>
</Tabs>

<Note>
  Organization dashboards respect site access for every viewer. If a dashboard includes sites someone cannot access, tinyanalytics hides those sites and shows how many were omitted without revealing their IDs or names.
</Note>

## Build a dashboard card

<Steps>
  <Step title="Create or open a dashboard">
    Open **Dashboards** at the site or organization level. Choose a template for a working set of cards, or start blank.
  </Step>

  <Step title="Write the query">
    Add a card and write a read-only `SELECT` against the available scoped tables. The preview shows the returned columns as you work.
  </Step>

  <Step title="Choose a visualization">
    Pick a line, area, bar, stat, horizontal bar, pie, map, calendar, or table visualization.
  </Step>

  <Step title="Map the result columns">
    Choose which query columns provide the X axis, value, label, and series. The required mapping changes with the visualization.
  </Step>

  <Step title="Arrange and save">
    Drag cards to move them, resize them from the edge, then save the dashboard. The dashboard records the layout, queries, mappings, selected site scopes, and creator.
  </Step>
</Steps>

## Which visualization fits your query?

| Visualization            | Best for                               | Reads                                                      |
| ------------------------ | -------------------------------------- | ---------------------------------------------------------- |
| **Line / area / bar**    | a value over time or across categories | an X column, one or more Y columns, and an optional series |
| **Stat**                 | a single headline number               | the first numeric value, with an optional label            |
| **Horizontal bar / pie** | a ranked breakdown                     | a label and a value; the long tail rolls into **Other**    |
| **Map**                  | values by country                      | ISO country codes and a value                              |
| **Calendar**             | activity by day                        | a date and a daily value                                   |
| **Table**                | raw rows                               | any columns, sortable and paginated                        |

## How do cards follow the date range?

Cards respond to the dashboard's global date picker and time bucket automatically. To bucket a time series by the selected granularity, use `{{bucket}}` in your SQL. tinyanalytics replaces it with the matching hour, day, week, or month interval before the query runs.

```sql theme={null}
SELECT
  toStartOfInterval(timestamp, INTERVAL {{bucket}}) AS bucket,
  count() AS pageviews
FROM scoped_events
WHERE type = 'pageview'
GROUP BY bucket
ORDER BY bucket
```

Leave the date range out of a query only when the card should read across all retained data.

## Who can edit an organization dashboard?

Any organization member can create a dashboard using only sites they can access. The organization's owners and admins, plus the dashboard's creator, can edit or delete it. The creator's name appears on the dashboard so teammates know who owns its definition.

<Warning>
  An organization query that calculates users across several sites can produce different semantics depending on the SQL. Use the built-in templates when you want the same **sum of per-site users** used by the [organization overview](/docs/organization-analytics-overview), where a person visiting two sites counts once on each site.
</Warning>

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Do I have to set a date range on every dashboard card?">
    No. Cards follow the dashboard's global date picker and time bucket automatically. If a query deliberately leaves the range out, that card reads across all retained data.
  </Accordion>

  <Accordion title="How do I compare sites in one chart?">
    Create an organization dashboard, scope the card to **All accessible sites** or a selected subset, and include `site_id` in the query's `SELECT` and `GROUP BY`. Map `site_id` as the series; the dashboard displays the corresponding site names.
  </Accordion>

  <Accordion title="What happens when a viewer cannot access every selected site?">
    tinyanalytics removes the inaccessible sites from that viewer's results and shows how many sites were hidden. It does not reveal their IDs or names.
  </Accordion>

  <Accordion title="Can I publish an organization dashboard publicly?">
    No. Organization dashboards stay inside the organization and follow each viewer's site permissions. Use [public dashboards](/docs/public-analytics-dashboards) for the supported site-level sharing options.
  </Accordion>
</AccordionGroup>

## Verify

<Check>
  Change the dashboard date range and confirm every time-scoped card refreshes. For an organization card, compare the site names shown with the selected scope and confirm a teammate with narrower access sees only their permitted sites.
</Check>

## Related

<Columns cols={2}>
  <Card title="Organization overview" icon="layer-group" href="/docs/organization-analytics-overview">
    Read the built-in portfolio view.
  </Card>

  <Card title="SQL query builder" icon="database" href="/docs/sql-analytics-query-builder">
    Write and test the queries your cards run.
  </Card>

  <Card title="Metric definitions" icon="ruler" href="/docs/analytics-data-dictionary">
    Understand the events and properties you can query.
  </Card>

  <Card title="Public dashboards" icon="share-nodes" href="/docs/public-analytics-dashboards">
    Share a supported site-level dashboard.
  </Card>
</Columns>


## Related topics

- [Embed an Analytics Dashboard](/docs/embed-analytics-dashboard.md)
- [Web Analytics Dashboard](/docs/web-analytics-dashboard.md)
- [Public Analytics Dashboards](/docs/public-analytics-dashboards.md)