Results and limits

Analytics streams a query result in batches. A client can begin processing rows before the whole report has been materialized, which is useful for tables and bounded exports.

Stream lifecycle

The first data batch includes the result column names and analytical data types. Later data batches omit repeated column metadata.

After all available rows have been sent, the server sends a final empty batch containing completion metadata:

whether the server row cap truncated the result;
the total number of rows actually returned;
elapsed execution time.

An empty result still produces the final batch, and its column metadata is included there if no data batch was sent.

Do not treat receipt of one data batch as query completion. A client should consume the stream until the final batch or an error.

Value types

Each result cell has one explicit value kind:

Analytical value	Returned representation
Null	Null
Boolean	Boolean
Signed integer	64-bit signed integer
Unsigned integer	64-bit unsigned integer
Floating point	Double
Text	String
Binary	Bytes
Decimal, date, time, timestamp, and other Arrow values	Exact display string

Rows and columns are positional. Read values against the column list from the first or final batch rather than assuming a fixed result schema.

Exact decimal values are deliberately strings at this boundary. Parse them with a decimal type in the client; do not route monetary totals through binary floating point.

Row limits and truncation

When no maximum is requested, the server returns at most 1,000 rows. A caller can request up to 10,000. A larger request is rejected rather than silently clamped.

The engine reads at most one row beyond the requested maximum so it can report truncation accurately. The final truncated value is true only when at least one matching result row was omitted by the server cap.

Analytics does not calculate the total number of matching rows automatically. The final row count is the number delivered, not the size of the uncapped result. Use a separate COUNT(*) query when an exact total is required.

This is separate from a SQL LIMIT:

final rows = minimum of SQL result and server maximum

If SQL itself limits the result to 100 and exactly 100 rows are produced, the server reports no truncation because it cannot claim that the SQL query would have returned more.

Batch and cell limits

External result batches contain at most 256 rows and approximately 2 MiB of encoded row data. A single string or binary cell may not exceed 1 MiB. A row too large for the batch limit, or a cell above its limit, ends the stream with a resource-exhausted error.

These transport batches are independent of DataFusion’s internal processing batches. Clients should not assume every batch has the same number of rows.

Execution timeout

Analytics applies 30-second bounds to catalog setup, query planning, query startup, and streamed execution. The streaming deadline covers the lifetime of query consumption rather than restarting for each batch.

A slow client can therefore contribute to reaching the overall execution deadline because the query remains active while the result is being consumed. Consume or cancel streams promptly.

Concurrent queries and memory

One server engine permits four analytics queries to be prepared or executed concurrently. Additional requests wait for a permit. A query holds its permit until its result is fully consumed or abandoned.

The shared analytical engine uses a 256 MiB fair memory pool and may spill intermediate data to a temporary directory, with up to 1 GiB of temporary spill storage. Large joins, sorts, and groups can still fail when they exceed available resources.

For reliable reports:

filter early;
select only columns the report uses;
aggregate before joining large child datasets when possible;
include an intentional SQL limit for detail views;
consume the stream continuously;
cancel work the user no longer needs.

Return to How Analytics works for catalog and permission behavior, or Writing analytical queries for examples.