Wikidata Query Service/User Manual/ja

ウィキデータクエリサービス (WDQS) は、ウィキデータのデータセットにクエリ（問い合わせ）することを可能にするSPARQLエンドポイントを提供するために設計されたソフトウェアパッケージであり、公開サービスです.

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

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

データセット
ウィキデータクエリサービスはWikidata.orgから得たデータセットを取り扱います. データセットはRDFダンプ形式説明文書に解説してあるとおり、RDF形式で表現されます.

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

同じデータの週ごとのダンプを以下からダウンロードすることができます.

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

基本 - SPO（主語、述語、目的語）またはセマンティックトリプルを理解する
SPOつまり「主語・述語・目的語」（Subject, Predicate, Object）はトリプルとして知られ、あるいはウィキデータでは一般的にデータの文（ステートメント）と呼ばれています.

「アメリカ合衆国の首都はワシントンD.C.である」という文の、主語は〈アメリカ合衆国〉（Q30）、述語は〈首都は〜である〉（P36）、目的語は〈ワシントンD.C.〉（Q61）です. この文は以下の3つのURIで表現することができます.

接頭辞（下記で詳述）のおかげで、同じ文をより簡潔に書くことができます. 最後にある文の終わりを表すドットに注意してください.

/entity/ (wd:)はウィキデータのエンティティ（Q-番号の値）を表します. /prop/direct/ (wdt:)は「真らしい」プロパティ、つまり文を見るときに最もよく想定されるであろう値です. ある文が他の文と比べて「より真」となりうるので、真らしいプロパティが必要とされます. 例えば「アメリカ合衆国の首都はニューヨークである」という文は真ですが、それは1790年という年の歴史的文脈においてのみです. WDQSはどの文を「真らしい」と扱うべきか、ランクを使って判断します.

真らしい文に加え、WDQSは（真らしい文もそうでないものも）すべての文を保存しますが、同じ接頭辞wdt:は使いません. アメリカの首都は、ワシントンDC、フィラデルフィア、ニューヨークという3つの値を持ち、さらにそれぞれの値が、「修飾子」— 開始日や終了日などのように、それぞれの文の範囲を絞り込む追加の情報 — を持ちます. WDQSはトリプルストアにこの情報を保存するために、自動的に「宣言」される主語を導入します. これは本質的には以下のような乱数です.

詳細はSPARQLチュートリアル - 修飾子を参照してください.

SPOはまた、RDFデータ構造をクエリするための基本的な構文のレイアウト形式として、あるいはあらゆるグラフデータベースやトリプルストアに対して使われます. 高性能グラフ データベースであるBlazegraphによって動作しているウィキデータクエリサービス（WDQS）もこれに含まれます.

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

基本 - 接頭辞（プレフィックス）とは
主語と述語（トリプルの最初と2番目の値）は常にURIとして保存する必要があります. 例えば、主語が宇宙 (Q1)の場合は  として保存されます. 接頭辞を用いると、この長いURIをコンパクトにwd:Q1と書くことができます. 主語や述語とは異なり、目的語（トリプルの3番目の値）はURIでも、数字や文字列などのリテラルでも構いません.

WDQSは接頭辞と呼ばれる多くの省略形ショートカットを解釈します. いくつかはウィキデータ内部のもの（例：wd, wdt, p, ps, bd）であり、その他の多くのものは一般的に使われているrdf、skos、owl、schemaのような外部接頭辞です.

下記のクエリでは、「P279 = Q7725634」という文にあてはまる項目を求めています. より完全な用語でいうと、述語として「上位クラス」を持ち、その目的語が＝「文芸作品」であるような主語を選択している、となります.

出力の変数：

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

ラベルサービス
クエリするエンティティのラベルや別名あるいは説明を言語フォールバックありで入手することに特化したサービスをURI で使うことができます. 他の方法で同じ効果を得ようとすると必要になるSPARQLクエリの複雑さを減らしてくれるので、このサービスはラベルを入手したいときに大変便利です.

サービスは手動と自動の2つのモードのうちいずれかで使うことができます.

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

そして WDQS が自動生成するラベルは以下のとおりです.


 * 内の未割り当て変数が という名前であるならば、WDQSは変数 のエンティティに対するラベルを生成します.
 * 内の未割り当て変数が という名前であるならば、WDQSは変数 のエンティティに対する別名を生成します.
 * 内の未割り当て変数が という名前であるならば、WDQSは変数 のエンティティに対する説明を生成します.

