Queries and results
Understand SQL scope, result metadata, query hints, and execution boundaries.
Queries and results
A query expresses the data you want through SQL. RawTree evaluates it against the tables your credential can access. The returned rows are only one part of the outcome: types, statistics, hints, and errors explain what the engine did.
Database scope and permissions
Each Query API request selects a database within a cluster. An API key can supply a default database when the request omits one. That default resolves unqualified table names. It does not restrict the key to that database.
Permissions remain separate from name resolution. A permission-based key has cluster-wide access at its permission level. Database-role credentials use their grants to determine accessible databases, tables, and columns. See Access control.
Reads and supported changes
RawTree supports SQL for reads, writes, and database administration. RawTree Cloud and RawTree BYOC expose a narrower interface through the Query API. An API rejection describes that interface, not the database's complete SQL support. See ClickHouse compatibility and API scope.
The Query API accepts one statement per request. Read operations include
SELECT, WITH, EXPLAIN, and DESCRIBE.
The same endpoint also accepts a restricted set of writes and management
statements. Examples include INSERT INTO ... SELECT, table creation,
projection operations, and role management. Each operation has its own
permission and validation rules.
A statement that starts with SELECT is not necessarily read-only:
CACHE INTO creates a stored cache destination and requires write
management permission. The endpoint is not an unrestricted database console.
See the SQL reference and
Query API for supported forms.
Read the whole result
The default JSON response separates the data from execution information.
| Field | Meaning |
|---|---|
meta | Names and types of the result columns. |
data | Returned rows. |
rows | Number of returned rows. |
statistics | Execution time, rows read, and bytes read. Insert queries can also report rows written. |
hints | Optional runtime type-compatibility warnings about incompatible Dynamic values. |
A small result can require a large scan. LIMIT bounds the result rows, but
an aggregate or sort can still read substantial data before producing them.
Statistics help distinguish result size from work done.
Successful execution and intended meaning
A successful query can substitute NULL or default results for incompatible
values, or exclude them from an aggregate. Its hints field can report these
cases as runtime type-compatibility warnings.
A warning does not always mean that a result row was removed. Some operations can skip incompatible values without a warning. See Runtime type-compatibility warnings for the behavior of scalar functions, comparisons, and aggregates.
The query's intended type determines whether to convert values, select one stored type, or count incompatible values separately. Comparisons, grouping, ordering, and joins all depend on that choice. See Dynamic fields.
SQL result order requires an explicit ORDER BY. A table's sorting key does
not guarantee the order of returned rows.
Limits, streaming, and cancellation
Execution-time, result-size, and request-rate limits bound query work. The Limits reference describes the limits exposed by the service. Query settings and permitted overrides depend on the operation.
Other output formats return their native bodies instead of the default JSON
envelope. Streaming results can begin before execution finishes. An HTTP 200
at the start of a stream does not establish success: an exception or broken
connection can leave an incomplete result.
A supplied query_id identifies an execution for cancellation and correlation.
Closing the client connection does not confirm cancellation on the server.
Cancellation has its own result and permission checks. Cancelling a write does
not undo rows already written.
Observe before optimizing
EXPLAIN describes the query plan. Execution statistics show its actual work.
Query history and request logs help connect a request with its outcome.
Compare the same data range when assessing a change, since new data and caches
can change the result of a measurement.
Adaptive optimization can improve repeated workloads, but it does not choose the business meaning of mixed data.