バージョン: 4.x

Elasticsearchカタログ

Elasticsearch Catalogは、ESメタデータの自動マッピングをサポートするだけでなく、Dorisの分散クエリ計画機能とES（Elasticsearch）の全文検索機能を組み合わせて、より包括的なOLAP分析ソリューションを提供します：

ESにおけるマルチインデックス分散Joinクエリ。
DorisとESのTable間でのジョイントクエリと、より複雑な全文検索フィルタリング。

前提条件

Elasticsearch 5.x以上をサポートします。

Elasticsearchへの接続

CREATE CATALOG es_catalog PROPERTIES (
    'type' = 'es',
    'hosts' = 'http://127.0.0.1:9200'
    {ElasticsearchProperties}
);

{ElasticsearchProperties}

Parameter	Required	Default	デスクリプション
`hosts`	Yes		ESアドレス、単一または複数、またはESロードバランサーアドレスを指定可能
`user`	No	Empty	ESユーザー名
`password`	No	Empty	対応するユーザーのパスワード
`doc_value_scan`	No	true	ES/Lucene列指向ストレージを通じてクエリフィールド値を取得することを有効にするかどうか
`keyword_sniff`	No	true	ESの文字列トークン化タイプに対してtext.fieldsを検出し、keywordを通じてクエリするかどうか。falseに設定するとトークン化されたコンテンツに基づいてマッチングされる
`nodes_discovery`	No	true	ESノード検出を有効にするかどうか、デフォルトはtrue。ネットワーク分離環境では指定されたノードのみに接続するためfalseに設定
`ssl`	No	false	ESがhttpsアクセスモードを有効にするかどうか、現在fe/beではtrust allとして実装
`mapping_es_id`	No	false	ESインデックスの_idフィールドをマップするかどうか
`like_push_down`	No	true	likeをwildcardに変換してESにプッシュダウンするかどうか、ESのCPU消費が増加する
`include_hidden_index`	No	false	隠しインデックスを含めるかどうか、デフォルトはfalse

注意事項：

認証は現在HTTP Basic認証のみサポートしており、ユーザーが/_cluster/state/、_nodes/httpなどのパスへのアクセス権限とIndexの読み取り権限を持つことを確認する必要があります。クラスターセキュリティ認証が有効でない場合、ユーザー名とパスワードは不要です。
5.xおよび6.xバージョンでは、1つのIndexに複数のtypeがある場合、デフォルトで最初のtypeが取得されます。

階層マッピング

ElasticsearchにはDatabaseの概念がないため、ESに接続すると一意のDatabaseが自動的に生成されます：default_db。

SWITCHコマンドを使用してES Catalogに切り替えると、自動的にdefault_dbに切り替わるため、USE default_dbコマンドを実行する必要はありません。

カラムタイプマッピング

ES Type	Doris Type	Comment
null	null
boolean	boolean
byte	tinyint
short	smallint
integer	int
long	bigint
unsigned_long	largeint
float	float
half_float	float
double	double
scaled_float	double
date	date	`default`/`yyyy-MM-dd HH:mm:ss`/`yyyy-MM-dd`/`epoch_millis`フォーマットのみサポート
keyword	string
text	string
ip	string
constant_keyword	string
wildcard	string
nested	json
object	json
flattened	json	バージョン3.1.4、4.0.3からサポート
other	UNSUPPORTED

配列タイプ

Elasticsearchには明示的な配列タイプはありませんが、そのフィールドは0個以上の値を含むことができます。

フィールドが配列タイプであることを示すために、インデックスマッピングの_metaセクションに特定のdoris構造注釈を追加できます。

Elasticsearch 6.x以前のバージョンについては、_metaを参照してください。

例えば、次のデータ構造を含むdocインデックスがあるとします：

{
  "array_int_field": [1, 2, 3, 4],
  "array_string_field": ["doris", "is", "the", "best"],
  "id_field": "id-xxx-xxx",
  "timestamp_field": "2022-11-12T12:08:56Z",
  "array_object_field": [
    {
      "name": "xxx",
      "age": 18
    }
  ]
}

