---
title: "Concepts & Glossary"
description: "The handful of nouns the dashboards docs lean on: query, widget, pin, dashboard, scope, snapshot, and publish mode, defined once and tied together."
section: "Dashboards"
canonical: "https://banksync.io/docs/dashboards/dashboards-concepts"
---

The rest of the dashboards docs reuse a small set of words: a *query*, a *widget*, a *pin*, a *scope*, a *snapshot*, a *publish mode*. This page defines each one in plain terms and shows how they fit together, so the other pages read cleanly. You do not need any of this to build a dashboard (the editor does it for you), but it helps when a feature behaves in a way that only makes sense once you know the model underneath.

> **Availability:** 'Dashboards are in beta and roll out per workspace. If you do not see Dashboards in your left navigation yet, it is not enabled for your workspace.'

[![A tour of BankSync dashboards showing the concepts on this page: the dashboards tree, the always-editable canvas, KPI tiles, charts and tables reading from feeds, and adding a widget from the library.](https://cdn.banksync.io/videos/dashboards-overview.poster.9dec43d3cf11a049.png)](https://cdn.banksync.io/videos/dashboards-overview.4bf1988e677f9209.mp4)

[Watch: A tour of BankSync dashboards showing the concepts on this page: the dashboards tree, the always-editable canvas, KPI tiles, charts and tables reading from feeds, and adding a widget from the library.](https://cdn.banksync.io/videos/dashboards-overview.4bf1988e677f9209.mp4)

## The three layers: query, widget, dashboard

The single most useful idea is that there are three separate things, stacked. Most of the time the editor collapses them into one screen, but they are distinct, and a few behaviors only make sense once you can tell them apart.

- **Query** — The data definition. Which feed (or bank, or static table) to read, and how to filter and
  summarize it. No colors, no chart, just rows.
- **Widget** — The visual. A query plus a chart kind and its styling: what goes on each axis, how numbers are
  formatted, the title. This is the thing you see and reuse.
- **Dashboard** — The page. A grid of placed widgets, plus dashboard-wide filters and a layout. Each placement is
  a "pin" of a widget.

Read it bottom to top: a **dashboard** holds **widgets**, and each widget reads from a **query**. Or read it as a sentence: a dashboard shows widgets, a widget draws a query, a query pulls your data.

| Layer     | Answers the question                  | Reusable?                         |
| --------- | ------------------------------------- | --------------------------------- |
| Query     | "Which numbers, and summarized how?"  | Yes, across many widgets.         |
| Widget    | "Drawn as what, and styled how?"      | Yes, pinned onto many dashboards. |
| Dashboard | "Arranged where, with which filters?" | It is the page itself.            |

> **Why the split matters:** 'Because the layers are separate, two widgets can share one query (they read the same data once, then draw it two different ways), and one widget can appear on several dashboards. Change the query and every widget that reads it updates; change the widget and every dashboard it is pinned to updates. That is the payoff of the model, and the reason "pin" and "duplicate" mean different things (next section).'

### Query

A **query** is a reusable, named pull of data: one source (a feed, a live bank, a small static table you type in, or two feeds combined) plus an optional pipeline that filters, summarizes, sorts, and limits the rows. It produces rows; it has no opinion about charts. Because a query is a first-class object in your workspace, two widgets pointing at the same query share a single read and (usually) a single round of summarizing.

You often will not create a query directly. When you point a widget at a feed in the inspector, BankSync authors a query for you behind the scenes. The [Binding data](/docs/dashboards/binding-data) guide is, in effect, the guide to authoring a query without ever using the word.

### Widget

A **widget** is the renderable unit: a query, plus a chart kind, plus styling. It is what you place, resize, and look at. A widget comes in one of two shapes:

- A **view** widget renders data: a chart, a KPI tile, a gauge, or a table. It carries a query (or an inline one-off data definition) and the field bindings that map columns onto the chart.
- A **control** widget emits state or an action instead of reading data: a filter control (like a date-range picker), a button, or a text input. It has no query of its own.

A view widget can also overlay a few **named datasets** alongside its main one, so a single chart can show, say, actual spend from one feed and a budget line from another at the same time. That is an advanced case; most widgets read exactly one query.

### Dashboard

A **dashboard** is the page: a grid layout, the widgets placed on it, the dashboard-wide filters in the header, an optional theme, and a few settings like a default time zone. The grid is twelve columns wide; each widget sits in a cell you can drag and resize. Mobile layouts are stacked into a single column automatically, so you only ever arrange the desktop layout.

![The dashboard editor's twelve-column grid canvas with three placed widget cells (a KPI tile, a chart, and a table), the first cell selected with a highlight ring](https://cdn.banksync.io/screenshots/dashboards/editor-canvas.440b6387416c1d58.png "A dashboard is a grid of placed widget cells: here a KPI, a chart, and a table sit side by side, each reading its own query underneath.")

## Pin vs. duplicate

When you add a widget you already built to another dashboard, you are choosing between two very different actions. The words matter.

|                     | Pin                                   | Duplicate                                  |
| ------------------- | ------------------------------------- | ------------------------------------------ |
| What you place      | The *same* widget again               | A *new, independent copy*                  |
| Edits flow through? | Yes, edit it once, every pin updates  | No, the copy is on its own from then on    |
| Good for            | One chart shown on several dashboards | A starting point you want to change freely |

**Pinning** places a reference to one widget. Internally each placement is a small "join" record that says "this widget, at this size, in this cell, on this dashboard," optionally with a per-placement title or filter override. The widget itself is stored once. So if you pin your "Monthly spend" chart onto three dashboards and later change its colors, all three update, because they are the same widget. BankSync tracks how many times a widget is used (its reference count) so it can warn you before you delete one that is pinned in several places.

**Duplicating** makes a brand-new widget that happens to start out identical. From the moment you duplicate, the two are unrelated: editing one never touches the other. Reach for duplicate when you want a variant ("same chart, but for the other account") that you intend to diverge.

> **Per-placement overrides:** 'A pin can carry small, local overrides without forking the whole widget: a different title for this dashboard, or a tweaked filter that applies only here. The shared widget stays shared; the override lives on the placement. This is how you reuse one chart but give it a dashboard-specific heading.'

## Scope: workspace vs. family

Every query reads at one of two **scopes**. Most reads are workspace-scoped; family scope is a capability for people who run several client workspaces.

- **Workspace** (the default): the query reads data from this workspace only, and only workspace members can see it.
- **Family**: the query rolls up across the child workspaces under a parent. For a [client portal](/docs/client-portals/setup) setup, that means one chart can total figures across every client workspace at once, instead of one chart per client.

If you only have a single workspace, scope never matters and you can ignore it: everything is workspace-scoped. Family scope is the lever that makes a multi-client roll-up possible, and it is the reason a number on a parent-workspace dashboard can be larger than what any single child workspace would show.

> **Family scope is a permission, not a default:** 'A family-scoped read aggregates across child workspaces, so it deliberately crosses a privacy boundary. It is opt-in per query and gated by your role. If you do not run a parent workspace with children beneath it, you will not see the option, and that is expected.'

## Snapshots and freshness

A **snapshot** is BankSync's internal, cached copy of the rows behind a source. You never see or manage snapshots directly; they exist so that two widgets reading the same data do not fetch it twice, and so a dashboard loads fast. The important part for you is how a snapshot stays honest:

- Every snapshot is stamped with a **version**. For a feed, the version tracks your last sync; for a live bank source, it is a short time window.
- A new version means the data may have changed, so the old snapshot is thrown out. **A stale snapshot is never served.** When your feed syncs, the next dashboard load reads the fresh copy.

This is why a dashboard does not need a refresh button: it re-reads its sources when it loads, and the snapshot version guarantees you are looking at current data, as current as your most recent sync.

| Source               | How fresh is it?                                                                       |
| -------------------- | -------------------------------------------------------------------------------------- |
| Feed                 | As fresh as your last sync (typically hourly or daily).                                |
| Live bank / provider | Read from the bank each time, the most up-to-the-moment, at the cost of a slower load. |

The one exception to "always current" is a **frozen** published link, covered next.

## Publish mode: frozen vs. live

When you publish a dashboard or a widget to share it, you pick one of two modes. This is the central trade-off of sharing, and it decides whether your shared link tracks new data.

- **Frozen (default)** — A snapshot taken at publish time is packaged and served from a fast edge cache. Nothing is read
  from your live data on the viewer's side. The link shows exactly what existed when you
  published, and will not change until you publish again.
- **Live** — Each viewer's load reads your current data through the normal data path. The link reflects new
  syncs as they happen, at the cost of a live read per view.

> **A frozen link does not update on its own:** 'This trips people up: a frozen public link is a point-in-time copy. New transactions, fresh balances, a re-synced feed, none of it appears on a frozen link until you re-publish. If you need a shared link that always shows current numbers, publish in live mode. If you want a stable, fast, point-in-time report (an end-of-month statement, say), frozen is the right choice.'

See [Publishing and sharing](/docs/dashboards/publishing-and-sharing) for how to publish, regenerate a link, and embed.

## Where things are created and where they live

A quick map of provenance, because a widget on your canvas did not necessarily come from you.

- **Origin** records who or what made a widget or dashboard: you, a built-in template, an AI agent (if you drive BankSync through one), or custom code. It is a label, not a permission.
- **A template** is a prebuilt dashboard you can instantiate against your own feeds. A dashboard made from a template remembers where it came from, which is what powers the "update available" prompt when the template is improved. See [Dashboard templates](/docs/dashboards/dashboard-templates).
- **Size presets** (small, medium, large, full-width) give a widget a sensible default footprint on the grid whether you place it in the app or through an agent, so the same widget lands the same size either way.

## A worked example, end to end

Suppose you want monthly spend on two dashboards, one of which also needs a client-specific heading.

1. You point a widget at your **Transactions** feed and set it to sum Amount by month. Behind the scenes this is a **query** (the data) wrapped in a **widget** (drawn as a bar chart).
2. You **pin** that widget onto your "Cashflow" dashboard. The placement records its cell and size.
3. You **pin** the same widget onto your "Board pack" dashboard, and give that placement a per-pin title override ("Spend, last 12 months"). Same widget, local heading.
4. Later you recolor the chart once. Both dashboards update, because both are pins of one widget.
5. For a client you instead **duplicate** the widget and switch its source to that client's feed. The copy is independent and will not change when you edit the original.
6. You **publish** the "Board pack" dashboard in **frozen** mode for a month-end snapshot. The shared link stays fixed until you re-publish, even as new transactions arrive.

That sequence touches every term on this page: query, widget, pin, override, duplicate, and frozen publish mode.

## Glossary at a glance

| Term            | In one line                                                                            |
| --------------- | -------------------------------------------------------------------------------------- |
| Query           | A reusable, named data pull: one source plus filter / summarize / sort. Produces rows. |
| Widget          | A query drawn as a chart, KPI, gauge, or table, with styling. The thing you reuse.     |
| View widget     | A widget that renders data and carries a query.                                        |
| Control widget  | A widget that emits a filter, button, or input, with no query.                         |
| Dashboard       | The page: a grid of pinned widgets plus dashboard-wide filters.                        |
| Pin             | A placement of an existing widget on a dashboard. Shared, edits flow through.          |
| Duplicate       | A new, independent copy of a widget. Diverges freely.                                  |
| Reference count | How many places a widget is used; warns you before deleting a shared one.              |
| Scope           | Workspace (this workspace only) or family (rolled up across child workspaces).         |
| Snapshot        | BankSync's internal cached rows for a source, versioned so stale data is never served. |
| Publish mode    | Frozen (point-in-time, edge-served) or live (reads current data per view).             |
| Origin          | Who made it: you, a built-in template, an AI agent, or custom code.                    |
| Template        | A prebuilt dashboard you point at your own feeds.                                      |

## Related guides

- [Dashboards & widgets overview](/docs/dashboards/dashboards-overview): the big picture and the editor.
- [Binding data](/docs/dashboards/binding-data): authoring a query without using the word.
- [KPI, table & gauge widgets](/docs/dashboards/kpi-table-gauge): the non-chart view widgets.
- [Dashboard templates](/docs/dashboards/dashboard-templates): start from a prebuilt dashboard.
- [Publishing and sharing](/docs/dashboards/publishing-and-sharing): frozen vs. live, links, and embeds.
- [Filters & cross-filtering](/docs/dashboards/filters-and-cross-filtering): control widgets and dashboard-wide filters.

[Learn to bind data](/docs/dashboards/binding-data)