trellum
Docs / Recommended workflow / Ad-hoc analysis

Ad-hoc analysis

Applies to: latest

Not every question deserves a report. Once a data source is configured, you can query it directly — from a script, a notebook, or an assistant writing one for you — with no report, no build, and no portal involved.

Query a configured source

This SQL example is for a database source. For files and APIs, use the framework's built-in readers or a Python adapter; document files need an explicit extraction step that returns a pandas DataFrame.

trellum query --source warehouse "
    select channel, sum(revenue) as revenue
    from orders
    where week = date_trunc('week', current_date - interval '7 days')
    group by 1
    order by revenue desc
"

warehouse is a source name from data-sources/config.yaml — omit --source when only one source is configured. Results print as an aligned table; --csv emits CSV instead, for piping into a notebook or a spreadsheet.

Note

This uses the same connection a built report uses. That is the point: an answer produced on Tuesday and a report shipped on Friday cannot disagree about where the data came from or how the source is configured.

From Python

The same sources, by the same names, from a script or a notebook:

from trellum import query, sources

sources()                                  # what data-sources/config.yaml configures
df = query("warehouse", "select channel, sum(revenue) as revenue from orders group by 1")

You get a pandas DataFrame back. It works from any subdirectory of the project — the project root is found by walking up to data-sources/config.yaml — and local file databases are opened read-only. None of it requires the report machinery.

Note

The full data API — listing configured sources, getting a connection for pandas.read_sql, file and API sources — is documented in the framework repository, alongside the code. This page only covers when to reach for it.

When to promote it to a report

To preserve the explanation of a finding, create a local analysis article with written conclusions and captured evidence. You can use unpublished reports in this project; reviewing the analysis locally does not publish or push it.

Move an ad-hoc script into reports/ when any of these is true:

  • Someone wants it on a schedule
  • More than one person needs to read the result
  • The number is going somewhere consequential and should be reviewed
  • You have written it more than twice

Until then, a script is the cheaper answer. See Two workflows for the promotion path.

What this is not

Ad-hoc querying is for the people writing the analysis, not for people reading a dashboard. Built reports compile their data at build time by default, so viewers do not need a warehouse connection. A report can opt into on-demand lookups with the framework's LiveDataSource; those queries run only when the report is served by a host that supports live queries (the portal or the local trellum serve server). Standalone files, share links, and email snapshots show the build-time snapshot and do not run live queries.