System-Tables on Opensource internals

ClickHouse System Tables Are Storages That Generate Their Own Rows

Jay Hubbert — Sat, 24 Oct 2026 09:00:00 +0000

TL;DR: system.parts is not a view over a table. It is an IStorage attached to the system database, and every query against it builds a new source object that walks the catalog and emits rows. Two tricks make that affordable: a column mask (only the columns you asked for are ever computed) and a filter split (your WHERE is pushed down into the enumeration, so a condition on database prunes the walk itself).

The obvious way to implement system.parts is to make it a view: a table in the system database that runs a query against the catalog when you read it. Postgres does roughly this with pg_class and friends.

ClickHouse does something different, and the difference is instructive. system.parts is a full IStorage, registered in the system database like any other table. When you SELECT from it, the query planner asks the storage for a reading step, and the reading step builds a source object that walks the catalog and produces blocks.

The consequences of that choice ripple through the whole design:

The system table is a real table in system.tables, with a real ColumnsDescription, a real engine name, a real SHOW CREATE TABLE.
The WHERE clause can be pushed into the enumeration.
The columns you do not select are never computed.
Every query sees fresh data, because the source is built per query.

Attaching a system table

System tables are attached at startup by attachSystemTables.cpp. The attachment helper is small and does exactly three things: make a StorageID, construct the storage, and attach it.

 cpp
 
 
// src/Storages/System/attachSystemTablesImpl.h:19
template<typename StorageT, bool with_description, typename... StorageArgs>
void attachImpl(ContextPtr context, IDatabase & system_database, const String & table_name, std::string_view comment, StorageArgs && ... args)
{
 chassert(comment.size() > 15);
 chassert(system_database.getDatabaseName() == DatabaseCatalog::SYSTEM_DATABASE);

 auto table_id = StorageID::createEmpty();
 String path;
 if (system_database.getUUID() == UUIDHelpers::Nil)
 {
 /// Attach to Ordinary database.
 table_id = StorageID(DatabaseCatalog::SYSTEM_DATABASE, table_name);
 }
 else
 {
 /// Attach to Atomic database.
 /// NOTE: UUIDs are not persistent, but it's ok since no data are stored on disk for these storages
 /// and path is actually not used
 table_id = StorageID(DatabaseCatalog::SYSTEM_DATABASE, table_name, UUIDHelpers::generateV4());
 DatabaseCatalog::instance().addUUIDMapping(table_id.uuid);
 path = DatabaseCatalog::getStoreDirPath(table_id.uuid);
 }

 std::shared_ptr<StorageT> storage;
 if constexpr (with_description)
 storage = std::make_shared<StorageT>(table_id, StorageT::getColumnsDescription(), std::forward<StorageArgs>(args)...);
 else
 storage = std::make_shared<StorageT>(table_id, std::forward<StorageArgs>(args)...);

 /// Set the comment on the storage before attaching it, so that we neither look the table back up in
 /// `DatabaseCatalog` nor copy its whole metadata (including the full `ColumnsDescription`) an extra time.
 storage->setInMemoryMetadataComment(String(comment));

 system_database.attachTable(context, table_name, storage, path);
 registerSystemTableDocumentationSource(table_name, ATTACHED_SYSTEM_TABLE_DOCUMENTATION_SOURCE, comment);
}

So system.parts is literally a StorageSystemParts object living in the system database. SELECT * FROM system.parts is a SELECT against a MergeTree-like storage whose “data” is generated on the fly.

The system database is a normal Atomic database, so the system tables get real UUIDs and real directory paths even though nothing is ever written there. The comment in the code says so explicitly: “no data are stored on disk for these storages and path is actually not used”.

The two shapes of system table

Not every system table is built the same way. There are two common shapes.

Shape 1: the one-block table. The whole result fits in a single chunk, built synchronously. The base class declares a single virtual method:

 cpp
 
 
// src/Storages/System/IStorageSystemOneBlock.h:23
class IStorageSystemOneBlock : public StorageWithCommonVirtualColumns
{
protected:
 /// If this method uses `predicate`, getFilterSampleBlock() must list all columns to which
 /// it's applied. (Otherwise there'll be a LOGICAL_ERROR "Not-ready Set is passed" on subqueries.)
 virtual void fillData(MutableColumns & res_columns, ContextPtr context, const ActionsDAG::Node * predicate, std::vector<UInt8> columns_mask) const = 0;

 /// Columns to which fillData() applies the `predicate`.
 virtual Block getFilterSampleBlock() const
 {
 return {};
 }

 virtual bool supportsColumnsMask() const { return false; }

 friend class ReadFromSystemOneBlock;

fillData is called once, and its output becomes a single chunk:

 cpp
 
 
// src/Storages/System/IStorageSystemOneBlock.cpp:83
void ReadFromSystemOneBlock::initializePipeline(QueryPipelineBuilder & pipeline, const BuildQueryPipelineSettings &)
{
 auto sample_block = getOutputHeader();
 MutableColumns res_columns = sample_block->cloneEmptyColumns();
 const ActionsDAG::Node * predicate = filter ? filter->getOutputs().at(0) : nullptr;
 storage->fillData(res_columns, context, predicate, std::move(columns_mask));

 UInt64 num_rows = res_columns.at(0)->size();

 Chunk chunk;
 if (num_rows > 0)
 chunk = Chunk(std::move(res_columns), num_rows);

 pipeline.init(Pipe(std::make_shared<SourceFromSingleChunk>(sample_block, std::move(chunk))));
}

Shape 2: the streaming source. The result is generated lazily, in chunks, by an ISource. system.columns is the canonical example:

 cpp
 
 
// src/Storages/System/StorageSystemColumns.cpp:100
class ColumnsSource final : public ISource
{
public:
 ColumnsSource(
 std::vector<UInt8> columns_mask_,
 SharedHeader header_,
 UInt64 max_block_size_,
 ColumnPtr databases_,
 ColumnPtr tables_,
 Storages storages_,
 ContextPtr context_)
 : ISource(header_)
 , columns_mask(std::move(columns_mask_))
 , max_block_size(max_block_size_)
 , databases(std::move(databases_))
 , tables(std::move(tables_))
 , storages(std::move(storages_))
 , context(std::move(context_))
 , client_info_interface(context->getClientInfo().interface)
 , total_tables(tables->size())
 , access(context->getAccess())
 , query_id(context->getCurrentQueryId())
 , lock_acquire_timeout(std::chrono::milliseconds(context->getSettingsRef()[Setting::lock_acquire_timeout].totalMilliseconds()))
 {
 need_to_check_access_for_tables = !access->isGranted(AccessType::SHOW_COLUMNS);
 }

