Wikidata Query Service/User Manual/ja

ウィキデータ･クエリサービス Wikidata Query Service (WDQS) はSPARQL（スパークル）エンドポイントを提供するソフトウェア兼公共サービスで、利用者はウィキデータのデータセットに検索をかけることができます.

サーバ運用は現在、ベータ段階にあり、そのため、事前のお知らせのないままデータセットもしくはサービス内容を変更することがある点にご留意ください.

このページあるいは関連するその他の説明文書は、臨機応変に更新されます. このサービスを利用する場合は、これらをウォッチリストに追加するようお勧めします.

SPARQLクエリのサンプルは、SPARQLの例のページを参照してください.

データセット
ウィキデータ・クエリサービスの対象はWikidata.orgに保存されたデータセットで、RDF ダンプ形式説明文書に解説してあるとおり、RDF形式で保存されます.

このサービスのデータセットは主に性能上の理由から、RDF形式のダンプファイルと完全には一致しません. 相違点の解説は説明文書を参照してください.

同じデータは毎週、次の場所でダンプを公開しています（訳注：ウィキデータ・ウィキの実体の索引）.

https://dumps.wikimedia.org/wikidatawiki/entities/

基本 - SPOまたは構文の3要素を理解する
SPOつまり「主語・述語・目的語」（Subject, Predicate, Object）の3つの要素はデータに関する情報を表現し、これをトリプルあるいはウィキデータではデータの文（ステートメント）と呼んでいます.

「アメリカ合衆国の首都はワシントンD.C.である」という文の、主語は〈アメリカ合衆国〉（Q30）、述部は〈ワシントンD.C.である〉（P36）、目的語は〈首都〉（Q61）で、この文を構成するURIは3つとなります.

接頭辞のおかげで（下記で詳述）、同じ文は下記のように簡潔に書き換えができます. 文の終わりにある句点に注意してください.

The /entity/ (wd:) represents Wikidata entity (Q-number values). The /prop/direct/ (wdt:) is a "truthy" property — a value we would expect most often when looking at the statement. The truthy properties are needed because some statements could be "true-er" than others. For example, the statement "The capital of U.S. is New York City" is also true — but only if you look at the context of U.S. history. WDQS uses rank to determine which statements should be used as "truthy".

In addition to the truthy statements, WDQS stores all statements (both truthy and not), but they don't use the same wdt: prefix. U.S. capital have three values: DC, Philadelphia, and New York. And each of these values have "qualifiers" - additional information, such as start and end dates, that narrows down the scope of each statement. To store this information in the triplestore, WDQS introduces an auto-magical "statement" subject, which is essentially a random number:

詳細はSPARQL tutorial - qualifiersを参照してください.

SPOはまた、クエリに用いる基本的なシンタックスのレイアウトとして、RDFデータ構造、あらゆるグラフデータベースを対象にします. 高度なパフォーマンスグラフデータベースにささえられた、triplestoreとしてのウィキデータクエリサービス（WDQS）も対象に含まれます.

トリプル（SPO）の高度な利用にはさらに、トリプルを目的語もしくは主語として他のトリプルに用いるところまで拡張します！

基本 - 接頭辞（プレフィックス）とは
主語と述語（トリプルの最初と2番目の要素）はつねにURIとして保存する必要があります. 一例として、主語が宇宙 (Q1)の場合は  として保存されます. 接頭辞があると左記の長いURIをコンパクトにwd:Q1と書くことができます. 主語や述語に対して、目的語は（トリプルの第3の要素）URIでも、そのまま数字または文字列などでも保存できます.

WDQSは接頭辞と呼ばれるショートカットの省略形をたくさん受け付けます. ウィキデータ固有のもの（例：wd, wdt, p, ps, bd）のほか、多くは用途が一般的なrdf、skos、owl、schemaなどの外部接頭辞です.

下記のクエリでは、文が「P279 = Q7725634」、展開すると「サブクラスの」述語で目的語が= 「literary work」を含む項目を求めています. 出力の変数：

拡張機能
このサービスはSPARQLの標準機能に対して、下記の拡張機能を提供します.

ラベル検索サービス
URI を使う特別なサービスにより、実行しようとするクエリのラベルや別名（Alias＝コマンドを別名で登録したエイリアス）あるいはエンティティの説明を入手できます. SPARQLクエリでこれらを入手しようとすると複雑な手順が必要ですが、このサービスはそれを省略してくれるため、ラベルを入手したいときに大変便利です.

