Wikidata Query Service/Uživatelská příručka

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

15 minutový výukový program Wikidata Query Service

Wikidata Query Service (WDQS) je softwarový balíček a veřejná služba navržená tak, aby poskytovala SPARQL koncový bod, který vám umožňuje dotazovat se na data Wikidata soubor.

Tato stránka nebo další relevantní stránky dokumentace budou odpovídajícím způsobem aktualizovány; pokud službu používáte, doporučujeme je sledovat.

Příklady dotazů SPARQL můžete vidět na stránce s příklady SPARQL.

Soubor dat

Služba Wikidata Query Service pracuje s datovým souborem z Wikidata.org, reprezentovaným v RDF, jak je popsáno v dokumentaci Formát výpisu RDF.

Datový soubor služby se přesně neshoduje s datovým souborem vytvořeným výpisy RDF, zejména z důvodů výkonu. Dokumentace popisuje malý soubor rozdílů.

Týdenní výpis stejných dat si můžete stáhnout z:

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

Základy – Porozumění SPO (předmět, predikát, objekt) známé také jako Semantic Triple

spo nebo "subjekt, predikát, objekt" je známé jako triple nebo se na Wikidata běžně označuje jako prohlášení o datech.

Výrok "Hlavním městem Spojených států je Washington DC" se skládá z předmětu "Spojené státy" (Q30), predikátu "kapitál je" (P36) a objekt "Washington DC" (Q61). Tento příkaz může být reprezentován jako tři URI:

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

Díky předponám (viz níže) lze stejný výrok napsat ve stručnější podobě. Všimněte si tečky na konci, která představuje konec příkazu.

wd:Q30  wdt:P36  wd:Q61 .

/entity/ (wd:) představuje entitu Wikidata (hodnoty Q-čísla). /prop/direct/ (wdt:) je "pravdivá" vlastnost – hodnota, kterou bychom při pohledu na výpis očekávali nejčastěji. Pravdivostní vlastnosti jsou potřebné, protože některá tvrzení mohou být "pravdivější" než jiná. Například výrok "Hlavním městem USA je New York City" je pravdivý – ale pouze v historickém kontextu roku 1790. WDQS používá hodnocení k určení, která prohlášení by měla být použita jako "pravdivá".

Kromě pravdivých prohlášení ukládá WDQS všechny výroky (pravdivé i ne), ale nepoužívají stejnou předponu wdt:. U.S. capital má tři hodnoty: DC, Philadelphia a New York. A každá z těchto hodnot má "kvalifikátory" – další informace, jako je počáteční a koncové datum, které zužují rozsah každého příkazu. Pro uložení těchto informací v triplestore zavádí WDQS automatický předmět "výpisu", což je v podstatě náhodné číslo:

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

Další informace naleznete na stránce SPARQL tutoriál - kvalifikátory.

spo se také používá jako forma základního rozložení syntaxe pro dotazování RDF datových struktur nebo jakékoli grafové databáze nebo triplestore, jako je Wikidata Query Service (WDQS), která je založena na Blazegraph, vysoce výkonnou grafovou databázi.

Pokročilá použití trojitého (spo) dokonce včetně použití trojitých jako objektů nebo předmětů jiných trojic!

Základy - Pochopení prefixů

Předměty a predikáty (první a druhá hodnota trojice) musí být vždy uloženy jako URI. Pokud je například předmět Vesmír (Q1), bude uložen jako <https://www.wikidata.org/wiki/Q1>. Předpony nám umožňují napsat tento dlouhý URI v kratším tvaru: wd:Q1. Na rozdíl od předmětů a predikátů může být objekt (třetí hodnota trojice) buď URI, nebo literál, např. číslo nebo řetězec.

WDQS rozumí mnoha zkratkám, známým jako předpony. Některé jsou interní pro Wikidata, např. wd, wdt, p, ps, bd a mnoho dalších jsou běžně používané externí předpony, jako rdf, skos, owl, schema.

V následujícím dotazu se ptáme na položky, kde je uvedeno "P279 = Q7725634" nebo v úplnějších termínech, vybíráme předměty, které mají predikát "podtřída" s předmětem = "literární dílo".

Výstupní proměnné:

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 labels(?label)
# 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 English labels

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

Rozšíření

Služba podporuje následující rozšíření standardních funkcí SPARQL:

Štítková služba

Štítek, alias nebo popis dotazovaných entit můžete načíst s jazykovou rezervou pomocí specializované služby s URI <http://wikiba.se/ontology#label>. Služba je velmi užitečná, když chcete načíst štítky, protože snižuje složitost dotazů SPARQL, které byste jinak potřebovali k dosažení stejného efektu.

Službu lze využívat v jednom ze dvou režimů: manuálním a automatickém.

V automatickém režimu stačí zadat šablonu služby, např.:

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

a WDQS automaticky vygeneruje štítky následovně:

Pokud se nesvázaná proměnná v SELECT jmenuje ?NAMELabel, pak WDQS vytvoří popisek (rdfs:label) pro entitu v proměnné ?NAME.
Pokud se nesvázaná proměnná v SELECT jmenuje ?NAMEAltLabel, pak WDQS vytvoří alias (skos:altLabel) pro entitu v proměnné ?NAME.
Pokud se nesvázaná proměnná v SELECT jmenuje ?NAMEDescription, pak WDQS vytvoří popis (schema:description) entity v proměnné ?NAME.

V každém případě by měla být proměnná v ?NAME svázána, jinak služba selže.

Automatický režim pouze kontroluje projekci dotazu – například v SELECT ?aLabel (GROUP_CONCAT(?bLabel) AS ?bLabels) je rozpoznán pouze první štítek a SELECT * není automatickým režimem podporován vůbec. V takových případech budete muset použít manuální režim (viz níže).

Upřednostňovaný(é) jazyk(y) štítku určíte jedním nebo více trojicemi bd:serviceParam wikibase:language "language-code". Každý řetězec může obsahovat jeden nebo více kódů jazyků oddělených čárkami. WDQS bere v úvahu jazyky v pořadí, v jakém je zadáte. Pokud není k dispozici žádný štítek v žádném ze zadaných jazyků, je jeho štítkem Q-id entity (bez předpony).

Webová stránka Wikidata Query Service automaticky nahradí [AUTO_LANGUAGE] kódem jazyka aktuálního uživatelského rozhraní. Pokud je například uživatelské rozhraní uživatele ve francouzštině, kód SPARQL bd:serviceParam wikibase:language "[AUTO_LANGUAGE],en" bude převeden na bd :serviceParam wikibase:language "fr,en" před odesláním dotazovací službě.

Příklad, který ukazuje seznam amerických prezidentů a jejich manželů:

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

Zkus to!

V tomto příkladu WDQS automaticky vytvoří štítky ?pLabel a ?wLabel pro vlastnosti.

V manuálním režimu explicitně svážete proměnné štítku v rámci servisního volání, ale WDQS bude stále poskytovat jazykové rozlišení a záložní řešení.

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

Toto vezme v úvahu štítky a popisy ve francouzštině, němčině a angličtině, a pokud žádné nejsou k dispozici, použije se jako štítek Q-id.

Geoprostorové vyhledávání

Služba umožňuje vyhledávat položky se souřadnicemi umístěnými v určitém poloměru centrálního bodu nebo v určitém ohraničujícím rámečku.

Hledání kolem bodu

Příklad:

# 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)

Zkus to!

První řádek servisního volání around musí mít formát ?item predicate ?location, kde výsledek hledání sváže ?item s položkami v zadaném umístění a ?location s jejich souřadnicemi. Podporované parametry jsou:

Předpověď	Význam
wikibase:center	Bod, kolem kterého se provádí vyhledávání. Aby hledání fungovalo, musíte být vázáni.
wikibase:radius	Vzdálenost od centra. Aktuálně je vzdálenost vždy v kilometrech, ostatní jednotky zatím nejsou podporovány.
wikibase:globe	Země, která se hledá. Volitelné, výchozí je Earth (wd:Q2).
wikibase:distance	Proměnná přijímající informace o vzdálenosti

Hledání v boxu

Příklad vyhledávání v boxu:

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

Zkus to!

nebo:

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

Zkus to!

Souřadnice lze zadat přímo:

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

Zkus to!

První řádek servisního volání box musí mít formát ?item predicate ?location, kde a výsledek hledání naváže ?item na položky v zadaném umístění a ?location na jejich souřadnice. Podporované parametry jsou:

Předpověď	Význam
wikibase:cornerSouthWest	Jihozápadní roh boxu.
wikibase:cornerNorthEast	Severovýchodní roh boxu.
wikibase:cornerWest	Západní roh boxu.
wikibase:cornerEast	Východní roh boxu.
wikibase:globe	Země, která se hledá. Volitelné, výchozí je Earth (wd:Q2).

wikibase:cornerSouthWest a wikibase:cornerNorthEast by měly být použity společně, stejně jako wikibase:cornerWest a wikibase:cornerEast, a nelze je kombinovat. Pokud jsou použity predikáty wikibase:cornerWest a wikibase:cornerEast, pak se předpokládá, že body jsou souřadnicemi úhlopříčky kvádru a rohy jsou odvozeny podle toho.

Rozšířené funkce

Funkce vzdálenosti

Funkce geof:distance vrací vzdálenost mezi dvěma body na Zemi v kilometrech. Příklad použití:

# 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

Zkus to!

# 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

Zkus to!

Funkce součástí souřadnic

Funkce geof:globe, geof:latitude & geof:longitude vrací části souřadnic - globe URI, zeměpisnou šířku a délku.

Dekódování funkcí URL