 String getName() const override { return "Columns"; }

protected:
 Chunk generate() override
 {
 if (db_table_num >= total_tables)
 return {};

 MutableColumns res_columns = getPort().getHeader().cloneEmptyColumns();
 size_t rows_count = 0;

 while (rows_count < max_block_size && db_table_num < total_tables)
 {
 const std::string database_name = (*databases)[db_table_num].safeGet<std::string>();
 const std::string table_name = (*tables)[db_table_num].safeGet<std::string>();
 ++db_table_num;

The generate() method is the source’s produce loop: it is called repeatedly until it returns an empty chunk. It walks a pre-computed list of (database, table) pairs, and for each one it takes a share lock on the table, reads its in-memory metadata, and emits one row per column.

The source is rebuilt for every query

Here is the trick that makes the whole thing work, and it is worth stating plainly: the source object is created inside initializePipeline, i.e. per query. There is no cached result, no snapshot of “the parts as of query start”.

For system.columns, the source is built in the pipeline initializer:

 cpp
 
 
// src/Storages/System/StorageSystemColumns.cpp:588
 ColumnPtr filtered_database_column = block_to_filter.getByName("database").column;
 ColumnPtr filtered_table_column = block_to_filter.getByName("table").column;

 pipes.emplace_back(std::make_shared<ColumnsSource>(
 std::move(columns_mask), std::move(header), max_block_size,
 std::move(filtered_database_column), std::move(filtered_table_column),
 std::move(storages), context));

 pipeline.init(Pipe::unitePipes(std::move(pipes)));

Note that the databases and tables columns and the storages map are moved into the source. They were computed a moment earlier, in the same function, by walking the catalog. If the source were cached, that walk would be stale.

For system.parts and friends, the same idea takes a slightly different shape: a StoragesInfoStream is created per query, and it enumerates storages lazily, one at a time, taking a share lock on each:

 cpp
 
 
// src/Storages/System/StorageSystemPartsBase.cpp:517
void ReadFromSystemPartsBase::initializePipeline(QueryPipelineBuilder & pipeline, const BuildQueryPipelineSettings &)
{
 auto stream = storage->getStoragesInfoStream(std::move(filter_by_database), std::move(filter_by_other_columns), context);
 auto header = getOutputHeader();

 MutableColumns res_columns = header->cloneEmptyColumns();

 /// The whole result is built eagerly here, so without this check a cancelled or timed out
 /// query would keep building rows over every storage until the very end.
 /// If the time limit is exceeded in the 'break' mode, stop instead of failing the query.
 QueryStatusPtr query_status = context->getProcessListElement();

 while (StoragesInfo info = stream->next())
 {
 if (query_status && !query_status->checkTimeLimit())
 break;

 storage->processNextStorage(context, res_columns, columns_mask, info, has_state_column);
 }

 UInt64 num_rows = res_columns.at(0)->size();
 Chunk chunk(std::move(res_columns), num_rows);

 pipeline.init(Pipe(std::make_shared<SourceFromSingleChunk>(std::move(header), std::move(chunk))));
}

Two things to notice:

The whole result is one chunk. system.parts does not stream. It builds every row in memory and hands over a single chunk. For a table with 10 000 parts and 60 columns, that is 600 000 rows in one Block. That is a deliberate trade: the enumeration is a walk over in-memory structures, and streaming it would mean yielding between storages and paying the pipeline’s per-chunk overhead for no benefit.
Cancellation is checked inside the loop. The comment says exactly why: without the check, a cancelled query would keep building rows over every storage until the very end.

The column mask

Now the trick that makes these tables cheap. system.parts has 68 columns. Almost nobody selects all of them. Computing all of them for every part of every table in the server — including the hash_of_all_files SipHash over the whole checksum map, the TTL info maps, the projections list — is a lot of work for columns that will be thrown away.

So the storage computes a mask of the requested columns and skips everything else:

 cpp
 
 
// src/Storages/System/getQueriedColumnsMaskAndHeader.cpp:8
std::pair<std::vector<UInt8>, Block> getQueriedColumnsMaskAndHeader(const Block & sample_block, const Names & column_names)
{
 std::vector<UInt8> columns_mask(sample_block.columns());
 Block header;

 NameSet names_set(column_names.begin(), column_names.end());
 for (size_t i = 0; i < columns_mask.size(); ++i)
 {
 const auto & column_with_type_and_name = sample_block.getByPosition(i);
 if (names_set.contains(column_with_type_and_name.name))
 {
 columns_mask[i] = 1;
 header.insert(column_with_type_and_name);
 }
 }

 return std::make_pair(columns_mask, header);
}

The mask is a vector<UInt8>, one byte per column of the table, and the fillData / processNextStorage implementations check it before every single insert:

 cpp
 
 
// src/Storages/System/StorageSystemParts.cpp:208
 size_t src_index = 0;
 size_t res_index = 0;
 if (columns_mask[src_index++])
 columns[res_index++]->insert(part->partition.serializeToString(partition_key_samples.get(*part)));
 if (columns_mask[src_index++])
 columns[res_index++]->insert(part->name);
 if (columns_mask[src_index++])
 columns[res_index++]->insert(part->uuid);
 if (columns_mask[src_index++])
 columns[res_index++]->insert(part->getTypeName());
 if (columns_mask[src_index++])
 columns[res_index++]->insert(part->getDataPartStorage().getType().toString());
 if (columns_mask[src_index++])
 columns[res_index++]->insert(part_state == State::Active);

and, for the expensive ones, the mask is consulted before the expensive computation rather than after:

 cpp
 
 
// src/Storages/System/StorageSystemParts.cpp:311
 {
 MinimalisticDataPartChecksums helper;
 if (columns_mask[src_index] || columns_mask[src_index + 1] || columns_mask[src_index + 2])
 helper.computeTotalChecksums(part->checksums);

 if (columns_mask[src_index++])
 {
 auto checksum = helper.hash_of_all_files;
 columns[res_index++]->insert(getHexUIntLowercase(checksum));
 }

computeTotalChecksums walks the whole checksum map and runs three SipHash-128 computations over it. If you did not ask for the hash columns, it is not called at all.

The same pattern shows up in system.columns, where the mask indices are hard-coded (which is why there is a warning comment at the top of the class):

 cpp
 
 
// src/Storages/System/StorageSystemColumns.cpp:176
 const bool needs_column_metadata = columns_mask[7] || columns_mask[8] || columns_mask[9] || columns_mask[21];
 bool can_expose_any_column_metadata = !needs_column_metadata;

The filter is pushed into the enumeration

The second trick. system.parts covers every MergeTree table in the server. Walking all of them to answer SELECT ... FROM system.parts WHERE database = 'default' is absurd. So the WHERE clause is split into pieces, and the pieces are used to prune the walk.

SourceStepWithFilter hands the storage a predicate, and the storage splits it by which columns it can evaluate early:

 cpp
 
 
// src/Storages/System/StorageSystemPartsBase.cpp:460
void ReadFromSystemPartsBase::applyFilters(ActionDAGNodes added_filter_nodes)
{
 SourceStepWithFilter::applyFilters(std::move(added_filter_nodes));

 if (filter_actions_dag)
 {
 const auto * predicate = filter_actions_dag->getOutputs().at(0);

 Block block;
 block.insert(ColumnWithTypeAndName({}, std::make_shared<DataTypeString>(), database_column_name));

 filter_by_database = VirtualColumnUtils::splitFilterDagForAllowedInputs(predicate, &block, context);
 if (filter_by_database)
 VirtualColumnUtils::buildSetsForDAG(*filter_by_database, context);

 block.insert(ColumnWithTypeAndName({}, std::make_shared<DataTypeString>(), table_column_name));
 block.insert(ColumnWithTypeAndName({}, std::make_shared<DataTypeString>(), engine_column_name));
 block.insert(ColumnWithTypeAndName({}, std::make_shared<DataTypeUInt8>(), active_column_name));
 block.insert(ColumnWithTypeAndName({}, std::make_shared<DataTypeUUID>(), storage_uuid_column_name));

 filter_by_other_columns = VirtualColumnUtils::splitFilterDagForAllowedInputs(predicate, &block, context);
 /// `StoragesInfoStream` reads the condition on `table` back from this filter to narrow the
 /// enumeration, which needs the elements of an `IN` over a subquery: keep them.
 if (filter_by_other_columns)
 VirtualColumnUtils::buildSetsForDAGKeepingElements(*filter_by_other_columns, context);
 }
}

Two DAGs come out: one that only mentions database, and one that mentions database, table, engine, active and storage_uuid. The first is applied to a block of database names before the table enumeration even starts. The second is applied to a block of (table, engine, active) tuples before the parts are read.

The enumeration itself is driven by the filter:

 cpp
 
 
// src/Storages/System/StorageSystemPartsBase.cpp:264
StoragesInfoStream::StoragesInfoStream(std::optional<ActionsDAG> filter_by_database, std::optional<ActionsDAG> filter_by_other_columns, ContextPtr context)
 : StoragesInfoStreamBase(context)
{
 /// Will apply WHERE to subset of columns and then add more columns.
 /// This is kind of complicated, but we use WHERE to do less work.

 Block block_to_filter;

 /// A condition on `table` prunes the enumeration below, which resolves every storage of
 /// every database that survived the condition on `database`. The sets of `filter_by_other_columns`
 /// were built in `applyFilters` with their elements kept, so an `IN` over a subquery is readable
 /// here too. A condition that names the database together with the table, such as
 /// `(database, table) IN (...)`, cannot be split off into `filter_by_database`; the exact
 /// database names are read from the same filter so such a condition also shortlists the databases.
 const auto * other_columns_predicate = filter_by_other_columns ? filter_by_other_columns->getOutputs().at(0) : nullptr;
 const auto table_name_filter = extractNameFilter(other_columns_predicate, table_column_name, context);
 const auto database_name_filter = extractNameFilter(other_columns_predicate, database_column_name, context);

extractNameFilter is the key: it recognises the shape column = 'literal' or column IN (...) and turns it into a predicate function that the database’s table iterator can use to skip tables without resolving them.

 cpp
 
 
// src/Storages/System/StorageSystemPartsBase.cpp:328
 for (size_t i = 0; i < rows; ++i)
 {
 offsets[i] = offsets[i - 1];

 if (time_limit_exceeded)
 continue;

 String database_name = (*database_column_for_filter)[i].safeGet<String>();
 const DatabasePtr & database = databases.at(database_name);
 const bool check_access_for_tables_in_db
 = check_access_for_tables && !access->isGranted(AccessType::SHOW_TABLES, database_name);

 offsets[i] = offsets[i - 1];
 auto iterator = database->getTablesIterator(context, table_name_filter, /* skip_not_loaded */ false);

getTablesIterator takes the filter, so a database with 10 000 tables resolves only the one you named. And the access check is folded into the same walk — SHOW TABLES permission is checked per database and per table while enumerating, not after.

The virtual columns

Every system table also exposes _database and _table as virtual columns, plus _state for the parts tables. They are declared in the base class:

 cpp
 
 
// src/Storages/System/StorageSystemPartsBase.cpp:568
VirtualColumnsDescription StorageSystemPartsBase::createVirtuals()
{
 VirtualColumnsDescription desc;
 desc.addEphemeral("_state", std::make_shared<DataTypeString>(), "", VirtualsMaterializationPlace::Reader);
 desc.addEphemeral("_table", std::make_shared<DataTypeLowCardinality>(std::make_shared<DataTypeString>()), "", VirtualsMaterializationPlace::Plan);
 desc.addEphemeral("_database", std::make_shared<DataTypeLowCardinality>(std::make_shared<DataTypeString>()), "", VirtualsMaterializationPlace::Plan);
 return desc;
}

VirtualsMaterializationPlace::Plan means “compute this in the query planner, before the source runs” — _table and _database are constants for the whole query, so they are substituted into the plan rather than emitted per row. _state is Reader place, because its value depends on the part.

The documentation source trick

One last detail, and it is a nice one. ClickHouse wants to show, for each system table, the source file that implements it. The obvious approach — __builtin_FILE() in the base-class constructor — gives the wrong file, because the base class constructor lives in the base class’s translation unit.

So each system table registers itself from its own .cpp:

 cpp
 
 
// src/Storages/System/SystemTableSourceRegistry.h:38
/// Place at file scope in a system table's `.cpp` (so that `__builtin_FILE()` resolves to that file). Accepts a type,
/// including a template instantiation, e.g. `REGISTER_SYSTEM_TABLE_SOURCE(::DB::SystemMergeTreeSettings<false>)`.
#define REGISTER_SYSTEM_TABLE_SOURCE_CONCAT_IMPL(a, b) a##b
#define REGISTER_SYSTEM_TABLE_SOURCE_CONCAT(a, b) REGISTER_SYSTEM_TABLE_SOURCE_CONCAT_IMPL(a, b)
/// `gnu::used` + `gnu::retain` keep the registration's static initializer from being discarded by the compiler or by
/// the linker's `--gc-sections`/`--icf` (the variable has internal linkage and is otherwise never referenced).
#define REGISTER_SYSTEM_TABLE_SOURCE(...) \
 namespace \
 { \
 [[maybe_unused, gnu::used, gnu::retain]] const bool REGISTER_SYSTEM_TABLE_SOURCE_CONCAT(registered_system_table_source_, __LINE__) \
 = (::DB::registerSystemTableSource(typeid(__VA_ARGS__), __builtin_FILE()), true); \
 }

and the invocation is one line at the bottom of the file:

 cpp
 
 
// src/Storages/System/StorageSystemParts.cpp:429
namespace DB { REGISTER_SYSTEM_TABLE_SOURCE(StorageSystemParts) }

gnu::used and gnu::retain are needed because the variable has internal linkage and nothing references it — without them the linker would drop it.

The whole picture

 text
 
 
 SELECT name, rows FROM system.parts WHERE database = 'default'
 |
 v
 StorageSystemParts (an IStorage in the `system` database)
 |
 | readImpl() -> build a ReadFromSystemPartsBase step
 | compute the columns_mask from the requested names
 v
 ReadFromSystemPartsBase
 |
 | applyFilters() -> split the WHERE into
 | filter_by_database (mentions only `database`)
 | filter_by_other_columns (mentions table/engine/active/uuid)
 v
 StoragesInfoStream (built per query)
 |
 | walk databases -> filter by database -> walk tables (with a name filter)
 | -> filter by table/engine/active -> take a share lock -> collect the parts
 v
 processNextStorage() -> for each part, for each column:
 if (columns_mask[i]) compute and insert
 |
 v
 ONE Chunk, handed to the pipeline

Trade-offs

What the storage-with-a-source design buys you:

Fresh data, trivially. There is no cache to invalidate. Two consecutive SELECT count() FROM system.parts see two different states if a merge happened in between, and that is the correct behaviour.
Predicate pushdown for free. Because the storage is a step in the query plan and not a view, the planner hands it the WHERE clause as a DAG, and the storage can use it however it likes — including to prune the catalog walk.
The column mask. This is the biggest win. system.parts computes 68 columns; the ones you did not ask for cost nothing. A SELECT count() FROM system.parts on a server with 100 000 parts does not compute a single checksum.
Access control integrated with the walk. Permissions are checked while enumerating, so a user who cannot see a table never causes it to be resolved, let alone locked.

What it costs:

The result is materialised. system.parts builds the entire result in one chunk. A server with a million parts and a SELECT * will allocate a lot of memory in one go. (The cancellation checkpoints exist precisely because of this.)
Hard-coded column positions. system.columns refers to columns_mask[7], columns_mask[21] and friends. There is a comment warning that the column list must be kept in sync, and the mask indices are a genuine footgun: insert a column in the middle of the ColumnsDescription and the mask silently misaligns.

The lock dance. Each table is locked for share with a timeout, in 100 ms slices, so that a cancelled query does not sit inside the lock acquisition:

 cpp
 
 
// src/Storages/System/StorageSystemPartsBase.cpp:577
bool StoragesInfoStreamBase::tryLockTable(StoragesInfo & info)
{
 const Poco::Timespan acquire_timeout(lock_timeout.count() * 1000);

 if (!query_status)
 {
 info.table_lock = info.storage->tryLockForShare(query_id, acquire_timeout);
 // nullptr means table was dropped while acquiring the lock
 return info.table_lock != nullptr;
 }

 /// Wait for the lock in short slices, polling the query status between them, so that a killed
 /// or soft-timed-out query does not sit inside RWLockImpl::getLock for the whole
 /// lock_acquire_timeout while a concurrent DDL query holds the drop lock. The slicing is done
 /// by IStorage below its throwing API boundary: an expired slice is a plain retry, not an
 /// exception, and only the exhaustion of the whole lock_acquire_timeout throws DEADLOCK_AVOIDED.
 static const Poco::Timespan cancellation_check_period(100 * 1000);

Two shapes to learn. IStorageSystemOneBlock for the small tables, a hand-written ISource for the big ones, and StorageSystemPartsBase for the family that needs a catalog walk. There is no single base class for “a system table”.

Wrapping up

The one thing to remember: a ClickHouse system table is a storage, and the rows are generated by a source that is constructed anew for every query. Nothing is cached, so nothing can be stale.

The part people get wrong: the system table does not compute all its columns and then throw some away. The column mask is checked before each expensive computation, so SELECT count() FROM system.parts never computes a checksum, never builds a TTL map, and never serialises a partition.

What to go do about it: measure the difference.

 sql
 
 
SELECT count() FROM system.parts;
SELECT count() FROM system.parts WHERE database = 'default';
SELECT sum(hash_of_all_files) != '' FROM system.parts;

The third one is the expensive one. If your monitoring queries the hash columns on every scrape, you are paying for three SipHash-128 computations over every part’s checksum map, every scrape.

ClickHouse Buffers the Query Log and Flushes It Into a Real MergeTree Table

Jay Hubbert — Sat, 24 Oct 2026 09:00:00 +0000

TL;DR: system.query_log is a real MergeTree table in the system database. But nobody writes to it directly. The query thread pushes a QueryLogElement onto an in-memory queue; a background thread wakes up every 7.5 seconds, builds one Block from everything queued, and runs a full INSERT against the table through InterpreterInsertQuery. The table itself is created lazily, on the first flush.

There is a piece of every database that has an awkward requirement: it must record what the server did, and it must not slow the server down while doing it.

Postgres solves this with csvlog and pg_stat_statements — a side process that tails a file. MySQL solved it with the slow query log. Every solution involves either a separate process, a separate file format, or a background writer that has to be told when to flush.

ClickHouse’s solution is unusual, and it is worth understanding because it explains a lot of the observable behaviour of system.query_log:

The log is a real MergeTree table. Not a view, not a file, not a ring buffer. system.query_log has parts, it gets merged, it can be OPTIMIZEd, it can be TTLed, and it can be read with the full power of the query engine.
But the writes are asynchronous and buffered. A query that finishes does not write a row; it appends to a queue and returns.
The table is created lazily, on the first flush, and rotated if the schema changes.

The queue

The heart of it is SystemLogQueue, a bounded, mutex-protected vector with a monotonically increasing index:

 cpp
 
 
// src/Common/SystemLogBase.h:185
 // Queue is bounded. But its size is quite large to not block in all normal cases.
 std::vector<LogElement> queue;

 // An always-incrementing index of the first message currently in the queue.
 // We use it to give a global sequential index to every message, so that we
 // can wait until a particular message is flushed. This is used to implement
 // synchronous log flushing for SYSTEM FLUSH LOGS.
 Index queue_front_index = 0;

 // Requested to flush logs up to this index, exclusive
 Index requested_flush_index = std::numeric_limits<Index>::min();
 // Flushed log up to this index, exclusive
 Index flushed_index = 0;

and then the two “prepare” indices, which track a separate concern — whether the table has been created:

 cpp
 
 
// src/Common/SystemLogBase.h:199
 // The same logic for the prepare tables: if requested_prepare_tables > prepared_tables we need to do prepare
 // except that initial prepared_tables is -1
 // it is due to the difference: when no logs have been written and we call flush logs
 // it becomes in the state: requested_flush_index = 0 and flushed_index = 0 -- we do not want to do anything
 // but if we need to prepare tables it becomes requested_prepare_tables = 0 and prepared_tables = -1
 // we trigger background thread and do prepare
 Index requested_prepare_tables = std::numeric_limits<Index>::min();
 Index prepared_tables = -1;

 size_t ignored_logs = 0;

This index-based protocol is the whole trick behind SYSTEM FLUSH LOGS. It is not “flush whatever is there right now” — it is “flush up to index N, and tell me when you have”. That is why SYSTEM FLUSH LOGS is synchronous and correct: a query that returns from SYSTEM FLUSH LOGS knows its rows are on disk.

Producing: `add()`

The producer side is a template that takes a callback, not a value:

 cpp
 
 
// src/Common/SystemLogBase.h:143
 // producer method: fill the element in place under a memory-tracker blocker, then enqueue it (moved).
 template <typename FillElement>
 requires std::is_invocable_r_v<void, FillElement, LogElement &>
 void add(FillElement && fill)
 {
 MemoryTrackerUntrackedAllocationsBlockerInThread untracked_allocations_blocker;
 MemoryTrackerBlockerInThread block_memory_tracker;
 LogElement element{};
 fill(element);
 push(std::move(element));
 }

Two things happen here that are easy to miss:

The element is filled in place, under a memory-tracker blocker. The QueryLogElement is a big struct — it holds the query text, the profile events map, the settings map, the exception stack trace. Building it on the stack and moving it into the queue means the allocation of the strings happens under the caller’s tracker, so a query that logs a 10 MB stack trace is charged for it. But the free happens later, on the flush thread, which cannot credit the original query’s tracker — hence the UntrackedAllocations blocker, which stops the flush thread’s frees from being charged to somebody else.

The static_assert in the class body guards the move:

 cpp
 
 
// src/Common/SystemLogBase.h:130
class SystemLogQueue
{
 /// `queue` reallocates while `mutex` is held. libc++ relocates with std::move_if_noexcept, so an element
 /// that can throw on move is deep-copied instead, and the critical section becomes O(queue size).
 static_assert(std::is_nothrow_move_constructible_v<LogElement>);

A throwing move would make std::vector’s reallocation copy every element, under the mutex, turning a push into an O(queue) operation.

The push

 cpp
 
 
// src/Common/SystemLogBase.cpp:101
template <typename LogElement>
void SystemLogQueue<LogElement>::push(LogElement && element)
{
 /// It is possible that the method will be called recursively.
 /// Better to drop these events to avoid complications.
 if (recursive_push_call)
 return;
 recursive_push_call = true;
 SCOPE_EXIT({ recursive_push_call = false; });

The recursion guard is worth a moment. Logging a message can itself log a message — a query that fails to log can fail to log that. The guard is a thread_local flag: if we are already inside a push, drop the event.

Then the two thresholds:

 cpp
 
 
// src/Common/SystemLogBase.cpp:118
 {
 std::unique_lock lock(mutex);

 if (is_shutdown)
 return;

 if (queue.size() == settings.buffer_size_rows_flush_threshold)
 {
 buffer_size_rows_flush_threshold_exceeded = true;

 // The queue more than half full, time to flush.
 // We only check for strict equality, because messages are added one
 // by one, under exclusive lock, so we will see each message count.
 // It is enough to only wake the flushing thread once, after the message
 // count increases past half available size.

 const auto last_log_index = queue_front_index + queue.size();
 notifyFlushUnlocked(last_log_index, /* should_prepare_tables_anyway */ false);
 }

 if (queue.size() >= settings.max_size_rows)
 {
 chassert(queue.size() == settings.max_size_rows);

 // Ignore all further entries until the queue is flushed.
 // To the next batch we add a log message about how much we have lost
 ++ignored_logs;
 return;
 }

 queue.push_back(std::move(element));
 }

The half-full threshold wakes the flush thread early. If the queue reaches buffer_size_rows_flush_threshold (by default half of max_size_rows), the push notifies the flush thread, which does not have to wait for its timer. This is what keeps the queue from filling up during a burst.

The hard limit drops events. If the queue is at max_size_rows, the event is dropped and ignored_logs is incremented. The count is reported at the next flush:

 cpp
 
 
// src/Common/SystemLogBase.cpp:283
 if (prev_ignored_logs)
 LOG_ERROR(log, "Queue had been full at {}, accepted {} logs, ignored {} logs.",
 result.last_log_index - result.logs.size(),
 result.logs.size(),
 prev_ignored_logs);

So: the query log is lossy under extreme load, by design, and it tells you it was lossy. That is a better failure mode than blocking the query path.

The defaults

 cpp
 
 
// src/Common/SystemLogBase.h:263
 static consteval size_t getDefaultMaxSize() { return 1048576; }
 static consteval size_t getDefaultReservedSize() { return 8192; }
 static consteval size_t getDefaultFlushIntervalMilliseconds() { return 7500; }
 static consteval bool shouldNotifyFlushOnCrash() { return false; }
 static consteval bool shouldTurnOffLogger() { return false; }

1 048 576 rows is the hard cap. 8192 rows is the reserved capacity (the vector’s initial reservation, so that a normal flush does not reallocate). 7500 ms is the flush interval — the famous 7.5 seconds.

The threshold and the interval come from the config, per table, with a global system_tables. prefix:

 cpp
 
 
// src/Interpreters/SystemLogSettingsFromConfig.h:44
template <typename TSystemLog>
void readSystemLogQueueSettingsFromConfig(SystemLogQueueSettings & queue_settings, const Poco::Util::AbstractConfiguration & config, const std::string & config_prefix)
{
 queue_settings.flush_interval_milliseconds = getSystemTableOption<size_t>("flush_interval_milliseconds", config, config_prefix).value_or(TSystemLog::getDefaultFlushIntervalMilliseconds());

 queue_settings.max_size_rows = getSystemTableOption<size_t>("max_size_rows", config, config_prefix).value_or(TSystemLog::getDefaultMaxSize());
 if (queue_settings.max_size_rows < 1)
 throw Exception(ErrorCodes::BAD_ARGUMENTS, "max_size_rows for {} is {} should be 1 at least",
 config_prefix,
 queue_settings.max_size_rows);

 queue_settings.reserved_size_rows = getSystemTableOption<size_t>("reserved_size_rows", config, config_prefix).value_or(TSystemLog::getDefaultReservedSize());
 if (queue_settings.max_size_rows < queue_settings.reserved_size_rows)
 {
 throw Exception(ErrorCodes::BAD_ARGUMENTS,
 "max_size_rows for {} is {} should be >= reserved_size_rows ({})",
 config_prefix,
 queue_settings.max_size_rows,
 queue_settings.reserved_size_rows);
 }

 queue_settings.buffer_size_rows_flush_threshold = getSystemTableOption<size_t>("buffer_size_rows_flush_threshold", config, config_prefix).value_or(queue_settings.max_size_rows / 2);

So the defaults compose to: flush every 7.5 s, or earlier if the queue reaches 524 288 rows; drop events beyond 1 048 576.

The flush thread

One thread per log table, started at startup:

 cpp
 
 
// src/Common/SystemLogBase.cpp:333
template <typename LogElement>
void SystemLogBase<LogElement>::startup()
{
 std::lock_guard lock(thread_mutex);
 saving_thread = std::make_unique<ThreadFromGlobalPool>([this] { savingThreadFunction(); });
}

Its loop is short:

 cpp
 
 
// src/Interpreters/SystemLog.cpp:857
template <typename LogElement>
void SystemLog<LogElement>::savingThreadFunction()
{
 DB::setThreadName(ThreadName::SYSTEM_LOG_FLUSH);

 while (true)
 {
 try
 {
 auto result = queue->pop();

 if (result.is_shutdown)
 {
 LOG_TRACE(log, "Terminating");
 return;
 }

 if (!result.logs.empty())
 {
 flushImpl(result.logs, result.last_log_index);
 }
 else if (result.create_table_force)
 {
 prepareTable();
 queue->confirm(result.last_log_index);
 }
 }
 catch (...)
 {
 tryLogCurrentException(__PRETTY_FUNCTION__);
 }
 }
}

Note the catch (...): a failed flush must not kill the thread. The next iteration continues.

`pop()`: the timer

This is where the 7.5 seconds live:

 cpp
 
 
// src/Common/SystemLogBase.cpp:240
template <typename LogElement>
typename SystemLogQueue<LogElement>::PopResult SystemLogQueue<LogElement>::pop()
{
 [[maybe_unused]] MemoryTrackerUntrackedAllocationsBlockerInThread blocker;

 PopResult result;
 size_t prev_ignored_logs = 0;

 {
 std::unique_lock lock(mutex);

 flush_event.wait_for(lock, std::chrono::milliseconds(settings.flush_interval_milliseconds), [&] ()
 {
 return requested_flush_index > flushed_index || requested_prepare_tables > prepared_tables || is_shutdown;
 });

 if (is_shutdown)
 return PopResult{.is_shutdown = true};

 /// Allocate the next batch's buffer outside the lock so a large reallocation
 /// does not block producers, then hand it over with a cheap swap below.
 if (!queue.empty())
 {
 const auto next_capacity = std::max(settings.reserved_size_rows, queue.size());
 lock.unlock();
 result.logs.reserve(next_capacity);
 lock.lock();

 if (is_shutdown)
 return PopResult{.is_shutdown = true};
 }

 const auto queue_size = queue.size();
 queue_front_index += queue_size;
 prev_ignored_logs = ignored_logs;
 ignored_logs = 0;

 result.last_log_index = queue_front_index;
 if (!queue.empty())
 result.logs.swap(queue);
 result.create_table_force = requested_prepare_tables > prepared_tables;
 }

Four things to notice:

wait_for with a predicate, not wait. The thread sleeps for up to flush_interval_milliseconds but wakes immediately when a flush is requested. That is how the half-full threshold produces an early flush.
The batch is allocated outside the lock. result.logs.reserve(...) happens with the mutex released, then the buffer is handed over with a swap. The producers are not blocked by a 100 000-element reallocation.
queue_front_index advances by the size of the batch, not by one. The index is therefore a logical sequence number: “the Nth log record ever produced”, regardless of batching. That is what makes SYSTEM FLUSH LOGS able to say “flush up to record 4 500 000”.
swap, not clear. The queue vector and the batch vector trade places. The next batch gets a fresh, correctly-sized buffer, and the old one is freed when the batch goes out of scope.

The flush itself

flushImpl is where the rows become a Block and the Block becomes an INSERT:

 cpp
 
 
// src/Interpreters/SystemLog.cpp:892
template <typename LogElement>
void SystemLog<LogElement>::flushImpl(const std::vector<LogElement> & to_flush, uint64_t to_flush_end)
{
 auto component_guard = Coordination::setCurrentComponent("SystemLog::flushImpl");
 Stopwatch stopwatch;
 UInt64 prepare_table_time = 0;
 UInt64 prepare_insert_data_to_block = 0;
 UInt64 execute_insert_time = 0;
 UInt64 confirm_time = 0;
 size_t flush_size = to_flush.size();
 bool is_manual_flush = flush_policy->isManualFlush(to_flush_end);

 try
 {
 LOG_TRACE(log, "Flushing system log, {} entries to flush up to offset {}",
 to_flush.size(), to_flush_end);

 fiu_do_on(FailPoints::sleep_in_logs_flush,
 {
 sleepForSeconds(30);
 });

 /// We check for existence of the table and create it as needed at every
 /// flush. This is done to allow user to drop the table at any moment
 /// (new empty table will be created automatically). BTW, flush method
 /// is called from single thread.
 prepareTable();
 prepare_table_time = stopwatch.elapsedMilliseconds();
 stopwatch.restart();

 ColumnsWithTypeAndName log_element_columns;
 auto log_element_names_and_types = LogElement::getColumnsDescription();

 for (const auto & name_and_type : log_element_names_and_types.getAll())
 log_element_columns.emplace_back(name_and_type.type, name_and_type.name);

 Block block(std::move(log_element_columns));

 MutableColumns columns = block.mutateColumns();

 for (auto & column : columns)
 column->reserve(to_flush.size());

 for (const auto & elem : to_flush)
 elem.appendToBlock(columns);

 block.setColumns(std::move(columns));

Three things:

prepareTable() is called on every flush, not once at startup. The comment explains: “We check for existence of the table and create it as needed at every flush. This is done to allow user to drop the table at any moment (new empty table will be created automatically).” So DROP TABLE system.query_log does not disable logging; the next flush recreates it.

reserve(to_flush.size()) on every column — a single allocation per column for the whole batch, instead of growth-by-doubling.

appendToBlock is per-element, per-column serialisation. The element knows how to write itself into the columns.

And then the insert:

 cpp
 
 
// src/Interpreters/SystemLog.cpp:942
 /// We write to table indirectly, using InterpreterInsertQuery.
 /// This is needed to support DEFAULT-columns in table.

 auto insert = make_intrusive<ASTInsertQuery>();
 insert->table_id = table_id;

 /// Explicitly specify column names to avoid mismatch when the table
 /// has been altered (e.g. columns added) between prepareTable() and this INSERT.
 auto columns_ast = make_intrusive<ASTExpressionList>();
 for (const auto & name : block.getNames())
 columns_ast->children.emplace_back(make_intrusive<ASTIdentifier>(name));
 insert->columns = std::move(columns_ast);

 ASTPtr query_ptr = std::move(insert);

 // we need query context to do inserts to target table with MV containing subqueries or joins
 auto insert_context = Context::createCopy(context);
 insert_context->makeQueryContext();
 addSettingsForQuery(insert_context, IAST::QueryKind::Insert);

 InterpreterInsertQuery interpreter(
 query_ptr,
 insert_context,
 /* allow_materialized */ false,
 /* no_squash */ false,
 /* no_destination */ false,
 /* async_isnert */ false);
 BlockIO io = interpreter.execute();

 PushingPipelineExecutor executor(io.pipeline);

 executor.start();
 executor.push(block);
 executor.finish();

This is a full INSERT through the query interpreter. Not a direct write to the storage. The comment says why: “This is needed to support DEFAULT-columns in table.” Because the table is a real MergeTree with a real schema, the log’s rows go through the same machinery as any other insert — the same column defaults, the same materialized views, the same partitioning.

The cost of that decision is that every flush builds a query plan, opens the table, takes locks, and goes through the whole insert pipeline. The benefit is that the log table is indistinguishable from a user table: it can have materialized views attached to it, it can be read with the full query engine, it participates in replication if you configure it, and OPTIMIZE works on it.

Note also that the whole batch is a single INSERT — typically one MergeTree part per partition, written in one transaction. A million log rows land as one part.

And the failure handling: a failed flush is logged, the profile event SystemLogErrorOnFlush is incremented, and the batch is confirmed anyway:

 cpp
 
 
// src/Interpreters/SystemLog.cpp:981
 catch (...)
 {
 if (is_manual_flush)
 flush_policy->cancelManualFlush();
 ProfileEvents::increment(ProfileEvents::SystemLogErrorOnFlush);
 tryLogCurrentException(__PRETTY_FUNCTION__, fmt::format("Failed to flush system log {} with {} entries up to offset {}",
 table_id.getNameForLogs(), to_flush.size(), to_flush_end));
 }

 queue->confirm(to_flush_end);

The rows are lost, not retried. The log is best-effort by design.

The table is created lazily

The table does not exist until the first flush. The engine definition is assembled from the log element’s own description plus the config:

 cpp
 
 
// src/Interpreters/SystemLog.cpp:254
 log_settings.engine = "ENGINE = MergeTree";

 /// PARTITION expr is not necessary.
 String partition_by = getSystemTableOption<std::string>("partition_by", config, config_prefix).value_or(TSystemLog::getDefaultPartitionBy());
 if (!partition_by.empty())
 log_settings.engine += " PARTITION BY (" + partition_by + ")";

 /// TTL expr is not necessary.
 String ttl = getSystemTableOption<std::string>("ttl", config, config_prefix).value_or(TSystemLog::getDefaultTTL());
 if (!ttl.empty())
 log_settings.engine += " TTL " + ttl;

 /// ORDER BY expr is necessary.
 String order_by = getSystemTableOption<std::string>("order_by", config, config_prefix).value_or(TSystemLog::getDefaultOrderBy());
 log_settings.engine += " ORDER BY (" + order_by + ")";

with the defaults coming from the base class:

 cpp
 
 
// src/Common/SystemLogBase.h:258
 static const char * getDefaultPartitionBy() { return "toYYYYMM(event_date)"; }
 static const char * getDefaultOrderBy() { return "event_date, event_time"; }
 static const char * getDefaultTTL() { return ""; }

So the default system.query_log is:

 sql
 
 
CREATE TABLE system.query_log (
 ...
) ENGINE = MergeTree
 PARTITION BY (toYYYYMM(event_date))
 ORDER BY (event_date, event_time)

A monthly partition, ordered by time. That is a real table with real parts, and it gets merged in the background like any other.

prepareTable() also handles the case where the schema has changed between server versions — an Enum8 column gained a value, a column was added:

 cpp
 
 
// src/Interpreters/SystemLog.cpp:1014
template <typename LogElement>
void SystemLog<LogElement>::prepareTable()
{
 auto component_guard = Coordination::setCurrentComponent("SystemLog::prepareTable");
 String description = table_id.getNameForLogs();

 auto table = getStorage();
 if (table)
 {
 if (old_create_query.empty())
 {
 old_create_query = getCreateTableQueryClean(table_id, getContext())->formatWithSecretsOneLine();

and if the definition no longer matches, the old table is renamed to query_log_1, query_log_2, … and a fresh one is created. The docs call this “rotation”. It is how system.session_log handles a new interface enum value: the old table keeps its old enum, a new table is created with the new one, and your old data is still there under the rotated name.

`SYSTEM FLUSH LOGS`

Now the index protocol pays off. SYSTEM FLUSH LOGS needs to guarantee “when I return, the rows are on disk”. The implementation:

 cpp
 
 
// src/Interpreters/SystemLog.cpp:667
 for (auto * log : getAllLogs())
 {
 log->flushBufferToLog(std::chrono::system_clock::now());

 auto last_log_index = log->getLastLogIndex();
 logs_to_wait.push_back({log, last_log_index});
 if (should_prepare_tables_anyway)
 log->setManualFlushTargetIndex(last_log_index);
 log->notifyFlush(last_log_index, should_prepare_tables_anyway);
 }

then:

 cpp
 
 
// src/Interpreters/SystemLog.cpp:744
 /// We must wait for the async flushes to finish
 for (const auto & [log, index] : logs_to_wait)
 {
 if (!ignore_errors)
 log->flush(index, should_prepare_tables_anyway);

log->flush(index) is waitFlush, which blocks until the flush thread reports flushed_index >= index:

 cpp
 
 
// src/Common/SystemLogBase.cpp:202
 auto result = confirm_event.wait_for(
 lock,
 std::chrono::seconds(timeout_seconds),
 [&]
 {
 return (flushed_index >= expected_flushed_index && (!should_prepare_tables_anyway || prepared_tables >= expected_flushed_index))
 || is_shutdown;
 });

 if (!result)
 {
 throw Exception(ErrorCodes::TIMEOUT_EXCEEDED, "Timeout exceeded ({} s) while flushing system log '{}'.",
 toString(timeout_seconds), demangle(typeid(*this).name()));
 }

180 seconds of patience, then a TIMEOUT_EXCEEDED. The comment above it is a small piece of engineering honesty:

 cpp
 
 
// src/Common/SystemLogBase.cpp:188
 // Use an arbitrary timeout to avoid endless waiting. 60s proved to be
 // too fast for our parallel functional tests, probably because they
 // heavily load the disk.
 const int timeout_seconds = 180;

Note the “prepare tables” condition: SYSTEM FLUSH LOGS also waits for the table to exist, not just for the rows to be written. That is why SYSTEM FLUSH LOGS on a freshly started server creates the table.

The whole picture

 text
 
 
 query finishes
 |
 | logQueryFinish(...) -> QueryLog::logQueryFinish
 v
 SystemLogBase::add(callback)
 | element filled in place under a memory-tracker blocker
 v
 SystemLogQueue::push()
 | under the mutex
 | if size == half of max -> notify the flush thread
 | if size == max -> DROP the event, ++ignored_logs
 v
 [ queue: vector<QueryLogElement>, up to 1 048 576 rows ]
 |
 | flush_event.wait_for(7.5 s) <- the timer
 | or woken by notifyFlush()
 v
 pop(): swap the queue out, advance queue_front_index
 |
 v
 flushImpl():
 | prepareTable() <- create the MergeTree table if missing
 | build one Block from the whole batch
 | InterpreterInsertQuery -> INSERT INTO system.query_log
 v
 [ a real MergeTree part ]
 |
 v
 merged, queried, TTLed, replicated -- like any other table

Trade-offs

What the “log is a real table” design buys you:

Full query power. system.query_log is a MergeTree table, so you can use system.query_log with PREWHERE, projections, skip indexes, FINAL, and every other MergeTree feature. A ring buffer or a CSV file gives you none of that.
The log is queryable while it is being written. The rows of the last 7.5 seconds are in memory, but everything before that is a normal part.
The log can be replicated, backed up, and shipped to a cluster with the same machinery as any other table.
Schema evolution is handled. A new enum value in a column means the old table is rotated and a new one created. Old data stays readable.
The write path is off the query’s critical path. The query thread only does a push_back under a mutex.

What it costs:

Up to 7.5 seconds of latency. A row appears in system.query_log up to 7.5 seconds after the query finished. This is the single most surprising thing about the query log, and it is why every monitoring script starts with SYSTEM FLUSH LOGS.
The log is lossy. When the queue is full, events are dropped and counted. Under a query storm, system.query_log will have holes. The LOG_ERROR about ignored logs is the only warning you get.
The flush is a full INSERT. Every 7.5 seconds, per log table, the server builds a query plan and runs an insert pipeline. With 30 log tables configured, that is 30 insert pipelines per 7.5 seconds. On a server with hundreds of log tables this is measurable.
The table can be dropped out from under the logger. The flush thread recreates it, but between the drop and the next flush, the log is silently going nowhere.
The Block is built in memory. A batch of a million log rows, each with a query string and a profile-events map, is a lot of RAM in one go. The max_size_rows bound is what keeps it finite.

Wrapping up

The one thing to remember: system.query_log is a real MergeTree table, but it is written by a background thread that batches rows in memory and flushes them every 7.5 seconds (or earlier, if the queue fills up). The query thread never touches the storage.

The part people get wrong: the log is not immediately visible. If you run a query and then immediately SELECT from system.query_log, the row may not be there. You need SYSTEM FLUSH LOGS first — or you need to wait 7.5 seconds.

What to go do about it: try it.

 sql
 
SELECT count() FROM system.query_log WHERE query LIKE '%flush%';

SYSTEM FLUSH LOGS query_log;

SELECT count() FROM system.query_log WHERE query LIKE '%flush%';

The second count is at least as large as the first — the SYSTEM FLUSH LOGS statement itself gets logged, and the flush is what makes it visible.

System-Tables on Opensource internals

ClickHouse System Tables Are Storages That Generate Their Own Rows

Attaching a system table

The two shapes of system table

The source is rebuilt for every query

The column mask

The filter is pushed into the enumeration

The virtual columns

The documentation source trick

The whole picture

Trade-offs

Wrapping up

ClickHouse Buffers the Query Log and Flushes It Into a Real MergeTree Table

The queue

Producing: add()

The push

The defaults

The flush thread

pop(): the timer

The flush itself

The table is created lazily

SYSTEM FLUSH LOGS

The whole picture

Trade-offs

Wrapping up

Producing: `add()`

`pop()`: the timer

`SYSTEM FLUSH LOGS`