この構造体の配列フィールドは、以下のコマンドを使用してターゲットインデックスマッピングの_meta.dorisプロパティにフィールドプロパティ定義を追加することで定義できます。

# ES 7.x and above
curl -X PUT "localhost:9200/doc/_mapping?pretty" -H 'Content-Type:application/json' -d '
{
    "_meta": {
        "doris":{
            "array_fields":[
                "array_int_field",
                "array_string_field",
                "array_object_field"
            ]
        }
    }
}'

# ES 6.x and before
curl -X PUT "localhost:9200/doc/_mapping/_doc?pretty" -H 'Content-Type: application/json' -d '
{
    "_meta": {
        "doris":{
            "array_fields":[
                "array_int_field",
                "array_string_field",
                "array_object_field"
            ]
        }
    }
}

array_fields: 配列型のフィールドを示すために使用されます。

flattened Type

flattened typeの場合、enable_docvalue_scan プロパティが false のとき、読み出されるJSONデータ形式はフラット化されます。enable_docvalue_scan プロパティが true の場合は、元のJSON形式で読み出されます。以下に例を示します：

Index definition:

"mappings": {
   "properties": {
      "column1": {
      "type": "keyword"
      },
      "extra": {
      "type": "flattened"
      }
   }
}

データ:

{
  "column1": 1,
  "extra": {
    "subcol1": "abc",
    "sub_array": [
      {"k1": "element1"},
      {"k2": "element2"},
      {"k3": "element3"}
    ]
  }
}

enable_docvalue_scanプロパティがfalseの場合

extra列のクエリ結果は以下の通りです：

{
   "subcol1": "abc",
   "sub_array": [
      {"k1": "element1"},
      {"k2": "element2"},
      {"k3": "element3"}
   ]
}

enable_docvalue_scanプロパティがtrueの場合

extraカラムのクエリ結果は以下の通りです：
```
["abc","element1","element2","element3"]
```

Query 運用

Catalogを設定した後、以下の方法でCatalog内のTableデータをクエリできます：

-- 1. switch to catalog, use database and query
SWITCH es_ctl;
SELECT * FROM es_tbl LIMIT 10;

-- 2. use default_db directly
USE es_ctl.default_db;
SELECT * FROM es_tbl LIMIT 10;

-- 3. use full qualified name to query
SELECT * FROM es_ctl.default_db.es_tbl LIMIT 10;

より高度なクエリ機能については、[Best Practices]セクションを参照してください。

Best Practices

フィルタ述語プッシュダウン

ES CatalogはFilter Predicate Pushdownをサポートしています：フィルタ条件はESにプッシュダウンされるため、条件を満たすデータのみが返され、クエリパフォーマンスが大幅に向上し、DorisとElasticsearchのCPU、Memory、IO使用量を削減できます。

以下の演算子は対応するES Queryに最適化されます：

SQL syntax	ES 5.x+ syntax
`=`	term query
`in`	terms query
`>` , `<` , `>=` , `<=`	range query
`and`	bool.filter
`or`	bool.should
`not`	bool.must_not
`not in`	bool.must_not + terms query
`is_not_null`	exists query
`is_null`	bool.must_not + exists query
`esquery`	ES native json form QueryDSL

Columnar Scanを有効にしてクエリ速度を最適化 (enable_docvalue_scan=true)

"enable_docvalue_scan" = "true"を設定

有効にすると、DorisはESからデータを取得する際に以下の2つの原則に従います：

Best Effort：読み取り対象フィールドがカラムナーストレージを有効にしているか（doc_value: true）を自動検出します。すべてのフィールドがカラムナーストレージを持つ場合、Dorisはカラムナーストレージからすべてのフィールド値を取得します。
Automatic Degradation：取得対象フィールドのいずれかがカラムナーストレージを持たない場合、すべてのフィールド値は行ストレージ_sourceから解析・取得されます。

