跳到主要内容
版本：Stable-3.5

Elasticsearch catalog

StarRocks 自 3.1 版本起支持 Elasticsearch Catalog。

StarRocks 与 Elasticsearch 都是目前流行的分析系统。StarRocks 擅长大规模分布式计算，且支持通过外部表查询 Elasticsearch。Elasticsearch 擅长全文检索。两者结合提供了一个更完善的 OLAP 解决方案。基于 Elasticsearch Catalog，您可以直接通过 StarRocks 使用 SQL 分析 Elasticsearch 集群内所有的索引数据，并且无需数据迁移。

区别于其他数据源的 Catalog，Elasticsearch Catalog 创建后，下面只有一个名为 default_db 的数据库 (Database)，每一个 Elasticsearch 索引 (Index) 自动映射一张数据表 (Table)，并且都会自动挂载在 default_db 数据库下面。

创建 Elasticsearch Catalog​

语法​

CREATE EXTERNAL CATALOG <catalog_name>
[COMMENT <comment>]
PROPERTIES ("key"="value", ...)

参数说明​

catalog_name​

Elasticsearch Catalog 的名称。命名规则如下：

  • 必须由字母 (a-z 或 A-Z)、数字 (0-9) 或下划线 (_) 组成，且只能以字母开头。
  • 总长度不能超过 1023 个字符。
  • Catalog 名称大小写敏感。

comment​

Elasticsearch Catalog 的描述。此参数为可选。

PROPERTIES​

Elasticsearch Catalog 的属性。支持如下属性：

参数是否必须默认值说明
hosts是无Elasticsearch 集群连接地址，用于获取 Elasticsearch 版本号以及索引的分片分布信息，可指定一个或多个。StarRocks 是根据 GET /_nodes/http API 返回的地址和 Elasticsearch 集群进行通讯，所以 hosts 参数值必须和 GET /_nodes/http 返回的地址一致，否则可能导致 BE（或 CN）无法和 Elasticsearch 集群进行正常的通讯。
type是无数据源的类型。创建 Elasticsearch Catalog 时，必须设置为 es。
user否空开启 HTTP Basic 认证的 Elasticsearch 集群的用户名，需要确保该用户有访问 /cluster/state/ nodes/http 等路径权限和对索引的读取权限。
password否空对应用户的密码信息。
es.type否_doc指定索引的类型。如果您要查询的是数据是在 Elasticsearch 8 及以上版本，那么在 StarRocks 中创建外部表时就不需要配置该参数，因为 Elasticsearch 8 以及上版本已经移除了 mapping types。
es.nodes.wan.only否false表示 StarRocks 是否仅使用 hosts 指定的地址，去访问 Elasticsearch 集群并获取数据。自 2.3.0 版本起，StarRocks 支持配置该参数。
  • true：StarRocks 仅使用 hosts 指定的地址去访问 Elasticsearch 集群并获取数据，不会探测 Elasticsearch 集群的索引每个分片所在的数据节点地址。如果 StarRocks 无法访问 Elasticsearch 集群内部数据节点的地址，则需要配置为 true。
  • false：StarRocks 通过 hosts 中的地址，探测 Elasticsearch 集群索引各个分片所在数据节点的地址。StarRocks 经过查询规划后，相关 BE（或 CN）节点会直接去请求 Elasticsearch 集群内部的数据节点，获取索引的分片数据。如果 StarRocks 可以访问 Elasticsearch 集群内部数据节点的地址，则建议保持默认值 false。
es.net.ssl否false是否允许使用 HTTPS 协议访问 Elasticsearch 集群。自 2.4 版本起，StarRocks 支持配置该参数。
  • true：允许，HTTP 协议和 HTTPS 协议均可访问。
  • false：不允许，只能使用 HTTP 协议访问。
enable_docvalue_scan否true是否从 Elasticsearch 列式存储获取查询字段的值。多数情况下，从列式存储中读取数据的性能要优于从行式存储中读取数据的性能。
enable_keyword_sniff否true是否对 Elasticsearch 中 TEXT 类型的字段进行探测，通过 KEYWORD 类型字段进行查询。设置为 false 会按照分词后的内容匹配。

创建示例​

执行如下语句创建一个名为 es_test 的 Elasticsearch Catalog：

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"
);

谓词下推​

StarRocks 支持对 Elasticsearch 表进行谓词下推，把过滤条件推给 Elasticsearch 进行执行，让执行尽量靠近存储，提高查询性能。目前支持下推的算子见下表：

SQL syntaxElasticsearch syntax
=term query
interms query
>=, <=, >, <range
andbool.filter
orbool.should
notbool.must_not
not inbool.must_not + terms
esqueryES Query DSL

查询示例​

通过 esquery() 函数将一些无法用 SQL 表述的 Elasticsearch 查询（如 Match 查询和 Geoshape 查询等）下推给 Elasticsearch 进行过滤处理。esquery() 的第一个列名参数用于关联索引，第二个参数是 Elasticsearch 的基本 Query DSL 的 JSON 表述，使用花括号（{}）包含，JSON 的根键 (Root Key) 有且只能有一个，如 match、geo_shape 或 bool 等。

  • 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
                   ]
                }
             }
          ]
       }
    }');

注意事项​

  • Elasticsearch 5.x 版本之前和之后的数据扫描方式不同，目前 StarRocks 只支持查询 Elasticsearch 5.x 版本之后的版本。
  • 支持查询使用 HTTP Basic 认证的 Elasticsearch 集群。
  • 一些通过 StarRocks 的查询会比直接请求 Elasticsearch 会慢很多，比如 count() 相关查询。这是因为 Elasticsearch 内部会直接读取满足条件的文档个数相关的元数据，不需要对真实的数据进行过滤操作，使得 count() 的速度非常快。