## TL;DR
Profile by aggregation, not by reading rows: have the agent compute null counts, distinct counts, and percentiles with warehouse-side aggregate queries per partition, and forbid full scans or row samples pulled into the agent. Billion-row profiling is a query-design problem, and the warehouse, not the agent, should do the counting.

```text
agent timed out when agent tried to profile a billion row table for null checks
```

## Use this when
- The check or run fails with this symptom: the agent's profiling run times out against the billion-row table.
- You are working on an agent profiling a billion-row table for null checks that times out and the failure repeats on the same data or configuration.
- You need the failing rows, rule, or stage isolated before changing thresholds or code.

## Not for this skill when
- Profiling a small table where direct reads are fine and aggregation design is overkill instead.
- The error text names a different tool, stage, or root cause. Match the verbatim error first and use that skill.

## Steps
1. Inspect the queries the agent issued and identify any that scan the full table or return row-level data. Verify: the offending query shapes are listed
2. Rewrite the profiling plan as aggregate queries: counts, null counts, min, max, and approximate distinct counts grouped by partition. Verify: the plan uses only aggregate queries with partition grouping
3. Run the aggregates partition by partition, storing each partition's profile before moving on. Verify: per-partition profiles are stored incrementally
4. Set a per-query timeout and a row budget in the agent's tool configuration so an unbounded query fails fast instead of hanging the run. Verify: query limits are configured in the tool layer
5. Assemble the table profile from the partition results and confirm it matches a warehouse-side summary query. Verify: the assembled profile matches the summary check

## Variant phrasings
### agent timed out profiling billion row table null checks
The verbatim billion-row phrasing.
### warehouse profiling aggregate queries null count partitions
The aggregate-query phrasing for partition profiling.
### agent profiling timeout full scan query design
The query-design phrasing for warehouse-side statistics.

Compatibility: Agent profiling jobs on Snowflake, BigQuery, and Spark tables at billion-row scale

## Why it happens
Agents default to reading data to reason about it, which collapses at billion-row scale. Profiling only needs statistics, and warehouses compute those statistics efficiently in place; the timeout is the symptom of moving computation to the wrong side of the connection.

## Edge cases / pitfalls
- Approximate distinct counts are fine for profiling. Exact counts are the expensive habit to break.
- Cache partition profiles and only re-profile changed partitions on later runs.

## Provenance

Resolved from the public thread: https://vectle.com/posts/pst_oXYip9ko9SLKSR-rB8FOvQ