利点：

デフォルトでは、Doris On ESは行ストレージ、つまり_sourceから必要なすべての列を取得します。_sourceストレージは行ベース + JSON形式を使用しており、特に少数の列のみが必要な場合、カラムナーストレージと比較してバッチ読み取りパフォーマンスが劣ります。少数の列のみが必要な場合、docvalueのパフォーマンスは_sourceのパフォーマンスの約10倍優れています。

注意事項：

textタイプのフィールドはESにカラムナーストレージを持たないため、取得対象フィールド値のいずれかがtextタイプの場合、自動的に_sourceからの取得に降格します。
取得するフィールド数が多すぎる場合（>= 25）、docvalueからフィールド値を取得するパフォーマンスは基本的に_sourceからフィールド値を取得するパフォーマンスと同じになります。
keywordタイプのフィールドは、この制限を超える長いテキストフィールドに対するignore_aboveパラメータの制限により空になることがあります。この場合、enable_docvalue_scanを無効にして_sourceから結果を取得する必要があります。

Keyword Typeフィールドの検出

"enable_keyword_sniff" = "true"を設定

ESでは、インデックスを作成せずに直接データをインポートできます。この場合、ESは自動的に新しいインデックスを作成します。文字列タイプのフィールドについて、ESはtextタイプとkeywordタイプの両方を持つフィールドを作成します。これはESのmulti fields機能で、マッピングは以下のようになります：

"k4": {
   "type": "text",
   "fields": {
      "keyword": {   
         "type": "keyword",
         "ignore_above": 256
      }
   }
}

k4でのフィルタリング（=など）を行う場合、Doris On ESはクエリをESのTermQueryに変換します。

SQLフィルタ条件：

k4 = "Doris On ES"

ES query DSLに変換:

"term" : {
    "k4": "Doris On ES"

}

k4の最初のフィールドタイプがtextであるため、データインポート時にk4の設定されたtokenizer（設定されていない場合は標準tokenizer）に従ってトークン化され、ES analyze APIで解析されるように3つのTerms（doris、on、es）が取得されます：

POST /_analyze
{
  "analyzer": "standard",
  "text": "Doris On ES"
}

トークン化の結果は以下の通りです：

{
   "tokens": [
      {
         "token": "doris",
         "start_offset": 0,
         "end_offset": 5,
         "type": "<ALPHANUM>",
         "position": 0
      },
      {
         "token": "on",
         "start_offset": 6,
         "end_offset": 8,
         "type": "<ALPHANUM>",
         "position": 1
      },
      {
         "token": "es",
         "start_offset": 9,
         "end_offset": 11,
         "type": "<ALPHANUM>",
         "position": 2
      }
   ]
}

クエリは以下を使用します：

"term" : {
    "k4": "Doris On ES"
}

Doris On ESという用語は辞書内のどの用語とも一致せず、結果を返しません。enable_keyword_sniff: trueを有効にすると、SQLセマンティクスに完全に一致するようk4 = "Doris On ES"をk4.keyword = "Doris On ES"に自動的に変換します。変換されたESクエリDSLは以下の通りです：

"term" : {
    "k4.keyword": "Doris On ES"
}

k4.keywordタイプはkeywordであり、データは完全な項として ES に書き込まれるため、一致させることができます。

ノード自動検出の有効化 (nodes_discovery=true)

"nodes_discovery" = "true"を設定

trueに設定すると、DorisはESから利用可能なすべての関連データノード（上記で割り当てられたシャード）を検出します。ESデータノードアドレスがDoris BEからアクセス可能でない場合は、falseに設定してください。ESクラスターはパブリックインターネットから隔離されたイントラネット内にデプロイされ、ユーザーはプロキシ経由でアクセスします。

ESクラスターがHTTPSアクセスモードを有効にしているかどうか

"ssl" = "true"を設定

現在のFE/BE実装はtrust allであり、これは一時的な解決策で、後で実際のユーザー設定証明書が使用されます。

