ウィキデータ クエリ サービス/利用者マニュアル

This page is a translated version of the page Wikidata Query Service/User Manual and the translation is 90% complete.

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

15分でわかるウィキデータクエリサービス

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

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で表現することができます。

<http://www.wikidata.org/entity/Q30>  <http://www.wikidata.org/prop/direct/P36>  <http://www.wikidata.org/entity/Q61> .

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

wd:Q30  wdt:P36  wd:Q61 .

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

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

wd:Q30  p:P36  <random_URI_1> .         # US "indirect capital" is <X>
<random_URI_1>  ps:P36  wd:Q61 .        # The X's "real capital value" is  Washington DC
<random_URI_1>  pq:P580  "1800-11-17" . # The X's start date is 1800-11-17

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

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

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

基本 - 接頭辞(プレフィックス)とは

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

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

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

出力の変数:

PREFIX wd: <http://www.wikidata.org/entity/>
PREFIX wds: <http://www.wikidata.org/entity/statement/>
PREFIX wdv: <http://www.wikidata.org/value/>
PREFIX wdt: <http://www.wikidata.org/prop/direct/>
PREFIX wikibase: <http://wikiba.se/ontology#>
PREFIX p: <http://www.wikidata.org/prop/>
PREFIX ps: <http://www.wikidata.org/prop/statement/>
PREFIX pq: <http://www.wikidata.org/prop/qualifier/>
PREFIX rdfs: <http://www.w3.org/2000/01/rdf-schema#>
PREFIX bd: <http://www.bigdata.com/rdf#>

# The below SELECT query does the following:
# Selects all the items(?s subjects) and their descriptions(?desc)
# that have(WHERE) the statement(?s subject) has a direct property(wdt:) = P279 <subclasses of>
# with a value of entity(wd:) = Q7725634 <Literary Work>
# and optionally return the label using the Wikidata label service

SELECT ?s ?desc WHERE {
  ?s wdt:P279 wd:Q7725634 .
  OPTIONAL {
     ?s rdfs:label ?desc filter (lang(?desc) = "en").
   }
 }

拡張機能

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

ラベルサービス

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

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

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

PREFIX wikibase: <http://wikiba.se/ontology#>
SERVICE wikibase:label {
    bd:serviceParam wikibase:language "en" .
}

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

  • SELECT内の未割り当て変数が?NAMELabelという名前であるならば、WDQSは変数?NAMEのエンティティに対するラベル(rdfs:label)を生成します。
  • SELECT内の未割り当て変数が?NAMEAltLabelという名前であるならば、WDQSは変数?NAMEのエンティティに対する別名(skos:altLabel)を生成します。
  • SELECT内の未割り当て変数が?NAMEDescriptionという名前であるならば、WDQSは変数?NAMEのエンティティに対する説明(schema:description)を生成します。

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

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

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

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


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

SELECT ?p ?pLabel ?w ?wLabel WHERE {
   wd:Q30 p:P6/ps:P6 ?p .
   ?p wdt:P26 ?w .
   SERVICE wikibase:label {
    bd:serviceParam wikibase:language "en" .
   }
 }

試用する

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

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

  SELECT *
   WHERE {
     SERVICE wikibase:label {
       bd:serviceParam wikibase:language "fr,de,en" .
       wd:Q123 rdfs:label ?q123Label .
       wd:Q123 skos:altLabel ?q123Alt .
       wd:Q123 schema:description ?q123Desc .
       wd:Q321 rdf:label ?q321Label .
    }
  }

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

地理空間検索

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

点の周辺を検索する

例:

# Airports within 100km from Berlin
#defaultView:Map
SELECT ?place ?placeLabel ?location ?dist WHERE {
  # Berlin coordinates
  wd:Q64 wdt:P625 ?berlinLoc . 
  SERVICE wikibase:around { 
      ?place wdt:P625 ?location . 
      bd:serviceParam wikibase:center ?berlinLoc . 
      bd:serviceParam wikibase:radius "100" . 
      bd:serviceParam wikibase:distance ?dist.
  } 
  # Is an airport
  FILTER EXISTS { ?place wdt:P31/wdt:P279* wd:Q1248784 }
  SERVICE wikibase:label {
    bd:serviceParam wikibase:language "en" . 
  }
} ORDER BY ASC(?dist)

