GraphQL API

RDF Portal は、広く普及している API クエリ言語 GraphQL を使ってライフサイエンスデータセットを検索できる GraphQL API を提供しています。GraphQL API は、スキーマ駆動型の直感的なクエリインターフェースとして SPARQL の代替手段となり、特に Web アプリケーション開発に慣れた方にとって、RDF データセットから構造化データを取得しやすくなります。

サービスURL: https://rdfportal.org/grasp

注意: GraphQL API は現在、限られたデータベースのみを対象としています: UniProt、ChEBI、ChEMBL、MedGen。今後のアップデートで対応データベースを追加する予定です。

GraphQL とは

GraphQL は、Facebook（現 Meta）が2012年に開発し、2015年にオープンソースとして公開した API 向けクエリ言語です。従来の REST API ではエンドポイントごとに固定のデータ構造が返されるのに対し、GraphQL ではクライアントが必要なフィールドを正確に指定して、1回のリクエストでデータを取得できます。主な利点は以下の通りです。

必要なデータだけ取得 — 取得するフィールドを正確に指定でき、不要なデータの過剰取得を避けられます。
単一エンドポイント — リソースごとに異なるURLを使い分ける必要がなく、すべてのクエリが1つのエンドポイントに送られます。
ネストされたクエリ — データセット間の関係をたどり、複数のエンティティにまたがる関連データを1つのクエリで取得できます。
自己文書化 — スキーマが利用可能なすべての型とフィールドを定義しており、GraphiQL などのツールを通じてインタラクティブに探索できます。

Grasp: GraphQL-SPARQL ブリッジ

RDF Portal の GraphQL API は、DBCLS が開発したオープンソースのミドルウェア Grasp によって実現されています。Grasp は GraphQL と SPARQL の間のブリッジとして機能します。クライアントから GraphQL クエリを受け取り、それを SPARQL クエリに変換し、RDF Portal の SPARQL エンドポイントに対して実行し、結果を標準的な GraphQL レスポンス形式で返します。

これにより、ユーザーは SPARQL クエリを書く必要なく、RDF Portal 上の豊富な相互リンクされた RDF データセットを活用できます。Grasp は、複数のデータベースにまたがるクエリも含めて、変換を透過的に処理します。

Grasp の詳細については、GitHub リポジトリをご参照ください。

インタラクティブクエリインターフェース

サービスURL https://rdfportal.org/grasp では、GraphiQL インターフェースを提供しています。GraphiQL は、GraphQL クエリをブラウザ上で記述・実行できるインタラクティブな IDE です。スキーマの探索、オートコンプリート付きのクエリ記述、結果の即時確認が可能です。

クエリ例

以下の例は、GraphQL API を通じて RDF Portal のデータセットにクエリする方法を示しています。

例 1: 基本クエリ — MedGen エントリの取得

特定の ID で MedGen エントリの基本情報を取得します。リンクされた NCBI Gene 識別子も含みます。

query {
  MedGen(id: ["C1835407", "C1835223"]) {
    iri
    id
    label
    ncbigene
  }
}

例 2: 詳細クエリ — MedGen の全フィールドの取得

MedGen から、説明、概念名、定義、関連メタデータなど包括的な情報を取得します。

query {
  MedGen(id: ["C1835407", "C1835223"]) {
    iri
    id
    label
    ncbigene
    description
    sty
    name_label
    name_source
    name_suppress
    mgdef_description
    mgdef_source
    mgdef_suppress
    mgconso_aui
    mgconso_ispref
    mgconso_stt
    mgconso_ts
    mgconso_label
    mgconso_source
    mgconso_suppress
    mgsat_metaui
    mgsat_stype
    mgsat_identifier
    mgsat_source
    mgsat_value
    mgsat_label
    mgsat_suppress
  }
}

例 3: ClinVar クエリ — バリアント情報の取得

ClinVar から臨床バリアントデータを取得します。アクセッション番号、サブミッション数、レビューステータス、種の情報を含みます。

query {
  ClinVar(id: "5378") {
    iri
    label
    accession
    submissions
    status
    species
  }
}

例 4: UniProt クエリ — タンパク質の詳細情報の取得

UniProt からタンパク質の詳細情報を取得します。遺伝子名、酵素分類、配列、機能アノテーションなどを含みます。

query {
  UniProt(id: "Q94KE2") {
    label
    mnemonic
    existence
    gene_name
    ec
    sequence
    function
    affinity
    activity
    kinetics
    ph_dependence
  }
}

例 5: ネストクエリ — UniProt とリンクされたデータベース

GraphQL の強みの1つは、1つのクエリで関係をたどれることです。この例では、UniProt のタンパク質エントリと、リンクされた ChEBI 化合物、Gene Ontology（GO）アノテーション、HGNC 遺伝子情報をまとめて取得しています。

query {
  UniProt(id: "Q94KE2") {
    label
    mnemonic
    existence
    gene_name
    ec
    sequence
    function
    affinity
    activity
    kinetics
    ph_dependence
    ChEBI {
      formula
    }
    GO {
      id
      label
      namespace
    }
    HGNC {
      id
      label
      description
      location
    }
  }
}

例 6: クロスデータベースクエリ — ChEMBL からChEBI・UniProt への横断検索

この例は、ChEMBL の化合物を起点としたクロスデータベースクエリです。化合物の化学的性質や医薬品開発情報に加え、リンクされた ChEBI 識別子および UniProt のタンパク質ターゲット情報を取得します。

query {
  ChEMBL(id: "CHEMBL941") {
    label
    smiles
    atc
    alogp
    drug_development_phase
    pchembl
    ChEBI {
      id
      charge
    }
    UniProt {
      mnemonic
      label
      organism
    }
  }
}

プログラムからのアクセス

GraphQL クエリはプログラムから送信することもできます。例えば、curl を使う場合：

curl -X POST https://rdfportal.org/grasp \
  -H "Content-Type: application/json" \
  -d '{"query": "{ UniProt(id: \"Q94KE2\") { label mnemonic gene_name } }"}'

Python の requests ライブラリを使う場合：

import requests

query = """
{
  UniProt(id: "Q94KE2") {
    label
    mnemonic
    gene_name
    ec
  }
}
"""

response = requests.post(
    "https://rdfportal.org/grasp",
    json={"query": query}
)
print(response.json())