拡張esquery()関数

esquery(field, QueryDSL)関数を使用して、SQLで表現できない一部のクエリ（match_phrase、geoshapeなど）をESにプッシュダウンしてフィルタリングを行います。esqueryの最初の列名パラメータはindexを関連付けるために使用され、2番目のパラメータは波括弧{}で囲まれたESの基本的なQuery DSLのJSON表現です。JSONroot keyはmatch_phrase、geo_shape、boolなどのように、1つだけ存在する必要があります。

match_phraseクエリ:

select * from es_table where esquery(k4, '{
        "match_phrase": {
           "k4": "doris on es"
        }
    }');

geo関連のクエリ：

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

boolクエリ：

select * from es_table where esquery(k4, ' {
         "bool": {
            "must": [
               {
                  "terms": {
                     "k1": [
                        11,
                        12
                     ]
                  }
               },
               {
                  "terms": {
                     "k2": [
                        100
                     ]
                  }
               }
            ]
         }
      }');

Time Type Field使用推奨事項

ES外部Tableにのみ適用されます。ES Catalogでは、date型は自動的にDateまたはDatetimeにマッピングされます。

ESでは、time型フィールドは非常に柔軟に使用できますが、ES外部Tableにおいて、time型フィールドが適切に設定されていない場合、フィルター条件をプッシュダウンできません。

インデックスを作成する際は、最大限のフォーマット互換性のためにtime型フォーマットを設定してください：

 "dt": {
     "type": "date",
     "format": "yyyy-MM-dd HH:mm:ss||yyyy-MM-dd||epoch_millis"
 }

Dorisでこのフィールドを設定する際は、dateまたはdatetimeに設定することを推奨します。またはvarchar型として設定することも可能です。以下のSQL文を使用することで、フィルタ条件を直接ESにプッシュダウンできます：

select * from doe where k2 > '2020-06-21';

select * from doe where k2 < '2020-06-21 12:00:00'; 

select * from doe where k2 < 1593497011; 

select * from doe where k2 < now();

select * from doe where k2 < date_format(now(), '%Y-%m-%d');

Note:

ESで時間型フィールドにformatを設定しない場合、デフォルトの時間型フィールドフォーマットは以下のとおりです：
```
strict_date_optional_time||epoch_millis
```
ESにインポートされる日付フィールドがタイムスタンプの場合、msに変換する必要があります。ESは内部的にタイムスタンプをmsで処理するため、そうしないとES外部Tableで表示エラーが発生します。

ESメタデータフィールドIDの取得

_idを指定せずにドキュメントをインポートする場合、ESは各ドキュメントにグローバルに一意な_id（主キー）を割り当てます。ユーザーは、インポート時に特別なビジネス意味を持つ_idを指定することもできます。

ES外部Tableでこのフィールド値を取得する必要がある場合、Table作成時にvarchar型の_idフィールドを追加できます：

CREATE EXTERNAL TABLE `doe` (
  `_id` varchar COMMENT "",
  `city`  varchar COMMENT ""
) ENGINE=ELASTICSEARCH
PROPERTIES (
"hosts" = "http://127.0.0.1:8200",
"user" = "root",
"password" = "root",
"index" = "doe"
}

ES Catalogでこのフィールド値を取得する必要がある場合は、"mapping_es_id" = "true"を設定してください。

注意:

_idフィールドのフィルタ条件は=とinのみサポートします。
_idフィールドはvarchar型である必要があります。

グローバルに順序付けられたクエリ結果の取得

関連性ランキングや重要なコンテンツの優先表示などのシナリオでは、ESクエリ結果がスコアによってソートされることは非常に有用です。DorisはESにクエリを実行する際、ESインデックスのshard分散に従ってデータを取得することでMPPアーキテクチャの利点を最大限に活用します。グローバルに順序付けられたソート結果を取得するには、ESを単一ポイントからクエリする必要があります。これはセッション変数enable_es_parallel_scroll（デフォルトはtrue）で制御できます。 enable_es_parallel_scroll=falseが設定された場合、Dorisはshard_preferenceとsort情報なしでscrollクエリをESクラスタに送信し、グローバルに順序付けられた結果を取得します。注意：クエリ結果セットが大きい場合は注意して使用してください。