試用する

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

述語 意味
wikibase:center この点の周辺の検索が行われる。検索を機能させるために割り当てが必須。
wikibase:radius 中心点からの距離。現状、距離は常にキロメートル単位で、他の単位はまだサポートされていない。
wikibase:globe 検索される天体。オプション、既定は地球 (wd:Q2)
wikibase:distance 距離情報を受け取る変数

矩形範囲内を検索する

矩形範囲検索の例:

# Schools between San Jose, CA and Sacramento, CA
#defaultView:Map
SELECT * WHERE {
  wd:Q16553 wdt:P625 ?SJloc .
  wd:Q18013 wdt:P625 ?SCloc .
  SERVICE wikibase:box {
      ?place wdt:P625 ?location .
      bd:serviceParam wikibase:cornerSouthWest ?SJloc .
      bd:serviceParam wikibase:cornerNorthEast ?SCloc .
  }
  FILTER EXISTS { ?place wdt:P31/wdt:P279* wd:Q3914 }
}

試用する

または:

#Schools between San Jose, CA and San Francisco, CA
#defaultView:Map
SELECT ?place ?location WHERE {
  wd:Q62 wdt:P625 ?SFloc .
  wd:Q16553 wdt:P625 ?SJloc .
  SERVICE wikibase:box {
    ?place wdt:P625 ?location .
    bd:serviceParam wikibase:cornerWest ?SFloc .
    bd:serviceParam wikibase:cornerEast ?SJloc .
  }
  FILTER EXISTS { ?place wdt:P31/wdt:P279* wd:Q3914 }
}

試用する

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

# Schools between San Jose, CA and Sacramento, CA
#same as previous
#defaultView:Map
SELECT * WHERE {
SERVICE wikibase:box {
    ?place wdt:P625 ?location .
    bd:serviceParam wikibase:cornerWest "Point(-121.872777777 37.304166666)"^^geo:wktLiteral .
    bd:serviceParam wikibase:cornerEast "Point(-121.486111111 38.575277777)"^^geo:wktLiteral .
  }
  FILTER EXISTS { ?place wdt:P31/wdt:P279* wd:Q3914 }
}

試用する

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

述語 意味
wikibase:cornerSouthWest 矩形の南西角。
wikibase:cornerNorthEast 矩形の北東角。
wikibase:cornerWest 矩形の西角。
wikibase:cornerEast 矩形の東角。
wikibase:globe 検索される天体。オプション、既定は地球 (wd:Q2)

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

その他の関数

距離関数

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

# Airports within 100km from Berlin
SELECT ?place ?placeLabel ?location ?dist WHERE {

  # Berlin coordinates
  wd:Q64 wdt:P625 ?berlinLoc . 
  SERVICE wikibase:around { 
      ?place wdt:P625 ?location . 
      bd:serviceParam wikibase:center ?berlinLoc . 
      bd:serviceParam wikibase:radius "100" . 
  } 
  # Is an airport
  ?place wdt:P31/wdt:P279* wd:Q1248784 .
  SERVICE wikibase:label {
    bd:serviceParam wikibase:language "en" . 
  }
  BIND(geof:distance(?berlinLoc, ?location) as ?dist) 
} ORDER BY ?dist

試用する

# Places around 0°,0° 
SELECT *
{
  SERVICE wikibase:around { 
      ?place wdt:P625 ?location . 
      bd:serviceParam wikibase:center "Point(0 0)"^^geo:wktLiteral .
      bd:serviceParam wikibase:radius "250" . 
  } 
  SERVICE wikibase:label { bd:serviceParam wikibase:language "en" . ?place rdfs:label ?placeLabel }
  BIND(geof:distance("Point(0 0)"^^geo:wktLiteral, ?location) as ?dist) 
} 
ORDER BY ?dist

試用する

座標部分関数

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

URLデコード関数

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

自動接頭辞

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

日付の延長

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

ブレーズグラフ関数

  警告: As Blazegraph is not actively developed, it is planned to migrate Wikidata Query Service to another triplestore. The following may be discontinued at some point.

