MarkLogic における GraphQL のご紹介

MarkLogic 11より、MarkLogicデータベースのビューに対してGraphQLクエリを実行できるようになりました。これにより、ますます人気が高まっているGraphQLに興味がある方、またはすでに使用している方が、このクエリ言語を使ってMarkLogicに対して安全にクエリを実行できるようになりました。

GraphQLとは何か

GraphQLは、API用のクエリ言語であり、既存のデータにクエリを実行するためのランタイムでもあります。GraphQLは、API内でデータを完全かつわかりやすく説明します。またクライアントが必要なものだけを要求する力を与え、時間の経過とともにAPIを進化させることを容易にし、強力な開発者ツールを可能にします。

— https://graphql.org/

MarkLogicのビューにGraphQLを使用する

MarkLogicでは、SQLおよびOptic APIでマルチモデルデータのビューをクエリ可能ですが、今回これにGraphQLが加わりました。GraphQLクエリを実行するにはビューが必要です。MarkLogicでは、2種類のビューを定義しています。インデックスビューとクエリベースビューです。インデックスビューは、TDE（Template Driven Extraction）で実現されます。

TDEでは、ドキュメントがデータベースに書き込まれる際に、ビューインデックスをポピュレートします。これらのビューは、データベース内に格納されているレコードとトランザクション的な一貫性があります。

—TDEの詳細については、https://docs.marklogic.com/guide/app-dev/TDEを参照してください。

QBV（Query Based Views）は、クエリ時に評価されるビューです。これらのビューは、MarkLogicのOptic APIで記述された保存済みクエリです。複数のモデルを対象としてロバストなクエリを記述できます。

-Optic APIおよびGBVの詳細については、 https://docs.marklogic.com/guide/app-dev/OpticAPIを参照してください。

GraphQLクエリを記述する

GraphQLクエリを構築する場合、その内部構造を理解しておくことが重要です。GraphQLクエリは内部的に翻訳され、MarkLogicのOptic APIにより実行されます。これにより、あらゆる形やサイズのデータに対してリッチなクエリを実行できます。

以下は、「住宅ローン」に関する情報を探すクエリの例です。GraphQLがサポートするシンタックスすべてについて理解を深めるには、https://graphql.org/learn/queries/を参照してください。とりあえずここでは、この例を使ってその構造を理解していきます。

操作タイプおよび操作名 – MarkLogicではGraphQLを使ってクエリできます。この例には、操作タイプ「query」および操作名「MortgageQuery」があります。操作のタイプと名前を指定することで、このコードの意味がはっきりするので、あとから見た人もクエリの意図をすぐ理解できるようになります。

スキーマとタイプ – GraphQLでは、オブジェクトのタイプとフィールドのリストを指定して、データをクエリできます。MarkLogicでは、Schema_Viewパターンでオブジェクトタイプを命名することで、このオブジェクトタイプがスキーマおよびビューにマッピングされます。上記の例では、Mortgage_Detailsオブジェクトタイプは、Mortgageスキーマ内のDetails ビューにマッピングされています。

フィルタリング – GraphQLでは、フィールドおよびマッチする値を指定することで、クエリ対象データを制限可能です。この例では、「LoanType」の値が「Conventional」である住宅ローンを検索します。

ページネーション – フィルタ内で「first」および「offset」フィールドを指定することで、結果の数やスキップするアイテムの数を指定可能です。

ソート – GraphQLでは@Sortを使って、ソートに使用するフィールドと方向を指定できます。この例では、住宅ローンの終了日をフィールドに指定し降順でソートしています。

フィールドの選択 – ビューに列がたくさんあった場合、フィールドを列挙することで、取得したいデータを指定可能です。

GraphQLクエリの送信

MarkLogicには、ビューデータとやり取りするためのAPIが複数標準装備されています。v1/rowsエンドポイントを使用すると、サポートされているいくつかのクエリ言語によりビューデータを取得できます。v1/rows/graphqlエンドポイントでは、GraphQLシンタックスを利用したクエリを送信できます。このRESTエンドポイントは、cURLのような単純なユーティリティでも、より高度なツールでも活用できます。

ファイルに保存されたGraphQLクエリを使用したcURLの例：

curl --location --request POST 
'http://localhost:8000/v1/rows/graphql' \ 
--header 'Content-Type: application/graphql' \ 
--data '@query.graphql'

GraphQLの結果を可視化する

多くのデータ可視化ソリューションが、データソースとしてのGraphQLエンドポイントに対応しています。以下の例では、人気の高い観測プラットフォームであるGrafanaが、MarkLogicにGraphQLクエリを送信し、結果を可視化する方法を示しています。

これを行うには、Grafana用のGraphQLプラグインが必要です。同社のマーケットプレイスには、いくつかのプラグインが用意されています。プラグインをインストールすると、MarkLogicで利用できる/v1/rows/graphqlエンドポイントに接続できます。

— GraphQLのプラグイン：https://grafana.com/grafana/plugins/fifemon-graphql-datasource/

データソースを設定したら、GraphQLデータソースを使用してパネルを追加できます。この例では、すべての住宅ローンのメタデータを表に表示しています。可視化の方法はいくかあります（グラフ、チャート、マップなど）。

全体が表示されているこのダッシュボードでは、MarkLogicサーバーへのライブ接続を利用することで、複数のGraphQLクエリを実行して、すべての情報を迅速かつ効果的にポピュレートします。ここではドキュメントビュー、グラフビュー（世帯）、地理情報といったマルチモデルデータが活用されていることがわかります。

まとめ

GraphQLは、モダンなAPIのための標準化されたクエリ言語です。今回、MarkLogicがGraphQLに対応することで、成長し続ける企業内でリッチなマルチモデルデータセットを統合できる新たな機会が生まれます。

MarkLogicのGraphQLクエリサービスの詳細については、MarkLogic 11リリースノート内の「GraphQL new feature update」を参照してください。