Zenn
😺

elasticsearch-spec-viewerを作ってみた

2023/01/24に公開
React
Elasticsearch
tech

Elasticsearchで現在多くの機能が提供されているのですが、現在の機能や今後バージョンアップで追加修正される機能をもう少し把握しやすくしたいと思っています。
elasticsearch-specificationリポジトリのschema.jsonというJSONファイルには各エンドポイントの仕様が記載されています。
このファイルを参照することでどのエンドポイントがどのバージョンで追加されたかが分かりそうだったので、Viewerを作成してみました。

※この記事で参照するElasticsearch関連の情報は、投稿時点の最新バージョンである8.6.0の情報となる

schema.jsonファイルの内容

schema.jsonはelasticsearch-specificationリポジトリの以下に配置されています。

JSONの中身を見てみると、JSONの構成は、_info, endpoints[], types[]の3プロパティで構成されていました（以下中身を抜粋）。JSONファイルは183450行、約4.6MBと結構大きめなファイルになっています。

     1 {
     2   "_info": {
     3     "license": {
     4       "name": "Apache 2.0",
     5       "url": "https://github.com/elastic/elasticsearch-specification/blob/main/LICENSE"
     6     },
     7     "title": "Elasticsearch Request & Response Specification"
     8   },
     9   "endpoints": [
    10     {
    11       "description": "Deletes the desired nodes. Designed for indirect use by ECE/ESS and ECK. Direct use is not supported.",
    12       "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/current/delete-desired-nodes.html",
    13       "name": "_internal.delete_desired_nodes",
    14       "request": null,
    15       "requestBodyRequired": false,
    16       "response": null,
    17       "responseMediaType": [
    18         "application/json"
    19       ],
    20       "stability": "experimental",
    21       "urls": [
    22         {
    23           "methods": [
    24             "DELETE"
    25           ],
    26           "path": "/_internal/desired_nodes"
    27         }
    28       ],
    29       "visibility": "private"
    30     },
    31     {
    32       "description": "This API is a diagnostics API and the output should not be relied upon for building applications.",
    33       "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/current/get-desired-balance.html",
      :
      :
      :
      :
 13902       "stability": "stable",
 13903       "urls": [
 13904         {
 13905           "methods": [
 13906             "GET"
 13907           ],
 13908           "path": "/_xpack/usage"
 13909         }
 13910       ],
 13911       "visibility": "public"
 13912     }
 13913   ],
 13914   "types": [
 13915     {
 13916       "inherits": {
 13917         "type": {
 13918           "name": "WriteOperation",
 13919           "namespace": "_global.bulk"
 13920         }
 13921       },
 13922       "kind": "interface",
 13923       "name": {
 13924         "name": "CreateOperation",
 13925         "namespace": "_global.bulk"
      :
      :
      :
183440       ],
183441       "kind": "interface",
183442       "name": {
183443         "name": "OverloadOf",
183444         "namespace": "_spec_utils"
183445       },
183446       "properties": [],
183447       "specLocation": "_spec_utils/behaviors.ts#L134-L140"
183448     }
183449   ]
183450 }

schema定義

_infoやtypes[]もありますが、ここではendpoints[]のみ詳しく見ていきます。
endpoints[]の構成を以下の表にまとめてみました。
Null許容かどうかまで見ることが出来ればよかったのですが、そこまでは見ていません。

JSONプロパティ 型 説明
description string APIに関する説明
docId string 公式ドキュメントID（ページ名のようだが、値が入っているは一部データのみ）
docUrl string 公式ドキュメントURL
name string API名（namespaceっぽい）
since string エンドポイントが追加されたElasticsearchバージョン
stability string 安定機能かどうか：stable,beta,experimentalのいずれか
visibility string 公開機能かどうか：public または private
リクエスト関連
JSONプロパティ 型 説明
request object
request.name string Request名
request.namespace string Requestのnamespace（コード自動生成用）
requestBodyRequired boolean リクエストボディの指定が必須かどうか
requestMediaType []string リクエスト時に指定するメディアタイプ

例）

"request": {
  "name": "Request",
  "namespace": "_global.search"
},
"requestBodyRequired": false,
"requestMediaType": [
  "application/json"
],
レスポンス関連
JSONプロパティ 型 説明
response object
response.name string Response名
response.namespace string Responseのnamespace（コード自動生成用）
responseMediaType []string レスポンス時に指定されているメディアタイプ 
"response": {
  "name": "Response",
  "namespace": "_global.search"
},
"responseMediaType": [
  "application/json"
],
URL関連
JSONプロパティ 型 説明
urls []object
urls[].method []string HTTPメソッド
urls[].path string URLパス
urls[].deprecation string
urls[].version string

