Liking cljdoc? Tell your friends :D

Expressions

Reference: 17. Expressions and Testing Values

SPARQL supports expressions, which can be used to compute values and filter query results. In particular, expressions can be used in the following circumstances:

  • As part of a :filter clause.
  • As part of a :bind clause, in an [expr var] form.
  • As part of a :group-by clause, either as a freestanding expression or in an [expr var] form.
  • To aggregate or compute values in a :select, :order-by or :having clause.

In Flint, an expression is either a list of the form (op expr...), similar to Clojure functions, or either a variable or literal terminal.

With certain exceptions, like exists and not-exists, expressions only accept other expressions as arguments.

The following is an example of an expression in Flint:

(if (< ?x ?y) (str ?x) (* 2 (+ 3 4)))

which is translated into SPARQL as:

IF((?x < ?y), STR(?x), (2 * (3 + 4)))

NOTE: Due to the complexity of SPARQL type semantics, Flint does not make any attempt to typecheck or validate expression arguments or return values. However, Flint does restrict the use of certain expressions (namely aggregators) to particular clauses, as explained later.

Boolean and Arithmetic Expressions

SPARQL supports boolean and arithmetic operations, with accept one or more expressions and return boolean or numeric values. Like all expressions, boolean and arithmetic ops are written in Clojure's prefix order in Flint, but are translated to SPARQL's infix order. (The exceptions are the unary not operator, as well as SPARQL's unary + and -, which are not supported in Flint.)

The in and not-in operations are special boolean operations that are equivalent to (or (= expr expr1) (= expr expr2) ...) and (and (not= expr expr1) (not= expr expr2) ...), respectively.

FlintSPARQL FormArglistReference
not!(expr)[expr]
or(expr \|\| expr)[expr & exprs]17.4.1.5
and(expr && expr)[expr & exprs]17.4.1.6
=(expr = expr)[expr expr]17.4.1.7
not=(expr != expr)[expr expr]
<(expr < expr)[expr expr]
>(expr > expr)[expr expr]
<=(expr <= expr)[expr expr]
?=(expr >= expr)[expr expr]
+(expr + expr + ...)[expr & exprs]
-(expr - expr - ...)[expr & exprs]
*(expr * expr * ...)[expr & exprs]
/(expr / expr / ...)[expr & exprs]
in(expr IN (expr, ...))[expr & exprs]17.4.1.9
not-in(expr NOT IN (expr, ...))[expr & exprs]17.4.1.10

Built-in Function Expressions

SPARQL accepts a number of built-in functions, which are translated from Flint's (fname expr expr ...) form to SPARQL's FNAME(expr, expr, ...) form. This section contains a list of all non-aggregate built-in expressions, grouped together by argument and return types.

FlintSPARQLArglistReference
ifIF[expr expr expr]17.4.1.2
coalesceCOALESCE[& expr]17.4.1.3
datatypeDATATYPE[expr]17.4.2.7

Graph Patterns

Unlike most expressions, exists and not-exists only accept graph patterns as arguments. The following example:

[:filter (exists [[?person :foaf/name ?name]])]

becomes:

FILTER EXISTS {
    ?person foaf:name ?name .
}
FlintSPARQLArglistReference
existsEXISTS[graph-pattern]17.4.1.4
not-existsNOT EXISTS[graph-pattern]17.4.1.4

URIs and IRIs

FlintSPARQL nameArglistReference
iriIRI[expr]17.4.2.8
uriURI[expr]17.4.2.8

Blank Nodes

FlintSPARQLArglistReference
bnodeBNODE[] or [expr]17.4.2.9

UUIDs

FlintSPARQLArglistReference
uuidUUID[]17.4.2.12
struuidSTRUUID[]17.4.2.13

Predicates

String-specific predicates are listed under Strings and Language Maps. Note that bound takes a variable instead of another expression as its argument.

FlintSPARQL nameArglistReference
boundBOUND[var]17.4.1.1
sametermSAMETERM[expr expr]17.4.1.8
iri?isIRI[expr]17.4.2.1
uri?isURI[expr]17.4.2.1
blank?isBLANK[expr]17.4.2.2
literal?isLITERAL[expr]17.4.2.3
numeric?isNUMERIC[expr]17.4.2.4

Strings and Language Maps

FlintSPARQLArglistReference
strSTR[expr]17.4.2.5
langLANG[expr]17.4.2.6
strdtSTRDT[expr expr]17.4.2.10
strlangSTRLANG[expr expr]17.4.2.11
strlenSTRLEN[expr]17.4.3.2
substrSUBSTR[expr expr] or [expr expr expr]17.4.3.3
ucaseUCASE[expr]17.4.3.4
lcaseLCASE[expr]17.4.3.5
strstartsSTRSTARTS[expr expr]17.4.3.6
strendsSTRENDS[expr expr]17.4.3.7
containsCONTAINS[expr expr]17.4.3.8
strbeforeSTRBEFORE[expr expr]17.4.3.9
strafterSTRAFTER[expr expr]17.4.3.10
encode-for-uriENCODE_FOR_URI[expr]17.4.3.11
concatCONCAT[& exprs]17.4.3.12
lang-matchesLANGMATCHES[expr expr]17.4.3.13
regexREGEX[expr expr] or [expr expr expr]17.4.3.14
replaceREPLACE[expr expr expr] or [expr expr expr expr]17.4.3.15

Numerics

FlintSPARQLArglistReference
absABS[expr]17.4.4.1
roundROUND[expr]17.4.4.2
ceilCEIL[expr]17.4.4.3
floorFLOOR[expr]17.4.4.4
randRAND[]17.4.4.5

Dates and Times

FlintSPARQLArglistReference
nowNOW[]17.4.5.1
yearYEAR[expr]17.4.5.2
monthMONTH[expr]17.4.5.3
dayDAY[expr]17.4.5.4
hoursHOURS[expr]17.4.5.5
minutesMINUTES[expr]17.4.5.6
secondsSECONDS[expr]17.4.5.7
timezoneTIMEZONE[expr]17.4.5.8
tzTZ[expr]17.4.5.9

Hash Functions

FlintSPARQLArglistReference
md5MD5[expr]17.4.6.1
sha1SHA1[expr]17.4.6.2
sha256SHA256[expr]17.4.6.3
SHA384SHA384[expr]17.4.6.4
sha512SHA512[expr]17.4.6.5

Aggregate Expressions

Aggregates are special expressions that can only be used in SELECT (and its DISTINCT and REDUCED variants), ORDER BY and HAVING clauses.

FlintSPARQLArglist
sumSUM[expr & {:keys [distinct?]}]
minMIN[expr & {:keys [distinct?]}]
maxMAX[expr & {:keys [distinct?]}]
avgAVG[expr & {:keys [distinct?]}]
sampleSAMPLE[expr & {:keys [distinct?]}]
countCOUNT[expr-or-wildcard & {:keys [distinct?]}]
group-concatGROUP_CONCAT[expr & {:keys [distinct? separator]}]

The count aggregate can accept either a normal expression or a wildcard, so both (for example) (count ?x) and (count *) are valid.

Unlike other expressions, aggregates in Flint support keyword arguments. Every aggregate function supports the :distinct? keyword arg, which accepts a boolean value. If :distinct? is true, then DISTINCT is added to the arg list in SPARQL. The example,

(sum ?x :distinct? true)

becomes

SUM(DISTINCT ?x)

group-concat also accepts the :separator keyword arg that takes a separator string. Both :distinct? and :separator can be supported in the same expression, so:

(group-concat ?y :distinct? true :separator ";")

which becomes

GROUP_CONCAT(DISTINCT ?y SEPARATOR = ";")

NOTE: Using aggregates in an invalid clause, e.g. a FILTER clause, will cause a spec error.

NOTE: Using aggregates in a SELECT query, or including a GROUP BY in the query, introduces aggregate restrictions on the SELECT clause. See the SPARQL Queries page for more details.

Custom Functions

Users can write their own custom functions, which consist of using an IRI or prefixed IRI instead of a symbol. The example:

[:filter (:func/isEven ?x)]

becomes

FILTER func:isEven(?x)

NOTE: Flint makes no attempt to validate that custom function IRIs resolve to valid resources, nor does it to attempt to validate input or output.

In :select, :order-by and :having clauses, custom aggregates are allowed, and any custom function can accept the :distinct? keyword arg. During aggregate validation, all custom functions in these clauses are treated as aggregates.

Variable Binding

Variables can be bound to the result of expressions in :bind, :select, and :group-by clauses. In Flint, they are written in as the vector [expr var], such as in this example:

[(+ 2 2) ?four]

which then becomes:

(2 + 2) AS ?four

NOTE: In a :select or :bind clause, the variable being bound to cannot already be in-scope. In a :select clause, the var cannot be already defined in the :where clause, nor be previously projected in that same clause. In the :bind case, it cannot be already defined in previously-listed graph patterns.

Can you improve this documentation?Edit on GitHub

cljdoc is a website building & hosting documentation for Clojure/Script libraries

× close