Phabricator のプロジェクト名 #WDQS

Wikidata Query Service/User Manual

From MediaWiki.org
Jump to navigation Jump to search
This page is a translated version of the page Wikidata Query Service/User Manual and the translation is 88% complete.
Outdated translations are marked like this.
Other languages:
Deutsch • ‎English • ‎dansk • ‎español • ‎español de América Latina • ‎français • ‎italiano • ‎polski • ‎português do Brasil • ‎Ελληνικά • ‎беларуская (тарашкевіца)‎ • ‎українська • ‎العربية • ‎हिन्दी • ‎বাংলা • ‎தமிழ் • ‎ไทย • ‎中文 • ‎日本語 • ‎한국어
5分でわかるウィキデータのクエリサービス

ウィキデータ クエリ サービス 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つとなります。 

<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:) は「真に近い」属性 — 文を読んだときにユーザーが最も想定しやすい値になります。「真に近い」属性は、文により他のものよりも「より真である」ものがあるため、設定が必要です。たとえば「アメリカ合衆国の首都はニューヨークである」という文もある意味で真で — ただしアメリカの歴史のコンクストを考慮に入れる必要があります。WDQS はどの文を「真に近い」と扱うか、ランクを使って判断します。

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

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 tutorial - qualifiersを参照してください。

SPOはまた、クエリに用いる基本的な構文のレイアウトとして、RDFデータ構造、あらゆるグラフ データベースを対象にします。高度なパフォーマンス グラフ データベースにささえられた、triplestoreとしてのウィキデータ クエリ サービス（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」、展開すると「サブクラスの」述語で目的語が= 「literary work」を含む項目を求めています。

出力の変数： 

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

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

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

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

and WDQS will automatically generate labels as follows:

  • If an unbound variable in SELECT is named ?NAMELabel, then WDQS produces the label (rdfs:label) for the entity in variable ?NAME.
  • If an unbound variable in SELECT is named ?NAMEAltLabel, then WDQS produces the alias (skos:altLabel) for the entity in variable ?NAME.
  • If an unbound variable in SELECT is named ?NAMEDescription, then WDQS produces the description (schema:description) for the entity in variable ?NAME.

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

You specify your preferred language(s) for the label with one or more of bd:serviceParam wikibase:language "language-code" 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 [AUTO_LANGUAGE] with the language code of current user's interface. For example, if the user's UI is in French, the SPARQL's code bd:serviceParam wikibase:language "[AUTO_LANGUAGE],en" will be converted to bd:serviceParam wikibase:language "fr,en" before being sent to the query service.


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


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" .
   }
 }

Try it!

In this example WDQS automatically creates the labels ?pLabel and ?wLabel 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: 

  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 .
    }
  }

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

地理空間検索

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

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

例: 

# 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
  ?place wdt:P31/wdt:P279* wd:Q1248784 .
  SERVICE wikibase:label {
    bd:serviceParam wikibase:language "en" . 
  }
} ORDER BY ASC(?dist)

Try it!

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 .
    }
  ?place wdt:P31/wdt:P279* wd:Q3914 .
}

Try it!

または: 


#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 .
  }
?place wdt:P31/wdt:P279* wd:Q3914 .
}

Try it!

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


# 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 .
  }
?place wdt:P31/wdt:P279* wd:Q3914 .
}

Try it!

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

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

wikibase:cornerSouthWestとwikibase:cornerNorthEastは、wikibase:cornerWestとwikibase:cornerEast同様に必ず一緒に使う必要があり、 混同はできません。 述語のwikibase:cornerWestとwikibase: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

Try it! 


# 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

Try it!

座標部分関数

関数のgeof:globeとgeof:latitudeおよびgeof:longitudeは座標の部分 - それぞれ地球URIと緯度および経度を返します。

URL関数を解読する

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

自動接頭辞

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

日付の延長

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

ブレーズグラフ関数

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

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

連合クエリ

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