いずれの場合も、変数 が割り当てられるべきで、そうしないとサービスが機能しません.

Automatic mode only inspects the projection of the query – for instance, in, only the first label is recognized, and   is not supported by automatic mode at all. このような場合、手動モードを使う必要があるでしょう（下記参照）.

ラベルに使う好きな言語を、ひとつまたは複数の トリプルで指定します. それぞれの文字列にひとつまたはカンマで区切られた複数の言語コードを含めることができます. WDQSは指定した順に言語を検討します. 指定されたいずれの言語のラベルも取得できない場合、そのエンティティの（いかなる接頭辞も含まない）Q-idがラベルとなります.

ウィキデータクエリサービスのウェブサイトは、自動的に を現状の利用者のインターフェースの言語コードに置き換えます. 例えば、利用者のUIがフランス語であるならば、 はクエリサービスに送信される前に へ変換されます.

たとえばアメリカ合衆国の大統領夫妻の一覧を閲覧する場合.

この例では、WDQSがプロパティに対するラベル と を自動生成します.

手動モードでは、サービス呼び出し内でラベル変数を明示的に割り当てますが、WDQSはそれでもなお言語の解決とフォールバックを提供します. 例：

ラベルと説明をフランス語、ドイツ語、英語で検討し、そのいずれも取得できない場合は、Q-idをラベルとして使います.

地理空間検索
このサービスは、特定の中心点から特定の半径の範囲内あるいは特定の矩形領域の範囲内に含まれる座標を持つ項目を検索することを可能にします.

点の周辺を検索する
例:

サービス呼び出しの1行目には    形式が必須で、検索結果は に指定された範囲内にある項目を割り当て、 にその項目の座標を割り当てます. 以下のパラメータがサポートされます.

矩形範囲内を検索する
矩形範囲検索の例：

または:

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

サービス呼び出しの1行目には    形式が必須で、検索結果は  に指定された範囲内にある項目を割り当て、 にその項目の座標を割り当てます. 以下のパラメータがサポートされます.

と を一緒に、また と を一緒に使うべきであり、混用はできません. と が述語として使われた場合、それらの点が矩形の対角の座標であると仮定し、それに応じて角を導出します.

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

座標部分関数
関数 、 および は、それぞれ座標の構成部分である天体のURI、緯度および経度を返します.

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

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

日付の延長
サービスは過去および未来のおよそ2900億年の範囲の 型の日付の値を1秒精度でサポートします. WDQSは日付をUnixエポックからの64ビットの秒数として保存します.

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

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

There is no documentation in the BlazeGraph wiki about the bd:sample extension. It's documented only in a comment in the code.

連携
SPARQL連携クエリを使って、選択した件数の外部データベースを呼び出すことができます. 専用ページで連携エンドポイントの総覧をご参照ください.

連携クエリの例:

連携エンドポイントが提供するデータベースが使用するオントロジーは、ウィキデータのものとは大きく異なる可能性があることに注意してください. これらのデータベースのオントロジーとデータへのアクセス方法について学ぶには、所有者の説明文書のリンクを参照してください.

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

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

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

公開エンドポイントのクエリの実行時間は60秒が上限です. GUIでも公開SPARQLエンドポイントでも同じです.

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

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

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

GUIは簡易なエンティティ・エクスプローラー機能も備えており、エンティティ結果の横の虫眼鏡アイコン「🔍」をクリックすることで起動することができます. エンティティのQ-ID自体をクリックすると、wikidata.org上のエンティティのページを表示します.

既定の表示

 * 詳細はwikidata:Special:MyLanguage/Wikidata:SPARQL query service/Wikidata Query Help/Result Viewsを参照

WDQS GUIでクエリを実行する場合、クエリの最初に というコメントで指定することによって、結果の表示形式を選択することができます.

タイトルを表示する
WDQS GUIでクエリを実行する場合、クエリの最初に というコメントで指定することによって、タイトルを結果の上部に表示することができます.

SPARQLエンドポイント
へのGETまたはPOSTリクエストで、SPARQLクエリを直接、SPARQLエンドポイントにサブミットすることができます.

GETリクエストは、  形式で、例えば   のようにURL内に指定されたクエリを持っています.

