ClickHouse 26.x in Production: QBit Vectors, Text Index, and Iceberg Writes

ClickHouse 26.x ships monthly on calendar versioning (YY.MM), and the ClickHouse 26.x line has been the most consequential run of releases since the project went commercial. As of August 2026, the latest stable is v26.7.3.19 (26.7 shipped July 22, with a patch on August 6). The current LTS is 26.3, released March 2026 and supported through March 2027. Two hard dates matter for anyone running this in production: 25.8 LTS hits end of life on August 29, 2026, and the next LTS, 26.8, is due roughly now — LTS releases land twice a year, in March and August.

If you are still on 25.8 LTS, you are days from running unsupported. That is the single most important operational fact in this post. Everything else is about what you get when you move to ClickHouse 26.x.

What actually shipped in ClickHouse 26.x

Three feature tracks matured in this line, all reaching production status in 26.2, plus a steady stream of performance work in 26.5 through 26.7. The table below is the short version of the ClickHouse 26.x release history — the parts that actually change how you operate a cluster rather than the parts that read well in a launch post.

Before you plan anything, confirm what your cluster is really running. Version drift between replicas is the most common reason a routine upgrade window turns into an incident.

-- What is each replica actually running?
SELECT
    hostName() AS host,
    version()  AS server_version,
    uptime()   AS uptime_seconds
FROM clusterAllReplicas('default', system.one)
ORDER BY host;

QBit: runtime-tunable vector precision in ClickHouse 26.x

Vector search in ClickHouse has been building since the vector similarity index went beta in 25.5. The interesting piece is QBit, a data type introduced in 25.10 and declared production-ready in 26.2, with further speedups landing in 26.7.

The operational pitch: QBit stores embeddings so that precision is tunable at query time, not at ingest time. With conventional quantization you decide once — full float32, or a compressed representation — and re-ingesting terabytes of embeddings to change your mind is a real cost.

QBit lets the same stored column serve a fast low-precision scan for candidate generation and a higher-precision pass for reranking, from one copy of the data. It achieves that by grouping the same binary digit position across all vectors, so a query can read the leading bit planes and skip the rest. The QBit data type documentation spells out the storage layout and the optional stride parameter.

Declaring and loading a QBit column

-- ClickHouse 26.x syntax: QBit(element_type, dimension[, stride])
-- element_type may be Int8, BFloat16, Float32 or Float64.
CREATE TABLE docs
(
    id    UInt64,
    body  String,
    emb   QBit(Float32, 1024)
)
ENGINE = MergeTree
ORDER BY id;

-- An existing Array(Float32) embedding column converts directly,
-- provided the array length matches the QBit dimension.
INSERT INTO docs (id, body, emb)
SELECT id, body, embedding
FROM legacy_embeddings;

-- The round trip is lossless for Int8, Float32 and Float64.
SELECT emb::Array(Float32) AS reconstructed
FROM docs
LIMIT 1;

The two-pass retrieval pattern

This is the pattern that makes the migration worth scheduling. Generate candidates cheaply across the whole table, then rerank only the survivors at full precision. Both passes read the same column; only the precision argument changes.

-- Pass 1: recall. Read 8 of 32 bit planes for roughly 4x less I/O.
WITH candidates AS
(
    SELECT id
    FROM docs
    ORDER BY L2DistanceTransposed(emb, {q:Array(Float32)}, 8) ASC
    LIMIT 1000
)
-- Pass 2: precision. Exact distances over a tiny row set.
SELECT
    id,
    body,
    L2DistanceTransposed(emb, {q:Array(Float32)}, 32) AS distance
FROM docs
WHERE id IN (SELECT id FROM candidates)
ORDER BY distance ASC
LIMIT 10;

For teams bolting semantic search onto an existing ClickHouse analytics deployment, this is the difference between running a separate vector database and not. You already have the events; now the embeddings live next to them, joinable in the same query.

A dedicated vector engine still wins on specialised ANN features — if you are weighing that trade-off, our breakdown of vector database indexing with HNSW, IVF, PQ, OPQ and ScaNN is the place to start, and ClickHouse for vector search and storage covers the storage side. But “one system, one bill, one on-call rotation” is a strong argument at most companies’ scale. Note that 26.6 also added AI embedding functions, which shortens the path from a raw text column to a searchable vector.