サービスは手動もしくは自動で実行します.

自動モードではサービスのテンプレートを指定するだけです. 例：

地理空間検索
このサービスでは座標を与えられたアイテムを、特定の枠組みの中心から特定の距離の範囲内で検索することができます.

特定のポイント周辺の検索
例:

The first line of the サービス呼び出しの1行目は     形式が必須で、検索結果は特定の位置にある を座標 の項目と対応させます.

枠組み内の検索
ボックス検索の例：

または:

座標は直接、指定できます：

The first line of the  service call must have format     , where and the result of the search will bind   to items within the specified location and   to their coordinates. The parameters supported are:

と は、 と 同様に必ず一緒に使う必要があり、 混同はできません. 述語の と が使われた場合、ボックスの対角線の座標を仮定し、そこから対角を導き出します.

距離関数
関数は地球上の2地点間の距離をキロメートル単位で返します. 使用例:

座標部分関数
関数の と および は座標の部分 - それぞれ地球URIと緯度および経度を返します.

URL関数を解読する
関数は指定されたURI文字列を解読（URLエンコーディングを逆処理）します. ウィキペディアの記事名（エンコードされている）を実際の文字列に変換するときに、これが必要な場合があります. この関数はSPARQL [$ w3-org encode_for_uri]の逆関数です.

自動接頭辞
一般的なクエリに用いる接頭辞の多くは、明示的に指定しなくてもエンジンによってサポートされています.

日付の延長
サービスは1秒で タイプの日付の値を過去から未来の290億年間を処理します. WDQSはUnixエポックから64ビット秒数で日付を保存します.

ブレーズグラフ関数
ブレーズグラフ（Blazegraph）プラットフォームはその上にWDQSが実装されており、独自のSPARQL拡張機能の組み合わせがあります. ブレーズグラフ Wikiで説明されたいくつかのグラフトラバーサルアルゴリズムがあり、その中にBFS、最短パス、CC、PageRankの実装を含みます.

クエリ実行のコントロールとエンジンのさまざまな特徴については、上記に加えてクエリのヒントに書かれたブレーズグラフの説明文書も参照してください.

Federation
SPARQL連合クエリから選択した件数の外部データベースの呼び出しができます. サポートされるエンドポイントは次のとおりです. 連合クエリのサンプル：

注記：上記にまとめたデータベースはウィキデータとは大きく異なるオントロジー（本体論）を使用している可能性があります. 上記の所有者の説明文書のリンクから、これらのデータベースのオントロジーとデータアクセスについて参照してください.

Mediawiki API
''完全版の解説はMediawiki APIサービス説明文書のページを参照してください. ''

Mediawiki API サービスはSPARQLからMediawiki APIを呼び出し、SPARQLクエリの結果を受け取ります. サンプル（カテゴリに属するものを探す）：

ウィキメディア・サービス
ウィキメディアが走らせるWDQSの公開サービスの例は、リンク先から利用できます.

公開エンドポイントのクエリのランタイムは60秒が上限で、エンドポイントがGUIでも公開SPARQLでも同じです. もしクエリを走らせるのにもっと長い時間が必要な場合は、Discoveryチームと打ち合わせをお願いします.

GUI
http://query.wikidata.org/のホームページにあるGUIは、SPARQLクエリの編集とクエリエンジンへの提出に使います. 結果はHTMLテーブルに表示されます. クエリごとに固有のURLが与えられ、ブックマークして後で閲覧することができます. ここでいうURLを開くと、クエリが編集ウィンドウに入力されるものの、そのままでは実行されません - 必ず「実行」ボタンを押してください.

また、クエリの短縮URLを作成するには、右側にある「短縮URLを作成」を押してURL短縮サービスを起動します - この操作でそのとき手がけているクエリの短縮URLが生成されます.

「接頭辞を追加」ボタンはSPARQLクエリの標準の接頭辞を記したヘッダを生成します. 便利に使える接頭辞の全体リストはRDF書式説明文書にまとめてあります. 注記：WDQSが既定でサポートしているため、ほとんどの一般的な接頭辞は自動で発動します.

GUIには軽量なエンティティ検索機能が備わり、エンティティ結果の横の虫眼鏡アイコン「🔍」を押して有効にします. エンティティのQ-IDを直接クリックすると、wikidata.orgが開きそのエンティティのページを表示します.

既定の表示

 * もとの記事: Wikidata:SPARQL query service/Wikidata Query Help/Result Views

