Algolia と NodeJS を使用して検索可能なインデックスを構築するまでの道のり

Starschema のフル スタック エンジニアである Soma Osvay とチームを組んで、私が心から大切にしているプロジェクト、開発者向けドキュメントについて書きました。 Soma と私は、この記事を楽しんでいただければ幸いです。この記事では、Soma が思いついたユース ケースと課題、および実装について説明します。

ここ Starschema では、マークダウン ドキュメントのコンサルテーションの一環として、多くのプロジェクトを行ってきました。これらの既存のソリューションをサポートしている場合、または新しいプロジェクトを開発したい場合、すべてのドキュメントを検索したいことがよくあります。この作業を手動で行わなければならないため、現在のところ解決策がなく、工数がかかっています。

使用事例

特定のトピックに関連するプロジェクトを検索して、実装の詳細を確認したり、コードからアイデアを取得したりできる必要があります。また、営業チームは、特定のトピックについてチームがどのような種類のプロジェクトを完了したかを判断し、それを見込み顧客に迅速に伝えることができるソリューションも必要としています。

また、Tableau で多くの深い技術的な作業を行っているため、開発者向けの内部スタック オーバーフローのようなものがあるとよいでしょう。また、プロジェクト マネージャーは、特定のテクノロジを使用したことがある従業員を特定して、質問に対する回答を迅速かつ簡単に得られるようにする必要もあります。

つまり、次の属性に基づいて独自のプロジェクトを検索できる必要があります。

1. 使用される技術 (コーディング言語、データベースなど)
2. プロジェクトのキーワード (タグ)
3. インストール手順、技術文書などのプロジェクト文書自体。
4. プロジェクトの発生時期

これらの属性はすべて、内部ドキュメントのマークダウン ファイル内に存在します。それらを検索する方法が必要なだけです。

実行計画

計画では、概念実証としてNodeJS CLIを使用します。これにより、次のことが可能になります。

1. トップの GitHub パブリック リポジトリをスクレイプし、README マークダウン ファイルを取得します (これは最終的に内部プロジェクトを表します)。
2. ドキュメント ファイルをプロジェクトの基本情報 (タイトル、プログラミング言語、タグなど) と一緒に Algolia に保存します。

CLI には、使いやすいように高度なロギングとコマンド ライン引数が含まれます。また、ウェブ上でホストして、人々が試用できるようにしたいと考えています。

チャレンジ

当面の最大の課題は、レコード サイズです。Algolia では、最大 100 KB のレコードしか許可されません。ただし、ほとんどのマークダウン ドキュメント ファイルははるかに大きくなります。解決策は、インデックス内でマークダウン ファイルを複数の部分に分割する必要があることです。また、何かを検索するときに、複数のレコードに分割されている場合でも、1 つのプロジェクトが 1 回だけ表示されるようにする必要があります。

幸いなことに、Algolia には独自の機能があるため、これらの結果の重複を非常に簡単に排除できます。

インデクサーの実装

インデクサーをできるだけ簡単に使用できるようにするために、上記のように CLI を作成することにしました。必要な引数を指定すると、ツールは自動的にリポジトリを初期化し、既存のレコードを削除して、関連性設定を構成します。

ツールを強化するのは、要求された数の上位リポジトリを取得し、それらのすべてのメタデータを抽出して README ファイルをダウンロードする簡単な GitHub API です。また、所有者が見つからないリポジトリや README ファイルが見つからないリポジトリも除外されるため、最良の結果が得られます。最後に、マークダウン コンテンツを HTML に変換して、フロントエンドでのレンダリングを容易にします。

レコード サイズを抑えるために、ツールは 50,000 文字を超える README を追加のレコードに自動的に分割します。この方法では、レコードが大きくなりすぎることはありませんが、1 つのレコードでほぼすべてのリポジトリを処理できます。次に、この情報を一度に Algolia 100 レコードに同期して、ドキュメントで説明されているバッチ処理の推奨事項を満たすことができるようにします。

フロントエンドの実装

出発点として、Algolia がリリースしたcreate-instantsearch-appライブラリを利用して、InstantSearch.js ボイラープレートを立ち上げました。ここから、ページネーションやページ サイズ セレクターなど、InstantSearch.js によって提供される追加のウィジェットを追加することができました。

マークダウンを使用してリポジトリ メタデータも収集したため、ヒット コンポーネントをカスタマイズして、この追加情報を含める必要もありました。多くの場合、メタデータはライブラリの説明と同じくらい重要であるため、開発者はそれが人気のあるライブラリであるかどうか、誰がそれをリリースしたか、タグなどを一目で確認できます。また、ファセットを追加して、ユーザーがプログラミング言語、タグ、またはフォークされた回数でフィルタリングできるようにしました。

パズルの最後のピースは、「ドキュメントを開く」ボタンを追加することでした。これにより、アプリケーションを離れることなく、リポジトリのマークダウン コンテンツをポップアップですばやく簡単に読むことができます。クリックしているレコードに複数の行がある場合、追加のレコードが自動的に読み込まれ、表示に連結されます。

結論

このプロジェクトは楽しいテストであり、私たちのようなさまざまなユースケースに対して Algolia がいかに柔軟であるかを実際に示してくれました。すぐに使えるウィジェットのおかげで、プロトタイピングの時間を大幅に節約できました。また、最初の数回のキーストロークで適切な結果が得られたことは非常に印象的です。また、Algolia Recommend のパワーを利用して、ユーザーがプロジェクトを内部的にクリックすることで十分なイベントを生成できれば、非常に興味深いと思います。

ここでGitHub テスト プロジェクトのライブ デモを表示できます。このボタンをクリックすると、インデックスを表示するためのデフォルトのデモ資格情報が設定されます。バックエンドのインデックス作成コードに興味がありますか?これは GitHubで見つけることができます。

こちらにも掲載。