Ad-hoc analysis

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

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.

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.

When to promote it to a report

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

This is not a live query layer for viewers. Built reports are pre-built static artifacts on purpose — viewer traffic never reaches your warehouse. Ad-hoc querying is for the people writing the analysis, not for the people reading the dashboard.