ElasticsearchとOpenSearch
Query DSL、SQL、ES|QL、PPLでの検索のしかた、ページ送りのしくみ、集計と「説明」に表示されるもの、そして「クエリー」が読むだけである理由。
場所: ワークスペース › ツール › クエリー
対象: Elasticsearch OpenSearch
「クエリー」は、入力した内容を開いているセッションでクラスタに送ります。「実行」(⌘↩)で実行し、「停止」(⌘.)で応答を待つのをやめます。サーバがすでに始めたことは、それでも終わることがあります。実行中、検索は経過時間とともに「アクティビティ」に表示され、そこからも停止できます。
言語
バーの言語のピッカーには、セッションの製品の言語だけが出ます。どちらにも「Query DSL」(_searchのJSON本文)とSQLがあります。
Elasticsearch
Elasticsearchには、パイプ形式の言語ES|QLもあります:FROM demo_productos | WHERE precio > 40 | LIMIT 10。
OpenSearch
OpenSearchには、パイプ形式の言語PPLもあります:source=demo_productos | where precio > 40 | head 10。
Query DSL
本文全体が、「インデックス」に書いたインデックスの_searchに送られます。空ならすべてで、複数はカンマで区切ります。「インデックスを選択」でその一覧が出ます。「ページ:50」メニューは1ページあたりのドキュメント数を決めます(変えなければ50件)。ただし本文に独自のsizeがあれば、そちらが優先されます。壊れたJSONはサーバが拒否し、エラーが間違いの場所(行と列、または本文のバイト位置)を示します。
ページと合計
「次のページ」で次のページを求めます。検索がソート(sort)していればsearch_afterで進み、受け取った最後のドキュメントから続けるので上限はありません。ソートしていなければfromで進み、サーバは10,000件で打ち切ります。表示にもそう出ます。サーバは10,000件で数えるのをやめ、合計は「10,000件以上」と表示されます。「正確な合計」はすべて数えるよう求めます(track_total_hits)。時間はかかります。
表示されるもの
「ドキュメント」は各ドキュメントを1行に折りたたみ、スコアとともに表示します。開くと_source全体が出ます。「表」はフィールドを列に並べ、ネストしたオブジェクトは平らにします。本文にaggsがあれば、下に「集計」がツリーで表示されます。各ドキュメントの「説明」は、そのドキュメントが検索に一致する理由をサーバに尋ね(_explain)、スコアの計算方法を表示します。
SQL、ES|QL、PPL
これらの言語では、インデックスはクエリーの中(FROM、source=)に書き、応答は表になります。各列の見出しにはサーバが宣言する型が付きますが、言語や製品の間で一致するとは限りません。クラスタのライセンスにその言語が含まれていなければ、サーバがそう伝えます。Elasticsearchのベーシックライセンスには、SQLとES|QLが含まれます。
Elasticsearch
SQLでの「Query DSLに変換」は、同じ意味のQuery DSLをElasticsearchに求め(_sql/translate)、FROMのインデックスを入れた状態で「Query DSL」に開きます。
OpenSearch
OpenSearchはSQLをQuery DSLに変換せず、エンジンの実行計画を返すだけです。そのため、OpenSearchではバーに「Query DSLに変換」がありません。
読むだけです
「クエリー」は書き込みません。Query DSLの本文は必ず_searchに送られ、SQL、ES|QL、PPLは問い合わせしかせず、SQLで書いたDELETEは送られません。クエリーによる削除や更新(_delete_by_query、_update_by_query)もここにはありません。
キーワード: Elasticsearch、OpenSearch、クエリー、検索、Query DSL、_search、SQL、ES|QL、ESQL、PPL、search_after、FROM、合計、集計、説明、_explain、変換
インデックスの各タブに表示されるもの、書き込めるものとその方法、スローログの行き先、そして再インデックスがない理由。
場所: ワークスペース › ツール › インデックス
対象: Elasticsearch OpenSearch
このタブには3つのセクションがあり、ツールバーのピッカーで選びます:「インデックス」、「テンプレート」、「パイプライン」。「再読み込み」は画面のセクションを読み直します。
インデックス
左側には、クラスタのインデックスが、ヘルス(グリフとその名前。色だけで示すことはありません)、ドキュメント数、サイズとともに並びます。システムインデックス(ドットで始まるものと、サーバが隠すもの)は専用のグループに折りたたまれます。一覧のドキュメント数はLuceneの数で、nestedフィールドのオブジェクトを1つずつ数えます。検索が返す数は「統計」にあります。インデックスを選ぶと右側に詳細が表示され、タブは開いたときに読み込まれます:
- 「フィールド」:マッピングをツリーで表示します。各フィールドに型、パラメータ、サブフィールドが付きます。
- 「設定」:インデックスに書かれた設定(デフォルトではないもの)で、最初にスローログのしきい値があります。
- 「シャード」:プライマリとレプリカの各シャードを、状態、ノード、ノードがなければその理由とともに表示します。
- 「エイリアス」:インデックスを指すエイリアス。
- 「ドキュメント」:ドキュメントのサンプル(25件ずつ)。
- 「統計」:トップレベルのドキュメント数とLuceneの数、サイズ、アクティビティのカウンタ。カウンタは、インデックスがそのノードで開かれてからの累計です。
ドキュメント
サンプルはインデックスが格納している順に並び、正確な合計が出ます。たどれるのは最初の10,000件(index.max_result_window)までで、それを超えると画面にそう表示されます。インデックス全体をたどるには、search_afterでページを送る「クエリー」を使います。
書き込めるもの
ツールバーの「新規インデックス…」は、新しいインデックスのJSONを開きます。シャード1つ、レプリカなし、空のマッピングです。詳細の「インデックスを削除…」は、インデックスの名前とドキュメント数を示して確認します。システムインデックスには出ません。「ドキュメント」の「新規ドキュメント…」は、入力した_idでドキュメントを作成します(すでにあれば、サーバは拒否し、置き換えません)。空にすれば、サーバが_idを割り当てます。「ドキュメントを編集…」はドキュメントを丸ごと置き換えます。シートで消したフィールドはなくなります。また、読み込んでから誰も変えていない場合に限ります。変えられていれば、サーバは拒否し、ほかの変更を上書きしません。「ドキュメントを削除…」は_idを示して確認します。すべて接続の保護を通り、読み出し専用のタグがあれば、どれも表示されません。
スローログ
「設定」の「スローログのしきい値を編集…」で、どれだけ遅い検索からログに書くかを設定します。クエリーフェーズとフェッチフェーズのそれぞれに、警告と情報があります。単位付きの時間(500ms、2s)を入力してください。-1でオフになり、空にすると何も記録しないデフォルトに戻ります。
OpenSearch
OpenSearchでは、シートにログレベル(index.search.slowlog.level)もあります。
ログを保持するのはCalíopeではなく、書くのはサーバです。パッケージでインストールした場合はログのディレクトリ(path.logs)の<cluster>_index_search_slowlogというファイルに、コンテナではコンテナの出力(docker logs)に書かれます。
テンプレートとパイプライン
インデックスではなくクラスタに属し、読み出し専用です。各行はテンプレート(パターン、優先度、構成するテンプレート)またはパイプライン(説明とプロセッサの数)を要約します。開くとJSON全体が表示されます。レガシーテンプレート(_template)もそう印を付けて表示されます。サーバが自分のものと宣言しているものと、ドットで始まるものは、グループに折りたたまれます。Calíopeは編集しません。変更はAPIで行います。
行わないこと
再インデックス(_reindex)も、既存のフィールドの型の変更もありません。サーバはすでにデータのあるフィールドの型を変えませんし、あるインデックスを別のインデックスにコピーするのは、APIで始めるサーバの長い作業だからです。
キーワード: Elasticsearch、OpenSearch、インデックス、マッピング、設定、シャード、エイリアス、ドキュメント、統計、スローログ、テンプレート、_index_template、パイプライン、インジェスト、max_result_window
緑・黄・赤の意味、ノードの数え方、ロールとは何か、シャードにノードがない理由の読み方。
場所: ワークスペース › ツール › クラスタ
対象: Elasticsearch OpenSearch
このタブは、開いたときと「更新」でクラスタを読み込みます。クラスタは変化を知らせないので、自動では更新されません。
ヘルス
いちばん上にヘルスが、グリフとその名前で表示されます。色だけで示すことはありません:
- 緑:プライマリもレプリカも、すべてのシャードにノードがあります。
- 黄:すべてのプライマリにノードがありますが、一部のレプリカにはありません。データはすべて読み書きできます。足りないのは、ノードが落ちたときにレプリカが与えるはずのコピーです。
- 赤:ノードのないプライマリがあり、そのシャードのドキュメントは読むことも書くこともできません。
その下に、クラスタが期待するノードのうち応答しているものの数があります。数はセッションが見たノードとクラスタの投票構成から出すので、接続する前に落ちたノードも数えられます。そのノードは名前を伝える者がいないので、IDで示されます。続いてマスター(_cat/master)とシャード:アクティブ、移動中、初期化中、未割り当て。ノードが落ちると、そのレプリカは別の場所にコピーされる前に、ノードが戻るのを1分待ちます(index.unassigned.node_left.delayed_timeout)。数のかっこ書きでそう示されます。
ノード
ノードごとに1行で、ロール、ヒープ、RAM、CPU、負荷、ディスク、シャード、バージョンを表示します。「ロール」はnode.roleの文字です:mはマスター、dはデータ、iはインジェスト、rはリモートクラスタのクライアント、lは機械学習、tは変換、vは投票専用、データ層はhがホット、wがウォーム、cがコールド、fがフローズン、sがコンテンツです。凡例は表の下に書かれ、Macではポインタを重ねると全部を読み上げます。
問題のあるシャード
アクティブでないシャード。未割り当てが先で、プライマリがレプリカより先、ユーザのインデックスがシステムのものより先です。最初の未割り当てのシャードはPOST /_cluster/allocation/explainで説明されます:「理由」(たとえばNODE_LEFTはノードが離脱したこと)、「割り当てできますか?」、そして各ノードの判断。「サーバの説明」はサーバのテキストそのままで、英語です。よくある例:ノードが2つのとき、レプリカ2つのインデックスには2つ目の置き場所がありません。ノードは同じシャードのコピーを2つ持たない(same_shard)ため、3つ目のノードが戻るまでクラスタは黄のままです。
待機中のクラスタタスクと進行中のリカバリ
順番を待っているクラスタタスク(_cat/pending_tasks)と、進行中のシャードのコピー(_cat/recovery)。
読み込めなかった部分には注意書きが付き、ほかの部分はそのまま表示されます。このタブは読むだけで、シャードの再割り当てもクラスタ設定の変更もしません。
キーワード: Elasticsearch、OpenSearch、クラスタ、ヘルス、緑、黄、赤、ノード、マスター、シャード、未割り当て、allocation explain、レプリカ、ロール、node.role、待機中のタスク、リカバリ
各カードが測るもの、ヒープの警告が75 %から出る理由、レートが2回の読み込みの差である理由、スレッドプールの拒否の意味。
場所: ワークスペース › ツール › ノード
対象: Elasticsearch OpenSearch
このタブは、開いたときと、前面にある間は5秒ごとにノードを読み込みます。タブを切り替えると読み込みは止まります。自動で読み込んでいる間、「アクティビティ」には「検索ノード(5秒ごと)」と表示されます。「更新」ですぐに読み込みます。
ノード
デフォルトは、セッションに応答しているノードです。クラスタに複数のノードがあれば、ピッカーで別のノードを選べます。
カード
- 「JVMヒープ」:最大値に対する使用量。75 %からグリフとテキストの警告が付きます。Elasticがメモリーの逼迫を調べるよう勧めるしきい値で、それを超えるとJVMはコレクションにより多くの時間を使い、ノードのメモリーが尽きる前に要求を打ち切る*サーキットブレーカー*が作動に近づくためです。
- 「ガベージコレクション」:新世代と旧世代のコレクションと、かかった時間。旧世代が急に増えるのは、ヒープが追いついていない兆候です。
- 「CPU」:マシンのCPUと、その下にノードのプロセスのCPU。
- 「ディスク」:使用量は合計から空きを引いたものです。85 %から警告が付きます。クラスタのディスクの低ウォーターマーク(cluster.routing.allocation.disk.watermark.low)で、それを超えるとクラスタはそのノードにレプリカを割り当てなくなります。
- 「1秒あたりのクエリー」と「1秒あたりにインデックスされたドキュメント」:前者には、期間内のクエリーの平均レイテンシが付きます。
レートは差です
サーバが返すのは、ノードの起動から累積したカウンタだけです。レートは2回の読み込みの差を、ノードの時計で測ったその間の時間で割ったものなので、最初の読み込みでは「2回目の読み込みが必要です」と表示され、数値は次の読み込みで出ます。その下に起動からの合計が付きます。
スレッドプール
各プールのスレッド、アクティブなもの、キュー、拒否、完了。プールのキューがいっぱいになると、ノードは待たずに次の要求を429で拒否します。拒否のあるプールはグリフで目立ち、アイドルのものは折りたたまれます。拒否と完了は起動から数えたものです。大きな数値は古いこともあり、大事なのは読み込みの間に増えているかどうかです。
ノードの詳細
バージョン、ロール、アドレス、オペレーティングシステム、プロセッサ、JVM、最大ヒープ、パス、プラグイン。
ホットスレッド
「ホットスレッドを読み込む」で、ノードは0.5秒サンプリングし、CPUをもっとも使った3つのスレッドを返します。サーバのテキストそのままで、英語です。ノードがアイドルなら見出しだけが届きます。
このタブは読むだけで、ノードの設定は変えません。
キーワード: Elasticsearch、OpenSearch、ノード、JVM、ヒープ、GC、ガベージコレクション、CPU、ディスク、ウォーターマーク、1秒あたりのクエリー、インデックス、スレッドプール、拒否、429、ホットスレッド、プラグイン
タスクのツリーに表示されるもの、読み直す頻度、キャンセルできるタスク、キャンセルしたときのサーバの応答。
場所: ワークスペース › ツール › タスク
対象: Elasticsearch OpenSearch
このタブは、開いたときと、前面にある間は3秒ごとに、クラスタのタスクを読み込みます(GET /_tasks?detailed=true&group_by=parents)。タブを切り替えると読み込みは止まります。自動で読み込んでいる間、「アクティビティ」には「検索タスク(3秒ごと)」と表示されます。「更新」ですぐに読み込みます。
ツリー
各親タスクの下に子タスクが、実行時間の長い順に並びます。各行にはアクション、説明、ノードの名前(名前が不明ならID)、実行時間が出ます。クエリーによる削除、クエリーによる更新、*再インデックス*では、何件中何件のドキュメントを処理したかも示します。
フィルタ
大文字と小文字を区別せずにアクションか説明に一致させ、子のどれかが一致すれば親も残ります。
キャンセルの対象に出ないもの
- 一覧を求めること自体がサーバのタスクで、「この一覧」と表示されます。
- 永続タスク(「永続(クラスタ自身のもの)」)は、サーバはキャンセル可能と示しますが、クラスタ自身のものなので対象に出ません。
- サーバがキャンセル可能と示さないタスク、すでにキャンセルを求めたタスク、そして読み出し専用の接続ではすべてのタスク。
タスクをキャンセル
先に確認します。アラートにはアクション、説明、ノードが表示され、「続行させる」で続行させられます。キャンセルは、できるだけ早く止めるようサーバに頼むもので、すでに行ったことは元に戻りません。サーバは必ず成功で応答し、画面に何が起きたかが表示されます:タスクをキャンセル済みにした、タスクはすでに終わっていた、またはそのノードがもうクラスタにない。
キーワード: Elasticsearch、OpenSearch、タスク、_tasks、キャンセル、delete_by_query、update_by_query、再インデックス、永続、ノード、進行状況
タブに表示されるリポジトリとスナップショット、作成のしかた、終わるまでの追い方、そして復元のしかた。
場所: ワークスペース › ツール › スナップショット
対象: Elasticsearch OpenSearch
このタブは、サーバのスナップショットのリポジトリ(GET /_snapshot)と、選んだリポジトリのスナップショット(GET /_snapshot/<repository>/_all)を読み込みます。
リポジトリ
サーバに複数あれば、バーで選びます。その下に種類と設定が表示されます。資格情報を指す設定は伏せられます(••••)。リポジトリがまったくなければ、画面にそう表示されます。リポジトリはサーバに登録するもので(PUT /_snapshot/<name>)、fsのリポジトリは、サーバの構成で、すべてのノードのpath.repoにそのフォルダが入っている必要があります。Calíopeはリポジトリを登録しません。
スナップショット
新しい順に並びます。各スナップショットには、状態がグリフと言葉(「完了」「進行中」「一部:失敗したシャードがあります」「失敗」)で、さらに開始時刻、所要時間、シャードとインデックス、そして失敗した各シャードの失敗内容が表示されます。
スナップショットを作成
名前とインデックスを入れるシートが開きます。提案される名前には日時が入ります(snapshot-YYYY.MM.DD-HHMMSS)。小文字で空白なしでなければならず、そうでなければサーバが拒否し、シートにその理由が表示されます。インデックスはカンマで区切り、ワイルドカードも使えます。空ならクラスタのすべてです。存在しないインデックスは飛ばされ、グローバルな状態(テンプレートとクラスタ設定)は含まれません。作成は接続の書き込みガードを通ります。読み出し専用の接続ではボタンが出ません。
サーバが要求を受け付けるとすぐにシートは閉じ、「アクティビティ」がスナップショットを「検索のスナップショット」として、終わったシャードを進行状況として追います。「停止」はありません。止めると中途半端に残るからです。終了はスナップショットの一覧で確かめます。OpenSearchは終わったと伝えるまで少し時間がかかるためです。10分たってもまだ実行中なら、画面にそう表示され、どう終わったかはあとで「更新」でわかります。
復元…
完了したスナップショットにはすべてあります(接続が読み出し専用でなければ)。シートでは、インデックス(最初はすべて)、名前のパターンと新しい名前、「グローバルな状態を含める」のスイッチを選びます。サーバは同じ名前の開いているインデックスの上には決して復元しません。snapshot_restore_exceptionで拒否し、シートにそのテキストが表示されます。そのためシートは別の名前を提案します:(.+) → restored_$1で、demo_logsは今あるものの隣にrestored_demo_logsとして戻ります。パターンを空にすると各インデックスは元の名前で戻りますが、それはそのインデックスが閉じているか、ないときだけ使えます。グローバルな状態(テンプレート、永続的な設定)は最初はオフです。復元すると現在のものが置き換わります。復元は接続の書き込みガードを通り、サーバが終えるまで待ち(POST /_snapshot/<repository>/<name>/_restore?wait_for_completion=true)、そのあとで戻ったインデックスを伝えます。
キーワード: Elasticsearch、OpenSearch、スナップショット、_snapshot、リポジトリ、path.repo、作成、復元、シャード、バックアップ
各セクションに表示されるもの、作成・変更・削除できるもの、APIキーが一度しか表示されない理由、そしてOpenSearchで変わること。
場所: ワークスペース › ツール › ユーザとロール
対象: Elasticsearch OpenSearch
このタブは、開いたときにサーバのユーザとロールを読み込みます。「更新」で読み直します。セクションはバーで選びます。
ユーザ
各ユーザにはロールと、該当すれば印が付きます:「自分」は接続しているユーザ、「予約済み」はサーバが作成したもので触れません、「無効」はサインインできません。自分のユーザと予約済みのユーザは、削除の対象にもロールの変更の対象にも出ません。自分から外すと、自分が締め出されてしまうからです。
「新規ユーザ」で、名前、パスワード、ロールを入れるシートが開きます。その名前のユーザがすでにあれば、シートはそう伝え、置き換えません。パスワードはサーバに送られ、Calíopeには保存されず、コマンドログでは伏せられます。Elasticsearchは6文字以上を求めます。OpenSearchは弱いものや名前に似たものを拒否し、シートにその理由が表示されます。
「ロールを変更…」はロールだけを変えます。パスワードやユーザのほかの部分はそのままです。「ユーザを削除」はユーザとサーバを示して確認を求め、元に戻せません。書き込むものはすべて接続の書き込みガードを通ります。読み出し専用の接続ではボタンが出ません。
ロール
クラスタとインデックスの権限付きのロールで、読むためのものです。予約済みのものには印が付きます。
Elasticsearch
APIキー
自分の有効なAPIキー。無効にしたものと期限切れのものは一覧に出ません。「新規キー」は名前と「有効期限」を尋ねます:期限なし、1日、1週間、30日、90日、1年。キーは「コピー」とともに一度だけ表示されます。サーバは二度と返さず、Calíopeも保存しません。Authorization: ApiKey <key>ヘッダに入れて使います。「キーを無効にする」は、サーバが確認した時点でキーを無効にし、元に戻せません。
OpenSearch
OpenSearchでは
ユーザとロールはセキュリティプラグインのものです(_plugins/_security/api/…)。ユーザのロールは、そのユーザかそのバックエンドロール(backend_roles)のどれかを指すロールの*マッピング*(rolesmapping)から来ます。バックエンドロールで持っているロールも一覧には出ますが、「ロールを変更…」のシートでは印が付いて灰色になります。外すのはここではなくサーバです。ロールの変更は各ロールの*マッピング*を書き直し、そのユーザの一覧だけに触れます。ユーザを削除すると*マッピング*からも外します。サーバが自動ではしないからです。APIキーのセクションはありません。OpenSearch 3の*APIトークン*はデフォルトでオフで、ユーザ自身のためではなく管理用です。
セキュリティなし
サーバでセキュリティが有効になっていなければ(OpenSearchでは、セキュリティプラグインがなければ)、タブはそう伝え、一覧もボタンも表示しません。サーバに到達できれば誰でも資格情報なしで入れます。
キーワード: Elasticsearch、OpenSearch、ユーザ、ロール、セキュリティ、_security、APIキー、apikey、パスワード、予約済み、rolesmapping、internalusers、backend_roles、セキュリティプラグイン
検索レポートとは何か:名前付きパラメータを使う製品のSQL、または一部のインデックスに対するQuery DSLの本文を、上限までページごとに読みます。
場所: ワークスペース › ツール › レポート
対象: Elasticsearch OpenSearch
ElasticsearchまたはOpenSearchのセッションでは、「新規レポート」で検索レポートを作成します。最初はSELECT * FROM demo_productos LIMIT 100のようなSQLです。「形式」で「SQL」と「Query DSL」を切り替えます。SELECTはJSONの本文ではないので、切り替えると最初からやり直しになります。
SQL
製品のSQLで、読むための1つの文だけです。INSERT、DELETE、2つの文は、何も送る前に拒否されます。パラメータは:nameと書き、「パラメータを宣言」で宣言します。値として送られ、テキストの中に入ることはありません。リストは値ごとに1つのプレースホルダに展開されます(IN (:ids))。記号を含む名前は、その製品の方法で囲みます:Elasticsearchでは二重引用符("@timestamp")、OpenSearchではバッククォートです(OpenSearchでは二重引用符は文字列)。OpenSearchは空のパラメータを受け付けません(レポートは何も送る前に拒否します)。時刻付きの日付はUTCのテキストとして届きます。
Query DSL
JSONの検索本文と、「インデックス」にカンマで区切ったインデックス(空ならすべて)。パラメータは取りません。本文は書いたとおりに送られ、size、from、search_after、pit、scrollは無視されます。たどり方はレポートが決めるからです。
読み込まれるもの
「実行」を押すたびに、Calíopeはレポートの行数の上限まで、1,000件ずつすべてのページを読み、打ち切ったらそう伝えます。「停止」は、あるページと次のページの間で止めます。SQLはサーバのカーソルに従い、最後に閉じます。Query DSLは、本文がソートしていればsearch_afterに従います。ソートしていなければCalíopeが_docでソートし、10,000件のドキュメントを超えません。それを超えるにはsortを求めます。SQLの列は応答の列で、型が付きます。Query DSLの列は_index、_id、平らにしたドキュメントのフィールド(cliente.nombre。リストは1つのセル)で、*マッピング*の型が付きます。
そのほか
レポートが読んだものは「コマンドログ」に残りません。ツールの読み込みであって、「クエリー」で実行した検索ではないからです。「書き出す」と「履歴」はほかのレポートと同じように使えます。検索レポートはElasticsearchまたはOpenSearchのセッションでしか実行できず、複数の文のスクリプトは受け付けません。スケジュールはほかのレポートと同じく「スケジュール」で行います。スケジューラはプロファイルから専用の接続を開きます。
キーワード: Elasticsearch、OpenSearch、レポート、SQL、Query DSL、パラメータ、インデックス、ページ、上限、書き出し、履歴