# SPARQL/Expressions and Functions
### Expressions
##### BIND

The BIND( expression AS ?variable ). clause can be used to assign the result of an expression to a variable (usually a new variable, but you can also overwrite existing ones).
Try it!
BIND can also be used to simply bind constant values to variables in order to increase readability. For example, a query that finds all female priests:
Try it!
The above gives the same result as
Try it!

##### IF

The IF( condition, thenExpression, elseExpression ) expressions are used to assign different values based on a condition.
For instance to calculate the age, precisely to the day. In the expression BIND( .... - (IF( condition,1,0 ) AS ?age) the condition determines to subtract 1 or 0 (nothing) from the ?age based on the month and the day of the birth and the death.
Try it!
Here an example to divide population in groups. The ?layer in the #defaultView:Map shows it in different colors.
Try it!

##### Operators

The familiar mathematical operators are available: +, -, *, / to add, subtract, multiply or divide numbers.
The operators <, >, =, <=, >= are available to compare values. Comparison is also defined for other types; for example, "abc" < "abd" is true (lexical comparison), as is "2016-01-01"^^xsd:dateTime > "2015-12-31"^^xsd:dateTime and wd:Q4653 != wd:Q283111. The inequality test ≠ is written !=. The ! can also be used as a prefix to functions that results a boolean like !BOUND and !REGEX.
Boolean conditions can be combined with && (logical and: a && b is true if both a and b are true) and || (logical or: a || b is true if either (or both) of a and b is true).
Examples IF( ?a != ?b, ... , ... ) and IF( ?a = ?b && ?c = ?d, ... , ... ).

##### VALUES

The VALUES ?var { val1 ... } clause generates a variable with one or more values. The values can be of any type, like numeric, strings, or even items, like VALUES ?number { 1 2 3 }, VALUES ?abc { "a" "b" "c" } or VALUES ?city { wd:Q84 wd:Q90 }.
Try it!
Values can have more dimensions too. The dimensions are grouped by ( ) like VALUES ( ?varA ?varB ... ) { ( valA1 valB1 ... ) ... }.
Try it!

### Functions
#### General functions
##### DATATYPE

    See also: d:Special:ListDatatypes
Each value in SPARQL has a type, which tells you what kind of value it is and what you can do with it. The most important types are:
* item, like wd:Q42 for Douglas Adams (Q42).
* boolean, with the two possible values true and false. Boolean values aren’t stored in statements, but many expressions return a boolean value, e. g. 2 < 3 (true) or "a" = "b" (false).
* string, a piece of text. String literals are written in double quotes.
* monolingual text, a string with a language tag attached. In a literal, you can add the language tag after the string with an @ sign, e. g. "Douglas Adams"@en.
* numbers, either integers (1) or decimals (1.23).
* dates. Date literals can be written by adding ^^xsd:dateTime (case sensitive – ^^xsd:datetime won’t work!) to an ISO 8601 date string: "2012-10-29"^^xsd:dateTime.
Try it!
Some datatypes are rdf:langString, xsd:string, xsd:integer, xsd:dateTime, xsd:decimal or "<http://www.opengis.net/ont/geosparql#wktLiteral>".

##### STR

The STR( value ) function converts values to a string. It also resolves prefixes, for instance wd:Q1339 will be converted into http://www.wikidata.org/entity/Q1339. The reversal of this is the IRI( string ), which will convert a string to an IRI.
Try it!

##### IRI

the IRI( string ), which will convert a string to an IRI, by applying the prefixes.
In the example below a Predicate like wdt:P569 get converted to a string http://www.wikidata.org/prop/direct/P569. To get a Label for the predicate it first needs to be replaced to get an entity (http://www.wikidata.org/entity/P569), which with IRI gets converted to wd:P569. The label of this can then be displayed as "date of birth (P569)".
Try it!

##### LANG

The LANG( string ) function retrieves the language tag of Labels, Descriptions, Aliases and of Monolingual texts.
Try it!

##### BOUND

The function BOUND( variable ) returns true if variable is bound to a value. It returns false otherwise. The BOUND expression is used often with IF(condition,thenExpression,elseExpression) expressions. For example, suppose you have a query that shows some humans, and instead of just showing their label, you’d like to display their pseudonym (P742) if they have one, and only use the label if a pseudonym doesn’t exist. For this, you select the pseudonym in an OPTIONAL clause (it has to be optional – you don’t want to throw out results that don’t have a pseudonym), and then use BIND(IF(BOUND(… to select either the pseudonym or the label.
Try it!

##### IN and NOT IN

The function value IN( list of values ) checks if a value is found in a list of values. For example 2 IN( 1, 2, 3 ) is true. A similar function value NOT IN( list of values ) checks if a value is not found in a list of values.
Try it!

##### isBLANK

The isBLANK( variable ) expression checks if a value is an "unknown value".
Try it!
Wikidata value can also have special value "no value". With normal triples this simply results in the absence of a result.
Try it!
The prefix wdno: selects the "no value" node. The code a is a special word.

#### Functions on strings
##### STRLEN

The function STRLEN( string ) returns the length of a string. For instance STRLEN(?name) where ?name is "ABC" will return 3.

##### SUBSTR

The function SUBSTR( string, beginposition, stringlength ) returns a substring of a string beginning at the position marked by beginposition, and will have a length as indicated. For instance SUBSTR( ?name,2,3 ) where ?name = "ABCDEFGH" will return "BCD". A substring without length like SUBSTR( ?name,2 ) will return "BCDEFGH".

##### UCASE

The function UCASE( string ) returns the string in Upper case. For instance a string "Abc" will be returned as "ABC".

##### LCASE

The function LCASE( string ) returns the string in Lower case. For instance a string "Abc" will be returned as "abc".

##### STRSTARTS

The function STRSTARTS( string, comparestring ) checks if the string starts with the compare string. For instance STRSTARTS( "ABCDEFGH", "ABC" ) returns true, indicating that the string starts with "ABC".

##### STRENDS

The function STRENDS( string, comparestring ) checks if the string ends with the compare string. For instance STRENDS( "ABCDEFGH", "FGH" ) returns true, indicating that the string ends with "FGH".

##### CONTAINS

The function CONTAINS( string, comparestring ) checks if the string contains the compare string. For instance CONTAINS( "ABCDEFGH", "DEF" ) returns true, indicating that the string contains "DEF".

##### STRBEFORE

The function STRBEFORE( string, comparestring ) returns the part of the string before the compare string. For instance STRBEFORE( "ABCDEFGH", "DEF" ) returns "ABC". If the compare string is not found it returns "".

##### STRAFTER

The function STRAFTER( string, comparestring ) returns the part of the string after the compare string. For instance STRAFTER( "ABCDEFGH", "DEF" ) returns "GH". If the compare string is not found, it returns "".

##### ENCODE_FOR_URI

The function ENCODE_FOR_URI( string ) converts the special characters in the string, to be able to use it in an web URL. For instance ENCODE_FOR_URI( "ABC DËFGH" ) returns "ABC%20D%C3%8BFGH". The reverse of this function is wikibase:decodeUri( string ).

##### CONCAT

The function CONCAT( string1, string2 ... ) returns the concatenation of 2 or more strings. For instance CONCAT( "ABCDEFGH", "XYZ" ) returns "ABCDEFGHXYZ".

##### LANGMATCHES

The function LANGMATCHES( languagetag, languagerange ) checks if the language tag matches the language range. For example this code FILTER LANGMATCHES( LANG(?label), "fr" ). filters labels in the french language. It is similar to FILTER (LANG(?label) = "fr"). with the difference that the LANGMATCHES filter will also output language tags with regions, e.g. "fr-BE" while (FILTER (LANG(?label) = "fr"). will only output the strings with the exact tag "fr". A language range of "*" matches any non-empty language-tag string.

##### REGEX

The function REGEX( string, pattern, flag ) checks if the string matches the pattern. It is mostly used in a FILTER clause like FILTER REGEX( string, pattern )..
The pattern may contain different special characters. Blazegraph instances such as the Wikidata Query Service interpret the pattern as a Java Pattern, which is a subset of ICU regular expressions. The table below lists the most common special characters:
| Special characters | Meaning |
| (a|b) | a or b |
| [abc] | Range (a or b or c) |
| [^abc] | Not (a or b or c) |
| [a-q] | Lower case letter from a to q |
| [A-Q] | Upper case letter from A to Q |
| [0-7] | Digit from 0 to 7 |
| . | Wildcard: Matches any single character except \n. |
| Special characters | Meaning |
| * | 0 or more |
| + | 1 or more |
| ? | 0 or 1 |
| {3} | Exactly 3 |
| {3,} | 3 or more |
| {3,5} | 3, 4 or 5 |
| (pattern) | Matches pattern and saves the match |
| \1 | Retrieves the saved match |
| (?:pattern) | Matches pattern but does not save the match |
| Special characters | Meaning |
| ^ | Start of string, or start of line in multi-line pattern |
| \A | Start of string |
| \b \B | Word boundary / Not word boundary |
| \d \D | Digits [0-9] / Nondigit characters [^0-9] |
| \p{ name } | Matches any single character in the Unicode general category or named block specified by name |
| \w \W | The characters [A-Za-z0-9_] / None of the characters [A-Za-z0-9_] |
| \< | Start of word |
| \> | End of word |
| $ | End of string, or end of line in multi-line pattern |
| \Z | End of string |
The flag is optional. Flag "i" means the match is case-insensitive.
Try it!
Examples
* title might be a rhyme FILTER(REGEX(?title, "^\\w*(\\w{3})(\\W+\\w*\\1)+$", "i") && !REGEX(?title, "^(\\w+)(\\W+\\1)+$", "i")).
* title is an alliteration FILTER(REGEX(STR(?title), "^(\\p{L})\\w+(?:\\W+\\1\\w+){2,}$", "i")).
PS: A single \ is used as an escape symbol in strings, so \\ is used to indicate a single \.

##### REPLACE

The function REPLACE( string, pattern, replacement, flag ) returns the string after replacing all occurrences of pattern in string with replacement. pattern is interpreted the same way as in REGEX. The replacement can contain $n or ${name}, which are replaced by the corresponding numbered or named capture group in the pattern. An optional flag affects the regular expression pattern, just as with the flag argument to REGEX. For example, REPLACE( "ABCDEFGH", "DEF", "_def_" ) returns "ABC_def_GH". REPLACE( "ABCDEFGH", "[AEIOU]", "" ) removes all the vowels from the original string.

#### Functions on numbers
##### ABS

The function ABS( number ) returns the absolute value of a number. For instance, ABS( -1 ) returns 1.

##### ROUND

The function ROUND( number ) returns the rounded value of a number. For instance, ROUND( 1.4 ) returns 1, while ROUND( 1.6 ) returns 2.

##### CEIL

The function CEIL( number ) returns the largest number (round up). For instance, both CEIL( 1.4 ) and CEIL( 1.6 ) return 2.

##### FLOOR

The function FLOOR( number ) returns the smallest number (round down). For instance, both FLOOR( 1.4 ) and FLOOR( 1.6 ) return 1.

##### RAND

The function RAND( ) returns a random value between 0 and 1. For instance, RAND( ) returns 0.7156405780739334.

##### COUNT, MIN, MAX, AVG and SUM

The functions COUNT, MIN, MAX, AVG, and SUM can only be used as Aggregate functions.
Try it!
For instance, BIND( MAX( ?var1, ?var2 ) AS ?max) does NOT work. Instead, use the expression BIND( IF( ?var1>?var2, ?var1, ?var2 ) AS ?max).

#### Functions on dates and times
##### NOW

The function NOW( ) returns the current date and time.
With constructions like NOW + "P1D"^^xsd:duration it is possible to add or subtract days from the current date. NOW + "P1M"^^xsd:duration will add 1 month. NOW + "P1Y"^^xsd:duration will add 1 year. You can add or subtract any combination of years, months, days and even hours, minutes and seconds using "P1Y1M1DT0H0M0.000S"^^xsd:duration.

##### YEAR, MONTH and DAY

The function YEAR( datevalue ) returns the year of the date value. The functions MONTH and DAY return the month or day.

##### HOURS, MINUTES and SECONDS

The function HOURS( datevalue ) returns the hour of the date value. The functions MINUTES and SECONDS returns the minutes or seconds. Currently Wikidata does not hold date values in hour, minutes or seconds.

##### TIMEZONE and TZ

The function TIMEZONE( datevalue ) returns the time zone of the date value. Currently in Wikidata all dates have a TIMEZONE of "PT0S" for UTC. Other valid values would be between -PT14H and PT14H indicating the time offset in hours.
The function TZ( datevalue ) returns the time zone as a simple literal of the date value. Currently in Wikidata all dates have a TZ of "Z" for UTC.
Example with dates
Try it!

#### Functions on coordinates
##### geof:distance

The function geof:distance returns distance between two points, in kilometers.
Example usage:
Try it!

##### geof:longitude and geof:latitude

The functions geof:longitude and geof:latitude convert a well-known text literal (<http://www.opengis.net/ont/geosparql#wktLiteral>) of a Point geometry to its longitude and latitude, respectively.
Example usage:
Try it!

##### wikibase:geoLongitude and wikibase:geoLatitude

It is also possible to retrieve the longitude and latitude of a coordinate node using wikibase:geoLongitude and wikibase:geoLatitude qualifiers. See here for an explanation.
Try it!

##### AUTO_COORDINATES

The code BIND("[AUTO_COORDINATES]" as ?loc) returns the current location, if you allow your browser to use it.
Try it!

### Aggregate functions

See Aggregate functions for COUNT, MIN, MAX, SUM, AVG, SAMPLE and GROUP_CONCAT

### References

* 1 2 The Wikidata Query Service uses a Wikimedia fork of Blazegraph that depends on OpenJDK 8. Other instances may run different versions of Java with different levels of Unicode support.
* ↑ QLever uses the \n syntax instead, which you need to escape as \\n inside a string literal.
* W3.org sparql11-query