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つとなります.

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

/entity/ (wd:) はウィキデータのエンティティを表します（値はQ-番号）. /prop/direct/ (wdt:) は「真に近い」属性 — 文を読んだときにユーザーが最も想定しやすい値になります. 「真に近い」属性は、文により他のものよりも「より真である」ものがあるため、設定が必要です. たとえば「アメリカ合衆国の首都はニューヨークである」という文もある意味で真で — ただしアメリカの歴史のコンクストを考慮に入れる必要があります. WDQS はどの文を「真に近い」と扱うか、ランクを使って判断します.

真に近いかどうかの文に加え、WDQS は（真も偽も）すべての文を保存しながら、同じ接頭辞 wdt: を使いません. アメリカの首都には、ワシントンDC、フィラデルフィア、ニューヨークという3種類の値があります. さらにこれらの値は「修飾子」 - 開始日と終了日など追加の情報でそれぞれの文の範囲を狭めるものがあります. WDQS は triplestore にこの情報を保存するため、本質的に乱数であるauto-magical 「文」の主語を取り入れます.

詳細は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クエリでこれらを入手しようとすると複雑な手順が必要ですが、このサービスはそれを省略してくれるため、ラベルを入手したいときに大変便利です.

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

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

and WDQS will automatically generate labels as follows:


 * If an unbound variable in  is named , then WDQS produces the label  for the entity in variable.
 * If an unbound variable in  is named , then WDQS produces the alias  for the entity in variable.
 * If an unbound variable in  is named , then WDQS produces the description  for the entity in variable.

In each case, the variable in  should be bound, otherwise the service fails.

You specify your preferred language(s) for the label with one or more of  triples. Each string can contain one or more language codes, separated by commas. WDQS considers languages in the order in which you specify them. If no label is available in any of the specified languages, the Q-id of the entity (without any prefix) is its label.

The Wikidata Query Service website auto-magically replaces  with the language code of current user's interface. For example, if the user's UI is in French, the SPARQL's code  will be converted to   before being sent to the query service.

Example, showing the list of US presidents and their spouses:

In this example WDQS automatically creates the labels  and   for properties.

In the manual mode, you explicitly bind the label variables within the service call, but WDQS will still provide language resolution and fallback. Example:

This will consider labels and descriptions in French, German and English, and if none are available, will use the Q-id as the label.

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

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

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

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

または:

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

サービス呼び出しの1行目は必ず      形式で、検索結果は   を指定の場所の項目と、  をその座標と結び付けます. サポートする変数の一覧を示します.

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

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

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

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

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

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

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

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

連合クエリ
SPARQL連合クエリから選択した件数の外部データベースの呼び出しができます. サポートされるエンドポイントは次のとおりです. Please see the full list of federated endpoints on the dedicated page.

連合クエリのサンプル：

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

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形式で返し、クエリのパラメータ$code2あるいはヘッダ$code3を与えると、JSON形式で返します. POSTリクエストはクエリのURLの代わりに、リクエスト本文で受け取ることで、URL文字数制限の上限に触れずに大きなクエリを走らせることができます. （ただしその場合もPOST 本体は単に ではなく であるべきです. SPARQLクエリはURLをエスケープする必要があります. ）

GET requests have the query specified in the URL, in the format, e.g..

POST requests can alternatively accept the query in the body of the request, instead of the URL, which allows running larger queries without hitting URL length limits. (Note that the POST body must still include the  prefix (that is, it should be   rather than just  ), and the SPARQL query must still be URL-escaped.)

The result is returned as XML by default, or as JSON if either the query parameter  is included in the URL, or the header   is provided with the request.

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

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

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

クエリの時間切れ
固定のクエリ期限は60秒 に設定されています. There are also following limits:


 * One client (user agent + IP) is allowed 60 seconds of processing time each 60 seconds
 * One client is allowed 30 error queries per minute

Clients exceeding the limits above are throttled with HTTP code. Use  header to see when the request can be repeated. If the client ignores 429 responses and continues to produce requests over the limits, it can be temporarily banned from the service.

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

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

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

カテゴリ
Please see full description on Categories documentation page.

Wikidata Query Service also provides access to category graph of select wikis. The list of covered wikis can be seen here: https://noc.wikimedia.org/conf/categories-rdf.dblist

The category namespace name is. The SPARQL endpoint for accessing it is https://query.wikidata.org/bigdata/namespace/categories/sparql.

Please see Categories page for detailed documentation.

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件. さらにスクリプトは下記の環境変数を確認（すべてオプション）.

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

オプションの ならびに の設定（あるいは設定なし）は、munge.sh ならびに runUpdate.sh と揃えるよう推奨します. さもないとデータ更新が適切に行われません.

例:

また、スクリプトは次の環境変数を確認します（すべてオプション）.

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

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

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

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


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

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

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

関連項目

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