ClickHouse Changelog

Backward Incompatible Changes

• Data type serialization: Propagate data types serialization versions to nested data types. String serialization version with_size_stream now applies to String types inside Array/Map/Variant/JSON/etc. Controlled by propagate_types_serialization_versions_to_nested_types (enabled by default). Upgrade is safe, but downgrade is not — data written by 26.3 in columns with nested types will be unreadable in older versions.
• Skip index type: Removed the hypothesis skip index type. Creating tables with INDEX ... TYPE hypothesis now produces an error.
• Function removal: Removed experimental detectProgrammingLanguage function.
• NOT operator precedence: Fixed to match SQL standard. NOT now binds looser than IS NULL, BETWEEN, LIKE, and arithmetic operators. Queries relying on previous non-standard behavior may change results.
• Skip index filenames: Fixed skip index files not respecting replace_long_file_name_to_hash setting. Long-named indices are now hashed like column files. Backward compatible for upgrades, but downgrading may cause long-named indices to be ignored.
• Async insert default: Async insert is now enabled by default. Batching all small inserts by default. Can be disabled at config, session, query, or table level. Set compatibility=<version less than 26.2> for previous behavior.
• MySQL datatype mapping: Changed default mysql_datatypes_support_level to decimal,datetime64,date2Date32, enabling proper mapping of MySQL DATE/DECIMAL/DATETIME to Date32/Decimal/DateTime64. Previously MySQL DATE mapped to Date (cannot represent dates before 1970-01-01).
• UDF stderr handling: Changed default stderr_reaction from throw to log_last for executable UDFs. UDFs writing warnings to stderr no longer fail when exit code is 0.
• Metadata changes: Fixed normal projections metadata so multi-column sorting keys are properly recognized.
• Index function API: mergeTreeAnalyzeIndexes{,UUID} now accepts array of part names instead of regexp for improved performance (experimental).

New Features

• Bucketed Map serialization: Added bucketed serialization for Map columns in MergeTree with map_serialization_version = 'with_buckets'. Keys split into hash-based buckets, providing 2-49x speedup for single-key lookups. New settings: map_serialization_version, max_buckets_in_map, map_buckets_strategy, map_buckets_coefficient, map_buckets_min_avg_size.
• Materialized CTE: Support evaluating CTEs only once and storing results in temporary tables.
• SQL-standard functions: Allow certain functions like NOW without parentheses for compatibility.
• naturalSortKey function: Added naturalSortKey(s) function.
• JSON input for JSONExtract: Support native JSON/Object input for JSONExtract functions.
• Nullable query parameters: If a query parameter has Nullable type and is not specified, assume value is NULL.
• ZooKeeper auxiliary support: Support auxiliary ZooKeeper for Replicated database.
• JSON has function: Support has function for JSON type to check path existence.
• mergeTreeTextIndex function: New table function to read data directly from a text index for introspection.
• table_readonly setting: Add MergeTree setting to mark tables as read-only.
• Partition pruning settings: New use_partition_pruning setting and use_partition_key alias to disable partition pruning.
• Iceberg EXECUTE expire_snapshots: Support ALTER TABLE ... EXECUTE expire_snapshots('<timestamp>') for Iceberg tables.
• HTTP handlers per port: Allow each type=http entry in <protocols> to specify custom <handlers> key for different routing rules per port.
• EXPLAIN improvements: Add pretty=1 option for tree-style indented output and compact=1 to collapse Expression steps.
• Access control: New restore_access_entities_with_current_grants setting for restored users/roles in backups.
• Unicode functions: Added caseFoldUTF8, removeDiacriticsUTF8, and normalizeUTF8NFKCCasefold functions.
• asciiCJK tokenizer: New tokenizer for full-text indexes and tokens function using Unicode word boundary rules.
• Unavailable shards limits: New max_skip_unavailable_shards_num and max_skip_unavailable_shards_ratio settings to limit silent shard skipping.
• SOME keyword: Added SOME keyword for subquery expressions (identical to ANY).
• FixedString output formatting: New output_format_trim_fixed_string setting to strip trailing null bytes.
• Parenthesized table joins: Support parenthesized table join expressions in FROM clause.
• toDaysInMonth function: Returns number of days in the month of specified date.

Experimental Features

