questllens-explore-a-database

questllens-explore-a-database

Orientation, in order. Each step narrows the next; skipping ahead is how you end up querying a table that has no rows in the window you care about.

1. Inventory

list_tables — every table and materialized view, with the designated timestamp, partitioning strategy, and WAL flag. Read three things off it:

• Which tables have no designated timestamp. These are reference/dimension tables. SAMPLE BY and LATEST ON don't apply to them.
• The partition unit (DAY/HOUR/MONTH). It tells you the granularity at which a time predicate becomes cheap.
• Materialized views vs base tables. An MV is derived; don't reason about ingestion from it.

2. Meaning before structure

If the operator supplied a domain context, it is already in the tool descriptions — read it first. It's the only source that explains why a table exists.

Then describe_table per interesting table. Two optional flags earn their cost:

• with_time_range=true — min/max designated timestamp and total row count. Do this before writing any time filter. One cheap aggregate that tells you whether the table covers the period the user is asking about. Answering "there's no data" when you queried the wrong window is the most common avoidable error here.
• with_symbol_stats=true — distinct count per SYMBOL column against its declared capacity. Use it to learn cardinality (is device_id 12 devices or 400,000?) and to spot capacity overruns. It's a full scan — worth it once per table, not per question.

describe_table also surfaces dedup keys (UPSERT KEYS). A table with dedup enabled silently replaces rows matching those keys — so a duplicate-looking count isn't necessarily a data-quality problem.

3. Shape of the data

• get_sample_data — actual rows. Set latest=true to see the newest rows rather than the oldest, which is almost always what you want on a time-series table. Project with columns on wide tables; narrow with where when you need a specific slice.
• get_table_stats — null percentage and distinct count per column. On a large table pass sample_rows to bound it to the latest N rows; without it you are scanning everything.
• search_columns — when the user names a column and you don't know which table holds it.