WDQS GUIでクエリを走らせる場合、結果の表示形式を選択できます：クエリの冒頭の でコメントを選択します.

SPARQLエンドポイント
にGETもしくはPOSTリクエストを送り、SPARQLクエリを直接、SPARQLエンドポイントで実行することができます. 結果は既定ではXML形式で返し、クエリのパラメータ あるいはヘッダ を与えると、JSON形式で返します. POSTリクエストはクエリのURLの代わりに、リクエスト本文で受け取ることで、URL文字数制限の上限に触れずに大きなクエリを走らせることができます. （ただしその場合もPOST 本体は単に ではなく であるべきです. SPARQLクエリはURLをエスケープする必要があります. ）

JSON 形式は標準SPARQL 1.1 Query Results JSON Format.

小規模なクエリにはGETを、大規模な場合はPOSTを利用するよう推奨されます. POSTはクエリをキャッシュしません.

サポートする形式
SPARQLエンドポイントでサポートする出力形式は下記のとおりです.

クエリの時間切れ
固定のクエリ期限は60秒 に設定されています.

この制限時間を超過したクエリはすべて時間切れになります. クエリを最適化する、もしくは問題のあるクエリをこちらで報告してください.

また現状では同一IPで並行処理できるクエリは、5件に制限されています. リソースと利用パターンを考慮し、これらの制限を変更する可能性があります.

名前空間
ウィキデータ・クエリサービスにはメインの名前空間 が含まれ、SPARQLエンドポイントやその他、以下に一覧した補助的な名前空間のクエリの対象になります. これら以外の名前空間のデータにクエリを実行するには、エンドポイントのURL https://query.wikidata.org/bigdata/namespace/NAMESPACENAME/sparql を当てます.

DCAT-AP
ウィキデータに対応するDCAT-AP（英語版）データ（訳注：RDFボキャブラリで、データ・カタログ間の相互運用性を促進. ）は 名前空間からSPARQLとして入手できます.

そのデータにアクセスするSPARQLエンドポイント：https://query.wikidata.org/bigdata/namespace/dcatap/sparql

データのソース：https://dumps.wikimedia.org/wikidatawiki/entities/dcatap.rdf

データを獲得するクエリのサンプル：

Linked Data Fragments エンドポイント
Triple Pattern Fragmentsインタフェースを使ったデータベースのクエリもサポートしています. これによりコストを下げて効率的にトリプルデータをブラウズすることができ、3つの構成要素のうち1ないし2のみわかる場合はこのテンプレートに対応するトリプルすべてを取得する必要があります. 詳細はLinked Data Fragmentsのウェブサイトを参照してください.

インタフェースの利用には次のURLからアクセスします. . リクエストのサンプル:


 * https://query.wikidata.org/bigdata/ldf?subject=http%3A%2F%2Fwww.wikidata.org%2Fentity%2FQ146 - を含むトリプルの一覧


 * https://query.wikidata.org/bigdata/ldf?subject=&predicate=http%3A%2F%2Fwww.w3.org%2F2000%2F01%2Frdf-schema%23label&object=%22London%22%40en - 英語のラベル「London」を含むトリプル

注；現状では と および パラメータの有効な値は完全なURLに限定されます.

既定でHTMLインタフェースが表示されるものの、他にもHTTPヘッダ で示した、いくつかのデータフォーマットが有効です.

ページサイズが100トリプルの場合、データは返します. ページには1から始まる番号が付与されていて、ページ番号は パラメータで定義します.

スタンドアローン方式のサービス
オープンソースのソフトウェアとして、このサービスは下記に示した手順に従うと、どんなユーザーのサーバ上でも稼動できます.

ハードウェアの推奨条件はBlazegraph説明文書を参照してください.

もしサービスの利用対象がウィキデータ以外のウィキベース案件の場合、詳細の確認をお願いします.

インストール
サービスのインストールで推奨されるのは完全版のサービスパッケージを圧縮形式のZIPファイルで（例：Maven Central から）ダウンロードすることで、グループ ID と artifact ID「 」を使って、あるいは https://github.com/wikimedia/wikidata-query-rdf/ でソース配分をクローンして「mvn package」で構築します. パッケージのZIPファイルは  として   ディレクトリに格納されています.

パッケージには .war アプリケーションとしてBlazegraphサーバが含まれ、ウィキデータサイトから新鮮なデータをライブラリに取得するには、修正プログラムサービスを走らせ、さまざまなタスクを簡単にこなすにはスクリプトを採用し、GUIを サブディレクトリにおく必要があります. GUIを使うには、HTTPサーバの設定を変更します.