POSTリクエストは、クエリをURLの代わりにリクエストボディに受け入れます. これによりURLの長さ制限に達することなく、より大きなクエリを実行することができるようになります. （それでもなおPOSTボディは 接頭辞を含めなければならず（つまり、単に ではなく、 とすべき）、SPARQLクエリはURLエスケープされていなければならないことに注意してください. ）

結果は既定ではXML、URLにクエリパラメータ が含まれるかリクエストでヘッダー が与えられているならばJSONとして返されます.

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

POSTクエリはキャッシュされないので、小規模なクエリにはGETを、大規模なクエリはPOSTを利用することが推奨されます.

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

クエリの制限
固定のクエリ期限は60秒 に設定されています. 以下の制限もあります.


 * 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. Clients who don’t comply with the User-Agent policy may be blocked completely – make sure to send a good  header.

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

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

Explain Query
Blazegraph allows to show query analysis that explains how the query has been parsed and which optimizations were applied. To see this information, add  parameter to the query string, for example:.

名前空間
ウィキデータクエリサービスにはメインの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 the category graph of select wikis. The list of covered wikis can be seen here: https://noc.wikimedia.org/conf/dblists/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ボキャブラリで、データ・カタログ間の相互運用性を促進. ) は https://query.wikidata.org/bigdata/namespace/dcatap/sparql エンドポイントで SPARQL として入手できます.

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

データを取得するクエリの例:

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

インターフェイスの利用には以下の URL からアクセスします:. このサービスはBlazegraphデータベース上で実装されているので、クエリサービスと同じようなラグがあります. リクエストの例：


 * 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サーバがGUIを提供するように設定を変更する必要があるでしょう.

既定では、http://localhost:9999/bigdata/namespace/wdq/sparql のSPARQLエンドポイントのみが設定されており、既定のBlazegraph GUIは http://localhost:9999/bigdata/ で利用可能です. 既定の設定ではどちらもローカルホストからのみアクセス可能であること注意してください. もし外部からアクセスするつもりであれば、外部エンドポイントと適切なアクセス制御を設定する必要があるでしょう.

スナップショット版の使用
未リリースのスナップショット版を利用したい場合（たいていはリリース版がバグを含んでいて、バグが修正されているものの、まだ新しいリリース版が利用可能でない場合に必要とされます）および自分でバイナリをコンパイルしたくない場合には、次のいずれかを利用できます.
 * https://github.com/wikimedia/wikidata-query-deploy - プロダクション・バイナリを含むデプロイメントリポジトリ. の作動が必須. 作動確認をして「 」を実行してください.
 * https://archiva.wikimedia.org/#artifact/org.wikidata.query.rdf/service のArchiva スナップショットデプロイメント - 最新版を選択し、続いてArtifacts、ダウンロードする最新版のパッケージを選択する.

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


 * 1) Download recent RDF dump from https://dumps.wikimedia.org/wikidatawiki/entities/ (the RDF one is the one ending in  ).
 * 2) Pre-process data with the   script. This creates a set of TTL files with preprocessed data, with names like , etc. See options for the script below.
 * 3) Start Blazegraph service by running the   script.
 * 4) Load the data into the service by using  . Note that loading data is usually significantly slower than pre-processing, so you can start loading as soon as several preprocessed files are ready. Loading can be restarted from any file by using the options as described below.
 * 5) After all the data is loaded, start the Updater service by using.

カテゴリの読み込み
カテゴリのデータも読み込みたいのであれば、以下の手順に従ってください:


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

これらのスクリプトは、ウィキメディアの設定に従い、ウィキメディアのウィキからのみデータを読み込むことに注意してください. もし他のウィキを扱う必要があるならば、スクリプト内のいくつかの変数を変更する必要があるかもしれません.

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

munge.sh
RDFダンプから読み込むためにデータを前処理します.

例:

loadData.sh
処理済みのデータをBlazegraphに読み込みます. がインストールされている必要があります.

例:

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

例:

スクリプト内で、以下の2つの変数を変更したい場合があるかもしれません. また、以下の環境変数がスクリプトによって確認されます（すべてオプション）.

runUpdate.sh
更新サービスを実行します.

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

例:

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

更新プログラムのオプション
以下のオプションが更新プログラムアプリケーションで機能します.

これらは スクリプトに追加のオプションとして の後に与えられるべきです. 例:.

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

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


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

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

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

関連項目

 * WDQからSPARQLへ構文翻訳
 * SPARQLクエリの例
 * Discoveryチーム
 * WDQS実装の注記事項
 * SPARQLクエリ構文の基本