StarRocks Elasticsearch Catalog 使用指南免数据迁移直连 ES 的联邦查询方案【免费下载链接】starrocksThe worlds fastest open query engine for sub-second analytics both on and off the data lakehouse. With the flexibility to support nearly any scenario, StarRocks provides best-in-class performance for multi-dimensional analytics, real-time analytics, and ad-hoc queries. A Linux Foundation project.项目地址: https://gitcode.com/GitHub_Trending/st/starrocksElasticsearch Catalog 是 StarRocks 自 v3.1 起提供的免迁移联邦查询能力无需将 Elasticsearch 中的索引数据导入 StarRocks即可直接在 StarRocks 上用 SQL 对 ES 集群的索引进行多维分析与全文检索并借助谓词下推把过滤逻辑下沉到 ES 执行。本文将从建目录语法、全部连接参数、谓词下推机制到esquery()高级查询结合本仓库 FE 端源码connector/elasticsearch逐层拆解其实现原理与实战配置。为什么需要 Elasticsearch CatalogStarRocks 与 Elasticsearch 是两款侧重点不同的分析系统StarRocks 擅长大规模分布式计算可通过外表方式查询 ES 中的数据Elasticsearch 则以全文检索能力见长。两者结合可以构成更完整的 OLAP 解决方案。借助 Elasticsearch Catalog你可以在 StarRocks 上直接用 SQL 分析 ES 集群中所有索引数据全程无需迁移数据。一个值得注意的模型差异是与其他数据源的 Catalog 不同Elasticsearch Catalog 创建后只含有一个名为default_db的数据库ES 中的每个索引index会自动映射为一张数据表并挂载到该数据库下。这一映射逻辑在源码 EsRestClient.listTables() 中实现它会通过_cat/indices枚举索引、通过_aliases枚举别名最终返回索引 别名的并集作为表集合并过滤掉以.开头的系统索引如.kibana_1、.opendistro_security。创建 Elasticsearch Catalog语法CREATE EXTERNAL CATALOG catalog_name [COMMENT comment] PROPERTIES (keyvalue, ...)参数说明参数必填默认值说明hosts是无ES 集群连接地址可指定一个或多个地址。StarRocks 会从该地址解析 ES 版本和索引分片分布。StarRocks 依据GET /_nodes/httpAPI 返回的地址与 ES 集群通信因此hosts的取值必须与GET /_nodes/http返回的地址一致否则 BE 或 CN 可能无法与 ES 集群通信。type是无数据源类型创建 ES Catalog 时必须设置为es。user否空开启 HTTP 基础认证时用于登录 ES 集群的用户名。需确保该用户有访问/cluster/state/nodes/http等路径及读取索引的权限。password否空登录 ES 集群的密码。es.type否_doc索引类型。查询 ES 8 及以后版本的数据时无需配置ES 8 已移除 mapping types。es.nodes.wan.only否FALSE是否仅使用hosts指定的地址访问 ES 集群并拉取数据。true不做数据节点嗅探当 StarRocks 无法访问 ES 集群内数据节点地址时须设为truefalseStarRocks 以hosts指定地址为入口嗅探索引分片所在的数据节点生成执行计划后由 BE/CN 直连集群内数据节点拉取分片数据网络互通时建议保留默认值false。es.net.ssl否FALSE是否允许使用 HTTPS 协议访问 ES 集群仅 StarRocks v2.4 及以后支持。trueHTTPS 与 HTTP 均可访问false仅支持 HTTP。enable_docvalue_scan否TRUE是否从 ES 列式存储doc_values中获取目标字段的值。多数场景下列式读取性能优于行式存储读取。enable_keyword_sniff否TRUE是否基于 ES 的 KEYWORD 类型字段嗅探 TEXT 类型字段。设为false时StarRocks 在分词后进行匹配。示例CREATE EXTERNAL CATALOG es_test COMMENT test123 PROPERTIES ( type es, es.type _doc, hosts https://xxx:9200, es.net.ssl true, user admin, password xxx, es.nodes.wan.only true );创建成功后可通过SHOW CATALOGS查看目录、SHOW DATABASES FROM es_test查看default_db数据库、SHOW TABLES FROM es_test.default_db查看自动映射出的索引表随后即可像查询普通表一样执行SELECT分析。参数背后的源码实现上述参数并非只是文档中的说明文字它们都有对应的 FE 端实现理解实现能帮你更好地判断该如何取值。配置解析参数解析集中在 EsConfig.java 中通过Config注解绑定hosts、user、password、es.net.ssl、es.nodes.wan.only、enable_docvalue_scan、enable_keyword_sniff等键键名常量定义于 EsTable.java。连接器初始化时由 ElasticsearchConnector.bindConfig() 把配置转交给EsRestClient构造 HTTP 客户端。hosts与节点容错EsRestClient在发起请求前会对节点地址做trim并自动补全缺失的http://前缀IPv6 请使用[addr]:port格式。若某节点请求失败会按nodes.length次循环切换到下一个节点重试见 execute()。版本嗅探与兼容StarRocks 通过请求 ES 根路径/读取响应中的version.number并解析为主版本号EsMajorVersion.parse()支持 0.x ~ 8.x 的识别用于后续请求路径与查询 DSL 的兼容性判断。这正对应StarRocks 可以从hosts地址解析 ES 版本这一文档描述。es.net.ssl开启后使用信任所有证书的 TLS SocketFactory 构造 HTTPS 客户端getOrCreateSSLClient()。enable_docvalue_scan默认true。源码注释EsTable.java引用 Solr 的 benchmark 指出当返回字段较少时 DocValues 列式读取性能优于 stored_fields但字段数量增多后差距缩小甚至反转因此实现中还有一个内部上限max_docvalue_fields默认 20可通过max_docvalue_fields配置超过该字段数会降级为从 stored_fields 提取text类型字段默认禁用 doc_values 扫描。索引映射与分片发现EsRestClient通过GET /_nodes/http发现集群 HTTP 节点getHttpNodes()通过GET {index}/_search_shards获取索引分片所在节点searchShards()。这就是es.nodes.wan.onlyfalse时 BE/CN 能直连数据节点读取分片数据的底层依据同时它也会通过_cat/indices/{index}?hdocs.count估算行数供 StarRocks 的 CBO 优化器使用。谓词下推Predicate PushdownStarRocks 支持将针对 ES 表的查询谓词下推到 ES 执行缩小查询引擎与存储源之间的距离从而提升查询性能。下推的 SQL 语法与生成的 ES 查询 DSL 对应关系如下SQL 语法Elasticsearch 语法term queryinterms query, , , rangeandbool.filterorbool.shouldnotbool.must_notnot inbool.must_not termsesqueryES Query DSL在 FE 端这一映射由 QueryConverter.java 完成。它以 AST 访问器的方式遍历查询表达式树将转为termQueryvisitBinaryPredicate()、IN转为termsQueryvisitInPredicate()、比较运算转为rangeQuery、AND/OR/NOT分别转为bool.must / bool.should / bool.mustNotvisitCompoundPredicate()。除此之外实现还额外支持了IS NULL映射为 exists query 及其取反和LIKE把_、%通配符转换为 ES wildcard 的?、*等下推规则。值得注意的下推边界下推过程会把能下推的表达式收集为remoteConjuncts由 ES 处理把无法下推的表达式收集为localConjuncts仍由 StarRocks BE 处理见 convert()。也就是说谓词下推是尽力而为的优化无法转换的过滤条件会自动留在 StarRocks 侧执行不会导致查询失败。使用 esquery() 下发 ES 原生查询esquery()函数用于把 SQL 无法表达的 ES 查询如 match、geo_shape 等原样下推到 ES 进行过滤处理。其第一个参数是用于关联索引的列名第二个参数是花括号{}包裹的、基于 ES Query DSL 的 JSON 表示该 JSON只能且必须有且仅有一个根键例如match、geo_shape或bool。在 FE 实现中esquery(col, {...})会被转换为一个 RawQueryBuilder直接将第二个参数的 JSON 原文拼入下推的查询 DSLvisitFunctionCall()。Match 查询SELECT * FROM es_table WHERE esquery(k4, { match: { k4: StarRocks on elasticsearch } });Geoshape 查询SELECT * FROM es_table WHERE esquery(k4, { geo_shape: { location: { shape: { type: envelope, coordinates: [ [ 13, 53 ], [ 14, 52 ] ] }, relation: within } } });Boolean 查询SELECT * FROM es_table WHERE esquery(k4, { bool: { must: [ { terms: { k1: [ 11, 12 ] } }, { terms: { k2: [ 100 ] } } ] } });配合上一节的谓词下推表可以看到esquery()是谓词下推的白名单外通道凡是标准 SQL 下推覆盖不到的 ES 高级检索全文 match、地理位置、嵌套 bool 组合等都可以通过它直接以原生 DSL 形式下发让 ES 的全文检索能力真正融入 StarRocks 的 SQL 分析链路。使用说明与注意事项版本兼容自 ES v5.x 起扫描数据的底层方式发生了变化StarRocks 仅支持查询 Elasticsearch v5.x 及之后版本的数据。FE 端 EsMajorVersion 的版本解析范围0.x ~ 8.x与此约束一致。认证要求StarRocks 仅支持查询开启了 HTTP 基础认证HTTP basic authentication的 ES 集群请确保在 PROPERTIES 中正确配置user与password且该用户具备访问/cluster/state/nodes/http等元数据路径和读取索引的权限。性能提醒某些查询如包含count()的查询在 StarRocks 上的执行速度会明显慢于直接在 ES 上执行因为 ES 可以直接读取满足查询条件的文档数量元数据而无需过滤实际数据。对这类聚合统计场景可评估直接在 ES 侧完成或采用定期物化的方式。连接模式选择若 BE/CN 与 ES 集群处于同一内网建议保持es.nodes.wan.only false让 BE/CN 直连分片所在数据节点以获得更好性能若存在网络隔离、无法访问 ES 内部数据节点地址则须设置为true此时所有流量都经由hosts指定的地址转发。参考源码路径连接器入口与配置绑定ElasticsearchConnector.java、EsConfig.javaREST 客户端版本嗅探、节点发现、分片发现、索引列表EsRestClient.java、EsMajorVersion.java谓词下推与 esquery 转换QueryConverter.java、QueryBuilders.java表属性常量与 doc_values 策略EsTable.java单元测试ElasticsearchMetadataTest.java【免费下载链接】starrocksThe worlds fastest open query engine for sub-second analytics both on and off the data lakehouse. With the flexibility to support nearly any scenario, StarRocks provides best-in-class performance for multi-dimensional analytics, real-time analytics, and ad-hoc queries. A Linux Foundation project.项目地址: https://gitcode.com/GitHub_Trending/st/starrocks创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
StarRocks Elasticsearch Catalog 使用指南：免数据迁移直连 ES 的联邦查询方案
StarRocks Elasticsearch Catalog 使用指南免数据迁移直连 ES 的联邦查询方案【免费下载链接】starrocksThe worlds fastest open query engine for sub-second analytics both on and off the data lakehouse. With the flexibility to support nearly any scenario, StarRocks provides best-in-class performance for multi-dimensional analytics, real-time analytics, and ad-hoc queries. A Linux Foundation project.项目地址: https://gitcode.com/GitHub_Trending/st/starrocksElasticsearch Catalog 是 StarRocks 自 v3.1 起提供的免迁移联邦查询能力无需将 Elasticsearch 中的索引数据导入 StarRocks即可直接在 StarRocks 上用 SQL 对 ES 集群的索引进行多维分析与全文检索并借助谓词下推把过滤逻辑下沉到 ES 执行。本文将从建目录语法、全部连接参数、谓词下推机制到esquery()高级查询结合本仓库 FE 端源码connector/elasticsearch逐层拆解其实现原理与实战配置。为什么需要 Elasticsearch CatalogStarRocks 与 Elasticsearch 是两款侧重点不同的分析系统StarRocks 擅长大规模分布式计算可通过外表方式查询 ES 中的数据Elasticsearch 则以全文检索能力见长。两者结合可以构成更完整的 OLAP 解决方案。借助 Elasticsearch Catalog你可以在 StarRocks 上直接用 SQL 分析 ES 集群中所有索引数据全程无需迁移数据。一个值得注意的模型差异是与其他数据源的 Catalog 不同Elasticsearch Catalog 创建后只含有一个名为default_db的数据库ES 中的每个索引index会自动映射为一张数据表并挂载到该数据库下。这一映射逻辑在源码 EsRestClient.listTables() 中实现它会通过_cat/indices枚举索引、通过_aliases枚举别名最终返回索引 别名的并集作为表集合并过滤掉以.开头的系统索引如.kibana_1、.opendistro_security。创建 Elasticsearch Catalog语法CREATE EXTERNAL CATALOG catalog_name [COMMENT comment] PROPERTIES (keyvalue, ...)参数说明参数必填默认值说明hosts是无ES 集群连接地址可指定一个或多个地址。StarRocks 会从该地址解析 ES 版本和索引分片分布。StarRocks 依据GET /_nodes/httpAPI 返回的地址与 ES 集群通信因此hosts的取值必须与GET /_nodes/http返回的地址一致否则 BE 或 CN 可能无法与 ES 集群通信。type是无数据源类型创建 ES Catalog 时必须设置为es。user否空开启 HTTP 基础认证时用于登录 ES 集群的用户名。需确保该用户有访问/cluster/state/nodes/http等路径及读取索引的权限。password否空登录 ES 集群的密码。es.type否_doc索引类型。查询 ES 8 及以后版本的数据时无需配置ES 8 已移除 mapping types。es.nodes.wan.only否FALSE是否仅使用hosts指定的地址访问 ES 集群并拉取数据。true不做数据节点嗅探当 StarRocks 无法访问 ES 集群内数据节点地址时须设为truefalseStarRocks 以hosts指定地址为入口嗅探索引分片所在的数据节点生成执行计划后由 BE/CN 直连集群内数据节点拉取分片数据网络互通时建议保留默认值false。es.net.ssl否FALSE是否允许使用 HTTPS 协议访问 ES 集群仅 StarRocks v2.4 及以后支持。trueHTTPS 与 HTTP 均可访问false仅支持 HTTP。enable_docvalue_scan否TRUE是否从 ES 列式存储doc_values中获取目标字段的值。多数场景下列式读取性能优于行式存储读取。enable_keyword_sniff否TRUE是否基于 ES 的 KEYWORD 类型字段嗅探 TEXT 类型字段。设为false时StarRocks 在分词后进行匹配。示例CREATE EXTERNAL CATALOG es_test COMMENT test123 PROPERTIES ( type es, es.type _doc, hosts https://xxx:9200, es.net.ssl true, user admin, password xxx, es.nodes.wan.only true );创建成功后可通过SHOW CATALOGS查看目录、SHOW DATABASES FROM es_test查看default_db数据库、SHOW TABLES FROM es_test.default_db查看自动映射出的索引表随后即可像查询普通表一样执行SELECT分析。参数背后的源码实现上述参数并非只是文档中的说明文字它们都有对应的 FE 端实现理解实现能帮你更好地判断该如何取值。配置解析参数解析集中在 EsConfig.java 中通过Config注解绑定hosts、user、password、es.net.ssl、es.nodes.wan.only、enable_docvalue_scan、enable_keyword_sniff等键键名常量定义于 EsTable.java。连接器初始化时由 ElasticsearchConnector.bindConfig() 把配置转交给EsRestClient构造 HTTP 客户端。hosts与节点容错EsRestClient在发起请求前会对节点地址做trim并自动补全缺失的http://前缀IPv6 请使用[addr]:port格式。若某节点请求失败会按nodes.length次循环切换到下一个节点重试见 execute()。版本嗅探与兼容StarRocks 通过请求 ES 根路径/读取响应中的version.number并解析为主版本号EsMajorVersion.parse()支持 0.x ~ 8.x 的识别用于后续请求路径与查询 DSL 的兼容性判断。这正对应StarRocks 可以从hosts地址解析 ES 版本这一文档描述。es.net.ssl开启后使用信任所有证书的 TLS SocketFactory 构造 HTTPS 客户端getOrCreateSSLClient()。enable_docvalue_scan默认true。源码注释EsTable.java引用 Solr 的 benchmark 指出当返回字段较少时 DocValues 列式读取性能优于 stored_fields但字段数量增多后差距缩小甚至反转因此实现中还有一个内部上限max_docvalue_fields默认 20可通过max_docvalue_fields配置超过该字段数会降级为从 stored_fields 提取text类型字段默认禁用 doc_values 扫描。索引映射与分片发现EsRestClient通过GET /_nodes/http发现集群 HTTP 节点getHttpNodes()通过GET {index}/_search_shards获取索引分片所在节点searchShards()。这就是es.nodes.wan.onlyfalse时 BE/CN 能直连数据节点读取分片数据的底层依据同时它也会通过_cat/indices/{index}?hdocs.count估算行数供 StarRocks 的 CBO 优化器使用。谓词下推Predicate PushdownStarRocks 支持将针对 ES 表的查询谓词下推到 ES 执行缩小查询引擎与存储源之间的距离从而提升查询性能。下推的 SQL 语法与生成的 ES 查询 DSL 对应关系如下SQL 语法Elasticsearch 语法term queryinterms query, , , rangeandbool.filterorbool.shouldnotbool.must_notnot inbool.must_not termsesqueryES Query DSL在 FE 端这一映射由 QueryConverter.java 完成。它以 AST 访问器的方式遍历查询表达式树将转为termQueryvisitBinaryPredicate()、IN转为termsQueryvisitInPredicate()、比较运算转为rangeQuery、AND/OR/NOT分别转为bool.must / bool.should / bool.mustNotvisitCompoundPredicate()。除此之外实现还额外支持了IS NULL映射为 exists query 及其取反和LIKE把_、%通配符转换为 ES wildcard 的?、*等下推规则。值得注意的下推边界下推过程会把能下推的表达式收集为remoteConjuncts由 ES 处理把无法下推的表达式收集为localConjuncts仍由 StarRocks BE 处理见 convert()。也就是说谓词下推是尽力而为的优化无法转换的过滤条件会自动留在 StarRocks 侧执行不会导致查询失败。使用 esquery() 下发 ES 原生查询esquery()函数用于把 SQL 无法表达的 ES 查询如 match、geo_shape 等原样下推到 ES 进行过滤处理。其第一个参数是用于关联索引的列名第二个参数是花括号{}包裹的、基于 ES Query DSL 的 JSON 表示该 JSON只能且必须有且仅有一个根键例如match、geo_shape或bool。在 FE 实现中esquery(col, {...})会被转换为一个 RawQueryBuilder直接将第二个参数的 JSON 原文拼入下推的查询 DSLvisitFunctionCall()。Match 查询SELECT * FROM es_table WHERE esquery(k4, { match: { k4: StarRocks on elasticsearch } });Geoshape 查询SELECT * FROM es_table WHERE esquery(k4, { geo_shape: { location: { shape: { type: envelope, coordinates: [ [ 13, 53 ], [ 14, 52 ] ] }, relation: within } } });Boolean 查询SELECT * FROM es_table WHERE esquery(k4, { bool: { must: [ { terms: { k1: [ 11, 12 ] } }, { terms: { k2: [ 100 ] } } ] } });配合上一节的谓词下推表可以看到esquery()是谓词下推的白名单外通道凡是标准 SQL 下推覆盖不到的 ES 高级检索全文 match、地理位置、嵌套 bool 组合等都可以通过它直接以原生 DSL 形式下发让 ES 的全文检索能力真正融入 StarRocks 的 SQL 分析链路。使用说明与注意事项版本兼容自 ES v5.x 起扫描数据的底层方式发生了变化StarRocks 仅支持查询 Elasticsearch v5.x 及之后版本的数据。FE 端 EsMajorVersion 的版本解析范围0.x ~ 8.x与此约束一致。认证要求StarRocks 仅支持查询开启了 HTTP 基础认证HTTP basic authentication的 ES 集群请确保在 PROPERTIES 中正确配置user与password且该用户具备访问/cluster/state/nodes/http等元数据路径和读取索引的权限。性能提醒某些查询如包含count()的查询在 StarRocks 上的执行速度会明显慢于直接在 ES 上执行因为 ES 可以直接读取满足查询条件的文档数量元数据而无需过滤实际数据。对这类聚合统计场景可评估直接在 ES 侧完成或采用定期物化的方式。连接模式选择若 BE/CN 与 ES 集群处于同一内网建议保持es.nodes.wan.only false让 BE/CN 直连分片所在数据节点以获得更好性能若存在网络隔离、无法访问 ES 内部数据节点地址则须设置为true此时所有流量都经由hosts指定的地址转发。参考源码路径连接器入口与配置绑定ElasticsearchConnector.java、EsConfig.javaREST 客户端版本嗅探、节点发现、分片发现、索引列表EsRestClient.java、EsMajorVersion.java谓词下推与 esquery 转换QueryConverter.java、QueryBuilders.java表属性常量与 doc_values 策略EsTable.java单元测试ElasticsearchMetadataTest.java【免费下载链接】starrocksThe worlds fastest open query engine for sub-second analytics both on and off the data lakehouse. With the flexibility to support nearly any scenario, StarRocks provides best-in-class performance for multi-dimensional analytics, real-time analytics, and ad-hoc queries. A Linux Foundation project.项目地址: https://gitcode.com/GitHub_Trending/st/starrocks创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考