→Constant (2 rows) |
| **Stream, Arranged, Index Lookup, Read** | Produces rows from either an existing relation (source/view/materialized view/table) or from a previous CTE in the same plan. A parent Fused Map/Filter/Project operator can combine with this operator.
There are four types of Get.
Stream indicates that the results are not arranged in memory and will be streamed directly.
Arranged indicates that the results are arranged in memory.
Index Lookup indicates the results will be looked up in an existing [arrangement]((/get-started/arrangements/#arrangements).
Read indicates that the results are unarranged, and will be processed as they arrive.
Arranged materialize.public.t |
| **Map/Filter/Project** | Computes new columns (maps), filters columns, and projects away columns. Works row-by-row. Maps and filters will be printed, but projects will not.
These may be marked as Fused Map/Filter/Project, which means they will combine with the operator beneath them to run more efficiently.
Map. Each row may also have less data, from the Project. There may be fewer rows, from the Filter. **Uses memory:** No | →Map/Filter/Project Filter: (#0{a} < 7) Map: (#0{a} + #1{b}) Appends the result of some (one-to-many) table function to each row in the input.
A parent Fused Table Function unnest_list operator will fuse with its child GroupAggregate operator. Fusing these operator is part of how we efficiently compile window functions from SQL to dataflows.
A parent Fused Map/Filter/Project can combine with this operator.
→Table Function generate_series(#0{a}, #1{b}, 1) Input key: (#0{a}) Both join operators indicate the join ordering selected.
Returns combinations of rows from each input whenever some equality predicates are true.
Joins will indicate the join order of their children, starting from 0. For example, Differential Join %1 » %0 will join its second child into its first.
The two joins differ in performance characteristics.
**Can increase data size:** Depends on the join order and facts about the joined collections. **Uses memory:** ✅ Uses memory for 3-way or more differential joins. |→Differential Join %1 » %0 Join stage %0: Lookup key #0{a} in %0 Groups the input rows by some scalar expressions, reduces each group using some aggregate functions, and produces rows containing the group key and aggregate outputs.
There are five types of GroupAggregate, ordered by increasing complexity:
Distinct GroupAggregate corresponds to the SQL DISTINCT operator.
Accumulable GroupAggregate (e.g., SUM, COUNT) corresponds to several easy to implement aggregations that can be executed efficiently.
Hierarchical GroupAggregate (e.g., MIN, MAX) corresponds to an aggregation requiring a tower of arrangements. These can be either monotonic (more efficient) or bucketed. These may benefit from a hint; see mz_introspection.mz_expected_group_size_advice. These may either be bucketed or monotonic (more efficient). These may consolidate their output, which will increase memory usage.
Collated Multi-GroupAggregate corresponds to an arbitrary mix of reductions of different types, which will be performed separately and then joined together.
Non-incremental GroupAggregate (e.g., window functions, list_agg) corresponds to a single non-incremental aggregation. These are the most computationally intensive reductions.
A parent Fused Map/Filter/Project can combine with this operator.
Distinct and Accumulable aggregates use a moderate amount of memory (proportional to twice the output size). MIN and MAX aggregates can use significantly more memory. This can be improved by including group size hints in the query, see mz_introspection.mz_expected_group_size_advice. Non-incremental aggregates use memory proportional to the input + output size. Collated aggregates use memory that is the sum of their constituents, plus some memory for the join at the end. | →Accumulable GroupAggregate Simple aggregates: count(*) Post-process Map/Filter/Project Filter: (#0 > 1) Groups the input rows, sorts them according to some ordering, and returns at most K rows at some offset from the top of the list, where K is some (possibly computed) limit.
There are three types of TopK. Two are special cased for monotonic inputs (i.e., inputs which never retract data).
Monotonic Top1.Monotonic TopK, which may give an expression indicating the limit.Non-monotonic TopK, a generic TopK plan.Each version of the TopK operator may include grouping, ordering, and limit directives.
Monotonic Top1 and Monotonic TopK use a moderate amount of memory. Non-monotonic TopK uses significantly more memory as the operator can significantly overestimate the group sizes. Consult mz_introspection.mz_expected_group_size_advice. | →Consolidating Monotonic TopK Order By #1 asc nulls_last, #0 desc nulls_first Limit 5 →Negate Diffs |
| **Threshold Diffs** | Removes any rows with negative counts. **Can increase data size:** No **Uses memory:** ✅ Uses memory proportional to the input and output size, twice. | →Threshold Diffs |
| **Union** | Combines its inputs into a unified output, emitting one row for each row on any input. (Corresponds to UNION ALL rather than UNION/UNION DISTINCT.) **Can increase data size:** No **Uses memory:** ✅ A Consolidating Union will make moderate use of memory, particularly at hydration time. A Union that is not Consolidating will not consume memory. | →Consolidating Union |
| **Arrange** | Indicates a point that will become an arrangement in the dataflow engine, i.e., it will consume memory to cache results. **Can increase data size:** No **Uses memory:** ✅ Uses memory proportional to the input size. Note that in the LIR / physical plan, Arrange/ArrangeBy almost always means that an arrangement will actually be created. (This is in contrast to the “optimized” plan, where an ArrangeBy being present in the plan often does not mean that an arrangement will actually be created.) | →Arrange Keys: 1 arrangement available, plus raw stream Arrangement 0: #0 →Unarranged Raw Stream |
| **With ... Return ...** | Introduces CTEs, i.e., makes it possible for sub-plans to be consumed multiple times by downstream operators. **Can increase data size:** No **Uses memory:** No | See Reading plans |
**Notes:**
- **Can increase data size:** Specifies whether the operator can increase the data size (can be the number of rows or the number of columns).
- **Uses memory:** Specifies whether the operator use memory to maintain state for its inputs.
**In decorrelated and optimized plans:**
The following table lists the operators that are available in the optimized plan.
- For those operators that require memory to maintain intermediate state, **Uses memory** is marked with **Yes**.
- For those operators that expand the data size (either rows or columns), **Can increase data size** is marked with **Yes**.| Operator | Description | Example |
| --- | --- | --- |
| **Constant** | Always produces the same collection of rows. **Can increase data size:** No **Uses memory:** No | Constant - ((1, 2) x 2) - (3, 4) Get materialize.public.ordered |
| **Project** | Produces a subset of the columns in the input rows. See also column numbering. **Can increase data size:** No **Uses memory:** No | Project (#2, #3) |
| **Map** | Appends the results of some scalar expressions to each row in the input. **Can increase data size:** Each row has more data (i.e., longer rows but same number of rows). **Uses memory:** No | Map (((#1 * 10000000dec) / #2) * 1000dec) |
| **FlatMap** | Appends the result of some (one-to-many) table function to each row in the input. **Can increase data size:** Depends on the table function used. **Uses memory:** No | FlatMap jsonb_foreach(#3) |
| **Filter** | Removes rows of the input for which some scalar predicates return false. **Can increase data size:** No **Uses memory:** No | Filter (#20 < #21) |
| **Join** | Returns combinations of rows from each input whenever some equality predicates are true. **Can increase data size:** Depends on the join order and facts about the joined collections. **Uses memory:** ✅ The Join operator itself uses memory only for type=differential with more than 2 inputs. However, Join operators need arrangements on their inputs (shown by the ArrangeBy operator). These arrangements use memory proportional to the input sizes. If an input has an appropriate index, then the arrangement of the index will be reused. | Join on=(#1 = #2) type=delta |
| **CrossJoin** | An alias for a Join with an empty predicate (emits all combinations). Note that not all cross joins are marked as CrossJoin: In a join with more than 2 inputs, it can happen that there is a cross join between some of the inputs. You can recognize this case by ArrangeBy operators having empty keys, i.e., ArrangeBy keys=[[]]. **Can increase data size:** Cartesian product of the inputs (\|N\| x \|M\|). **Uses memory:** ✅ Uses memory for 3-way or more differential joins. | CrossJoin type=differential |
| **Reduce** | Groups the input rows by some scalar expressions, reduces each group using some aggregate functions, and produces rows containing the group key and aggregate outputs. **Can increase data size:** No **Uses memory:** ✅ SUM, COUNT, and most other aggregations use a moderate amount of memory (proportional either to twice the output size or to input size + output size). MIN and MAX aggregates can use significantly more memory. This can be improved by including group size hints in the query, see mz_introspection.mz_expected_group_size_advice. | Reduce group_by=[#0] aggregates=[max((#0 * #1))] |
| **Distinct** | Alias for a Reduce with an empty aggregate list. **Can increase data size:** No **Uses memory:** ✅ Uses memory proportional to twice the output size. | Distinct |
| **TopK** | Groups the input rows by some scalar expressions, sorts each group using the group key, removes the top offset rows in each group, and returns the next limit rows. **Can increase data size:** No **Uses memory:** ✅ Can use significant amount as the operator can significantly overestimate the group sizes. Consult mz_introspection.mz_expected_group_size_advice. | TopK order_by=[#1 asc nulls_last, #0 desc nulls_first] limit=5 |
| **Negate** | Negates the row counts of the input. This is usually used in combination with union to remove rows from the other union input. **Can increase data size:** No **Uses memory:** No | Negate |
| **Threshold** | Removes any rows with negative counts. **Can increase data size:** No **Uses memory:** ✅ Uses memory proportional to the input and output size, twice. | Threshold |
| **Union** | Sums the counts of each row of all inputs. (Corresponds to UNION ALL rather than UNION/UNION DISTINCT.) **Can increase data size:** No **Uses memory:** ✅ Moderate use of memory. Some union operators force consolidation, which results in a memory spike, largely at hydration time. | Union |
| **ArrangeBy** | Indicates a point that will become an arrangement in the dataflow engine (each keys element will be a different arrangement). Note that if an appropriate index already exists on the input or the output of the previous operator is already arranged with a key that is also requested here, then this operator will just pass on that existing arrangement instead of creating a new one. **Can increase data size:** No **Uses memory:** ✅ Depends. If arrangements need to be created, they use memory proportional to the input size. | ArrangeBy keys=[[#0]] |
| **With ... Return ...** | Introduces CTEs, i.e., makes it possible for sub-plans to be consumed multiple times by downstream operators. **Can increase data size:** No **Uses memory:** No | See Reading plans |
**Notes:**
- **Can increase data size:** Specifies whether the operator can increase the data size (can be the number of rows or the number of columns).
- **Uses memory:** Specifies whether the operator use memory to maintain state for its inputs.
**In raw plans:**
The following table lists the operators that are available in the raw plan.
- For those operators that require memory to maintain intermediate state, **Uses memory** is marked with **Yes**.
- For those operators that expand the data size (either rows or columns), **Can increase data size** is marked with **Yes**.| Operator | Description | Example |
| --- | --- | --- |
| **Constant** | Always produces the same collection of rows. **Can increase data size:** No **Uses memory:** No | Constant - ((1, 2) x 2) - (3, 4) Get materialize.public.ordered |
| **Project** | Produces a subset of the columns in the input rows. See also column numbering. **Can increase data size:** No **Uses memory:** No | Project (#2, #3) |
| **Map** | Appends the results of some scalar expressions to each row in the input. **Can increase data size:** Each row has more data (i.e., longer rows but same number of rows). **Uses memory:** No | Map (((#1 * 10000000dec) / #2) * 1000dec) |
| **CallTable** | Appends the result of some (one-to-many) table function to each row in the input. **Can increase data size:** Depends on the table function used. **Uses memory:** No | CallTable generate_series(1, 7, 1) |
| **Filter** | Removes rows of the input for which some scalar predicates return false. **Can increase data size:** No **Uses memory:** No | Filter (#20 < #21) |
| **~Join** | Performs one of INNER / LEFT / RIGHT / FULL OUTER / CROSS join on the two inputs, using the given predicate. **Can increase data size:** For CrossJoins, Cartesian product of the inputs (\|N\| x \|M\|). Note that, in many cases, a join that shows up as a cross join in the RAW PLAN will actually be turned into an inner join in the OPTIMIZED PLAN, by making use of an equality WHERE condition. For other join types, depends on the join order and facts about the joined collections. **Uses memory:** ✅ Uses memory proportional to the input sizes, unless the inputs have appropriate indexes. Certain joins with more than 2 inputs use additional memory, see details in the optimized plan. | InnerJoin (#0 = #2) |
| **Reduce** | Groups the input rows by some scalar expressions, reduces each group using some aggregate functions, and produces rows containing the group key and aggregate outputs. In the case where the group key is empty and the input is empty, returns a single row with the aggregate functions applied to the empty input collection. **Can increase data size:** No **Uses memory:** ✅ SUM, COUNT, and most other aggregations use a moderate amount of memory (proportional either to twice the output size or to input size + output size). MIN and MAX aggregates can use significantly more memory. This can be improved by including group size hints in the query, see mz_introspection.mz_expected_group_size_advice. | Reduce group_by=[#0] aggregates=[max((#0 * #1))] |
| **Distinct** | Removes duplicate copies of input rows. **Can increase data size:** No **Uses memory:** ✅ Uses memory proportional to twice the output size. | Distinct |
| **TopK** | Groups the input rows by some scalar expressions, sorts each group using the group key, removes the top offset rows in each group, and returns the next limit rows. **Can increase data size:** No **Uses memory:** ✅ Can use significant amount as the operator can significantly overestimate the group sizes. Consult mz_introspection.mz_expected_group_size_advice. | TopK order_by=[#1 asc nulls_last, #0 desc nulls_first] limit=5 |
| **Negate** | Negates the row counts of the input. This is usually used in combination with union to remove rows from the other union input. **Can increase data size:** No **Uses memory:** No | Negate |
| **Threshold** | Removes any rows with negative counts. **Can increase data size:** No **Uses memory:** ✅ Uses memory proportional to the input and output size, twice. | Threshold |
| **Union** | Sums the counts of each row of all inputs. (Corresponds to UNION ALL rather than UNION/UNION DISTINCT.) **Can increase data size:** No **Uses memory:** ✅ Moderate use of memory. Some union operators force consolidation, which results in a memory spike, largely at hydration time. | Union |
| **With ... Return ...** | Introduces CTEs, i.e., makes it possible for sub-plans to be consumed multiple times by downstream operators. **Can increase data size:** No **Uses memory:** No | See Reading plans |
**Notes:**
- **Can increase data size:** Specifies whether the operator can increase the data size (can be the number of rows or the number of columns).
- **Uses memory:** Specifies whether the operator use memory to maintain state for its inputs.
Operators are sometimes marked as `Fused ...`. This indicates that the operator is fused with its input, i.e., the operator below it. That is, if you see a `Fused X` operator above a `Y` operator:
```
→Fused X
→Y
```
Then the `X` and `Y` operators will be combined into a single, more efficient operator.
See also:
- [`EXPLAIN PLAn`](/sql/explain-plan/)
---
## Isolation levels
An *isolation level* determines which effects of concurrent transactions are
visible to a transaction during its execution.
## Supported isolation levels
Materialize accepts the following isolation levels:
| Isolation level | Behavior in Materialize |
| --- | --- |
| [**Strict Serializable**](#strict-serializable) | **Default.** Provides serializability and linearizability. |
| [**Serializable**](#serializable) | Provides serializability but not linearizability. |
| Read Uncommitted, Read Committed, Repeatable Read | Accepted for compatibility; treated as Serializable. |
## Serializable
Serializable prevents the following three phenomena[^1]:
| Phenomenon | Description |
| --- | --- |
| **P1 (Dirty read)** | A transaction **T1** modifies a row; another transaction **T2** reads the row before **T1** commits. If **T1** rolls back, **T2** has read a row that was never committed. |
| **P2 (Non-repeatable read)** | A transaction **T1** reads a row; another transaction **T2** modifies or deletes that row and commits. If **T1** attempts to reread the row, it may see the modified value or discover that the row no longer exists.|
| **P3 (Phantom)** | A transaction **T1** reads a set of rows that match a specific search condition; another transaction **T2** inserts rows that also match the condition and commits. If **T1** repeats the read with the same search condition, it gets a different set of rows. |
[^1]: Phenomenon descriptions adapted from ISO/IEC 9075-2:1999 (E), §4.32
"SQL-transactions."
Serializable also guarantees that the result of concurrently executing
transactions is equivalent to some serial execution of those transactions. A
serial execution is one in which each transaction completes before the next one
begins. However, Serializable does not guarantee
[linearizability](https://jepsen.io/consistency/models/linearizable); that is,
it does not guarantee that the serial order matches the real-time order of the
transactions. For example, if transaction **T1** completes before transaction
**T2** begins in real time, the result may be equivalent to a serial execution
in which **T2** executes before **T1**.
Non-linearizable orderings are more likely to occur when querying indexes and
materialized views with large propagation delays. For example, suppose
transaction **T1** queries table `t` and is followed in real time by transaction
**T2**, which queries a computationally expensive materialized view `mv` defined
over `t`. If the two transactions execute sufficiently close together, `mv` may
not yet reflect the latest updates to `t` that **T1** observed, so **T2** may
not observe all rows visible to **T1**.
### Logical timestamp selection {#serializable-logical-timestamp-selection}
When using the [serializable](/reference/isolation-level#serializable)
isolation level, the logical timestamp may be arbitrarily ahead of or behind the
system clock. For example, at a wall clock time of 9pm, Materialize may choose
to execute a serializable query as of logical time 8:30pm, perhaps because data
for 8:30–9pm has not yet arrived. In this scenario, `now()` would return 9pm,
while `mz_now()` would return 8:30pm.
## Strict Serializable
Strict Serializable provides all the guarantees of Serializable isolation and
additionally guarantees
[linearizability](https://jepsen.io/consistency/models/linearizable). With
linearizability, the serial order matches the real-time order of the
transactions. For example, if transaction **T1** completes before transaction
**T2** begins in real time, the result is equivalent to a serial execution in
which **T1** executes before **T2**.
More concretely, suppose transaction **T1** queries table `t` and is followed in
real time by transaction **T2**, which queries a computationally expensive
materialized view `mv` defined over `t`. Under Strict Serializable, **T2** is
guaranteed to observe all rows visible to **T1**.
The linearizable guarantee applies only to transactions (including single-statement SQL queries, which are implicitly single-statement transactions), not to data written while ingesting from upstream sources.
- If a piece of data has been fully ingested from an upstream source, it is not
guaranteed to appear in the next read transaction. See [real-time
recency](#real-time-recency) for more details.
- However, once that data is included in the results of a read transaction, all
subsequent read transactions are guaranteed to see it.
### Logical timestamp selection {#strict-serializable-logical-timestamp-selection}
When using the [strict
serializable](/reference/isolation-level#strict-serializable) isolation level,
Materialize attempts to keep the logical timestamp reasonably close to wall
clock time. In most cases, the logical timestamp of a query will be within a few
seconds of the wall clock time. For example, when executing a strict
serializable query at a wall clock time of 9pm, Materialize will choose a
logical timestamp within a few seconds of 9pm, even if data for 8:30–9pm has not
yet arrived and the query will need to block until the data for 9pm arrives. In
this scenario, both `now()` and `mz_now()` would return 9pm.
### Real-time recency
Materialize offers a form of "end-to-end linearizability" known as real-time
recency. When using real-time recency, all client-issued `SELECT` statements
include at least all data visible to Materialize in any external source (i.e.,
sources created with `CREATE SOURCE` that use `CONNECTION`s, such as Kafka,
MySQL, and PostgreSQL sources) after Materialize receives the query. This is
what we mean by linearizable––the results are guaranteed to contain all visible
data according to physical time.
For example, real-time recency ensures that if you have just performed an
`INSERT` into a PostgreSQL database that Materialize ingests as a source, all of
your real-time recency queries will include the just-written data in their
results.
Note that real-time recency only guarantees that the results will contain _at
least_ the data visible to Materialize when we receive the query. We cannot
guarantee that the results will contain _only_ the data visible when Materialize
receives the query. For instance, the rate at which Materialize ingests data
might include additional data made visible after the timestamp we determined to
be "real-time recent." Another example is that, due to network latency, the
timestamp from the external system that we determine to be "real-time recent"
might be later (i.e. include more data) than you expected.
Because Materialize waits until it ingests the data from the external system,
real-time recency queries can have additional latency. This latency is
introduced by both the time it takes us to ingest and commit data from the
source and the time spent communicating with it to determine what data it has
made available to us (e.g., querying PostgreSQL for the replication slot's LSN).
**Details**
- Real-time recency is only available with sessions running at the [strict
serializable isolation level](#strict-serializable).
- Enable this feature per session using `SET real_time_recency = true`.
- Control the timeout for connecting to the external source to determine the
timestamp with the `real_time_recency_timeout` session variable.
- Real-time recency queries only guarantee visibility of data from external
systems (e.g., sources like Kafka, MySQL, and PostgreSQL). Real-time recency
queries do not offer any form of guarantee when querying Materialize-local
objects, such as [`LOAD GENERATOR`](/sql/create-source/load-generator/)
sources or system tables.
- Each real-time recency query connects to each external source transitively
referenced in the query. The more external sources that are referenced, the
greater the likelihood of latency caused by the network or ingestion rates.
- Materialize doesn't currently offer a mechanism to provide a "lower bound"
on the data we consider to be "real-time recent" in an external source.
Real-time recency queries return at least all data visible to Materialize
when our client connection communicates with the external system.
## Isolation levels and query latency
Strict Serializable provides stronger consistency guarantees but may have slower
reads than Serializable.
- **Strict Serializable** (the default) may need to wait for recent writes to
propagate through materialized views and indexes before serving a read, so
that the read reflects the real-time order of transactions.
- [Real-time recency](#real-time-recency) (available only with Strict
Serializable) introduces additional latency, since Materialize waits to
determine and ingest the latest data available in upstream sources before
serving the query.
- **Serializable** does not wait for writes to propagate. It reads a consistent
(but possibly slightly stale) snapshot, which avoids that latency at the cost
of linearizability. However, if a consistent snapshot is not available, the
query blocks until one becomes available.
## Setting isolation level
> **Tip:** Materialize recommends starting with the default Strict Serializable isolation
> level.
You can set the isolation level using the session-level [configuration parameter
`TRANSACTION_ISOLATION`](/sql/set/); for example:
```mzsql
SET TRANSACTION_ISOLATION TO 'STRICT SERIALIZABLE';
```
You can also set the isolation level for an explicit transaction block as part
of the [`BEGIN` statement](/sql/begin); for example:
```mzsql
BEGIN ISOLATION LEVEL STRICT SERIALIZABLE;
--- ...
--- ...
--- ...
COMMIT;
```
## Learn more
Check out:
- [PostgreSQL documentation](https://www.postgresql.org/docs/current/transaction-iso.html) for more information on
isolation levels.
- [Jepsen Consistency Models documentation](https://jepsen.io/consistency) for more information on consistency models.
---
## M.1 to cc size mapping
The following table provides a general mapping between cc and M.1 cluster sizes:
**cc to M.1:**
| cc Size | M.1 Size |
| --- | --- |
| 25cc | M.1-nano |
| 50cc | M.1-nano |
| 100cc | M.1-micro |
| 200cc | M.1-xsmall |
| 300cc | M.1-small |
| 400cc | M.1-small |
| 600cc | M.1-medium |
| 800cc | M.1-large or M.1-medium |
| 1200cc | M.1-1.5xlarge |
| 1600cc | M.1-2xlarge or M.1-1.5xlarge |
| 3200cc | M.1-8xlarge or M.1-4xlarge or M.1-3xlarge |
| 6400cc | M.1-16xlarge |
| 128C | M.1-32xlarge |
| 256C | M.1-64xlarge |
| 512C | M.1-128xlarge |
**M.1 to cc:**
| M.1 Size | cc Size |
| --- | --- |
| M.1-nano | 25cc |
| M.1-nano | 50cc |
| M.1-micro | 100cc |
| M.1-xsmall | 200cc |
| M.1-small | 300cc or 400cc |
| M.1-medium | 600cc or 800cc |
| M.1-large | 800cc |
| M.1-1.5xlarge | 1200cc or 1600cc |
| M.1-2xlarge | 1600cc |
| M.1-3xlarge | 3200cc |
| M.1-4xlarge | 3200cc |
| M.1-8xlarge | 3200cc |
| M.1-16xlarge | 6400cc |
| M.1-32xlarge | 128C |
| M.1-64xlarge | 256C |
| M.1-128xlarge | 512C |
Some sizes have multiple mappings. When converting between cc and M.1 sizing, we
recommend choosing the larger mapping size first.
---
## System catalog
Materialize exposes a system catalog that contains metadata about the running
Materialize instance.
The system catalog consists of several schemas that are implicitly available in
all databases. These schemas contain sources, tables, and views that expose
different types of metadata.
* [`mz_catalog`](mz_catalog), which exposes metadata in Materialize's
native format.
* [`pg_catalog`](pg_catalog), which presents the data in `mz_catalog` in
the format used by PostgreSQL.
* [`information_schema`](information_schema), which presents the data in
`mz_catalog` in the format used by the SQL standard's information_schema.
* [`mz_internal`](mz_internal), which exposes internal metadata about
Materialize in an unstable format that is likely to change.
* [`mz_introspection`](mz_introspection), which contains replica
introspection relations.
These schemas contain sources, tables, and views that expose metadata like:
* Descriptions of each database, schema, source, table, view, sink, and
index in the system.
* Descriptions of all running dataflows.
* Metrics about dataflow execution.
Whenever possible, applications should prefer to query `mz_catalog` over
`pg_catalog`. The mapping between Materialize concepts and PostgreSQL concepts
is not one-to-one, and so the data in `pg_catalog` cannot accurately represent
the particulars of Materialize.
---
## System clusters
## Overview
When you enable a Materialize region, various [system
clusters](/sql/system-clusters/) are pre-installed to improve the user
experience as well as support system administration tasks.
### `quickstart` cluster
A cluster named `quickstart` with a size of `25cc` and a replication factor of
`1` will be pre-installed in every environment. You can modify or drop this
cluster at any time.
> **Note:** The default value for the `cluster` session parameter is `quickstart`.
> This cluster functions as a default option, pre-created for your convenience.
> It allows you to quickly start running queries without needing to configure a cluster first.
> If the `quickstart` cluster is dropped, you must run [`SET cluster`](/sql/select/#ad-hoc-queries)
> to choose a valid cluster in order to run `SELECT` queries. A _superuser_ (i.e. `Organization Admin`)
> can also run [`ALTER SYSTEM SET cluster`](/sql/alter-system-set) to change the
> default value.
### `mz_catalog_server` system cluster
A system cluster named `mz_catalog_server` will be pre-installed in every
environment. This cluster has several indexes installed to speed up `SHOW`
commands and queries using the system catalog.
To take advantage of these indexes, Materialize will automatically re-route
`SHOW` commands and queries using system catalog objects to the
`mz_catalog_server` system cluster. You can disable this behavior in
your session via the `auto_route_catalog_queries`
[configuration parameter](/sql/show/#other-configuration-parameters).
The following characteristics apply to the `mz_catalog_server` cluster:
* You are **not billed** for this cluster.
* You cannot create objects in this cluster.
* You cannot drop this cluster.
* You can run `SELECT` or `SUBSCRIBE` queries in this cluster as long
as you only reference objects in the [system catalog](/reference/system-catalog/).
### `mz_probe` system cluster
A system cluster named `mz_probe` will be pre-installed in every environment.
This cluster is used for internal uptime monitoring.
The following characteristics apply to the `mz_probe` cluster:
* You are **not billed** for this cluster.
* You cannot create objects in this cluster.
* You cannot drop this cluster.
* You cannot run `SELECT` or `SUBSCRIBE` queries in this cluster.
### `mz_support` system cluster
A system cluster named `mz_support` will be pre-installed in every environment.
This cluster is used for internal support tasks.
The following characteristics apply to the `mz_support` cluster:
* You are **not billed** for this cluster.
* You cannot create objects in this cluster.
* You cannot drop this cluster.
* You cannot run `SELECT` or `SUBSCRIBE` queries in this cluster.
### `mz_system` system cluster
A system cluster named `mz_system` will be pre-installed in every environment.
This cluster is used for internal system jobs.
The following characteristics apply to the `mz_system` cluster:
* You are **not billed** for this cluster.
* You cannot create objects in this cluster.
* You cannot drop this cluster.
* You cannot run `SELECT` or `SUBSCRIBE` queries in this cluster.
## Related pages
- [`CREATE CLUSTER`](/sql/create-cluster)
- [`SHOW CLUSTER`](/sql/show-clusters)
- [`DROP CLUSTER`](/sql/drop-cluster)