Text index in ClickHouse 26.x: GA after a proper bake

Full-text search followed the cadence you want from a database vendor: experimental in 25.9, beta in 25.12, GA in 26.2. That is roughly five months of public hardening before the production label — a reasonable signal that the GA means something. The text index documentation is now explicit that no special settings need to be configured on 26.2 and newer.

Operationally, the text index changes the economics of log and event search. Before it, substring hunting in ClickHouse meant LIKE '%needle%' over compressed columns — fast for what it is, because ClickHouse scans absurdly quickly, but still a scan. A proper inverted-style text index turns “find this request ID across 90 days of logs” from a scan problem into an index lookup. Release 26.7 added position-aware phrase search on top, so multi-word queries respect word order rather than degenerating into bag-of-terms matching.

Adding a text index to an existing log table

-- Add the index definition, then materialise it for existing parts.
ALTER TABLE logs
    ADD INDEX msg_idx message
    TYPE text(tokenizer = splitByNonAlpha)
    GRANULARITY 1;

ALTER TABLE logs MATERIALIZE INDEX msg_idx;

-- Single-token lookup: the request-ID case.
SELECT ts, host, message
FROM logs
WHERE hasToken(message, 'req-4f9a')
  AND ts >= now() - INTERVAL 90 DAY
ORDER BY ts DESC
LIMIT 100;

-- Every token must be present.
SELECT count()
FROM logs
WHERE hasAllTokens(message, ['timeout', 'upstream']);

-- Any one token is enough.
SELECT count()
FROM logs
WHERE hasAnyTokens(message, ['ECONNRESET', 'EPIPE', 'ETIMEDOUT']);

Confirm the index is actually being used

A text index that is defined but not selected is worse than no index: you pay the build and storage cost and still scan. Check it explicitly rather than assuming.

EXPLAIN indexes = 1
SELECT count()
FROM logs
WHERE hasToken(message, 'req-4f9a');

-- Read the skip-index section and compare Granules selected against
-- Granules total. If they are identical, the tokenizer is not producing
-- the token you searched for -- splitByNonAlpha, ngrams and sparseGrams
-- tokenize very differently, and that choice is not reversible without
-- rebuilding the index.

-- Track index size so the win stays economic as retention grows.
SELECT
    name,
    type,
    formatReadableSize(sum(data_compressed_bytes)) AS compressed
FROM system.data_skipping_indices
WHERE table = 'logs'
GROUP BY name, type;

If you are paying an Elasticsearch bill primarily to grep logs, this feature is aimed directly at you. We have written before about inverted indexes in ClickHouse and how to perform a full-text phrase search in ClickHouse; the 26.2 GA is the release where those techniques stop being a workaround and become the supported path. Elasticsearch still wins on relevance scoring and analyzer breadth, so cost the migration honestly rather than assuming parity.

Iceberg writes in ClickHouse 26.x: the lakehouse door opens both ways

ClickHouse has read Iceberg for a while; 26.2 made Iceberg writes and INSERTs production-ready. Around it: Hive Metastore catalog support (since 25.5), PREWHERE pushdown for Iceberg reads, and in 26.5, Iceberg v3 geo types plus a query condition cache. The Iceberg table engine reference covers the catalog and credential options.

Why this matters operationally: Iceberg writes turn ClickHouse from a lakehouse consumer into a lakehouse citizen. You can land data in ClickHouse for hot serving, then write aged partitions out to Iceberg tables that Spark, Trino, Snowflake, or Redshift can read — no export pipeline, no duplicate ETL. The whole industry converged on Iceberg as the interchange layer in 2025–2026 (Redshift added Iceberg read/write, BigQuery’s managed Iceberg tables went GA), and ClickHouse 26.x writing natively to it means you are no longer locked into MergeTree as the only durable home for your data. It is also the coexistence mechanism that makes warehouse migrations incremental instead of big-bang.

Tiering aged partitions out to Iceberg

Move one partition at a time, verify counts, and only then drop the hot copy. A failed month-sized INSERT is a retry; a failed year-sized INSERT is an afternoon.

-- Register the Iceberg table (catalog-backed or path-based).
CREATE TABLE iceberg_events
ENGINE = IcebergS3('https://your-bucket.s3.amazonaws.com/warehouse/events/');