scrollリクエストのバッチサイズの変更

scrollリクエストのデフォルトのbatchサイズは4064です。セッション変数batch_sizeを通じて変更できます。

よくある質問

X-Pack認証を使用するESクラスタをサポートしますか？

HTTP Basic認証を使用するすべてのESクラスタをサポートします。
一部のクエリがESに直接リクエストするよりもかなり遅い

はい、_count関連クエリなどです。ESは条件を満たすドキュメント数に関するメタデータを内部で直接読み取り、実際のデータをフィルタリングしません。
集約操作をプッシュダウンできますか？

現在、Doris On ESはsum、avg、min/maxなどの集約操作のプッシュダウンをサポートしていません。計算方法は、条件を満たすすべてのドキュメントをESからバッチストリームで取得し、その後Dorisで計算することです。

付録

DorisがESをクエリする原理

+----------------------------------------------+
|                                              |
| Doris      +------------------+              |
|            |       FE         +--------------+-------+
|            |                  |  Request Shard Location
|            +--+-------------+-+              |       |
|               ^             ^                |       |
|               |             |                |       |
|  +-------------------+ +------------------+  |       |
|  |            |      | |    |             |  |       |
|  | +----------+----+ | | +--+-----------+ |  |       |
|  | |      BE       | | | |      BE      | |  |       |
|  | +---------------+ | | +--------------+ |  |       |
+----------------------------------------------+       |
   |        |          | |        |         |          |
   |        |          | |        |         |          |
   |    HTTP SCROLL    | |    HTTP SCROLL   |          |
+-----------+---------------------+------------+       |
|  |        v          | |        v         |  |       |
|  | +------+--------+ | | +------+-------+ |  |       |
|  | |               | | | |              | |  |       |
|  | |   DataNode    | | | |   DataNode   +<-----------+
|  | |               | | | |              | |  |       |
|  | |               +<--------------------------------+
|  | +---------------+ | | |--------------| |  |       |
|  +-------------------+ +------------------+  |       |
|   Same Physical Node                         |       |
|                                              |       |
|           +-----------------------+          |       |
|           |                       |          |       |
|           |      MasterNode       +<-----------------+
| ES        |                       |          |
|           +-----------------------+          |
+----------------------------------------------+

FEはTable作成時に指定されたホストにリクエストを送信し、すべてのノードのHTTPポート情報やインデックスのシャード分散情報などを取得します。リクエストが失敗した場合、成功するか完全に失敗するまでホストリストを順次たどります。
クエリ実行時、FEが取得したノード情報とインデックスメタデータ情報に基づいてクエリプランが生成され、対応するBEノードに送信されます。
BEノードはproximity principleに従って、まずローカルにデプロイされたESノードにリクエストを送信します。BEはHTTP Scrollメソッドを使用して_sourceまたはdocvalueからストリーミングで、ESインデックスの各シャードから並行してデータを取得します。
Dorisが計算を完了すると、結果をユーザーに返します。

前提条件​

Elasticsearchへの接続​

階層マッピング​

カラムタイプマッピング​

配列タイプ​

flattened Type​

Query 運用​

Best Practices​

フィルタ述語プッシュダウン​

Columnar Scanを有効にしてクエリ速度を最適化 (enable_docvalue_scan=true)​

Keyword Typeフィールドの検出​

ノード自動検出の有効化 (nodes_discovery=true)​

ESクラスターがHTTPSアクセスモードを有効にしているかどうか​

拡張esquery()関数​

Time Type Field使用推奨事項​

ESメタデータフィールドIDの取得​

グローバルに順序付けられたクエリ結果の取得​

scrollリクエストのバッチサイズの変更​

よくある質問​

付録​

DorisがESをクエリする原理​