Basic SPARQL query

Films in the Star Wars Series

Here is your first SPARQL query. This simple query displays the films that are part of the Star Wars series.

#Star Wars Films
SELECT ?item  
WHERE 
{
  ?item wdt:P179 wd:Q22092344.
}

WDQS color coding

WDQS color codes certain SPARQL words, which helps to understand and to explain the SPARQL code:

  • Grey: the first line of the query has a hashtag (#) followed by a grey text. This indicates a comment – something we write that does not affect the query itself. Everything after a ‘#’ is a comment and ignored by WDQS, except certain patterns, which we will see in other sections.
  • Red: the words SELECT and WHERE on lines 2 and 3 are shown in capital red letters. This is reserved for SPARQL syntax words, a kind of “command”:
    • SELECT – here we state the names of the variables that will be returned and displayed by the query.
    • WHERE – here we provide the pattern to match with the data, i.e., define the conditions for finding the values for the variables in the SELECT clause, often in the forms of triples that reflect the Item-Property-Value structure of the database.
  • Green: on lines 2 and 5, “?item” appears in green. In SPARQL, variable names are preceded by a question mark and indicated in green. Almost any string can be a variable name (except reserved words), such as ?film, ?x, or ?any_variable_name. Variables hold values for future use.
  • Blue: on line 5, we see some terms shown in blue. These indicate prefixes. Prefixes are shortcut abbreviations, allowing queries to be presented in a more compact and transparent manner. Without the prefixes we would need to specify the full URL for each element of the query.
    • wdt: a prefix for Wikidata properties + the property (P) number.
      Without the prefix we would need to refer to this property as: http://www.wikidata.org/prop/direct/>:P179
      
    • wd: a prefix for Wikidata items + the Q-ID of the value.
      Without the prefix we would need to precede the Q-ID by <http://www.wikidata.org/entity/>:Q22092344

Query explanation

Now we turn to look at how the query works.

A SPARQL query is usually composed of two or more clauses, which are parts of the query which have different functions. Our basic SPARQL query has two clauses:

The SELECT clause

The SELECT clause lists variables that you want returned – in this case the variable ?item. Essentially this line says “We’re going to find some values to store in ?item, and then we’re going to display those values.”

The WHERE clause

The WHERE clause specifies the conditions for the variables, mostly in the form of triples. SPARQL works on the logic of pattern matching. The SPARQL processor matches patterns you declare within the WHERE clause against the three-part statements stored on Wikidata. The WHERE clause tells the processor which property values to fill into the variables you are SELECTing and how to pull the data out.

This basic query pattern of SPARQL reflects the Item-Property-Value structure of the linked data database. The pattern for matching in our simple query is given as a statement:
?item – has property:part of a series – with value:Star Wars (film series)

In other words, this query selects Wikidata items that: (1) have a property:part of a series (P179), and (2) that property has as value “Star Wars (film series)”  (Q22092344).
Note that if you hover with your cursor over the prefix or its associated element, the WDQS interface will show the label and description of that property or item.

Press the “Play” button to run the query. Scroll within the frame to see the results.

The query retrieves the Q number of each of the films in the Star Wars series, but not the title of the film.
In the next part you will learn how to retrieve the names of the films as well.

Adding labels

Label service

Items on Wikidata are identified by a unique Q number. Every item also has a label, which is the main name given to it in a particular language. The following query retrieves the films of the Star Wars series and their label.

#Star Wars films

SELECT ?item  ?itemLabel 
WHERE 
{ 
  ?item wdt:P179 wd:Q22092344.
SERVICE wikibase:label { bd:serviceParam wikibase:language "[AUTO_LANGUAGE]". }
}

Query explanation

In the SELECT clause, two variables are stated: ?item and ?itemLabel.
Label is a special string: it refers to the label of the item that is specified by the variable name. If we named our variable ?x, the variable for the label would be ?xLabel, if we named it ?film, the variable for the label would be ?filmLabel, and so on.

In the WHERE clause we see the same pattern for selection as before:
?item wdt:P179 wd:Q22092344.
In addition, we see in red the SERVICE command followed by the text (in blue):
wikibase:label { bd:serviceParam wikibase:language “[AUTO_LANGUAGE]”.

This code snippet is a kind of shortcut to a service which retrieves labels of items. In other words, if a variable in SELECT is named ?NAMELabel, WDQS retrieves the label for the item in variable ?NAME. This specialized service is very helpful, as it reduces the complexity of SPARQL queries that would otherwise be needed to achieve the same effect.

What is the AUTO_LANGUAGE?

The default language for WDQS is English, as indicated on the upper right hand corner. This affects both the language of the WDQS interface, as well as the label retrieved for items.

Run the query. Then change the auto language and run the query again.

Specifying label language

Choosing one or more Label language

Another way to specify the retrieved label language is to state it in the SERVICE code snippet instead of the “AUTO LANGUAGE”.

For example, in the following query, Dutch (nl) labels will be retrieved and presented:

#Star Wars films

SELECT ?item  ?itemLabel 
WHERE 
{ 
  ?item wdt:P179 wd:Q22092344.
  SERVICE wikibase:label { bd:serviceParam wikibase:language "nl". }
}

One can specify several languages and the order in which labels are retrieved. For example, the following query first retrieves the French (fr) label, but if there is no label in French then the German (de) label will be retrieved, and if that one is missing the Italian (it) label will be shown, and so on.

#Star Wars films

SELECT ?item  ?itemLabel 
WHERE 
{ 
  ?item wdt:P179 wd:Q22092344.
SERVICE wikibase:label { bd:serviceParam wikibase:language "fr,de,it,es,no,pt". }
}


Autocompletion

WDQS built-in search function

The code snippet for the Wikidata Label Service is not easy to remember. Fortunately, WDQS offers a great solution to this: autocompletion. In the WDQS window, whenever you press Ctrl+Space (or Alt+Enter) at any point in the query, a drop-down menu will offer suggestions for code that might be appropriate; select the right suggestion with the up/down arrow keys, and press Enter to select it.

For example, instead of writing out 

SERVICE wikibase:label { bd:serviceParam wikibase:language “[AUTO_LANGUAGE]”.}

you can just type SERV, hit Ctrl+Space, and the first suggestion will be that complete label service code. Just hit Enter to accept it. You may want to change the code to retrieve labels in specific languages.

Autocompletion can also search for Q numbers for items or P numbers for properties. If you type one of the Wikidata prefixes, like wd: (for items) or wdt: (for properties) and write text afterwards, Ctrl+Space will search for that text on Wikidata and suggest results for items and properties. 

Adding description

Retrieving an item’s description

As was previously explained in the introduction to Wikidata, each item on Wikidata has a unique Q number. Items also have a label in one or more languages. In addition, an item may also have a description – a short phrase in a particular language. Because item labels are not necessarily unique, the description on a Wikidata item is designed to disambiguate items with the same or similar labels. A description does not need to be unique either; however no two items can have both the same label and the same description.

In WDQS, the string “Description”, like the string “Label”, is a special reserved string for retrieving the description of the item that is specified by the variable name. In other words, if a variable in the SELECT clause is named ?NAMEDescription, then WDQS produces the description for the item in variable ?NAME.

The following query retrieves the films of the Star Wars series, their label and their description.


Exercise: simple query

| Exercise: list the items, including label and description, that are part of the Harry Potter film series (Q216930)

Write your SPARQL query in the window below using SELECT, and WHERE.

Press the “Play” button to run your query.

Show solution

Your solution may not look exactly like ours. You may have used different variable names or chosen a different label language. These small differences are okay; it’s the results that matter.

Press the “Play” button to run the query.

Retrieving a statement value

Queries retrieving a statement value 

As noted in the introduction, Wikidata stores information in the form of statements that have an Item-Property-Value structure.

In our first example, our query returns Wikidata items that match our query pattern: they match a specific combination of Property and Value, namely, they have a P179 property (part of a series) with a value of Q22092344 (Star Wars film series). In other words, the variable with the name “item” collects those Wikidata items that have a statement which matches the pattern:

?item – has property:part of a series – with value:Star Wars (film series)

In this case, the item part of a matching statement is retrieved. But queries do not necessarily have to return the first part (Item) of statements.

In the following query the ?actor variable collects values of the property cast member (P161) of the item Star Wars Episode IV: A New Hope (Q17738). That is to say, the variable collects the third part (the object) of the statements:

Two or more match patterns

Adding match patterns

Until now our queries had only one pattern matching condition. For example, they selected items that have a P179 property (part of a series) with a value of Q22092344 (Star Wars film series). In the following query, there are two pattern matching conditions:

The query retrieves four items. These are items that satisfy both conditions. In other words, the patterns have an AND relation between them:
?item wdt:P179 wd:Q22092344.
AND
?item wdt:P57 Q38222.

# A little bit of syntax

Another way of formulating the above query, using a semicolon to join the two statements:

#Star Wars films

SELECT ?item  ?itemLabel
WHERE 
{ 
  ?item wdt:P179 wd:Q22092344; 	# item is part of the series Star Wars (film series)
  	   	wdt:P57 wd:Q38222. 		# item has director property with value George Lucas.
  SERVICE wikibase:label { bd:serviceParam wikibase:language "[AUTO_LANGUAGE]". }
}

Because there is a semicolon on line 6, which joins the two patterns to match, the ?item variable is omitted on line 7.

UNION operator

Pattern matching with an OR relationship

In the previous section we saw that if there are two pattern matching conditions, they have an AND relation – the query will return only those items that match both patterns. If we want to have an OR relation between the conditions, we use the UNION operator. The following query retrieves items that are either part of the Star Wars film series or part of the Star Trek film series.

Skip to content