-- Age out one month at a time so a failure retries cheaply.
INSERT INTO iceberg_events
SELECT *
FROM events
WHERE event_date >= '2026-01-01'
  AND event_date <  '2026-02-01';

-- Reconcile before you drop anything.
SELECT
    (SELECT count() FROM events         WHERE toYYYYMM(event_date) = 202601) AS hot_rows,
    (SELECT count() FROM iceberg_events WHERE toYYYYMM(event_date) = 202601) AS lake_rows;

-- Only once hot_rows = lake_rows.
ALTER TABLE events DROP PARTITION 202601;

Serving one logical timeline across both tiers

-- Dashboards keep asking one question; storage answers it from two places.
SELECT
    event_date,
    count() AS events
FROM
(
    SELECT event_date FROM events          -- hot: MergeTree, sub-second
    UNION ALL
    SELECT event_date FROM iceberg_events  -- cold: Iceberg on object storage
)
WHERE event_date >= today() - 365
GROUP BY event_date
ORDER BY event_date;

If your endgame is observability data on open formats, our write-up on the ClickHouse observability stack with Apache Iceberg and OpenTelemetry applies the same tiering pattern to telemetry rather than product events.

The rest of the ClickHouse 26.x line: 26.5 through 26.7

The 26.6 release — the project’s ten-year anniversary — brought hypothetical skip indexes, which let you test whether an index would help before paying to build it. That is a genuinely useful tuning workflow. It also shipped cascading refreshable materialized views, experimental streaming and continuous queries (STREAM), and roughly 3× faster deeply nested queries, which matters now that the JSON type (production-ready in the 25.x line) is pulling semi-structured workloads in.

Release 26.7 was a performance release: GROUP BY, ORDER BY, and LIMIT speedups, three separate JOIN improvements, around 2.5× faster regex, and EXPLAIN ANALYZE. That last one deserves emphasis. ClickHouse query introspection has historically meant stitching together trace logs and system tables; EXPLAIN ANALYZE gives you actual per-operator execution statistics in one statement. If you support ClickHouse clusters for a living, as we do, this is the ClickHouse 26.x feature you will use daily.

-- 26.7: per-operator runtime statistics in a single statement.
EXPLAIN ANALYZE
SELECT
    customer_id,
    sum(amount) AS revenue
FROM orders
WHERE order_date >= today() - 30
GROUP BY customer_id
ORDER BY revenue DESC
LIMIT 20;

-- 26.6 hypothetical skip indexes: the workflow, not a magic setting.
--   1. Describe the candidate index (type, expression, granularity).
--   2. Attach it hypothetically and re-run EXPLAIN indexes = 1.
--   3. Compare Granules selected vs Granules total for the predicate.
--   4. Only then ALTER TABLE ... ADD INDEX for real.
-- Check the changelog for the exact syntax on your patch release --
-- it moved during the 26.6 cycle.
EXPLAIN indexes = 1
SELECT count() FROM logs WHERE status_code = 503;

The JOIN work matters strategically too. “ClickHouse can’t join” has been the standard objection from warehouse vendors for years. It was always overstated; with each ClickHouse 26.x release it gets less true. If your joins are still slow after upgrading, the cause is usually an ordering key or schema problem rather than the engine — we catalogued the usual suspects in ClickHouse performance pitfalls. The upstream repository is the fastest way to confirm whether a specific fix landed in your patch version.

Who should upgrade to ClickHouse 26.x, and to what

If you are on 25.8 LTS: move now. End of life is August 29, 2026. Target 26.3 LTS if your change-control process demands a shipped LTS today, but check for 26.8 LTS first — it is due this month and gets you a support window into 2027 plus everything described above, without another upgrade cycle in six months. If 26.8 has landed by the time you schedule the work, go straight there.

If you are on 26.3 LTS: you are supported through March 2027. Upgrade to 26.8 LTS when it is out and has a patch release or two behind it, on your own schedule. The pull is EXPLAIN ANALYZE, the JOIN and aggregation speedups, and text index and QBit maturity if those features are on your roadmap.

