Data sources

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.

​

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. Test query cost and refresh frequency with representative volumes; read-only access does not make an expensive query free of performance impact.

​

Approve a reporting source

Open Settings → Admin → Reporting → Allowed sources. Viewing the list requires reporting.datasources.view or reporting.sources.manage; adding and removing approvals requires reporting.sources.manage (also covered by reporting.admin).

1. Review whether the table or view is already approved and what data it exposes.
2. Choose Add source, enter its schema and object name, and add a description of its intended reporting use.
3. Save. The object must exist and be readable by reporting. If the product reports missing access, ask the person responsible for the data source to make it available, then retry.
4. Test the dependent reporting query and confirm the returned columns before publishing a dashboard.

Approval controls which source objects reporting queries may read. It does not grant every viewer direct access to those objects.

​

Remove approval deliberately

Identify the dependent data sources and dashboards before removing an approval. Revocation also invalidates existing snapshots backed by that approval; it is not limited to preventing the next refresh. Those dashboards can lose their data until their sources are corrected and refreshed. If removal reports an active run or another conflict, let that operation finish and retry. Check the final approval list and affected dashboards to confirm the outcome.

​

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.

​

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 source with at least one viewer-supplied value parameter runs live with that input. A source whose parameters are all query-based can still refresh on its schedule and serve a snapshot. The presence of a parameter alone does not determine whether execution is live. 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, Yes/No, or one of the two lookups, Document type group and Document type. 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.

​

Lookup parameters

A Document type group or Document type parameter is picked from a list instead of typed: the viewer sees the groups and types they are allowed to view, by name, and the selected id binds to @Name as a number. Nobody has to know an internal id, and a value outside the viewer’s own access is refused when the dashboard loads. Two options apply to lookups only:

• Allow several — the viewer can pick more than one. The picks bind as a JSON array of ids, which the SQL expands with OPENJSON. With a documents view an administrator has made available to reporting, holding one row per document and its document type id:
  SELECT DocumentTypeId, COUNT(*) AS Documents
  FROM dbo.Documents
  WHERE DocumentTypeId IN (SELECT CAST(value AS bigint) FROM OPENJSON(@DocTypes))
  GROUP BY DocumentTypeId
  
• Narrow by group parameter — on a document type parameter, names a document type group parameter of the same source. The viewer then only sees the types in the group they picked, and a type pick that no longer fits is cleared when the group changes. The group parameter itself does not have to appear in the SQL; it can exist purely to narrow the list.

An optional lookup left unpicked binds NULL, so a query can treat it as “all”: WHERE (@Group IS NULL OR DocumentTypeGroupId = @Group). The table and column names above are illustrative — the ids a lookup binds are the document type and document type group ids of Nobly Insight, and the view to match them against is whatever an administrator has made available to reporting.

​

Query rules

To keep reporting safe and predictable, queries are validated before they run:

​

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 source with viewer-supplied parameters that runs on demand.

​

Where to read next

Once a data source is saved and refreshed, you can surface it on a dashboard — see Building dashboards.