連合クエリの例: 


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でも同じです。 もしクエリを走らせるのにもっと長い時間が必要な場合は、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でクエリを走らせる場合、結果の表示形式を選択できます：クエリの冒頭の#defaultView:viewNameでコメントを選択します。

SPARQLエンドポイント

SPARQL queries can be submitted directly to the SPARQL endpoint with a GET or POST request to https://query.wikidata.org/sparql.

GET requests have the query specified in the URL, in the format https://query.wikidata.org/sparql?query=(SPARQL_query), e.g. https://query.wikidata.org/sparql?query=SELECT%20?dob%20WHERE%20{wd:Q42%20wdt:P569%20?dob.}.

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 query= prefix (that is, it should be query=(SPARQL_query) rather than just (SPARQL query)), 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 format=json is included in the URL, or the header Accept: application/sparql-results+json is provided with the request.

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

小規模なクエリにはGETを、大規模な場合はPOSTを利用するよう推奨されます。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秒 に設定されています。 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 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.

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

また現状では同一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.

名前空間

ウィキデータ・クエリサービスにはメインの名前空間wdqが含まれ、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 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ボキャブラリで、データ・カタログ間の相互運用性を促進。) は dcatap 名前空間から SPARQL として入手できます。

そのデータにアクセスするSPARQLエンドポイント：https://query.wikidata.org/bigdata/namespace/dcatap/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 
  ] .
}

Try it!

Linked Data Fragments エンドポイント

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

インタフェースの利用には次のURLからアクセスします。https://query.wikidata.org/bigdata/ldf. リクエストのサンプル:

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

既定でHTMLインタフェースが表示されるものの、他にも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説明文書を参照してください。

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

インストール

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

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

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

画面キャプチャ版の使用

未リリースの画面キャプチャ版を利用する場合で（修正済みのバグを含むリリース版はあるがリリース版が更新されていない場合によくある事例）、バイナリをコンパイルしたくない場合、次のどちらかを利用できます。

データの読み込み

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

  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 いいえ 指定すると、サイトリンクのデータを除外。サイトリンクに対するクエリが不用の場合はこのオプションを有効にして、性能を上げデータベースのサイズを抑える。

例:

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

loadData.sh

処理済みのデータをブレイズグラフに読みこむ。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 を指定。 Default=wdq
-h host いいえ SPARQL エンドポイントのホスト名。既定では localhost
-c context いいえ SPARQL エンドポイントのコンテクスト URL。既定では bigdata - 通常、WDQS に対して変更は不要
-l language いいえ 指定すると、指定した言語のラベルのみ取得。単一言語のみ必要な場合はこのオプションを有効にして、性能を上げ、データベースのサイズを抑えてクエリを単純化する。
-s いいえ 指定すると、サイトリンクに関するデータを除外。サイトリンクのクエリが不用の場合はこのオプションを有効にして、性能を上げ、データベースのサイズを抑える。
-t secs いいえ ブレイズブラフに問い合わせたときのタイムアウト設定。単位は秒。
-N No 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 No 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.
--wikibaseScheme SCHEME ウィキベースの問い合わせに用いる URL スキーマ（http、https） (廃止予定) Use wikibaseUrl above instead.
--wikibaseHost HOSTNAME ウィキベースに問い合わせるときに用いるホスト名。 (廃止予定) Use wikibaseUrl above instead.
-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
-v --verbose Verbose logging (DEBUG level).


構成可能な属性

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

名前 意味 既定
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
wikibaseHost ウィキベースのインスタンスのホスト名。ブレイズグラフと修正プログラムの両方に適用。 (廃止予定) Use wikibaseConceptUri above. www.wikidata.org
org.wikidata.query.rdf.blazegraph.inline.literal.WKTSerializer.noGlobe 天体がない座標の既定の天体の値。「2」は Q2 というエンティティを天体に指定する。「0」だと既定の天体は存在しない。ブレイズグラフに適用。 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ボードで確認してください。

関連項目

Retrieved from "https://www.mediawiki.org/w/index.php?title=Wikidata_Query_Service/User_Manual/ja&oldid=3234573"