urls配列の要素が複数あるケース

  • 以下のようなdeprecationとなった場合のほか、"path": "/_search" , "path": "/{index}/_search" のようにURLパスが複数の場合もあり

例）

"urls": [
  {
    "methods": [
      "GET",
      "POST"
    ],
    "path": "/_search/scroll"
  },
  {
    "deprecation": {
      "description": "A scroll id can be quite large and should be specified as part of the body",
      "version": "7.0.0"
    },
    "methods": [
      "GET",
      "POST"
    ],
    "path": "/_search/scroll/{scroll_id}"
  }
],
権限関連
JSONプロパティ 型 説明
privileges object
privileges.cluster []string クラスタを操作する権限 Cluster privileges
privileges.index []string インデックスを操作する操作権限 Indices privileges

ざっと確認したところ主にilmやindices,ml,security,transform関連のエンドポイントで定義されていました。

例）

"name": "ilm.put_lifecycle",
"privileges": {
  "cluster": [
    "manage_ilm"
  ],
  "index": [
    "manage"
  ]
},

jqクエリでの指定エンドポイント情報の抽出

schema.jsonをダウンロードしてローカル環境に任意の場所に配置して指定したエンドポイントの情報を抽出してみました。今回は各エンドポイントがどのElasticsearchバージョンで追加されたかを知りたかったため、以下情報を抽出しました。

  • .name - API名
  • .since - エンドポイントが追加されたElasticsearchバージョン
$ cat schema.json| jq 'limit(10; .endpoints[]) | .name + " " + .since'
"_internal.delete_desired_nodes "
"_internal.get_desired_nodes "
"_internal.health "
"_internal.update_desired_nodes "
"async_search.delete 7.7.0"
"async_search.get 7.7.0"
"async_search.status 7.11.0"
"async_search.submit 7.7.0"
"autoscaling.delete_autoscaling_policy 7.11.0"
"autoscaling.get_autoscaling_capacity 7.11.0"

試しに 8. でgrepしてバージョン8.xで追加されたエンドポイントを抽出してみました。

$ cat schema.json| jq '.endpoints[] | .name + " " + .since' | egrep " 8." | sort -k2
"knn_search 8.0.0"
"ml.put_trained_model_definition_part 8.0.0"
"ml.put_trained_model_vocabulary 8.0.0"
"ml.start_trained_model_deployment 8.0.0"
"ml.stop_trained_model_deployment 8.0.0"
"security.enroll_kibana 8.0.0"
"security.enroll_node 8.0.0"
"transform.reset_transform 8.1.0"
"ml.get_memory_stats 8.2.0"
"security.activate_user_profile 8.2.0"
"security.disable_user_profile 8.2.0"
"security.enable_user_profile 8.2.0"
"security.get_user_profile 8.2.0"
"security.suggest_user_profiles 8.2.0"
"security.update_user_profile_data 8.2.0"
"ml.infer_trained_model 8.3.0"
"security.has_privileges_user_profile 8.3.0"
"security.update_api_key 8.4.0"
"indices.downsample 8.5.0"
"ml.clear_trained_model_deployment_cache 8.5.0"

ブラウザからの確認

エディターやjqコマンドを使ったりせず、もっと容易に確認出来るようにするためViewerを作成しました。

https://kimai07.github.io/elasticsearch-spec-viewer/

今回はtanstack/react-tableを利用してテーブル形式で表示するようにしました。参考にしたコードは以下のexampleとなります。

example同様に、ビルドツールはViteを利用し、makeData.tsファイルでJSONファイルをロード、main.tsxファイルでロードした情報を用いてテーブル表示しています。
今回実装したelasticsearch-spec-viewerのソースコードはこちら。

https://github.com/kimai07/elasticsearch-spec-viewer

さいごに

elasticsearch-specificationリポジトリにあるschema.jsonの内容把握からViewerでのテーブル表示までを行いました。そして、各Elasticsearchバージョンで追加されたエンドポイントを容易に確認することが出来るようになりました。

Descriptionカラムは日本語で表示したかったのですが、Google翻訳を行ってみたところイマイチな内容もあり今回は用いませんでした。
また、ViewerはGitHub Pagesにデプロイしているのですが、schema.jsonファイルを更新する仕組みはまだ入れていません。schema.jsonに新たな情報が入ったタイミングなどで定期更新なども検討したいと思います。

Discussion