ブレーズグラフ(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連携クエリを使って、選択した件数の外部データベースを呼び出すことができます。 専用ページで連携エンドポイントの総覧をご参照ください。

連携クエリの例:


SELECT ?workLabel WHERE {
  wd:Q165257 wdt:P2799 ?id 
  BIND(uri(concat("http://data.cervantesvirtual.com/person/", ?id)) as ?bvmcID)
  SERVICE <http://data.cervantesvirtual.com/openrdf-sesame/repositories/data> {
    ?bvmcID <http://rdaregistry.info/Elements/a/otherPFCManifestationOf> ?work .
    ?work rdfs:label ?workLabel        
  }
}

Try it!

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

MediaWiki API

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

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


SELECT * WHERE {
  wd:Q6501349 wdt:P910 ?category .
  ?link schema:about ?category; schema:isPartOf <https://en.wikipedia.org/>; schema:name ?title .
  SERVICE wikibase:mwapi {
	 bd:serviceParam wikibase:api "Generator" .
     bd:serviceParam wikibase:endpoint "en.wikipedia.org" .
     bd:serviceParam mwapi:gcmtitle ?title .
     bd:serviceParam mwapi:generator "categorymembers" .
     bd:serviceParam mwapi:gcmprop "ids|title|type" .
     bd:serviceParam mwapi:gcmlimit "max" .
    # out
    ?subcat wikibase:apiOutput mwapi:title  .
    ?ns wikibase:apiOutput "@ns" .
    ?item wikibase:apiOutputItem mwapi:item .
  }
}

Try it!

ウィキメディア・サービス

ウィキメディアが走らせる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でクエリを実行する場合、クエリの最初に#defaultView:viewNameというコメントで指定することによって、結果の表示形式を選択することができます。

タイトルを表示する

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

SPARQLエンドポイント

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

GETリクエストは、 https://query.wikidata.org/sparql?query=(SPARQL_query) 形式で、例えば https://query.wikidata.org/sparql?query=SELECT%20?dob%20WHERE%20{wd:Q42%20wdt:P569%20?dob.} のようにURL内に指定されたクエリを持っています。

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

結果は既定ではXML、URLにクエリパラメータformat=jsonが含まれるかリクエストでヘッダーAccept: application/sparql-results+jsonが与えられているならばJSONとして返されます。

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

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

サポートする形式

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

形式 HTTP ヘッダー クエリパラメータ 説明
XML Accept: application/sparql-results+xml format=xml XML 出力形式は既定。https://www.w3.org/TR/rdf-sparql-XMLres/ で規定されている通り。
JSON Accept: application/sparql-results+json format=json JSON 出力形式。https://www.w3.org/TR/sparql11-results-json/ の通り。 
TSV Accept: text/tab-separated-values https://www.w3.org/TR/sparql11-results-csv-tsv/ で規定されている通り。
CSV Accept: text/csv https://www.w3.org/TR/sparql11-results-csv-tsv/ で規定されている通り。
バイナリRDF Accept: application/x-binary-rdf-results-table

クエリの制限

固定のクエリ期限は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 429. Use Retry-After 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 User-Agent 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 explain=details parameter to the query string, for example: https://query.wikidata.org/sparql?query=SELECT%20?dob%20WHERE%20{wd:Q42%20wdt:P569%20?dob.}&explain=details.

名前空間

ウィキデータクエリサービスにはメインのSPARQLエンドポイントがクエリの対象とする標準名前空間wdqが含まれますが、その他の補助的な名前空間を以下に列挙します。 別の名前空間からデータをクエリするには、エンドポイントの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 categories. 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

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

PREFIX dcat: <http://www.w3.org/ns/dcat#>
PREFIX dct: <http://purl.org/dc/terms/>

SELECT ?url ?date ?size WHERE {
  <https://www.wikidata.org/about#catalog> dcat:dataset ?dump .
  ?dump dcat:distribution [
    dct:format "application/json" ;
    dcat:downloadURL ?url ;
    dct:issued ?date ;
    dcat:byteSize ?size 
  ] .
}

Linked Data Fragments エンドポイント

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

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

subjectpredicateおよびobjectパラメータとして、現状は完全なURLのみがサポートされていることに注意してください。

既定ではHTMLインタフェースが表示されますが、他にもAccept HTTPヘッダで定義された、いくつかのデータ形式が利用可能です。

利用可能なデータ形式
Accept 形式
text/html 既定の HTML ブラウザー インターフェイス
text/turtle Turtle形式
application/ld+json JSON-LD形式
application/n-triples N-Triples形式
application/rdf+xml RDF/XML 形式

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

