Elasticsearchの公式リファレンスを高速ダウンロード

はじめに

この記事は、ZOZO Advent Calendar 2023 カレンダー シーズン6 の 3日目の記事です。
昨日の記事は @itiblogさんによる「AWS re:invent参加にあたって知っておいたほうが少し快適になること」でした。

概要

Elasticsearchの公式ドキュメントをGitコマンドを使ってローカルにサクッとダウンロードする方法について紹介します。

※ スクレイピング等の負荷をかけることはしません

前提知識

Elasticsearchの公式ドキュメントは下記リポジトリで管理されています。
https://github.com/elastic/elasticsearch/tree/main/docs/reference

ただし、我々がよく見るhtmlではなく下記のようなasciidoc形式で書かれています
https://github.com/elastic/elasticsearch/blob/main/docs/README.asciidoc

これらのファイルは、下記リポジトリで管理されているツールによってHTMLにビルドできます
https://github.com/elastic/docs

本記事では割愛しますが、ビルド方法を知りたい場合は、下記記事が参考になるはずです
https://qiita.com/plumchang/items/8bdb1577fe23b788f327

また、公式リポジトリにてビルド済みのファイルも管理されています
https://github.com/elastic/built-docs

問題点

今回やりたいこととしては、上記リポジトリをクローンすれば完了になります。ただ、このリポジトリでは、Elasticsearchのドキュメントだけではなく、Elastic Stack（ElasticsearchやKibanaなどのサービス）のサービスごとの様々なドキュメントも一元管理されています。さらに、これらのドキュメントはバージョンごとに用意されているので、本来必要なドキュメント以外も同時に大量にクローンされるため、完了までに膨大な時間がかかります。

そこで、本記事ではサクッと1~2分ぐらいで手元に用意する方法を紹介します。

実践

結論、下記コマンドを実行するだけです。

$ git clone --filter=blob:none --sparse https://github.com/elastic/built-docs.git \
    && cd built-docs \
    && git sparse-checkout set ./raw/en/elasticsearch/reference/current

下記パスにドキュメントがダウンロードされました

$ ls raw/en/elasticsearch/reference/current/
_actions.html
_all_permission_check.html
_api_usage.html
_applying_a_policy_to_our_index.html
_client_jvm_check.html
_discovery_configuration_check.html
_early_access_check.html
_executing_searches.html
_explain_analyze.html
_file_descriptor_check.html
...

前提知識の章でも記載しましたが、単純にcloneしてしまうと10~20分かかります。
この方法を使うことで、必要なドキュメントだけダウンロードできます。（時間だけではなく、容量も節約できますね）

コマンドの説明

メタデータの取得

まずは、下記コマンドについて説明します

git clone --filter=blob:none --sparse https://github.com/elastic/built-docs.git

• --filter=blob:none: このオプションは、リモートから取得するデータを「blob」（ファイルの内容）に関して制限しています。blob:noneは、ファイルの中身を取得しないという指示です。これにより、大量のデータを取得せずにリポジトリを複製できます。通常、コミットのメタデータだけが取得され、ファイルの中身は取得されません。

• --sparse: このオプションは、スパースクローン（Sparse Clone）を有効にします。スパースクローンは、リモートリポジトリから一部のディレクトリやファイルだけを取得してきます。これにより、必要な部分だけを取得し、ディスクスペースを節約できます。

必要なファイルやサブディレクトリだけを取得

次に下記コマンドについて説明します

$ cd built-docs
$ git sparse-checkout set ./raw/en/elasticsearch/reference/current

• git sparse-checkout set: sparse-checkoutのsetサブコマンドを使用して、スパースチェックアウト(sparseはまばらな、少ないなどの意味があります)を設定します。スパースチェックアウトは、レポジトリの一部のみ使用したい場合に使用できます。

• ./raw/en/elasticsearch/reference/current: スパースチェックアウトを適用する対象のディレクトリパスを指定しています

これらのコマンドを組み合わせる事によって、部分クローンを実現しています。

おまけ

リポジトリでは、バージョンごとにドキュメントが管理されているので、パスを少し修正するだけで旧バージョンのドキュメントもダウンロードできます

例えば、バージョン5.1のドキュメントをダウンロードしてみましょう

$ git sparse-checkout set ./raw/en/elasticsearch/reference/5.1

ドキュメントがウンロードされました

$ ls raw/en/elasticsearch/reference/5.1/ | head
_basic_concepts.html
_batch_processing.html
_client_jvm_check.html
_cluster_health.html
_conclusion.html
_create_an_index.html
_delete_an_index.html
_deleting_documents.html
_executing_aggregations.html
_executing_filters.html

おわりに

Elasticsearchの公式ドキュメントをGitコマンドを使ってサクッとローカルにダウンロードする方法を紹介しました。

例えば、ChatGPTに翻訳するために使ったり、ベクトル化して、ドキュメントの検索精度を上げたりと、色々と活用できそうです。