Funkce wikibase:decodeUri dekóduje (tj. obrátí procentuální kódování) daný řetězec URI. To může být nezbytné při převodu názvů Wikipedie (které jsou kódované) na skutečné řetězce. Tato funkce je opakem funkce SPARQL encode_for_uri.

# Example usage of wikibase:decodeUri function
SELECT DISTINCT * WHERE {
  ?el wdt:P31 wd:Q5.
  ?webRaw schema:about ?el;
    schema:inLanguage "ru";
    schema:isPartOf <https://ru.wikipedia.org/>.
  BIND(URI(wikibase:decodeUri(STR(?webRaw))) AS ?webHyperlink) .
  BIND(wikibase:decodeUri(STR(?webRaw)) AS ?webString) .
}
LIMIT 20

Automatické předpony

Většina prefixů, které se používají v běžných dotazech, je podporována modulem, aniž by bylo nutné je explicitně specifikovat.

Prodloužená data

Služba podporuje hodnoty data typu xsd:dateTime v rozsahu přibližně 290 miliard let v minulosti a v budoucnosti s rozlišením jedné sekundy. WDQS ukládá data jako 64bitový počet sekund od epochy Unixu.

Rozšíření Blazegraph

Varování:

Protože Blazegraph není aktivně vyvíjen, plánuje se migrace Wikidata Query Service do jiného triplestore. Následující může být v určitém okamžiku přerušeno.

Platforma Blazegraph, na které je implementován WDQS, má vlastní sadu rozšíření SPARQL. Mezi nimi několik algoritmů pro procházení grafů, které jsou zdokumentované na Blazegraph Wiki, včetně implementací BFS, nejkratší cesty, CC a PageRank.

Nahlédněte také do Blazegraph dokumentace o nápovědách k dotazům, kde najdete informace o tom, jak řídit provádění dotazů a různé aspekty enginu.

Na wiki BlazeGraph není žádná dokumentace o rozšíření bd:sample. Je to zdokumentováno pouze v komentáři v kódu.

Federace

Umožňujeme SPARQL Federated Queries volat do vybraného počtu externích databází. Podívejte se prosím na úplný seznam federovaných koncových bodů na vyhrazené stránce.

Příklad federovaného dotazu:

Items used: Félix Lope de Vega y Carpio (Q165257)

Properties used: BVMC person ID (P2799)