• WebAssembly UDFs: Experimental support for WebAssembly-based user-defined functions with Wasmtime backend.
• External SQL dialects: Support for external SQL dialects using polyglot library.
• ALP codec: Floating-point compression codec (without ALP_rd fallback).
• Lazy JSON type hints: Experimental lazy type hints for JSON columns. ALTER TABLE ... MODIFY COLUMN json JSON(path TypeName) completes as metadata-only operation without rewriting data.
• YTsaurus parallel reads: Enable parallel reads from YTsaurus table engine.

Performance Improvements

• Object storage reads: Improved data lake reading performance by resizing pipeline to number of processing threads, providing ~40x improvements on multi-core machines.
• Parallel replicas logic: Clarified relationship between enable_parallel_replicas and automatic_parallel_replicas_mode. Queries use parallel replicas if enable_parallel_replicas > 0. automatic_parallel_replicas_mode=1 uses statistics-based decision; mode=0 uses parallel replicas for all supported queries.
• Enhanced partition pruning: Allow partition pruning when predicate contains comparison operators and partition key is wrapped in deterministic function chain (e.g., cityHash64(x) % 5 > 2, toYYYYMM(x) < 2026).

• Fixed sumCount aggregate function unable to read older serialized states after introduction of Nullable(Tuple)
• Fixed exception in tuple comparison involving Nothing type with GROUPING SETS and ORDER BY
• Fixed non-deterministic uncompressed_hash computation for Compact MergeTree parts with multiple compression codecs
• Fixed logical error during INSERT SELECT with JSON and buckets in shared data
• Fixed MEMORY_LIMIT_EXCEEDED being reported as CORRUPTED_DATA during SummingMergeTree and CoalescingMergeTree merges
• Fixed "Context has expired" exception for correlated subqueries with table functions like url()
• Fixed exceptions and incorrect behavior in optimize_syntax_fuse_functions with aggregate projections and Date types
• Fixed replaceRegexpOne to extract query rewrite producing wrong results; fixed exception with GROUP BY ... WITH CUBE and group_by_use_nulls=1
• Fixed DROP DATABASE hanging indefinitely with database_atomic_wait_for_drop_and_detach_synchronously
• Fixed KILL QUERY unable to terminate queries stuck in WITH FILL, dictionary loading, or ALTER DELETE
• Fixed security issue: loop table function bypassed row policies and column-level grants
• Fixed incorrect partition pruning with pre-epoch DateTime64 and toDate() function
• Fixed hasPartitionId returning incorrect results with multiple partitions
• Fixed possible crashes reading empty granules in advanced shared data in JSON
• Fixed Cannot schedule a file error on INSERT into Distributed due to race between DROP and INSERT
• Fixed server crash in mapContainsKey/mapContainsKeyLike with tokenbf_v1 skip index
• Fixed LOGICAL_ERROR with LowCardinality inside compound types in various functions
• Fixed LOGICAL_ERROR in MergingAggregatedTransform with ARRAY JOIN and merge() over Distributed tables
• Fixed server crash caused by uncaught exception in HTTP connection pool destructor
• Fixed incorrect result with grace_hash algorithm and non-equi joins
• Fixed performance inefficiency in DeltaLake metadata scanning
• Fixed data race in ZooKeeper client between sendThread and receiveThread
• Fixed bug preventing CTE with distributed insert selects
• Fixed exception from CachedOnDiskReadBufferFromFile::readBigAt
• Fixed LOGICAL_ERROR in Alias engine with materialized columns
• Fixed Keeper data loss after restart with Azure Blob Storage
• Fixed JIT miscompilation of sign function for integer types wider than Int8
• Fixed DUPLICATE_COLUMN exception and silent NULLs reading Delta Lake tables with name mode column mapping
• Fixed mutation after lightweight update and secondary indices
• Fixed incorrect result of FINAL queries mixing primary and non-primary key skip indexes
• Enforced READ ON FILE checks for scalar file() and DESCRIBE TABLE file()
• Fixed crash with glob pattern in file() when directory contains dangling symlinks
• Fixed segfault in query plan optimization converting outer join to inner join with arrayJoin
• Fixed ProtobufList format not working with Kafka engine
• Fixed logical error with analyzer_compatibility_join_using_top_level_identifier and ARRAY JOIN
• Set Watch component for watch responses in aggregated_zookeeper_log
• Fixed partition pruning with FINAL deduplication when partition key not covered by sorting key
• Fixed logical error in kql_array_sort_asc/kql_array_sort_desc with constant array arguments
• Fixed out-of-bounds access in ColumnConst::getExtremes with extremes = 1
• Fixed potential deadlock with concurrent MOVE PARTITION operations
• HTTP server now returns error message in response body for 400 Bad Request
• Fixed wrong results with distributed index analysis and query condition cache
• Fixed LOGICAL_ERROR in MergeTreeSetIndex with toDate conversion on key columns
• Fixed LOGICAL_ERROR with RIGHT JOIN wrapped in CROSS JOIN in legacy join code path
• Fixed segfaults and OOM from corrupted DDSketch deserialization in quantilesDD
• Fixed LOGICAL_ERROR with correlated columns in lambda functions like arrayMap
• Fixed logical error in caseWithExpression with materialize(NULL) or Nullable(Nothing) arguments
• Fixed bad cast exception when filtering _table virtual column in merge table function
• Fixed sporadic deduplication failure with inconsistent cleanup ordering in ZooKeeper
• Fixed exception with ORDER BY ... WITH FILL used together with LIMIT BY
• Fixed silent data corruption inserting Parquet/Arrow Date into Enum column
• Fixed exception reading Arrow file with Array column into table with Nested column
• Fixed MATERIALIZE INDEX and MATERIALIZE PROJECTION mutations getting stuck
• Fixed exception reading from Nullable(Tuple(...)) with colliding element names
• Fixed exception when joining Merge table wrapping Distributed table