If you track stable monthly releases: you are on 26.7 already and know the drill. Our only caution: treat STREAM continuous queries as the experiment they are labelled as, and keep hypothetical indexes in your tuning workflow rather than your production DDL until you have burned them in.

ClickHouse 26.x upgrade mechanics and validation

Upgrade mechanics are the usual for ClickHouse: roll replicas one at a time, verify mixed-version replication is clean, and test any query that touches experimental settings — features that were experimental flags in 25.x may have changed defaults on the way to GA. Budget real time for validating materialized view behaviour across versions; materialized views are where upgrade surprises live.

-- 1. Before you touch anything: capture every setting you have
--    changed from the defaults of the version you are leaving.
SELECT name, value, default, description
FROM system.settings
WHERE changed
ORDER BY name;

-- 2. After each replica restarts: replication must be clean
--    before you move on to the next one.
SELECT
    database,
    table,
    is_readonly,
    absolute_delay,
    queue_size,
    inserts_in_queue,
    merges_in_queue
FROM system.replicas
WHERE is_readonly
   OR absolute_delay > 60
   OR queue_size > 100;

-- 3. Materialized views: compare refresh status against the
--    pre-upgrade baseline, not against your expectations.
SELECT
    database,
    view,
    status,
    last_success_time,
    exception
FROM system.view_refreshes
ORDER BY database, view;

-- 4. Catch queries that started failing on the new version.
SELECT
    type,
    exception_code,
    any(exception) AS sample,
    count()        AS failures
FROM system.query_log
WHERE event_time > now() - INTERVAL 1 HOUR
  AND type IN ('ExceptionBeforeStart', 'ExceptionWhileProcessing')
GROUP BY type, exception_code
ORDER BY failures DESC;

Two things are worth doing before the maintenance window rather than during it: take a verified backup, and rehearse the restore. Our guides to ClickHouse-Backup for backup and restore operations and to disaster recovery drills exist because “we have backups” and “we have tested restores” are different statements. Pair that with the query and IOPS metrics you should already be watching and you have a rollback story rather than a hope.

Frequently asked questions about ClickHouse 26.x

Is ClickHouse 26.x safe for production?

Yes, with one caveat. The three features this post covers — QBit, the text index, and Iceberg writes — were all promoted to production status in 26.2, and 26.3 is a supported LTS through March 2027. The parts to keep out of production are the ones the project still labels experimental, notably STREAM continuous queries.

Which ClickHouse 26.x version should I run?

If you need an LTS, run 26.3 today, or 26.8 once it has a patch release or two behind it. If you track monthly stable, 26.7.3.19 is the current release. The one answer that is wrong in every case is staying on 25.8 past August 29, 2026.

Do I still need a separate vector database with ClickHouse 26.x?

For most workloads, no. QBit plus the vector similarity index covers candidate generation and reranking on data you already store, in one system. A dedicated engine still wins on specialised ANN tuning and very high query-per-second serving, so the honest answer depends on whether vector search is your product or a feature of it.

Can the ClickHouse 26.x text index replace Elasticsearch for log search?

For token and phrase lookups over large log volumes, the 26.2 GA closes most of the gap and 26.7 phrase search closes more of it. Elasticsearch still wins on relevance scoring, analyzer breadth, and the tooling around them. It is worth costing out if search is the main reason you keep the cluster.

What usually breaks when upgrading to ClickHouse 26.x?

Settings that were experimental in the 25.x line may ship different defaults on the way to GA, so any query pinned to an experimental setting needs a test. Materialized views are the other recurring surprise. Roll replicas one at a time and check system.replicas between each one.

Getting help with a ClickHouse 26.x upgrade

One more signal worth noting: ClickHouse Inc. raised a $400M Series D in January 2026 at roughly a $15B valuation, and its named customers include OpenAI, Anthropic, and Tesla. Whatever you think of valuations, the engineering investment behind the release cadence above is not slowing down. ClickHouse 26.x is the strongest argument yet that ClickHouse is a platform rather than a niche engine — but platforms still need people who run them well.

ChistaDATA provides full-stack ClickHouse consulting, 24×7 production support, and managed services — from ClickHouse 26.x upgrade planning and LTS lifecycle management to performance engineering on the newest features in this line. If 25.8 LTS is still anywhere in your fleet, the clock on that one is measured in days. Talk to us at chistadata.com.