SELECT ?workLabel WHERE {
  wd:Q165257 wdt:P2799 ?id 
  BIND(uri(concat("https://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        
  }
}

Zkus to!

Vezměte prosím na vědomí, že databáze, které federované koncové body obsluhují, používají ontologie, které se mohou velmi lišit od ontologie Wikidata. Podívejte se prosím na odkazy na dokumentaci vlastníka, kde se dozvíte o ontologiích a přístupu k datům do těchto databází.

API MediaWiki

Úplný popis naleznete na stránce dokumentace služby MediaWiki API.

Služba MediaWiki API umožňuje volat na MediaWiki API ze SPARQL a přijímat výsledky z dotazu SPARQL. Příklad (hledání členů kategorie):

Items used: parking lot (Q6501349)

Properties used: topic's main category (P910)

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

Zkus to!

Služba Wikimedie

Wikimedie provozuje veřejnou instanci WDQS, která je k dispozici pro použití na http://query.wikidata.org/.

Doba běhu dotazu na veřejném koncovém bodu je omezena na 60 sekund. To platí jak pro GUI, tak pro veřejný koncový bod SPARQL.

GUI

GUI na domovské stránce http://query.wikidata.org/ vám umožňuje upravovat a odesílat dotazy SPARQL do dotazovacího stroje. Výsledky se zobrazí jako HTML tabulka. Všimněte si, že každý dotaz má jedinečnou adresu URL, kterou lze uložit do záložek pro pozdější použití. Přejdete-li na tuto adresu URL, dotaz se vloží do okna úprav, ale nebude spuštěn – k tomu musíte stále kliknout na "Provést".

Krátkou adresu URL pro dotaz lze také vygenerovat pomocí služby zkracování adresy URL kliknutím na odkaz "Vygenerovat krátkou adresu URL" vpravo – tím se vytvoří zkrácená adresa URL pro aktuální dotaz.

Tlačítko "Přidat předpony" vygeneruje hlavičku obsahující standardní předpony pro dotazy SPARQL. Úplný seznam prefixů, které mohou být užitečné, je uveden v dokumentaci formátu RDF. Všimněte si, že většina běžných prefixů funguje automaticky, protože WDQS je podporuje hned po vybalení.

GUI také obsahuje jednoduchý průzkumník entit, který lze aktivovat kliknutím na symbol "🔍" vedle výsledku entity. Kliknutím na samotné Q-id entity se dostanete na stránku entity na wikidata.org.

Výchozí zobrazení

Hlavní článek: Wikidata:SPARQL dotazovací služba/Wikidata dotazovací nápověda/zobrazení výsledků

Pokud spustíte dotaz v grafickém uživatelském rozhraní WDQS GUI, můžete si vybrat, které zobrazení chcete prezentovat, zadáním značky: #defaultView:viewName na začátku dotazu.

Zobrazit název

Pokud spustíte dotaz v grafickém uživatelském rozhraní WDQS GUI, můžete nad výsledky zobrazit název zadáním značky: #title: Řetězec, který chcete zobrazit na začátku dotazu.

Koncový bod SPARQL

Dotazy SPARQL lze odesílat přímo do koncového bodu SPARQL pomocí požadavku GET nebo POST na https://query.wikidata.org/sparql.

Požadavky GET mají dotaz uvedený v URL ve formátu https://query.wikidata.org/sparql?query=(SPARQL_query), např. https://query.wikidata.org/sparql?query=SELECT%20?dob%20WHERE%20{wd:Q42%20wdt:P569%20?dob.}.

Požadavky POST mohou alternativně přijmout dotaz v těle požadavku namísto adresy URL, což umožňuje spouštění větších dotazů bez narušení limitů délky adresy URL. (Všimněte si, že tělo POST musí stále obsahovat předponu query= (to znamená, že by to mělo být query=(SPARQL_query) spíše než jen (dotaz SPARQL)) a dotaz SPARQL musí stále obsahovat kódování URL.)

Výsledek je ve výchozím nastavení vrácen jako XML nebo jako JSON, pokud je v adrese URL zahrnut buď parametr dotazu format=json, nebo je v požadavku poskytnuta hlavička Accept: application/sparql-results+json.

Formát JSON je standardní SPARQL 1.1 Query Results Formát JSON.

Pro menší dotazy se doporučuje používat GET a pro větší dotazy POST, protože dotazy POST se neukládají do mezipaměti.

Podporované formáty

Koncový bod SPARQL aktuálně podporuje následující výstupní formáty:

Formát	HTTP hlavička	Parametr dotazu	Popis
XML	Accept: application/sparql-results+xml	format=xml	Ve výchozím nastavení je vrácen formát výsledku XML. Jak je uvedeno v https://www.w3.org/TR/rdf-sparql-XMLres/
JSON	Accept: application/sparql-results+json	format=json	Formát výsledků JSON, jako na: https://www.w3.org/TR/sparql11-results-json/
TSV	Accept: text/tab-separated-values		Jak je uvedeno na https://www.w3.org/TR/sparql11-results-csv-tsv/
CSV	Accept: text/csv		Jak je uvedeno na https://www.w3.org/TR/sparql11-results-csv-tsv/
Binární RDF	Accept: application/x-binary-rdf-results-table

Limity dotazů

Je nakonfigurován pevný termín dotazu, který je nastaven na 60 sekund. Existují také následující limity:

Jeden klient (uživatelský agent + IP) má každých 60 sekund povoleno 60 sekund zpracování
Jeden klient má povoleno 30 chybových dotazů za minutu

Klienti překračující výše uvedené limity jsou omezeni kódem HTTP 429. Použijte Retry-After header, abyste viděli, kdy lze požadavek opakovat. Pokud klient ignoruje 429 odpovědí a pokračuje ve vytváření požadavků nad limity, může mu být dočasně zakázána služba. Klienti, kteří nedodržují User-Agent policy, mohou být zcela zablokováni – nezapomeňte odeslat dobrý User-Agent záhlaví.

Každý dotaz vyprší, když jeho provedení trvá déle, než je tento nakonfigurovaný termín. Možná budete chtít optimalizovat dotaz nebo nahlásit problematický dotaz zde.

Všimněte si také, že v současné době je přístup ke službě omezen na 5 paralelních dotazů na IP. Výše uvedené limity se mohou změnit v závislosti na zdrojích a způsobech používání.

Vysvětlující dotaz

Blazegraph umožňuje zobrazit analýzu dotazů, která vysvětluje, jak byl dotaz analyzován a jaké optimalizace byly použity. Chcete-li zobrazit tyto informace, přidejte do řetězce dotazu parametr explain=details, například: https://query.wikidata.org/sparql?query=SELECT%20?dob%20WHERE%20{wd:Q42%20wdt:P569%20?dob.}&explain=details.

Jmenné prostory

Data na Wikidata Query Service obsahují hlavní jmenný prostor wdq, na který jsou směrovány dotazy na hlavní koncový bod SPARQL, a další pomocné jmenné prostory, které jsou uvedeny níže. Chcete-li se dotazovat na data z jiného oboru názvů, použijte adresu URL koncového bodu https://query.wikidata.org/bigdata/namespace/NAMESPACENAME/sparql.

Kategorie

Úplný popis naleznete na stránce dokumentace kategorií.

Wikidata Query Service také poskytuje přístup ke grafu kategorií vybraných wikin. Seznam pokrytých wikin lze vidět zde: https://noc.wikimedia.org/conf/dblists/categories-rdf.dblist

Název jmenného prostoru kategorie je categories. Koncový bod SPARQL pro přístup k němu je https://query.wikidata.org/bigdata/namespace/categories/sparql.

Podrobnou dokumentaci naleznete na Stránce kategorií.

DCAT-AP

Data DCAT-AP pro Wikidata jsou dostupná jako SPARQL na https://query.wikidata.org/bigdata/namespace/dcatap/sparql koncovém bodu.

Zdroj dat je: https://dumps.wikimedia.org/wikidatawiki/entities/dcatap.rdf

Příklad dotazu pro načtení dat:

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

Koncový bod propojených datových fragmentů

Podporujeme také dotazování databáze pomocí rozhraní Triple Pattern Fragments. To umožňuje levně a efektivně procházet trojitá data, kde je známa jedna nebo dvě složky trojky a potřebujete získat všechny trojice, které odpovídají této šabloně. Viz více informací na webu Linked Data Fragments.

Rozhraní je přístupné z adresy URL: https://query.wikidata.org/bigdata/ldf. Tato služba je implementována v horní části databáze Blazegraph, takže bude mít stejné zpoždění jako Query Service. Příklady požadavků:

https://query.wikidata.org/bigdata/ldf?subject=http%3A%2F%2Fwww.wikidata.org%2Fentity%2FQ146 – všechny trojice s předmětem cat (Q146)
https://query.wikidata.org/bigdata/ldf?subject=&predicate=http%3A%2F%2Fwww.w3.org%2F2000%2F01%2Frdf-schema%23label&object=%22London%22%40en - všechny trojice, které mají anglický štítek "London"
https://query.wikidata.org/bigdata/ldf?predicate=http%3A%2F%2Fwww.wikidata.org%2Fprop%2Fdirect%2FP212&object=%22978-0-262-03293-3%22 All triples that have 978-0-262-03293-3 as the value for ISBN-13 (P212). Následující příkaz shellu používá curl k vytvoření stejné adresy URL a získání stejných dat.

$ curl \
  --get \
  -H 'Accept: application/rdf+xml' \
  --data-urlencode 'predicate=http://www.wikidata.org/prop/direct/P212' \
  --data-urlencode 'object="978-0-262-03293-3"' \
  'https://query.wikidata.org/bigdata/ldf'

Všimněte si, že pro parametry subjectect, $preddicate a objectect jsou aktuálně podporovány pouze úplné adresy URL.

Ve výchozím nastavení je zobrazeno HTML rozhraní, nicméně je k dispozici několik datových formátů definovaných HTTP hlavičkou Accept.

Dostupné datové formáty
Accept	Formát
text/html	Výchozí rozhraní pro procházení HTML
text/turtle	Formát Turtle
application/ld+json	Formát JSON-LD
application/n-triples	Formát N-Triples
application/rdf+xml	Formát RDF/XML

Data jsou vrácena ve stránkách, velikost stránky je 100 trojnásobek. Stránky jsou číslovány od 1 a číslo stránky je definováno parametrem page.

Samostatná služba

Vzhledem k tomu, že se jedná o software s otevřeným zdrojovým kódem, je také možné službu spustit na libovolném serveru uživatele pomocí níže uvedených pokynů.

Hardwarová doporučení lze nalézt v dokumentace Blazegraph.

Pokud plánujete provozovat službu na jiné instanci Wikidata, než jsou Wikidata, přečtěte si prosím další pokyny.

Instalace

Pro instalaci služby se doporučuje stáhnout si kompletní balíček služeb jako soubor ZIP, např. z Maven Central, s ID skupiny org.wikidata.query.rdf a ID artefaktu service nebo naklonujte zdrojovou distribuci na https://github.com/wikimedia/wikidata-query-rdf/ a sestavte ji s "balíčkem mvn". Balíček ZIP bude v adresáři dist/target pod service-VERSION-dist.zip.

Balíček obsahuje server Blazegraph jako aplikaci .war, knihovny potřebné ke spuštění aktualizační služby pro načítání čerstvých dat z webu wikidata, skripty pro usnadnění různých úkolů a GUI v gui. Pokud chcete používat GUI, budete muset nakonfigurovat svůj HTTP server, aby jej obsluhoval.

Ve výchozím nastavení je nakonfigurován pouze koncový bod SPARQL na http://localhost:9999/bigdata/namespace/wdq/sparql a výchozí grafické uživatelské rozhraní Blazegraph je dostupné na http://localhost:9999/bigdata/. Všimněte si, že ve výchozí konfiguraci jsou oba přístupné pouze z localhost. Chcete-li k nim přistupovat zvenčí, budete muset poskytnout externí koncové body a odpovídající řízení přístupu.

Použití verzí snímků

Pokud chcete nainstalovat nevydanou verzi snímku (obvykle je to nutné, pokud vydaná verze obsahuje chybu, která je opravena, ale nové vydání ještě není k dispozici) a nechcete kompilovat své vlastní binární soubory, můžete použít buď:

https://github.com/wikimedia/wikidata-query-deploy - repo pro nasazení obsahující produkční binární soubory. Potřebuje fungovat git fat. Podívejte se na to a proveďte "git fat pull".
Nasazení snímků archivu na https://archiva.wikimedia.org/#artifact/org.wikidata.query.rdf/service – vyberte nejnovější verzi, poté Artefakty a vyberte nejnovější balíček ke stažení.

Načítání dat

Varování:

Od roku 2020 bude na serverech Wikimedia trvat asi 12 dní, než budou importována všechna data z výpisu, a dalších 12 dní, než dotazovací služba dožene zpoždění.

Další postup instalace je podrobně popsán v dokumentu Getting Started, který je součástí distribuce a zahrnuje následující kroky:

Stáhněte si poslední výpis RDF z https://dumps.wikimedia.org/wikidatawiki/entities/ (RDF je ten, končící na .ttl.gz).
Předběžně zpracujte data pomocí skriptu munge.sh. Tím se vytvoří sada souborů TTL s předzpracovanými daty s názvy jako wikidump-000000001.ttl.gz atd. Viz možnosti pro skript níže. Viz možnosti pro skript níže.
Spusťte službu Blazegraph spuštěním skriptu runBlazegraph.sh.
Načtěte data do služby pomocí loadData.sh. Upozorňujeme, že načítání dat je obvykle výrazně pomalejší než předběžné zpracování, takže můžete začít načítat, jakmile bude připraveno několik předzpracovaných souborů. Načítání lze restartovat z libovolného souboru pomocí níže popsaných možností.
Po načtení všech dat spusťte službu Updater pomocí runUpdate.sh.

Načítání kategorií

Pokud chcete také načíst data kategorie, proveďte následující:

Vytvořte jmenný prostor, např. categories: createNamespace.sh categories
Nahrajte do něj data: forAllCategoryWikis.sh loadCategoryDump.sh categories

Všimněte si, že tyto skripty pouze načítají data z wikin Wikimedie podle nastavení Wikimedie. Pokud potřebujete pracovat s jinou wiki, možná budete muset změnit některé proměnné ve skriptech.

Skripty

Součástí distribuce jsou následující užitečné skripty:

munge.sh

Předzpracujte data z výpisu RDF pro načtení.

Volba	Povinné?	Vysvětlení
-f filename	Požadované	Název souboru výpisu RDF
-d directory	Volitelné	Adresář, kam se budou zapisovat zpracované soubory, výchozí je aktuální adresář
-l language	Volitelné	Pokud je zadáno, budou zachovány pouze štítky pro daný jazyk. Tuto možnost použijte, pokud potřebujete pouze jeden jazyk, protože může zlepšit výkon, snížit velikost databáze a zjednodušit dotazy.
-s	Volitelné	Pokud je zadáno, údaje o odkazech na podstránky jsou vyloučeny. Tuto možnost použijte, pokud se nepotřebujete dotazovat na odkazy na podstránky, protože to může zlepšit výkon a snížit velikost databáze.
-c size	Volitelné	Tuto volbu použijte k přepsání výchozí velikosti bloku. Příliš velké kusy mohou při importu vypršet.

Příklad:

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

loadData.sh

Načtěte zpracovaná data do Blazegraph. Vyžaduje instalaci curl.

Volba	Povinné?	Vysvětlení
-n namespace	Požadované	Určuje jmenný prostor grafu, do kterého jsou data načtena, což by mělo být wdq pro data WDQS
-d directory	Volitelné	Adresář, kde jsou uloženy zpracované soubory, standardně aktuální adresář
-h host	Volitelné	Název hostitele koncového bodu SPARQL, standardně localhost
-c context	Volitelné	Kontextová adresa URL koncového bodu SPARQL, ve výchozím nastavení bigdata – pro WDQS se obvykle nemusí měnit
-s start	Volitelné	Číslo zpracovaného souboru pro začátek, ve výchozím nastavení 1
-e end	Volitelné	Číslo zpracovávaného souboru, kterým má být ukončeno

Příklad:

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

runBlazegraph.sh

Spusťte službu Blazegraph.

Volba	Povinné?	Vysvětlení
-d directory	Volitelné	Domovský adresář instalace Blazegraph, standardně stejný adresář, kde je skript
-c context	Volitelné	Kontextová adresa URL koncového bodu SPARQL, ve výchozím nastavení bigdata – pro WDQS se obvykle nemusí měnit
-p port	Volitelné	Číslo portu služby SPARQL, standardně 9999
-o options	Volitelné	Přidejte možnosti do příkazového řádku

Příklad:

./runBlazegraph.sh

Uvnitř skriptu jsou dvě proměnné, které můžete upravit:

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

Skript také kontroluje následující proměnné prostředí (všechny jsou volitelné):

Proměnná	Výchozí	Vysvětlení
HOST	localhost	Název hostitele pro vazbu služby Blazegraph
PORT	9999	Port pro vazbu služby Blazegraph
DIR	adresář, kde je skript umístěn	Adresář, kde jsou uloženy konfigurační soubory
HEAP_SIZE	16g	Velikost shluku Java pro Blazegraph
MEMORY	`-Xms${HEAP_SIZE} -Xmx${HEAP_SIZE}`	Úplné nastavení paměti Java pro Blazegraph
GC_LOGS	viz zdroj	Nastavení protokolování GC
CONFIG_FILE	RWStore.properties	Umístění konfiguračního souboru Blazegraph
BLAZEGRAPH_OPTS	prázdné	Další volby jsou předány tak, jak jsou, do příkazového řádku Java

runUpdate.sh

Spusťte službu Updater.

Volba	Povinné?	Vysvětlení
-n namespace	Volitelné	Určuje jmenný prostor grafu, do kterého se data načítají, pro data WDQS by měl být wdq. Výchozí: wdq
-h host	Volitelné	Název hostitele koncového bodu SPARQL, standardně localhost
-c context	Volitelné	Kontextová adresa URL koncového bodu SPARQL, ve výchozím nastavení bigdata – pro WDQS se obvykle nemusí měnit
-l language	Volitelné	Pokud je zadáno, budou zachovány pouze štítky pro daný jazyk. Tuto možnost použijte, pokud potřebujete pouze jeden jazyk, protože může zlepšit výkon, snížit velikost databáze a zjednodušit dotazy.
-s	Volitelné	Pokud je zadáno, údaje o odkazech na podstránky jsou vyloučeny. Použijte tuto možnost, nemusíte se dotazovat na odkazy na podstránky, protože to může zlepšit výkon a snížit velikost databáze.
-t secs	Volitelné	Časový limit při komunikaci s Blazegraph v sekundách.
-N	Volitelné	Tato možnost způsobí, že skript bude ignorovat možnosti, které mohou způsobit problémy při spuštění druhého nástroje Updater, zatímco první již běží. Použijte jej při spuštění sekundárního Updateru, např. chcete-li dohnat konkrétní položku pomocí `--ids` (viz níže).
-S	Volitelné	Přihlaste se do konzoly místo souborů protokolu. Užitečné při spouštění skriptu z příkazového řádku pro úlohy údržby.

Doporučuje se, aby nastavení voleb -l a -s (nebo jejich absence) bylo stejné pro munge.sh a runUpdate.sh, jinak nemusí být data řádně aktualizovány.

Příklad:

./runUpdate.sh

Skript také kontroluje následující proměnné prostředí (všechny jsou volitelné):

Proměnná	Výchozí	Vysvětlení
UPDATER_OPTS	prázdné	Další volby jsou předány tak, jak jsou, do příkazového řádku Java

Možnosti aktualizace

Následující možnosti fungují s aplikací Updater.

Měly by být poskytnuty skriptu runUpdate.sh jako další možnosti po --, např.: runUpdate.sh -- -v.

Možnosti pro Updater
Volba	Dlouhá možnost	Význam
-v	--verbose	Podrobný režim
-s TIMESTAMP	--start TIMESTAMP	Začněte shromažďovat data od určitého časového razítka ve formátu `2015-02-11T17:11:08Z` nebo `20150211170100`.
	--keepTypes	Udržujte všechny typy prohlášení
	--ids ID1,ID2,...	Aktualizujte určitá ID a ukončete
	--idrange ID1-ID2	Aktualizujte rozsah ID a ukončete
-d SECONDS	--pollDelay SECONDS	Jak dlouho spát, když nejsou k dispozici žádná nová data
-t NUMBER	--threadCount NUMBER	Kolik vláken použít při načítání dat Wikibase
-b NUMBER	--batchSize NUMBER	Kolik změn se má načíst z API RecentChanges
-V	--verify	Po načtení ověřte data (POMALU! Pouze pro ladění)
-T SECONDS	--tailPollerOffset SECONDS	Použijte sekundární koncový poller s daným offsetem za hlavním
	--entityNamespaces NUMBER,NUMBER,...	Seznam jmenných prostorů Wikibase ke kontrole změn
-W	--wikibaseUrl URL	Adresa URL, která se použije při komunikaci s Wikibase. Např. `https://www.wikidata.org`. Musí být nastaveno, pokud aktualizace nepocházejí z Wikidat.
-U	--conceptUri URL	Základ URL adres URL používaných k reprezentaci entit Wikibase v RDF. Např. `http://www.wikidata.org`. Musí být nastaveno, pokud instance Wikibase nepoužívá předpony založené na Wikidatech.
	--commonsUri URL	Commons URI pro podporu SDC. Aby to fungovalo, je třeba nastavit `--conceptUri` i `--commonsUri`.
	--wikibaseScheme SCHEME	Schéma URL (http, https), které se použije při komunikaci s Wikibase. (zastaralé) Místo toho použijte wikibaseUrl výše.
	--wikibaseHost HOSTNAME	Název hostitele, který se má použít při komunikaci s Wikibase. (zastaralé) Místo toho použijte wikibaseUrl výše.
-I	--init	Je-li zadán společně s časem zahájení, je tento čas v databázi označen jako čas poslední změny a budoucí požadavky jej budou používat jako výchozí bod, i když nebudou nalezena žádná novější data.
	--constraints	Načtěte porušení omezení pro aktualizované položky prostřednictvím `constraintsrdf` API.
-K SERVERS	--kafka SERVERS	Pokud je to zadáno, Updater použije Kafka jako zdroj aktualizací a zadané servery jako zprostředkovatele. Např. `kafka1001.eqiad.wmnet:9092,kafka1002.eqiad.wmnet:9092,kafka1003.eqiad.wmnet:9092`
-C NAME	--consumer NAME	Spotřebitelské jméno Kafka. Je dobré jej nastavit na název hostitele nebo něco na něm založeného.
-c NAME1,NAME2	--cluster NAME1,NAME2	Názvy klastrů Kafka. Pokud je zadáno, před názvy témat Kafka budou uvedeny názvy clusterů, takže místo `topic1` by zde byly `NAME1.topic1` a `NAME2.topic2`.
	--resetKafka	Resetujte Kafkovy offsety
	--apiPath	Cesta k API, např. `/w/api.php` (výchozí) nebo `/api.php`. (zavedeno od I78c222fe8b)
	--entityDataPath	Cesta k entitám, např. `/wiki/Special:EntityData/` (výchozí) nebo `/Special:EntityData/`. (zavedeno od I78c222fe8b)

Konfigurovatelné vlastnosti

Následující vlastnosti lze konfigurovat jejich přidáním do příkazu spuštění skriptu ve skriptech výše:

Název	Význam	Výchozí
wikibaseServiceWhitelist	Název souboru whitelistu vzdálené služby. Platí pro Blazegraph.	whitelist.txt
org.wikidata.query.rdf.blazegraph.mwapi.MWApiServiceFactory.config	Konfigurační soubor pro integraci MWAPI	mwservices.json
com.bigdata.rdf.sail.sparql.PrefixDeclProcessor.additionalDeclsFile	Název souboru, který obsahuje další definice předpon. Syntaxe je stejná jako v dotazu SPARQL. Tyto definice načte Blazegraph a budou dostupné pro všechny dotazy.
wikibaseConceptUri	Předpona URL pro data Wikibase, která se používá v RDF reprezentaci entit. Je třeba nastavit, pokud datová sada nepoužívá předpony Wikidata.	http://www.wikidata.org
commonsConceptUri	Předpona URL pro podporu Structured Data on Commons. Aby to fungovalo, je třeba nastavit `wikibaseConceptUri` i `commonsConceptUri`.
wikibaseHost	Název hostitele instance wikibase. Platí pro Blazegraph i Updater. (zastaralé) Použijte výše uvedený wikibaseConceptUri.	www.wikidata.org
org.wikidata.query.rdf.blazegraph.inline.literal.WKTSerializer.noGlobe	Výchozí hodnota země pro souřadnice, které nemají zemi. "2" by znamenalo, že entita Q2 je výchozí země. "0" znamená, že neexistuje výchozí země. Platí pro Blazegraph.	0
org.wikidata.query.rdf.tool.rdf.RdfRepository.timeout	Časový limit při komunikaci s úložištěm RDF v sekundách. Platí pro Updater.	-1
org.wikidata.query.rdf.tool.wikibase.WikibaseRepository.timeout	Časový limit při komunikaci s úložištěm wikibase v milisekundách. Platí pro Updater.	5000
http.userAgent	Uživatelský agent, kterého by služba používala při volání jiných služeb
http.proxyHost http.proxyPort https.proxyHost https.proxyPort	Nastavení proxy používané při volání jiných služeb
wikibaseMaxDaysBack	Před kolika dny si můžeme z Updateru vyžádat údaje o posledních změnách. Pokud je databáze o více než tento počet dní starší, měla by být znovu načtena z novějšího výpisu.	30

Chybějící funkce

Níže jsou uvedeny funkce, které aktuálně nejsou podporovány:

Přesměrování jsou reprezentována pouze jako owl:sameAs triple, ale nevyjadřují žádnou ekvivalenci v datech a nemají žádnou zvláštní podporu.

Kontakty

Pokud si všimnete něčeho špatného se službou, můžete kontaktovat Discovery tým e-mailem na seznamu [email protected] nebo na IRC kanálu #wikimedia-discovery.

Chyby lze také odeslat Phabricator a sledovat na nástěnce Discovery Phabricator.

Související odkazy