スタンドアローンのサービス

このサービスはオープンソースソフトウェアなので、以下の手順に従って、任意の利用者のサーバ上で稼動させることもできます。

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

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

インストール

サービスをインストールするために、例えばMaven Central から、group ID org.wikidata.query.rdf と artifact ID serviceで完全なサービスパッケージを圧縮形式のZIPファイルとしてダウンロードするか、あるいは https://github.com/wikimedia/wikidata-query-rdf/ でソース配布物をクローンし、「mvn package」でビルドすることが推奨されます。 パッケージのZIPファイルは service-VERSION-dist.zip として dist/target ディレクトリに格納されています。

パッケージには、 .war アプリケーションとしてBlazegraphサーバ、ウィキデータサイトから新しいデータを取得する更新サービスを実行するために必要となるライブラリ、さまざまなタスクをより簡単にするスクリプト、そしてguiサブディレクトリ内にGUIが含まれています。 GUIを使いたい場合は、あなたのHTTPサーバがGUIを提供するように設定を変更する必要があるでしょう。

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

スナップショット版の使用

未リリースのスナップショット版を利用したい場合(たいていはリリース版がバグを含んでいて、バグが修正されているものの、まだ新しいリリース版が利用可能でない場合に必要とされます)および自分でバイナリをコンパイルしたくない場合には、次のいずれかを利用できます。

データの読み込み

  警告: 2020年現在、ウィキメディアサーバではインポートされたダンプですべてのデータを手に入れるには約12日かかり、クエリサービスのラグを解消するにはさらに12日かかります。

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

  1. Download recent RDF dump from https://dumps.wikimedia.org/wikidatawiki/entities/ (the RDF one is the one ending in .ttl.gz).
  2. Pre-process data with the munge.sh script. This creates a set of TTL files with preprocessed data, with names like wikidump-000000001.ttl.gz, etc. See options for the script below.
  3. Start Blazegraph service by running the runBlazegraph.sh script.
  4. Load the data into the service by using loadData.sh. 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 runUpdate.sh.

カテゴリの読み込み

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

  1. 名前空間を作成する。例えば、 categories: createNamespace.sh categories
  2. そこにデータを読み込む: forAllCategoryWikis.sh loadCategoryDump.sh categories

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

スクリプト

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

munge.sh

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

オプション 必須かどうか 説明
-f filename はい RDF ダンプのファイル名
-d directory いいえ 処理が済んだファイルを書き込むディレクトリ。既定では現在のディレクトリ
-l language いいえ 指定すると、その言語のラベルのみ取得。単一言語のみ必要な場合はこのオプションを有効にして、性能を上げ、データベースのサイズを抑えてクエリを単純化する。
-s いいえ 指定すると、サイトリンクのデータを除外。サイトリンクに対するクエリが不要の場合はこのオプションを使用すると、性能を上げデータベースのサイズを抑えることができます。
-c size いいえ Use this option to override the default chunk size. Too big chunks may time out when importing.

例:

./munge.sh -c 50000 -f data/wikidata-20150427-all-BETA.ttl.gz -d data -l en -s

loadData.sh

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

オプション 必須かどうか 説明
-n namespace はい データを読み込むグラフ名前空間を指定。WDQSデータに対しては wdqとすべきです。
-d directory いいえ 処理したファイルを保存するディレクトリの指定。既定では現在のディレクトリ。
-h host いいえ SPARQL エンドポイントのホスト名。既定ではlocalhost
-c context いいえ SPARQL エンドポイントのコンテキスト URL。既定ではbigdata - 通常、WDQS に対して変更は不要。
-s start いいえ 処理を開始するファイルの番号。既定では1
-e end いいえ 処理を終了するファイルの番号

例:

./loadData.sh -n wdq -d `pwd`/data

runBlazegraph.sh

ブレイズグラフ・サービスを実行。

オプション 必須かどうか 説明
-d directory いいえ ブレイズグラフをインストールするホームディレクトリ。既定ではスクリプトが保存されたディレクトリ
-c context いいえ SPARQL エンドポイントのコンテキスト URL。既定では bigdata - 通常は WDQS に対して変更は不要
-p port いいえ SPARQL サービスのポート番号。既定では 9999
-o options いいえ コマンドラインにオプションを追加

