EXPLAIN TIMESTAMP displays the timestamps used for a
SELECT statement – valuable information to acknowledge query delays.
EXPLAINis not part of Materialize’s stable interface and is not subject to our backwards compatibility guarantee. The syntax and output of
EXPLAINmay change arbitrarily in future versions of Materialize.
You can select between
TEXT for the output format of
EXPLAIN TIMESTAMP. Non-text
output is more machine-readable and can be parsed by common graph visualization libraries,
while formatted text is more human-readable.
|TEXT||Format the explanation output as UTF-8 text.|
|JSON||Format the explanation output as a JSON object.|
The explanation is divided in two parts:
- Determinations for a timestamp
- Sources frontiers
Having a query timestamp outside the [read, write) frontier values of a source can explain the presence of delays. While in the middle, the space of processed but not yet compacted data, allows building and returning a correct result immediately.
Determinations for a timestamp
Queries in Materialize have a logical timestamp, known as query timestamp. It plays a critical role to return a correct result. Returning a correct result implies retrieving data with the same logical time from each source present in a query.
In this case, sources are objects providing data: materialized views, views, indexes, tables, or sources. Each will have a pair of logical timestamps frontiers, denoted as sources frontiers.
This section contains the following fields:
|query timestamp||The query timestamp value||
|oracle read||The value of the timeline’s oracle timestamp, if used.||
|largest not in advance of upper||The largest timestamp not in advance of upper.||
|since||The maximum read frontier of all involved sources.||
|upper||The minimum write frontier of all involved sources||
|can respond immediately||Returns true when the query timestamp is greater or equal to since and lower than upper||
|timeline||The type of timeline the query’s timestamp belongs||
A timeline value of
None means the query is known to be constant across all timestamps.
Every source has a beginning read frontier and an ending write frontier. They stand for a source’s limits to return a correct result immediately:
- Read frontier: Indicates the minimum logical timestamp to return a correct result (known as compaction)
- Write frontier: Indicates the maximum timestamp to build a correct result without waiting unprocessed data.
Each source has its own output section consisting of the following fields:
|read frontier||Minimum logical timestamp.||
|write frontier||Maximum logical timestamp.||
EXPLAIN TIMESTAMP FOR MATERIALIZED VIEW users;
Timestamp --------------------------------------------------------------------------- query timestamp: 1673618185152 (2023-01-13 13:56:25.152) + oracle read timestamp: 1673618185152 (2023-01-13 13:56:25.152) + largest not in advance of upper: 1673618185152 (2023-01-13 13:56:25.152) + upper:[1673618185153 (2023-01-13 13:56:25.153)]+ since:[1673618184000 (2023-01-13 13:56:24.000)]+ can respond immediately: true + timeline: Some(EpochMilliseconds) + + source materialize.public.raw_users (u2014, storage): + read frontier:[1673618184000 (2023-01-13 13:56:24.000)]+ write frontier:[1673618185153 (2023-01-13 13:56:25.153)]+
The privileges required to execute this statement are:
USAGEprivileges on the schemas that all relations and types in the query are contained in.
USAGEprivileges on all types used in the query.