> ## Documentation Index > Fetch the complete documentation index at: https://docs.insight.nobly.dk/llms.txt > Use this file to discover all available pages before exploring further. # Data sources > Author, test, schedule, and parameterize the queries that feed reporting dashboards in Nobly Insight. A **data source** is a named, saved query that returns the rows and columns a dashboard element displays. You author it once, and every element that needs that data points at it. Creating and editing data sources requires the **Manage Reporting Data Sources** permission — held by whoever builds reporting, whether a customer administrator, super user, or consultant. With **View Reporting Data Sources** only, you can see existing data sources but not change them. ## How a data source works A data source has two states: * **Definition** — the query you author and save. * **Materialized snapshot** — the result set, captured into a snapshot table when the data source **refreshes**. Dashboards read from the snapshot, not from your live tables, so a heavy query runs only at refresh time and dashboards stay fast. Reporting queries always run **read-only**, and only against the data an administrator has made available to reporting — never your own account's wider access. This keeps reporting isolated from the rest of the system. Queries also run in a non-blocking way, so a heavy reporting query never locks or slows the live tables it reads. A data source that declares [runtime parameters](#runtime-parameters) is the exception: it is **never materialized on a schedule**. Instead it runs live each time a dashboard opens, using the values the viewer supplies. ## Create a data source The editor is split into two panes: you author the **query** on the left and set its **configuration** — refresh schedule and run limits — on the right. Go to the reporting administration area and choose to add a new data source. The reporting administration data sources list, showing existing data sources with their freshness and a button to add a new one. Give it a clear, descriptive **name** — this is what you pick from when adding an element. Add an optional **description** so other builders recognize what it returns. Enter a `SELECT` query that returns the columns you want to report on. Keep it to the columns you need: the column names become the field names available to every element. Common table expressions (`WITH … SELECT`) are supported for structuring more complex queries. Click **Test SQL**. Nobly Insight validates the query, runs it read-only with a small preview cap, and shows you the resulting columns and a sample of rows — along with the objects the query referenced — so you can confirm the shape before saving. The two-pane data source editor, showing the name and description, the SQL editor with Test SQL, and the Configuration pane with the Enabled toggle, refresh schedule, preferred time, row cap, and blackout window. In the **Configuration** pane, set how the source refreshes — the **schedule**, an optional **row cap**, and, if needed, a **blackout window** (below). Leave **Enabled** on so the scheduler keeps it current. Save the data source. It is now selectable when designing dashboards. Until the first refresh, elements bound to it show an *Awaiting first run* freshness state — use **Refresh now** to materialize the snapshot immediately rather than waiting for the schedule. ## Runtime parameters A data source can declare **runtime parameters** — named values the viewer fills in when the dashboard opens. Reference each one in the SQL as `@Name`, matching the parameter's name. A parameterized source behaves differently from a scheduled one: **it runs live every time a dashboard opens**, with the viewer's values, and is **never materialized on a schedule**. Use parameters when the result genuinely depends on viewer input; use a plain scheduled source when everyone should see the same snapshot. Each parameter has: * **Name** — letters, digits, and underscores, starting with a letter. Used both as the label and as the `@Name` reference in SQL. * **Type** — **Text**, **Number**, **Date**, or **Yes/No**. This decides how the viewer is prompted for the value. * **Required** — whether the viewer must supply a value before the dashboard loads. * **Test values** — sample values used only when you click **Test SQL**; they are not saved. Add at least one parameter and the Configuration pane notes that the source now runs live when a dashboard opens — the schedule no longer applies. Remove all parameters to return it to scheduled refresh. ## Query rules To keep reporting safe and predictable, queries are validated before they run: Only read queries are allowed. Statements that change data or schema are rejected at validation. A few read-only constructs are also blocked for safety — linked-server and cross-database access, `OPENROWSET`, `EXEC`, and query hints among them — so if validation rejects a query it considers unsafe, the message names the construct to remove. Reporting can only read the data an administrator has made available to it. If your query references something reporting can't read, the test fails with a message pointing at what's missing — ask an administrator to make that data available to reporting, rather than changing your query. An administrator may pin reporting to a fixed set of source tables. When that allowlist is in place, a query that references any table not on it is rejected with a message naming the table (common table expressions are exempt). If you need a table that isn't allowed yet, ask an administrator to add it to the allowlist — and to make sure reporting can read it. Test results are capped to a small preview so a large query stays responsive while you author it. This preview cap is separate from the data source's row cap; the full result set is captured when the source refreshes. ## Refresh and freshness A scheduled data source refreshes automatically on its **schedule**, and you can also refresh it on demand with **Refresh now**. Each refresh re-captures the snapshot under the row cap you set; if the query's columns have changed since the last refresh, the snapshot table is rebuilt to match — the refresh still succeeds, and the element's freshness then shows *Schema drift detected*. * **Schedule** — pick how often the source refreshes. Presets range from **Every 15 minutes** through **Hourly** and **Every 4 hours** to **Daily** (at 02:00 or 06:00 UTC) and **Weekly** (Monday 02:00 UTC). Set a **Preferred time (UTC)** as advisory metadata, and use the **Enabled** toggle to pause scheduled runs. * **Row cap** — the maximum rows captured per refresh, up to 10,000. Leave at zero to use the server default. If a source has more rows than the cap, dashboards read only the captured rows and elements show a notice that totals, charts, and exports may be incomplete — raise the cap for sources that need the full set. * **Blackout window** — scheduled runs skip when they would fall inside this window (for example, during a nightly maintenance window). Set both a start and an end, or neither. **Manual refresh is not affected.** * **Freshness** — every dashboard element shows the state of its source: *Updated 2 hr ago* after a successful run, *Awaiting first run* before the first snapshot, *Stale* when overdue, *Schema drift detected*, *Last run failed*, or **Live** for a parameterized source that runs on demand. Changing a scheduled data source's **query or row cap** drops its current snapshot, so dashboards bound to it report the source as *stale* — with no data — until the next refresh. Click **Refresh now** after such an edit so its dashboards don't sit empty. Test the query before saving. After saving, the next scheduled run picks it up — or click **Refresh now** if you can't wait. ## Next Once a data source is saved and refreshed, you can surface it on a dashboard — see [Building dashboards](/reporting/building-dashboards).