例:

./runBlazegraph.sh

スクリプト内で、以下の2つの変数を変更したい場合があるかもしれません。

# Q-id of the default globe
DEFAULT_GLOBE=2
# Blazegraph HTTP User Agent for federation
USER_AGENT="Wikidata Query Service; https://query.wikidata.org/";

また、以下の環境変数がスクリプトによって確認されます(すべてオプション)。

変数 既定 説明
HOST localhost ブレイズグラフ・サービスをバインドするホスト名
PORT 9999 ブレイズグラフ・サービスをバインドするポート
DIR スクリプトを保存するディレクトリ 設定ファイルを保存するディレクトリ
HEAP_SIZE 16g ブレイズクラフの Java ヒープのサイズ
MEMORY -Xms${HEAP_SIZE} -Xmx${HEAP_SIZE} ブレイズグラフの総 Java メモリ設定
GC_LOGS ソースを参照 GC ログ設定
CONFIG_FILE RWStore.properties ブレイズグラフの設定ファイルの保存先
BLAZEGRAPH_OPTS その他のオプションはそのまま Java コマンドラインに渡す

runUpdate.sh

更新サービスを実行します。

オプション 必須かどうか 説明
-n namespace いいえ データを読み込むグラフ名前空間の指定。WDQS データに対しては必ず wdq を指定。 既定値: wdq
-h host いいえ SPARQL エンドポイントのホスト名。既定では localhost
-c context いいえ SPARQL エンドポイントのコンテキスト URL。既定では bigdata - 通常、WDQS に対して変更は不要
-l language いいえ 指定すると、指定した言語のラベルのみ取得。単一言語のみ必要な場合はこのオプションを有効にして、性能を上げ、データベースのサイズを抑えてクエリを単純化する。
-s いいえ 指定すると、サイトリンクに関するデータを除外。サイトリンクのクエリが不用の場合はこのオプションを有効にして、性能を上げ、データベースのサイズを抑える。
-t secs いいえ ブレイズブラフに問い合わせたときのタイムアウト設定。単位は秒。
-N いいえ This option causes the script to ignore options that may cause problems when running second Updater while the first is already running. Use it when running secondary Updater e.g. to catch up specific item with --ids (see below).
-S いいえ Log to console instead of log files. Useful when running the script from the command line for maintenance tasks.

オプションの-l-sの設定(あるいは設定なし)は、munge.sh と runUpdate.sh で同じにすることが推奨されます。さもないとデータを適切に更新することができません。

例:

./runUpdate.sh

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

変数 既定 説明
UPDATER_OPTS その他のオプションはそのまま Java コマンドラインに渡す

更新プログラムのオプション

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

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

更新プログラムのオプション
オプション ロングオプション 意味
-v --verbose 冗長モード
-s TIMESTAMP --start TIMESTAMP 特定のタイムスタンプからデータ取得を開始、形式は 2015-02-11T17:11:08Z もしくは 20150211170100
--keepTypes すべてのタイプのタイムスタンプを保存
--ids ID1,ID2,... 特定のIDを更新して終了
--idrange ID1-ID2 特定の範囲のIDを更新して終了
-d SECONDS --pollDelay SECONDS 新規データが見つからない場合の待ち受けの長さ
-t NUMBER --threadCount NUMBER ウィキベースのデータを取得するときのスレッド数
-b NUMBER --batchSize NUMBER RecentChanges API から取得する変更の件数
-V --verify 読み込み後のデータを確認 (たいへん遅い! デバッグ専用)
-T SECONDS --tailPollerOffset SECONDS 第一のポーリングに時差を与えた、第二の追跡ポーリングを使用
--entityNamespaces NUMBER,NUMBER,... 変更を確認するデータベースの名前空間一覧
-W --wikibaseUrl URL URL to use when talking to Wikibase. E.g. https://www.wikidata.org. Must be set if updates do not come from Wikidata.
-U --conceptUri URL URL base of the URLs used to represent Wikibase entities in RDF. E.g. http://www.wikidata.org. Must be set if the Wikibase instance does not use Wikidata-based prefixes.
--commonsUri URL Commons URI for SDC support. Both --conceptUri and --commonsUri should be set for this to work.
--wikibaseScheme SCHEME ウィキベースの問い合わせに用いる URL スキーマ(http、https) (廃止予定) 上述のwikibaseUrlを代用してください。
--wikibaseHost HOSTNAME ウィキベースに問い合わせるときに用いるホスト名。 (廃止予定) 上述のwikibaseUrlを代用してください。
-I --init 開始時間とともに指定すると、この時間はデータベースで最も最近の変更時間として記録され、その後のリクエストがあった場合は、たとえ新規のデータが見つからなくても、この時間を開始ポイントとして使用。
--constraints Load constraints violations for updated items via constraintsrdf API.
-K SERVERS --kafka SERVERS If specified, Updater will use Kafka as the update source and the specified servers as brokers. E.g. kafka1001.eqiad.wmnet:9092,kafka1002.eqiad.wmnet:9092,kafka1003.eqiad.wmnet:9092
-C NAME --consumer NAME Kafka consumer name. It is a good idea to set it to the host name or something based on it.
-c NAME1,NAME2 --cluster NAME1,NAME2 Kafka cluster names. If specified, the Kafka topic names will be prefixed by cluster names, so instead of topic1 there would be NAME1.topic1 and NAME2.topic2.
--resetKafka Reset Kafka offsets
--apiPath Path to the API, e.g. /w/api.php (default) or /api.php. Introduced in I78c222fe8b.
--entityDataPath Path to the entities, e.g. /wiki/Special:EntityData/ (default) or /Special:EntityData/. Introduced in I78c222fe8b.

