ClickHouse v26.5.6.64-stable 版本深度解析aiEmbed 嵌入函数、查询正确性修复与性能回归治理【免费下载链接】ClickHouseClickHouse® is a real-time analytics database management system项目地址: https://gitcode.com/GitHub_Trending/cli/ClickHouse导读本文以 ClickHouse 官方变更日志 docs/changelogs/v26.5.6.64-stable.md 为骨架深入解析 v26.5.6.64-stable 相对 v26.5.5.8-stable 的全部变更新增的实验性 AI 嵌入函数aiEmbed、S3 小文件读取性能回归修复、一系列新分析器兼容性开关以及 30 余项涉及 MergeTree 数据安全、查询正确性、安全加固与崩溃修复的缺陷修复。读完本文你将掌握每个变更的适用场景、关键配置项含默认值与取值说明并能结合仓库源码定位对应实现为升级评估与问题排查提供依据。一、版本发布概览v26.5.6.64-stable 是 2026 年度变更日志中的第一个稳定版条目见 docs/changelogs/v26.5.6.64-stable.md 开头的sidebar_position: 1发布形式为相对 v26.5.5.8-stable 的增量补丁版。整个变更日志按 ClickHouse 官方惯例分为五个区块Experimental Feature1 项aiEmbed嵌入函数Performance Improvement3 项聚焦对象存储小文件读取与 PREWHERE 优化Improvement5 项覆盖分析器兼容性、数据湖集成、MySQL 协议与系统表可见性Bug Fix官方稳定版中的用户可见行为问题30 余项是本次发布的主体Build/Testing/Packaging Improvement3 项含安全漏洞修复与依赖升级。其中每一行变更均标注了对应的 backport issue如#108984与原始 PR 编号便于读者在仓库 Git 历史中回溯提交。二、实验特性aiEmbed嵌入函数2.1 功能定位本次发布通过 backport 引入了新的实验性函数aiEmbedsrc/Functions/aiEmbed.cpp用于在 ClickHouse 内部直接调用 LLM 提供商的嵌入接口把文本转换为向量aiEmbed(text, model[, params])text要嵌入的文本String或Nullable(String)model嵌入模型名称必须为常量Stringparams可选常量Map(String, String)函数特有键为dimensions目标向量维度0或省略表示使用模型原生维度通用键为credentials指定命名集合。函数返回Array(Float32)。返回值语义在源码FunctionDocumentation中有明确说明若输入为NULL或空字符串、请求失败且ai_function_throw_on_error被禁用、或配额超限且ai_function_throw_on_quota_exceeded被禁用均返回空数组src/Functions/aiEmbed.cpp。2.2 实现要点源码级从 src/Functions/aiEmbed.cpp 的实现看该函数有几个值得注意的设计决策有状态且适合短路执行每次调用会更新配额并可能发起昂贵的 HTTP 请求因此isStateful()返回true同时它不参与常量折叠也不适合短路参数求值。显式处理 NULL 与常量列useDefaultImplementationForNulls与useDefaultImplementationForConstants均返回false意味着NULL/空字符串行不会触发 HTTP 调用而是直接映射为输出中的空数组[]避免无效请求。批量请求单个数据块内的输入按每批最多ai_function_embedding_max_batch_size条合并为一个 HTTP 请求减少请求开销src/Functions/aiEmbed.cpp。默认凭证分离嵌入端点与对话端点不同因此aiEmbed使用独立的默认凭证设置ai_function_embedding_default_credentials区别于文本类 AI 函数。模型必须显式传入与文本类 AI 函数不同aiEmbed不从命名集合或参数映射中读取model若命名集合定义了model会被拒绝。源码中注册的introduced_in标注为 26.6而本 changelog 将其作为 backport 实验特性列入 26.5.6因此在 26.5.6 分支上使用时应将其视为实验功能并关注后续正式发布。2.3 相关设置与示例aiEmbed依赖以下会话设置定义于 src/Core/Settings.cpp设置说明ai_function_embedding_max_batch_size每个 HTTP 请求打包的最大文本条数ai_function_embedding_default_credentials参数映射中未提供credentials时的默认命名集合ai_function_request_timeout_sec单次请求超时秒实现中覆盖 HTTP receive timeoutai_function_max_retries失败重试次数ai_function_retry_initial_delay_ms重试初始退避延迟毫秒ai_function_throw_on_error出错时是否抛异常官方文档示例源码FunctionDocumentation内嵌-- 嵌入单个字符串已设置默认凭证时可省略 credentials SELECT aiEmbed(Hello world, text-embedding-3-small, map(credentials, ai_embedding_credentials)); -- 显式指定输出维度 SELECT aiEmbed(Hello world, text-embedding-3-small, map(credentials, ai_embedding_credentials, dimensions, 256)); -- 嵌入整列文本 CREATE TABLE articles (title String) ENGINE Memory; INSERT INTO articles VALUES (ClickHouse is a fast analytical database.); SELECT aiEmbed(title, text-embedding-3-small, map(credentials, ai_embedding_credentials, dimensions, 256)) FROM articles LIMIT 10;在仓库中可同时看到aiSimilaritysrc/Functions/aiSimilarity.cpp、FunctionBaseAIsrc/Functions/FunctionBaseAI.cpp与IAIProvidersrc/Functions/AI/IAIProvider.h等配套基础设施说明该函数与既有 AI 函数家族共享提供商抽象、配额跟踪与重试逻辑。三、性能改进对象存储小文件读取与 PREWHERE3.1 恢复 S3 表函数的小对象预取prefetch本次修复针对 PR #71781 引入的性能回归通过s3()等表函数读取对象存储中大量小文件时预取prefetch机制失效退化为同步读取导致单线程/低并发场景下读取大量小文件显著变慢。本版本恢复了对小对象的预取PR #108872。适用场景任何通过s3、s3Cluster等表函数批量读取大量小对象的查询典型如日志文件目录、小分片数据集的扫描。3.2 预取覆盖文件系统缓存路径紧随其后的修复PR #109478把首次小对象预取扩展到了走文件系统缓存的读取路径上一项修复仅恢复了对非缓存读取的预取而启用filesystem_cache_name后许多小文件的读取例如S3Queue摄取场景仍保持同步、受延迟主导。本次版本让缓存读取路径同样触发初始小对象预取进一步消除S3Queue摄取与缓存启用的性能瓶颈。3.3 Map 子列参与 PREWHERE 优化PREWHERE 优化在选择下推列时需要评估各列在磁盘上的大小。本版本修复了 Map 子列subcolumn磁盘大小未计入的问题PR #110623纠正了此前 PR #99200 引入的 PREWHERE 回归使带Map列的表在做 PREWHERE 列选择时能更准确地权衡 I/O 代价。四、改进项兼容性、数据湖与协议细节4.1 新分析器兼容性设置HAVING 非聚合项回退新增设置analyzer_compatibility_allow_non_aggregate_in_having默认false定义于 src/Core/Settings.cpp。启用后新分析器模拟 v24.3 之前查询分析器的旧行为将HAVING中非聚合的 AND 连接项移动到WHERE而不是抛出NOT_AN_AGGREGATE错误。源码注释明确了边界条件src/Core/Settings.cpp实现见 src/Analyzer/Resolve/QueryAnalyzer.cpp包含聚合、grouping或非确定性函数的连接项保留在HAVING若任一连接项含窗口函数或有状态函数如rowNumberInBlock整个重写被禁用与旧PredicateExpressionsOptimizer行为一致当GROUP BY使用WITH CUBE、WITH ROLLUP、WITH TOTALS或GROUPING SETS时该设置被忽略。这是一个为历史 SQL 迁移设计的兼容开关标准合规的拒绝是默认行为启用它只为让那些曾被旧分析器静默接受的查询继续工作。4.2 新分析器兼容性设置别名优先于子列另一新增设置analyzer_compatibility_prefer_alias_over_subcolumn默认falsesrc/Core/Settings.cpp。当形如b.id的多段标识符既可以解释为表别名b的id列又可以解释为某列的 Tuple 子列b.id时默认false新分析器优先按子列解释启用true优先按别名-前缀解释恢复旧分析器的解析行为。该开关用于规避 CTE/子查询内联JOIN场景下星号重命名列如b.id将内部表标识符泄漏到外层作用域、从而触发AMBIGUOUS_IDENTIFIER等错误的问题。4.3 DataLakeCatalogOneLake 默认改用 Blob 端点DataLakeCatalog数据库新增catalog_type onelake的默认端点切换默认使用 OneLake Blob 端点.blob.fabric.microsoft.com读取表数据设置onelake_use_blob_endpoint false可恢复旧的 DFS 端点.dfs.fabric.microsoft.com行为PR #106843。同时旧版本25.12 及更早创建、auth_header配置损坏的DataLakeCatalog数据库在升级到 26.2 后不再阻塞服务启动auth_header仅在CREATE时校验ATTACH时目录改为首次使用时惰性构建PR #108674单个配置错误或不可达的目录数据库不再阻止服务器启动。4.4 系统表可见性设置拆分恢复show_data_lake_catalogs_in_system_tables作为仅控制DataLakeCatalog在system.tables、system.columns、system.completions中可见性的设置同时新增默认启用的show_remote_databases_in_system_tables允许用户单独隐藏MySQL与PostgreSQL数据库PR #109082。4.5 MySQL 握手协议修复修复 MySQL 握手中对auth_response长度的读取长度字节 128时因按有符号char读取而被解释为数十亿字节multi-gigabyte的值PR #107384。4.6 自适应编码选择adaptive codec的读取侧前置MergeTree 现在可以读取压缩流中各块使用不同 codec 的数据PR #108592。这是自适应 codec 选择特性issue #105404的读取侧前置工作属于格式层面的向前兼容准备。4.7 调试体验更简单的指标添加方式针对调试期间难以在 dashboard 上快速添加多个指标的问题本次改进支持直接从源码或文档添加指标PR #109449降低开发者在调试会话中扩展指标面板的摩擦。五、缺陷修复解析按主题分类以下为 30 余项用户可见行为修复按影响面归类展开。5.1 MergeTree 数据安全与一致性RENAME COLUMN 与后台合并竞态PR #104822ALTER TABLE ... RENAME COLUMN与并发OPTIMIZE TABLE ... FINAL或任意后台合并之间存在竞态可能导致重命名列的数据被静默替换为默认值。修复通过在发布新内存元数据与在current_mutations_by_version注册重命名 mutation 期间持有currently_processing_in_background_mutex关闭了竞态窗口。空 part 迁移到 plain_rewritable 磁盘崩溃PR #107040ALTER TABLE ... MOVE PARTITION ... TO DISK移动remove_empty_parts 0保留的空 part 到plain_rewritable磁盘时导致服务崩溃已修复。采纳 part 后的 FINAL 重复行PR #107481CREATE TABLE ... CLONE AS、ATTACH PARTITION ... FROM、MOVE PARTITION ... TO TABLE把 plainMergeTree的 part 采纳进ReplacingMergeTree、SummingMergeTree或AggregatingMergeTree后SELECT ... FINAL/OPTIMIZE TABLE ... FINAL返回重复行。修复方案是在源与目标引擎不同时将采纳 part 的 merge level 重置为 0使目标表在下一次合并时正确去重。projection 读取 ADD COLUMN DEFAULT 错误PR #108569当投影projection创建后执行ALTER TABLE ... ADD COLUMN ... DEFAULTSELECT *由投影回答时返回的是列类型默认值如0而非DEFAULT值如-1基础表读取原本正确只有投影回答的读取受影响直到投影重建。ALIAS 列含 IN 操作符时的逻辑错误PR #111039在存在使用IN操作符的 ALIAS 列包括经另一 ALIAS 列间接使用的表上执行ALTER TABLE ... DROP COLUMN、ALTER TABLE ... DELETE/UPDATEmutation 及轻量 DELETE会触发LOGICAL_ERRORNo set is registered for key。异步插入与去重的崩溃与数据丢失崩溃PR #109229异步插入 去重时若optimize_on_insert使插入块变为空例如SummingMergeTree中行求和为零服务崩溃静默数据丢失PR #111049async_insert1, async_insert_deduplicate1时多个不同insert_deduplication_token的异步条目合并为一次 flush 并写入不同分区时每个 token 会被注册到 flush 触及的所有分区的去重日志而非其行实际落盘的分区。后续在未写入过的分区复用同一 token 的插入会被静默去重丢弃。现在 token 仅注册到行实际落盘的分区。物化/虚拟列上的 GROUP BY mutationPR #109532修复含物化列或启用持久化虚拟列的表上的 group-by mutations这些列现在使用any聚合。rollup 合并无限重调度PR #109410修复 rollup 合并被无限重新调度的问题。文件段争用回归PR #109577修复 26.1 引入的多余文件段file segment争用问题。5.2 查询正确性查询条件缓存的三个修复查询条件缓存use_query_condition_cache默认true定义见 src/Core/Settings.cpp在本版本集中修复SAMPLE 错误结果PR #108488SELECT [...] SAMPLE [...]与查询条件缓存组合时返回错误结果on-fly mutations / 行级安全策略污染缓存PR #107145apply_mutations_on_fly 1的查询在 PREWHERE 前过滤行可能污染缓存使后续apply_mutations_on_fly 0且谓词相同的查询跳过本应读取的 marks、返回过少行行级安全策略作为过滤器置于 PREWHERE 之前也有同样问题。Distributed 通过 Merge 查询时 skip-unused-shards 失效PR #106250Distributed表经由Merge表或merge表函数查询、谓词作用于其上时optimize_skip_unused_shards未生效且force_optimize_skip_unused_shards会错误失败。分布式 ALIAS 列错位PR #107675分布式查询选择共享公共子表达式的ALIAS列时列可能错位、值被放到错误的列名下。运行时 JOIN 过滤器与 JSON 列PR #107663运行时 join filter 对 JSON 列产生错误结果。UNION/INTERSECT/EXCEPT 的 Sparse 列冲突PR #107041当UNION/INTERSECT/EXCEPT的一个分支读取 Sparse 序列化列、另一分支读取同一列的完整形式例如向物化视图推送时触发Block structure mismatch in UnionStep stream逻辑错误debug/sanitizer 构建下服务中止release 构建下Code: 49。文本索引谓词在 PREWHERE 与 WHERE 中重复PR #110710Merge表叠在Distributed表上查询时同一文本索引谓词同时出现在PREWHERE与WHERE触发Column ... already added for reading逻辑错误。Iceberg 读取修复PR #110233默认排序顺序引用需要引用的列如timestamp时合成存储ORDER BY解析失败SYNTAX_ERROR导致表不可读。RestCatalog 空判断PR #106301Iceberg REST 目录包含表时RestCatalog::empty返回错误结果。5.3 聚合状态与崩溃修复深层嵌套表达式/字面量堆栈溢出PR #108493max_parser_depth设为较大值时[[[ ... ]]]或array(array(...))等深度嵌套表达式导致栈溢出崩溃。深层嵌套字面量复制/析构崩溃PR #110393深度嵌套的Array/Tuple/Map/Object字面量被复制或销毁时原生栈溢出。uniqExact 聚合状态并行合并崩溃与竞态PR #108928、PR #109389GROUPING SETS/ROLLUP/CUBE且max_threads 1时合并uniqExact状态的分段错误以及两级集合two-level sets并行合并的数据竞态罕见崩溃。groupArrayLastMerge 越界PR #109485聚合函数状态反序列化缺少校验损坏状态导致越界访问现已加入校验。quantileTDigest 状态并发序列化溢出PR #110263quantileTDigest系列聚合状态列作为GROUP BY键被多线程并发序列化时可能触发 heap-buffer-overflow 崩溃。Dynamic/Variant 嵌套在 Tuple 中的转换PR #108061accurateCastOrNull/accurateCastOrDefault把Tuple内嵌套的Dynamic或Variant列转换为非Nullable元素类型时出现逻辑错误。5.4 安全与权限query_log 权限泄漏PR #106425system.query_log的used_privileges与missing_privileges列可能包含来自其他用户、数据库或会话的不相关早期查询的权限字符串现已修复。SYSTEM RESET DDL WORKER 权限收紧PR #108460SYSTEM RESET DDL WORKER现在要求新增的SYSTEM RESET DDL WORKER权限。此前任何已认证用户包括readonly用户都能执行并反复重置 DDL worker 状态从而阻塞ON CLUSTERDDL。catboostEvaluate 模型路径限制PR #108463catboostEvaluate的模型路径被限制在user_files目录内与file()及字典数据源一致。此前函数接受任意文件系统路径且无包含性检查可探测并触发读取user_files之外的文件。MySQL 协议命令权限对齐PR #108508MySQL 线协议的COM_FIELD_LISTmysql_list_fields与COM_INIT_DBUSE database现在强制执行与其 SQL 等价物SHOW COLUMNS/DESCRIBE与USE相同的访问控制此前可能泄露仅部分列权限用户的表列名并在无SHOW DATABASES权限时切换当前数据库。敏感信息隐藏system.query_views_log.view_query中的敏感信息被隐藏PR #108214getClientHTTPHeader中按 RFC 9110 对 header 大小写不敏感authorization被加入过滤名单PR #109791。5.5 配置、备份与其他HTTP 禁止头大小写不敏感PR #108509http_forbid_headers改为大小写不敏感匹配——禁止Authorization也会拦截authorization、AUTHORIZATION等变体配置的header_regexp模式无需显式(?i)即可大小写不敏感匹配。S3 设置优先级PR #109251URL 作用域的s3端点块现在优先于顶层s3默认值。增量备份不再内嵌 S3 凭证PR #107357增量备份不再在.backup元数据文件的base_backup定位符中存储 S3 凭证。use_same_s3_credentials_for_base_backup 1或显式 base-backup 凭证与定位符匹配时存储非机密标记且无需额外恢复期设置即可还原凭证不同的旧备份需在RESTORE时通过base_backup设置传入旧版本创建的内嵌凭证备份仍可还原。只读表后台刷新PR #108034只读表刷新数据 part 时的瞬时错误不再永久停止后台刷新任务。system.tables 跳过数据库PR #109723查询仅读取name/database列时system.tables对按数据库授权per-database grants的用户静默跳过数据库26.2 引入已修复。格式模式推断Nullable(Tuple)PR #109185Arrow、ArrowStream、Avro格式及旧版ORC/Parquet读取器对可空 struct 列推断出Nullable(Tuple)而该类型不被允许allow_experimental_nullable_tuple_type关闭导致DESCRIBE返回的类型被CREATE TABLE拒绝。现在推断结果不再产生被禁用的Nullable Tuple类型。Arrow Java 19.0.0 空嵌套列PR #111101读取 Apache Arrow Java 19.0.0随 Apache Spark 分发生成的空嵌套Array/Map列时此前因偏移缓冲过小报INCORRECT_DATA现已修复。六、构建/测试/打包改进与安全修复libarchive 升级3.8.7 → 3.8.8PR #109874c-ares 升级1.34.6 → 1.34.8PR #109905krb5 安全修复修复 CVE-2026-40355 与 CVE-2026-40356PR #109910。此外该区块还包含一批NOT FOR CHANGELOG / INSIGNIFICANT条目如修复 release 分支上的 flaky 测试04146_iceberg_orc_row_policy_prewhere、test_server_no_logging、00965_send_logs_level_concurrent_queries、LRUFileCachePriority::tryIncreasePriority改用 try-lock、Rust 组合 ASan/UBSan 构建传递-Zsanitizeraddress等 CI 与内部稳定性改进。虽然不面向终端用户但保证了发布分支的测试稳定性。七、升级评估与总结v26.5.6.64-stable 是一个以正确性修复与安全加固为主的补丁版同时带来一项实验特性与多处性能改进。升级评估建议重点关注新实验特性aiEmbed需要命名集合配置 LLM 提供商凭证且要求设置allow_experimental_ai_functions实验特性开关后使用分析器兼容性设置analyzer_compatibility_allow_non_aggregate_in_having与analyzer_compatibility_prefer_alias_over_subcolumn默认均关闭仅为迁移历史查询提供不应在生产中无脑开启show_remote_databases_in_system_tables默认开启若你依赖隐藏 MySQL/PostgreSQL 数据库的行为需显式关闭涉及数据安全的修复RENAME COLUMN 与合并竞态、异步插入去重 token 误注册、FINAL 重复行、projection 默认值错误等修复值得在变更后做针对性的数据一致性回归验证行为变更提醒catboostEvaluate模型路径现在必须位于user_files、SYSTEM RESET DDL WORKER需要新权限、http_forbid_headers大小写不敏感、增量备份凭证存储方式变化这些都可能影响现有脚本与运维流程。如需逐条核对变更细节可直接阅读变更日志原文 docs/changelogs/v26.5.6.64-stable.md并结合 src/Core/Settings.cpp 中新增设置的定义、src/Functions/aiEmbed.cpp 中 AI 函数实现以及 src/Analyzer/Resolve/QueryAnalyzer.cpp 中分析器兼容逻辑进行代码级确认。【免费下载链接】ClickHouseClickHouse® is a real-time analytics database management system项目地址: https://gitcode.com/GitHub_Trending/cli/ClickHouse创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 ClickHouse v26.5.6.64-stable 版本深度解析：aiEmbed 嵌入函数、查询正确性修复与性能回归治理
ClickHouse v26.5.6.64-stable 版本深度解析aiEmbed 嵌入函数、查询正确性修复与性能回归治理【免费下载链接】ClickHouseClickHouse® is a real-time analytics database management system项目地址: https://gitcode.com/GitHub_Trending/cli/ClickHouse导读本文以 ClickHouse 官方变更日志 docs/changelogs/v26.5.6.64-stable.md 为骨架深入解析 v26.5.6.64-stable 相对 v26.5.5.8-stable 的全部变更新增的实验性 AI 嵌入函数aiEmbed、S3 小文件读取性能回归修复、一系列新分析器兼容性开关以及 30 余项涉及 MergeTree 数据安全、查询正确性、安全加固与崩溃修复的缺陷修复。读完本文你将掌握每个变更的适用场景、关键配置项含默认值与取值说明并能结合仓库源码定位对应实现为升级评估与问题排查提供依据。一、版本发布概览v26.5.6.64-stable 是 2026 年度变更日志中的第一个稳定版条目见 docs/changelogs/v26.5.6.64-stable.md 开头的sidebar_position: 1发布形式为相对 v26.5.5.8-stable 的增量补丁版。整个变更日志按 ClickHouse 官方惯例分为五个区块Experimental Feature1 项aiEmbed嵌入函数Performance Improvement3 项聚焦对象存储小文件读取与 PREWHERE 优化Improvement5 项覆盖分析器兼容性、数据湖集成、MySQL 协议与系统表可见性Bug Fix官方稳定版中的用户可见行为问题30 余项是本次发布的主体Build/Testing/Packaging Improvement3 项含安全漏洞修复与依赖升级。其中每一行变更均标注了对应的 backport issue如#108984与原始 PR 编号便于读者在仓库 Git 历史中回溯提交。二、实验特性aiEmbed嵌入函数2.1 功能定位本次发布通过 backport 引入了新的实验性函数aiEmbedsrc/Functions/aiEmbed.cpp用于在 ClickHouse 内部直接调用 LLM 提供商的嵌入接口把文本转换为向量aiEmbed(text, model[, params])text要嵌入的文本String或Nullable(String)model嵌入模型名称必须为常量Stringparams可选常量Map(String, String)函数特有键为dimensions目标向量维度0或省略表示使用模型原生维度通用键为credentials指定命名集合。函数返回Array(Float32)。返回值语义在源码FunctionDocumentation中有明确说明若输入为NULL或空字符串、请求失败且ai_function_throw_on_error被禁用、或配额超限且ai_function_throw_on_quota_exceeded被禁用均返回空数组src/Functions/aiEmbed.cpp。2.2 实现要点源码级从 src/Functions/aiEmbed.cpp 的实现看该函数有几个值得注意的设计决策有状态且适合短路执行每次调用会更新配额并可能发起昂贵的 HTTP 请求因此isStateful()返回true同时它不参与常量折叠也不适合短路参数求值。显式处理 NULL 与常量列useDefaultImplementationForNulls与useDefaultImplementationForConstants均返回false意味着NULL/空字符串行不会触发 HTTP 调用而是直接映射为输出中的空数组[]避免无效请求。批量请求单个数据块内的输入按每批最多ai_function_embedding_max_batch_size条合并为一个 HTTP 请求减少请求开销src/Functions/aiEmbed.cpp。默认凭证分离嵌入端点与对话端点不同因此aiEmbed使用独立的默认凭证设置ai_function_embedding_default_credentials区别于文本类 AI 函数。模型必须显式传入与文本类 AI 函数不同aiEmbed不从命名集合或参数映射中读取model若命名集合定义了model会被拒绝。源码中注册的introduced_in标注为 26.6而本 changelog 将其作为 backport 实验特性列入 26.5.6因此在 26.5.6 分支上使用时应将其视为实验功能并关注后续正式发布。2.3 相关设置与示例aiEmbed依赖以下会话设置定义于 src/Core/Settings.cpp设置说明ai_function_embedding_max_batch_size每个 HTTP 请求打包的最大文本条数ai_function_embedding_default_credentials参数映射中未提供credentials时的默认命名集合ai_function_request_timeout_sec单次请求超时秒实现中覆盖 HTTP receive timeoutai_function_max_retries失败重试次数ai_function_retry_initial_delay_ms重试初始退避延迟毫秒ai_function_throw_on_error出错时是否抛异常官方文档示例源码FunctionDocumentation内嵌-- 嵌入单个字符串已设置默认凭证时可省略 credentials SELECT aiEmbed(Hello world, text-embedding-3-small, map(credentials, ai_embedding_credentials)); -- 显式指定输出维度 SELECT aiEmbed(Hello world, text-embedding-3-small, map(credentials, ai_embedding_credentials, dimensions, 256)); -- 嵌入整列文本 CREATE TABLE articles (title String) ENGINE Memory; INSERT INTO articles VALUES (ClickHouse is a fast analytical database.); SELECT aiEmbed(title, text-embedding-3-small, map(credentials, ai_embedding_credentials, dimensions, 256)) FROM articles LIMIT 10;在仓库中可同时看到aiSimilaritysrc/Functions/aiSimilarity.cpp、FunctionBaseAIsrc/Functions/FunctionBaseAI.cpp与IAIProvidersrc/Functions/AI/IAIProvider.h等配套基础设施说明该函数与既有 AI 函数家族共享提供商抽象、配额跟踪与重试逻辑。三、性能改进对象存储小文件读取与 PREWHERE3.1 恢复 S3 表函数的小对象预取prefetch本次修复针对 PR #71781 引入的性能回归通过s3()等表函数读取对象存储中大量小文件时预取prefetch机制失效退化为同步读取导致单线程/低并发场景下读取大量小文件显著变慢。本版本恢复了对小对象的预取PR #108872。适用场景任何通过s3、s3Cluster等表函数批量读取大量小对象的查询典型如日志文件目录、小分片数据集的扫描。3.2 预取覆盖文件系统缓存路径紧随其后的修复PR #109478把首次小对象预取扩展到了走文件系统缓存的读取路径上一项修复仅恢复了对非缓存读取的预取而启用filesystem_cache_name后许多小文件的读取例如S3Queue摄取场景仍保持同步、受延迟主导。本次版本让缓存读取路径同样触发初始小对象预取进一步消除S3Queue摄取与缓存启用的性能瓶颈。3.3 Map 子列参与 PREWHERE 优化PREWHERE 优化在选择下推列时需要评估各列在磁盘上的大小。本版本修复了 Map 子列subcolumn磁盘大小未计入的问题PR #110623纠正了此前 PR #99200 引入的 PREWHERE 回归使带Map列的表在做 PREWHERE 列选择时能更准确地权衡 I/O 代价。四、改进项兼容性、数据湖与协议细节4.1 新分析器兼容性设置HAVING 非聚合项回退新增设置analyzer_compatibility_allow_non_aggregate_in_having默认false定义于 src/Core/Settings.cpp。启用后新分析器模拟 v24.3 之前查询分析器的旧行为将HAVING中非聚合的 AND 连接项移动到WHERE而不是抛出NOT_AN_AGGREGATE错误。源码注释明确了边界条件src/Core/Settings.cpp实现见 src/Analyzer/Resolve/QueryAnalyzer.cpp包含聚合、grouping或非确定性函数的连接项保留在HAVING若任一连接项含窗口函数或有状态函数如rowNumberInBlock整个重写被禁用与旧PredicateExpressionsOptimizer行为一致当GROUP BY使用WITH CUBE、WITH ROLLUP、WITH TOTALS或GROUPING SETS时该设置被忽略。这是一个为历史 SQL 迁移设计的兼容开关标准合规的拒绝是默认行为启用它只为让那些曾被旧分析器静默接受的查询继续工作。4.2 新分析器兼容性设置别名优先于子列另一新增设置analyzer_compatibility_prefer_alias_over_subcolumn默认falsesrc/Core/Settings.cpp。当形如b.id的多段标识符既可以解释为表别名b的id列又可以解释为某列的 Tuple 子列b.id时默认false新分析器优先按子列解释启用true优先按别名-前缀解释恢复旧分析器的解析行为。该开关用于规避 CTE/子查询内联JOIN场景下星号重命名列如b.id将内部表标识符泄漏到外层作用域、从而触发AMBIGUOUS_IDENTIFIER等错误的问题。4.3 DataLakeCatalogOneLake 默认改用 Blob 端点DataLakeCatalog数据库新增catalog_type onelake的默认端点切换默认使用 OneLake Blob 端点.blob.fabric.microsoft.com读取表数据设置onelake_use_blob_endpoint false可恢复旧的 DFS 端点.dfs.fabric.microsoft.com行为PR #106843。同时旧版本25.12 及更早创建、auth_header配置损坏的DataLakeCatalog数据库在升级到 26.2 后不再阻塞服务启动auth_header仅在CREATE时校验ATTACH时目录改为首次使用时惰性构建PR #108674单个配置错误或不可达的目录数据库不再阻止服务器启动。4.4 系统表可见性设置拆分恢复show_data_lake_catalogs_in_system_tables作为仅控制DataLakeCatalog在system.tables、system.columns、system.completions中可见性的设置同时新增默认启用的show_remote_databases_in_system_tables允许用户单独隐藏MySQL与PostgreSQL数据库PR #109082。4.5 MySQL 握手协议修复修复 MySQL 握手中对auth_response长度的读取长度字节 128时因按有符号char读取而被解释为数十亿字节multi-gigabyte的值PR #107384。4.6 自适应编码选择adaptive codec的读取侧前置MergeTree 现在可以读取压缩流中各块使用不同 codec 的数据PR #108592。这是自适应 codec 选择特性issue #105404的读取侧前置工作属于格式层面的向前兼容准备。4.7 调试体验更简单的指标添加方式针对调试期间难以在 dashboard 上快速添加多个指标的问题本次改进支持直接从源码或文档添加指标PR #109449降低开发者在调试会话中扩展指标面板的摩擦。五、缺陷修复解析按主题分类以下为 30 余项用户可见行为修复按影响面归类展开。5.1 MergeTree 数据安全与一致性RENAME COLUMN 与后台合并竞态PR #104822ALTER TABLE ... RENAME COLUMN与并发OPTIMIZE TABLE ... FINAL或任意后台合并之间存在竞态可能导致重命名列的数据被静默替换为默认值。修复通过在发布新内存元数据与在current_mutations_by_version注册重命名 mutation 期间持有currently_processing_in_background_mutex关闭了竞态窗口。空 part 迁移到 plain_rewritable 磁盘崩溃PR #107040ALTER TABLE ... MOVE PARTITION ... TO DISK移动remove_empty_parts 0保留的空 part 到plain_rewritable磁盘时导致服务崩溃已修复。采纳 part 后的 FINAL 重复行PR #107481CREATE TABLE ... CLONE AS、ATTACH PARTITION ... FROM、MOVE PARTITION ... TO TABLE把 plainMergeTree的 part 采纳进ReplacingMergeTree、SummingMergeTree或AggregatingMergeTree后SELECT ... FINAL/OPTIMIZE TABLE ... FINAL返回重复行。修复方案是在源与目标引擎不同时将采纳 part 的 merge level 重置为 0使目标表在下一次合并时正确去重。projection 读取 ADD COLUMN DEFAULT 错误PR #108569当投影projection创建后执行ALTER TABLE ... ADD COLUMN ... DEFAULTSELECT *由投影回答时返回的是列类型默认值如0而非DEFAULT值如-1基础表读取原本正确只有投影回答的读取受影响直到投影重建。ALIAS 列含 IN 操作符时的逻辑错误PR #111039在存在使用IN操作符的 ALIAS 列包括经另一 ALIAS 列间接使用的表上执行ALTER TABLE ... DROP COLUMN、ALTER TABLE ... DELETE/UPDATEmutation 及轻量 DELETE会触发LOGICAL_ERRORNo set is registered for key。异步插入与去重的崩溃与数据丢失崩溃PR #109229异步插入 去重时若optimize_on_insert使插入块变为空例如SummingMergeTree中行求和为零服务崩溃静默数据丢失PR #111049async_insert1, async_insert_deduplicate1时多个不同insert_deduplication_token的异步条目合并为一次 flush 并写入不同分区时每个 token 会被注册到 flush 触及的所有分区的去重日志而非其行实际落盘的分区。后续在未写入过的分区复用同一 token 的插入会被静默去重丢弃。现在 token 仅注册到行实际落盘的分区。物化/虚拟列上的 GROUP BY mutationPR #109532修复含物化列或启用持久化虚拟列的表上的 group-by mutations这些列现在使用any聚合。rollup 合并无限重调度PR #109410修复 rollup 合并被无限重新调度的问题。文件段争用回归PR #109577修复 26.1 引入的多余文件段file segment争用问题。5.2 查询正确性查询条件缓存的三个修复查询条件缓存use_query_condition_cache默认true定义见 src/Core/Settings.cpp在本版本集中修复SAMPLE 错误结果PR #108488SELECT [...] SAMPLE [...]与查询条件缓存组合时返回错误结果on-fly mutations / 行级安全策略污染缓存PR #107145apply_mutations_on_fly 1的查询在 PREWHERE 前过滤行可能污染缓存使后续apply_mutations_on_fly 0且谓词相同的查询跳过本应读取的 marks、返回过少行行级安全策略作为过滤器置于 PREWHERE 之前也有同样问题。Distributed 通过 Merge 查询时 skip-unused-shards 失效PR #106250Distributed表经由Merge表或merge表函数查询、谓词作用于其上时optimize_skip_unused_shards未生效且force_optimize_skip_unused_shards会错误失败。分布式 ALIAS 列错位PR #107675分布式查询选择共享公共子表达式的ALIAS列时列可能错位、值被放到错误的列名下。运行时 JOIN 过滤器与 JSON 列PR #107663运行时 join filter 对 JSON 列产生错误结果。UNION/INTERSECT/EXCEPT 的 Sparse 列冲突PR #107041当UNION/INTERSECT/EXCEPT的一个分支读取 Sparse 序列化列、另一分支读取同一列的完整形式例如向物化视图推送时触发Block structure mismatch in UnionStep stream逻辑错误debug/sanitizer 构建下服务中止release 构建下Code: 49。文本索引谓词在 PREWHERE 与 WHERE 中重复PR #110710Merge表叠在Distributed表上查询时同一文本索引谓词同时出现在PREWHERE与WHERE触发Column ... already added for reading逻辑错误。Iceberg 读取修复PR #110233默认排序顺序引用需要引用的列如timestamp时合成存储ORDER BY解析失败SYNTAX_ERROR导致表不可读。RestCatalog 空判断PR #106301Iceberg REST 目录包含表时RestCatalog::empty返回错误结果。5.3 聚合状态与崩溃修复深层嵌套表达式/字面量堆栈溢出PR #108493max_parser_depth设为较大值时[[[ ... ]]]或array(array(...))等深度嵌套表达式导致栈溢出崩溃。深层嵌套字面量复制/析构崩溃PR #110393深度嵌套的Array/Tuple/Map/Object字面量被复制或销毁时原生栈溢出。uniqExact 聚合状态并行合并崩溃与竞态PR #108928、PR #109389GROUPING SETS/ROLLUP/CUBE且max_threads 1时合并uniqExact状态的分段错误以及两级集合two-level sets并行合并的数据竞态罕见崩溃。groupArrayLastMerge 越界PR #109485聚合函数状态反序列化缺少校验损坏状态导致越界访问现已加入校验。quantileTDigest 状态并发序列化溢出PR #110263quantileTDigest系列聚合状态列作为GROUP BY键被多线程并发序列化时可能触发 heap-buffer-overflow 崩溃。Dynamic/Variant 嵌套在 Tuple 中的转换PR #108061accurateCastOrNull/accurateCastOrDefault把Tuple内嵌套的Dynamic或Variant列转换为非Nullable元素类型时出现逻辑错误。5.4 安全与权限query_log 权限泄漏PR #106425system.query_log的used_privileges与missing_privileges列可能包含来自其他用户、数据库或会话的不相关早期查询的权限字符串现已修复。SYSTEM RESET DDL WORKER 权限收紧PR #108460SYSTEM RESET DDL WORKER现在要求新增的SYSTEM RESET DDL WORKER权限。此前任何已认证用户包括readonly用户都能执行并反复重置 DDL worker 状态从而阻塞ON CLUSTERDDL。catboostEvaluate 模型路径限制PR #108463catboostEvaluate的模型路径被限制在user_files目录内与file()及字典数据源一致。此前函数接受任意文件系统路径且无包含性检查可探测并触发读取user_files之外的文件。MySQL 协议命令权限对齐PR #108508MySQL 线协议的COM_FIELD_LISTmysql_list_fields与COM_INIT_DBUSE database现在强制执行与其 SQL 等价物SHOW COLUMNS/DESCRIBE与USE相同的访问控制此前可能泄露仅部分列权限用户的表列名并在无SHOW DATABASES权限时切换当前数据库。敏感信息隐藏system.query_views_log.view_query中的敏感信息被隐藏PR #108214getClientHTTPHeader中按 RFC 9110 对 header 大小写不敏感authorization被加入过滤名单PR #109791。5.5 配置、备份与其他HTTP 禁止头大小写不敏感PR #108509http_forbid_headers改为大小写不敏感匹配——禁止Authorization也会拦截authorization、AUTHORIZATION等变体配置的header_regexp模式无需显式(?i)即可大小写不敏感匹配。S3 设置优先级PR #109251URL 作用域的s3端点块现在优先于顶层s3默认值。增量备份不再内嵌 S3 凭证PR #107357增量备份不再在.backup元数据文件的base_backup定位符中存储 S3 凭证。use_same_s3_credentials_for_base_backup 1或显式 base-backup 凭证与定位符匹配时存储非机密标记且无需额外恢复期设置即可还原凭证不同的旧备份需在RESTORE时通过base_backup设置传入旧版本创建的内嵌凭证备份仍可还原。只读表后台刷新PR #108034只读表刷新数据 part 时的瞬时错误不再永久停止后台刷新任务。system.tables 跳过数据库PR #109723查询仅读取name/database列时system.tables对按数据库授权per-database grants的用户静默跳过数据库26.2 引入已修复。格式模式推断Nullable(Tuple)PR #109185Arrow、ArrowStream、Avro格式及旧版ORC/Parquet读取器对可空 struct 列推断出Nullable(Tuple)而该类型不被允许allow_experimental_nullable_tuple_type关闭导致DESCRIBE返回的类型被CREATE TABLE拒绝。现在推断结果不再产生被禁用的Nullable Tuple类型。Arrow Java 19.0.0 空嵌套列PR #111101读取 Apache Arrow Java 19.0.0随 Apache Spark 分发生成的空嵌套Array/Map列时此前因偏移缓冲过小报INCORRECT_DATA现已修复。六、构建/测试/打包改进与安全修复libarchive 升级3.8.7 → 3.8.8PR #109874c-ares 升级1.34.6 → 1.34.8PR #109905krb5 安全修复修复 CVE-2026-40355 与 CVE-2026-40356PR #109910。此外该区块还包含一批NOT FOR CHANGELOG / INSIGNIFICANT条目如修复 release 分支上的 flaky 测试04146_iceberg_orc_row_policy_prewhere、test_server_no_logging、00965_send_logs_level_concurrent_queries、LRUFileCachePriority::tryIncreasePriority改用 try-lock、Rust 组合 ASan/UBSan 构建传递-Zsanitizeraddress等 CI 与内部稳定性改进。虽然不面向终端用户但保证了发布分支的测试稳定性。七、升级评估与总结v26.5.6.64-stable 是一个以正确性修复与安全加固为主的补丁版同时带来一项实验特性与多处性能改进。升级评估建议重点关注新实验特性aiEmbed需要命名集合配置 LLM 提供商凭证且要求设置allow_experimental_ai_functions实验特性开关后使用分析器兼容性设置analyzer_compatibility_allow_non_aggregate_in_having与analyzer_compatibility_prefer_alias_over_subcolumn默认均关闭仅为迁移历史查询提供不应在生产中无脑开启show_remote_databases_in_system_tables默认开启若你依赖隐藏 MySQL/PostgreSQL 数据库的行为需显式关闭涉及数据安全的修复RENAME COLUMN 与合并竞态、异步插入去重 token 误注册、FINAL 重复行、projection 默认值错误等修复值得在变更后做针对性的数据一致性回归验证行为变更提醒catboostEvaluate模型路径现在必须位于user_files、SYSTEM RESET DDL WORKER需要新权限、http_forbid_headers大小写不敏感、增量备份凭证存储方式变化这些都可能影响现有脚本与运维流程。如需逐条核对变更细节可直接阅读变更日志原文 docs/changelogs/v26.5.6.64-stable.md并结合 src/Core/Settings.cpp 中新增设置的定义、src/Functions/aiEmbed.cpp 中 AI 函数实现以及 src/Analyzer/Resolve/QueryAnalyzer.cpp 中分析器兼容逻辑进行代码级确认。【免费下载链接】ClickHouseClickHouse® is a real-time analytics database management system项目地址: https://gitcode.com/GitHub_Trending/cli/ClickHouse创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考