http://localhost:9999/bigdata/namespace/wdq/sparql のSPARQLエンドポイントのみ既定で設定されており、既定のBlazegraph GUIは http://localhost:9999/bigdata/ にあります. 既定の設定ではどちらにアクセスするのもローカルホストに限定される点にご注意ください. 外部からアクセスするには、外部のエンドポイントと適切なアクセスコントロールの設定が欠かせません.

画面キャプチャ版の使用
未リリースの画面キャプチャ版を利用する場合で（修正済みのバグを含むリリース版はあるがリリース版が更新されていない場合によくある事例）、バイナリをコンパイルしたくない場合、次のどちらかを利用できます.
 * https://github.com/wikimedia/wikidata-query-deploy - プロダクション・バイナリを含むdeployment repo. の作動が必須. 作動確認をして「 」を実行してください.
 * https://archiva.wikimedia.org/#artifact/org.wikidata.query.rdf/serviceでArchiva スナップショットを実装 - 最新版を選択し、続いてArtifactsを選び最新版のパッケージをダウンロード.

データの読み込み
詳細なインストール手順は、配布の一部である使用開始の説明文書で詳しく説明されており、以下の手順が含まれます.


 * 1) https://dumps.wikimedia.org/wikidatawiki/entities/ から最新の RDF ダンプをダウンロード（RDF ダンプの目印は で終わるもの）.
 * 2)   スクリプトでデータの事前処理. 処理が終わると TTL ファイルが生成され、ファイル名は   などになる. オプションの説明は下記を参照.
 * 3)   スクリプトを使って Blazegraph サービスを実行.
 * 4)   を使ってサービスにデータを読み込む. 注記：事前処理よりもデータ読みこみにはかなり時間がかかることから、データの事前処理が数件分終わっら、データ読みこみを開始するとよい. 以下のオプションにより、データ読みこみはどのファイルからも実行できる.
 * 5) すべてのデータの読みこみが完了したら   を使い、修正プログラムを実行.

カテゴリの読みこみ
カテゴリのデータの読みこみも行うには、以下の手順に従ってください.


 * 1) 名前空間の作成. 例えば  :
 * 2) その名前空間にデータを読みこむ.

注記：ウィキメディアの設定に従い、これらのスクリプトが読みこむデータはウィキメディアに限定. 他のウィキからの読みこみをするには、場合によりスクリプトの変数を変更する必要があります.

スクリプト
配布には以下の便利なスクリプトが同梱されています.

munge.sh
データの読みこみに備えた RDF ダンプのデータの事前処理

例:

loadData.sh
処理済みのデータをブレイズグラフに読みこむ. のインストールが必須.

例:

runBlazegraph.sh
ブレイズグラフ･サービスを実行.

例:

スクリプト内の変数のうち、ユーザーによっては変更を検討するものは2件. DEFAULT_GLOBE=2 USER_AGENT="Wikidata Query Service; https://query.wikidata.org/"; さらにスクリプトは下記の環境変数を確認（すべてオプション）.
 * 1) Q-id of the default globe
 * 1) Blazegraph HTTP User Agent for federation

runUpdate.sh
修正プログラムサービスを走らせる.

It is recommended that the settings for the  and   options (or absence thereof) be the same for munge.sh and runUpdate.sh, otherwise data may not be updated properly.

例:

Also, the following environment variables are checked by the script (all of them are optional):

修正プログラムのオプション
以下のオプションは修正プログラムアプリケーションに使えます.

に次ぐオプションとして スクリプトに追加. 例:.

構成可能な属性
下記の属性の設定をするには、上記のスクリプトのスクリプト操作コマンドに追加します.

不足している機能
現状ではサポートしていない機能を以下に一覧にします.


 * リダイレクトはowl:sameAs tripleとしてサンプルはあるものの、対応するデータや固有のサポートがない.

お問い合わせ
サービスの不備についてお気づきの点は、送信先リスト 宛てに電子メールを送るか、チャットルーム にてDiscoveryチームまでご連絡をいただけないでしょうか.

バグの報告はで受け付け、進捗状況はDiscovery Phabricatorボードで確認してください.

関連項目

 * WDQからSPARQLへシンタックス移植
 * SPARQLクエリのサンプル
 * Discoveryチーム
 * WDQS実装の注記事項
 * SPARQLクエリシンタックスの基本