Multiple bug fixes including:

Parquet and Data Format Fixes:

• Fixed incorrect Parquet Bool to FixedString conversion in native V3 reader
• Fixed HTTP Basic Auth to accept base64 credentials without padding

Query Execution Fixes:

• Fixed incorrect partition pruning with Nullable partition key columns
• Fixed rare exception in pipeline executor during query cancellation
• Fixed 'Column identifier is already registered' exception with count_distinct_optimization and QUALIFY
• Fixed exception with IN/NOT IN using LowCardinality column arguments
• Fixed 'Pipeline stuck' exception in full_sorting_merge joins
• Fixed LOGICAL_ERROR with TTL merging and aggregate projections
• Fixed logical error with CROSS JOIN and INNER JOIN USING
• Fixed null pointer dereference in dictGetOrDefault with Nullable keys
• Fixed exception in DISTINCT queries with aggregate projections and LowCardinality
• Fixed LOGICAL_ERROR with arrayJoin in filter expression with OUTER JOIN
• Fixed logical error with parallel replicas and optimize_aggregation_in_order
• Fixed pipeline deadlock with sort_overflow_mode and window functions
• Fixed column rollback in Buffer engine during exception handling

Type System and Comparison Fixes:

• Fixed bad cast exception in null-safe comparison with Dynamic/Variant and NULL
• Fixed IS DISTINCT FROM with Dynamic/Variant vs NULL returning incorrect results

Index and Optimization Fixes:

• Fixed tryGetColumnDescription to filter subcolumns by parent column kind
• Fixed text index usage with other skip indexes
• Fixed distributed index analysis with expressions in primary key
• Fixed S3 requests being incorrectly retried on non-retryable errors
• Fixed set skip index usefulness detection with OR predicates

ClickHouse Keeper Fixes:

• Fixed Keeper disconnecting Java ZooKeeper clients after addWatch request
• Fixed zk_followers and zk_synced_followers metrics not decreasing
• Fixed Keeper's secure raft port ignoring cipherList and dhParamsFile configuration
• Fixed misleading Keeper log messages about operation timing
• Fixed Keeper TCP connections preventing graceful server shutdown

Join and Filter Fixes:

• Fixed LOGICAL_ERROR with PREWHERE and IN subquery on MergeTree tables
• Fixed exception 'Sorting column wasn't found in ActionsDAG' with query_plan_convert_join_to_in
• Fixed BAD_GET exception with non-boolean expression in WHERE and SELECT with JOIN
• Fixed LOGICAL_ERROR with read_in_order_through_join and parallel replicas

Data Type and Function Fixes:

• Fixed MongoDB dictionary source failing with named collections
• Fixed LOGICAL_ERROR when Identifier is empty after parameter substitution
• Fixed exception with input table function as argument of remote
• Fixed outdated data parts resurrection from incorrect cleanup
• Fixed exception in LogicalExpressionOptimizerPass with Variant return type
• Fixed parseDateTimeBestEffort incorrectly parsing month/weekday prefixes
• Fixed UNKNOWN_IDENTIFIER with merge() table function over tables with different JSON parameters
• Fixed optimize_skip_unused_shards with Distributed storage in Views
• Fixed tuple subcolumn access by name for external tables
• Fixed reverseUTF8 exception on invalid UTF-8 input
• Fixed LOGICAL_ERROR with FINAL, PREWHERE, constant WHERE and column-independent aggregates

Configuration and System Fixes:

• Fixed system.trace_log entries for dictionary auto-reloads having non-empty query IDs
• Fixed crash from null pointer dereference in system tables iteration
• Fixed SYSTEM START REPLICATED VIEW not waking up refresh task
• Fixed 'Inconsistent table names' exception with view() containing JOINs
• Fixed adjusting RLIMIT_SIGPENDING via pending_signals

Security Fix:

• Fixed RBAC bypass allowing users to DESCRIBE any table via remote/cluster functions without SHOW_COLUMNS privilege

Performance Fixes:

• Fixed unexpected result with read_in_order_use_virtual_row and monotonic functions
• Fixed JIT expression compilation bugs preventing optimization passes

TTL and Transactions:

• Fixed LOGICAL_ERROR in renameAndCommitEmptyParts with concurrent TRUNCATE TABLE and OPTIMIZE TABLE
• Fixed decimal overflow when partition pruning with DateTime64

Performance Improvements:

• Allow read-in-order optimization and primary-key pruning with Nullable CAST target types for monotonic conversions
• Allow index pruning and filter pushdown when comparing integral columns with float literals
• Added SLRU cache for Parquet metadata to improve read performance
• Support swapping sides of ANTI, SEMI and FULL joins based on optimizer statistics
• Optimized granules skipping for pointInPolygon and fixed index analysis issues
• Improved levenshteinDistance function performance
• Optimized batch decimal type conversions by avoiding per-element function calls
• Iceberg tables now support asynchronous metadata prefetching and cached metadata usage
• S3Queue ordered mode uses ListObjectsV2 StartAfter to reduce ListObjects calls
• Lowered memory usage for inserts deduplication in sync mode
• Use arch-specific cache line size instead of hardcoded 64-byte value
• Optimized text index dictionary reading and analysis
• Sped up LZ4 decompression of 16 byte blocks in ARM
• Refactored tokenization to high-performance interface with SIMD support
• Improved text index analysis for queries with combined conditions
• Improved performance of queries with constant expressions generating large arrays/maps
• Fixed key condition analysis for DateTime64 primary keys compared with integer constants
• Setting optimize_syntax_fuse_functions enabled by default
• Optimized avgWeighted aggregate function with local accumulators (~27% improvement for Nullable inputs)
• Improved performance and reduced memory usage for parallel window functions and arrayFold workloads
• Improved sorted merges performance
• Optimized INTERSECT ALL and EXCEPT ALL
• Added read_in_order_use_virtual_row optimization support for reverse-order reads
• Reduced cache contention in RIGHT and FULL JOINs
• Optimized PrefetchingHelper::calcPrefetchLookAhead with integer arithmetic
• Reduced Keeper memory consumption by replacing absl::flat_hash_set with CompactChildrenSet (KeeperMemNode reduced from 144 to 128 bytes)

Feature Improvements:

• Aggregate projections now correctly supported in views
• Support OUTER to INNER join conversion optimization with join_use_nulls
• Improved subcolumns reading with correct sizes calculation
• Separate jemalloc arenas for mark, uncompressed and page caches to avoid memory fragmentation
• Tables with DELETE TTL rules can now use vertical merge algorithm
• Apply data skipping indexes during distributed index analysis
• Secondary index marks prewarmed when prewarm_mark_cache setting enabled
• Reduced locking during access control
• Compound AND conditions in row policies and PREWHERE now decomposed for sorting-key atoms extraction
• Reduced lock contention in MergeTreeBackgroundExecutor
• Fixed excessive memory usage (~514 MiB) during format auto-detection for non-Arrow data
• Parse GeoParquet files with different Geo types in same column
• Introduced tokensForLikePattern SQL function for LIKE pattern tokenization
• Added {_schema_hash} placeholder for S3 table engine
• SymbolIndex, addressToSymbol, system.symbols, buildId now work on macOS
• system.stack_trace table now works on macOS
• Added per-server LDAP config option <follow_referrals> to control referral chasing
• Track data skipping indices used in query execution via skip_indices column in query_log
• ACCESS_DENIED hints no longer reveal column names unless user can show all required columns
• Added dedicated cleanup thread for MergeTree to prevent cleanup delays
• Reload cluster config if IPs of local server's hostname changed
• Allow optimize_aggregators_of_group_by_keys to correctly optimize in GROUPING SETS queries
• Keeper-bench: report errors in metrics and generate JSON metrics file
• Added ROLE clause to CREATE USER
• Internal_replication settings can now be set for Replicated database clusters
• New setting allow_nullable_tuple_in_extracted_subcolumns controls Tuple subcolumns behavior

Add information about deferred filters as a separate item to EXPLAIN query output. Enable type_json_allow_duplicated_key_with_literal_and_nested_object by default to avoid errors about duplicated keys during JSON parsing. Keeper improvement: find_super_nodes command is more reliable when finding multiple super nodes by forbidding traversal of their children. Initial completion support for clickhouse-keeper-client. Flush async logging buffers in case of crash. Enable the impersonate feature by default (see EXECUTE AS target_user). Improve canceling queries with SQLite, MongoDB and MySQL table engines by KILL QUERY and cancel query (Ctrl+C). Add server setting jemalloc_profiler_sampling_rate to control jemalloc profiling. Support weights in concurrent bounded queue implementation. Add sslmode to allowed keys for PostgreSQL dictionary sources to support SSL connections. Show clear "no such file" error when passing non-existent file paths. Text indexes can now be built on Nullable and Array(Nullable) columns. Avoid dropping named collections that are dependencies of dictionary sources. Enable grace_hash join algorithm for queries with totals. Cancel background merges early in DROP DATABASE. Remove NetlinkMetricsProvider and use procfs exclusively for per-thread taskstats metric collection. Refactor Iceberg manifest file handling to fix caching issues. Optimize PREWHERE decisions for expressions like toDate(time). Add MaxAllocatedEphemeralLockSequentialNumber metric for ZooKeeper. Add new profile event KeeperRequestTotalWithSubrequests for better Keeper workload visibility. SYSTEM RELOAD DICTIONARIES now reloads dictionaries in topological order. Restart statistics cache after changing MergeTree settings. Only "alive" replicas participate in distributed index analysis. Add setting access_control_improvements.disallow_config_defined_profiles_for_sql_defined_users. Cap automatic parallel replicas heuristic to actual node count. Implement hedged requests and asynchronous reading for distributed index analysis. Deserialization of binary AggregateFunction states now requires consuming full input. Make TRUNCATE DATABASE respond to query cancellation. Improve keeper-bench with request pipelining and better stats. Support SAMPLE clause in distributed index analysis. Show chart title in dashboard even with empty results. Cap column lists in analyzer error messages to 10 entries. Return column stats from sub-queries with joins. Mark ZooKeeper session as expired immediately on finalization. Use more math functions from LLVM-libc. Reduce memory usage in system.jemalloc_profile_text. Add is_subrequest column to system.aggregated_zookeeper_log. Allow ALTER TABLE MODIFY COLUMN x TTL without specifying column type. Skip stale Keeper requests for disconnected sessions. Support text index on mapValues(map) with IN operator. Shell-like completion support in clickhouse keeper-client. Prevent Keeper mntr command from getting stuck. Reduce lock contention in Keeper dispatcher. Tolerate missing padding at the end of parquet file blocks. Fix how Alias table targets are saved as DDL dependencies. Fix wrong result or exception during reading subcolumns of ALIAS columns. Fix missing column in JOIN with non-standard identifier alias. Fix crashes in Kusto dialect functions with empty arguments. Forbid mounting local_object_storage outside user_files_path in clickhouse-client. Fix logical race in DeltaLake table engine on snapshot version change. Fix logical error on attaching a part in MergeTree with chained renames. Fix explicit settings being silently ignored when sent with compatibility. Fix client reporting NETWORK_ERROR instead of actual parsing error in INSERT with parallel parsing.