Elasticsearch Catalog

StarRocks 从 v3.1 版本开始支持 Elasticsearch catalog。

StarRocks 和 Elasticsearch 都是流行的分析系统，各有优势。 StarRocks 擅长大规模分布式计算，支持通过外部表查询 Elasticsearch 中的数据。 Elasticsearch 以其全文搜索功能而闻名。 StarRocks 和 Elasticsearch 的结合提供了更全面的 OLAP 解决方案。 使用 Elasticsearch catalog，您无需迁移数据，即可通过在 StarRocks 上使用 SQL 语句直接分析 Elasticsearch 集群中的所有索引数据。

与其他数据源的 catalog 不同，Elasticsearch catalog 在创建时只有一个名为 default 的数据库。每个 Elasticsearch 索引都会自动映射到一个数据表并挂载到 default 数据库。

创建 Elasticsearch catalog

语法

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

参数

catalog_name

Elasticsearch catalog 的名称。命名约定如下

• 该名称可以包含字母、数字 (0-9) 和下划线 (_)。它必须以字母开头。
• 该名称区分大小写，长度不能超过 1023 个字符。

comment

Elasticsearch catalog 的描述。此参数是可选的。

PROPERTIES

Elasticsearch catalog 的属性。下表描述了 Elasticsearch catalog 支持的属性。

参数	必需	默认值	描述
hosts	是	None (无)	Elasticsearch 集群的连接地址。您可以指定一个或多个地址。 StarRocks 可以从此地址解析 Elasticsearch 版本和索引分片分配。 StarRocks 根据 GET /_nodes/http API 操作返回的地址与您的 Elasticsearch 集群通信。因此，hosts 参数的值必须与 GET /_nodes/http API 操作返回的地址相同。否则，BE 或 CN 可能无法与您的 Elasticsearch 集群通信。
type	是	None (无)	数据源的类型。创建 Elasticsearch catalog 时，将此参数设置为 es。
user	否	空	用于登录启用 HTTP 基本身份验证的 Elasticsearch 集群的用户名。确保您有权访问诸如 /cluster/state/ nodes/http 之类的路径，并且有权读取索引。
password	否	空	用于登录 Elasticsearch 集群的密码。
es.type	否	_doc	索引的类型。如果您想查询 Elasticsearch 8 及更高版本中的数据，则无需配置此参数，因为映射类型已在 Elasticsearch 8 及更高版本中删除。
es.nodes.wan.only	否	FALSE	指定 StarRocks 是否仅使用 hosts 指定的地址来访问 Elasticsearch 集群并获取数据。 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 集群。只有 StarRocks v2.4 及更高版本支持配置此参数。 true：HTTPS 和 HTTP 协议都可以用于访问您的 Elasticsearch 集群。 false：只有 HTTP 协议可以用于访问您的 Elasticsearch 集群。
enable_docvalue_scan	否	TRUE	指定是否从 Elasticsearch 列式存储中获取目标字段的值。在大多数情况下，从列式存储读取数据优于从行式存储读取数据。
enable_keyword_sniff	否	TRUE	指定是否基于 KEYWORD 类型字段嗅探 Elasticsearch 中的 TEXT 类型字段。如果此参数设置为 false，则 StarRocks 在分词后执行匹配。

示例

以下示例创建一个名为 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 以执行。这最大限度地减少了查询引擎和存储源之间的距离，并提高了查询性能。下表列出了可以下推到 Elasticsearch 的运算符。

SQL 语法	Elasticsearch 语法
=	term query
in	terms query
>=, <=, >, <	range
and	bool.filter
或	bool.should
not	bool.must_not
not in	bool.must_not + terms
esquery	ES Query DSL

查询示例

esquery() 函数可用于将无法用 SQL 表示的 Elasticsearch 查询（例如 match 和 geoshape 查询）下推到 Elasticsearch 以进行过滤和处理。在 esquery() 函数中，指定列名的第一个参数用于与索引关联，第二个参数是基于 Elasticsearch 查询的 Elasticsearch Query DSL 的 JSON 表示形式，用花括号 ({}) 括起来。 JSON 表示形式可以并且必须只有一个根键，例如 match、geo_shape 或 bool。

• Match query

  SELECT * FROM es_table WHERE esquery(k4, '{
     "match": {
        "k4": "StarRocks on elasticsearch"
     }
  }');

• Geoshape query

  SELECT * FROM es_table WHERE esquery(k4, '{
  "geo_shape": {
     "location": {
        "shape": {
           "type": "envelope",
           "coordinates": [
              [
                 13,
                 53
              ],
              [
                 14,
                 52
              ]
           ]
        },
        "relation": "within"
     }
  }
  }');

• Boolean query

  SELECT * FROM es_table WHERE esquery(k4, ' {
     "bool": {
        "must": [
           {
              "terms": {
                 "k1": [
                    11,
                    12
                 ]
              }
           },
           {
              "terms": {
                 "k2": [
                    100
                 ]
              }
           }
        ]
     }
  }');

使用说明

• 从 v5.x 版本开始，Elasticsearch 采用了一种不同的数据扫描方法。 StarRocks 仅支持从 Elasticsearch v5.x 及更高版本查询数据。
• StarRocks 仅支持从启用了 HTTP 基本身份验证的 Elasticsearch 集群查询数据。
• 某些查询，例如涉及 count() 的查询，在 StarRocks 上的运行速度比在 Elasticsearch 上慢得多，因为 Elasticsearch 可以直接读取与满足查询条件的指定文档数量相关的元数据，而无需过滤请求的数据。