設定可能なプロパティ

下記のプロパティは、上記のスクリプトのスクリプト実行コマンドに追加することで設定可能です。

名前 意味 既定
wikibaseServiceWhitelist リモートサービスのホワイトリストのファイル名。 Blazegraphに適用。 whitelist.txt
org.wikidata.query.rdf.blazegraph.mwapi.MWApiServiceFactory.config MWAPI integrationの設定ファイル mwservices.json
com.bigdata.rdf.sail.sparql.PrefixDeclProcessor.additionalDeclsFile Filename that contains additional prefix definitions. The syntax is as in SPARQL query. These definitions will be loaded by Blazegraph and available for all queries.
wikibaseConceptUri URL prefix for Wikibase data, which is used in RDF representation of entities. Needs to be set if the dataset does not use Wikidata prefixes. http://www.wikidata.org
commonsConceptUri URL prefix for Structured Data on Commons support. Both wikibaseConceptUri and commonsConceptUri should be set for it to work.
wikibaseHost ウィキベースのインスタンスのホスト名。Blazegraphと更新プログラムの両方に適用。 (廃止予定) 上述のwikibaseConceptUriを使用してください。 www.wikidata.org
org.wikidata.query.rdf.blazegraph.inline.literal.WKTSerializer.noGlobe 天体がない座標の既定の天体の値。「2」はエンティティ Q2 を既定の天体とすることを意味する。「0」は既定の天体なしを意味する。 Blazegraphに適用。 0
org.wikidata.query.rdf.tool.rdf.RdfRepository.timeout RDFリポジトリとやり取りする時のタイムアウト値。単位は秒。更新プログラムに適用。 -1
org.wikidata.query.rdf.tool.wikibase.WikibaseRepository.timeout ウィキベース・リポジトリとやり取りする時のタイムアウト値。単位はミリ秒。更新プログラムに適用。 5000
http.userAgent その他のサービスを呼び出す間にサービスが用いるユーザーエージェント
http.proxyHost http.proxyPort

https.proxyHost https.proxyPort

その他のサービスを呼び出す間に用いるプロキシの設定
wikibaseMaxDaysBack 最近の変更データを何日前までさかのぼって更新プログラムから要求することができるか。データベースがこの日数よりも古い場合、より最近のダンプから再読み込みすべきです。 30

不足している機能

以下は現状サポートされていない機能です。

  • リダイレクトはowl:sameAs tripleとしてのみ表現されますが、データではいかなる等価性も表さず、特別なサポートもありません。

お問い合わせ

サービスの不備についてお気づきの点は、送信先リストdiscovery@lists.wikimedia.org宛てにメールを送るか、チャットルーム#wikimedia-discoveryにてDiscoveryチームまでご連絡をいただけないでしょうか。

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

関連項目