Run SQL query
run_sqlRun a read-only SELECT against the FactIQ data warehouse, scoped to one schema — the power tool for joins, pivots and aggregation.
Read-only role, 30s statement timeout, with FactIQ's query transforms and
series-metadata enrichment. Resolve ids from series before filtering
data_points. auto_retry=true opts into a server-side reviser on zero
rows. See the factiq://guide/sql resource.
Returns at most 50 rows. If the query matches more, the result is flagged
"truncated": true — that is your cue to aggregate or compute in SQL
(GROUP BY, date_trunc, a SUM/AVG/rank/ratio) and return that, NOT to try
to fetch the raw rows. A chart or a summary needs the aggregated result, and
large raw results don't fit in context anyway.
Year-over-year and other period comparisons must join on the calendar
period (date_trunc('month', prior.time) = date_trunc('month', cur.time) - interval '1 year' — the stored day of the month varies by source, so never
compare exact dates), never on a row offset such as
LAG(value, 12) OVER (ORDER BY time): a series with one missing month
compares the wrong periods for the twelve rows after the gap (LEAD: the
twelve before it) and the numbers still look plausible. For one series prefer get_series with transform. When
the result carries a coverage_note, the rows have periods with no
observation (listed in missing_periods, per series): name them in the
answer, do not interpolate, and label any aggregate that spans them as
partial.
page is the one exception and works only on the nasa_fires schema, where
a row is a single fire detection that belongs to no series and so cannot be
aggregated into one. Each page holds 50 rows; the answer carries page and
has_more, and you read the next block with page=2, page=3 and so on.
Give the query an ORDER BY, otherwise Postgres may return the same row on
two pages and never return another. Still prefer a count or a total when
that answers the question — paging through thousands of detections does not.
Runs through FactIQ's read-only database role, which rejects any attempt to modify data (INSERT/UPDATE/DELETE/DROP/…).
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| sql | Yes | ||
| page | No | ||
| schema | Yes | ||
| explore | No | ||
| question | No | ||
| auto_retry | No |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||