Logical Functions

This topic describes the logical functions in Graph Studio.

Typographical Conventions

This documentation uses the following conventions in function syntax:

  • CAPS: Although SPARQL is case-insensitive, function names and other keywords are written in uppercase for readability.
  • [ argument ]: Brackets are used to indicate optional arguments. Arguments without brackets are required.

Functions

  • AND: Evaluates two logical expressions and returns true if both expressions are true.
  • BOUND: Evaluates whether an RDF term type is bound.
  • CASE: Evaluates a series of conditions for the specified value and returns the matching result.
  • COALESCE: Evaluates a number of expressions and returns the results for the first expression that is bound and does not raise an error.
  • EQUAL: Evaluates whether two values are equal.
  • IF: Evaluates a condition and returns the specified result depending on the outcome of the test.
  • IFERROR: Synonym for COALESCE.
  • IN: Evaluates whether the specified RDF term is found in any of the given test values.
  • NOT: Evaluates whether the specified logical expression is not true.
  • NOT_EQUAL: Evaluates whether two values are not equal.
  • NOT_IN: Evaluates whether the specified RDF term is not found in any of the given test values.
  • OR: Evaluates two logical expressions and returns true if at least one of the expressions is true.
  • PARTITIONINDEX: Returns the zero-based index of the bucket in which the specified value falls.
  • SAMETERM: Evaluates whether two RDF term type values are the same.
  • UNBOUND: Extends the SPARQL UNDEF functionality to enable users to include an undefined value as a function argument.

AND

This function evaluates two logical expressions. If both expressions are true, the function returns true. If one or both arguments are false, the function returns false.

Syntax

AND(logical_expression1, logical_expression2)
Argument Type Description
logical_expression1 evaluates to boolean The first logical expression to evaluate.
logical_expression2 evaluates to boolean The second logical expression to evaluate.

Returns

Type Description
boolean True if both conditions are true and false if either condition is false.

BOUND

This function evaluates whether the specified RDF term has a value bound to it.

Syntax

BOUND(term)
Argument Type Description
term RDF term The literal, URI, or blank node value to evaluate.

Returns

Type Description
boolean True if the term is bound and false if it is not.

CASE

This function evaluates a series of conditions for the specified value and returns the matching result. CASE acts like an IF-THEN-ELSE statement.

Syntax

CASE(test_value, condition1, [ condition2 ] [, conditionN ]
     result1 [, result2 ] [, resultN ] [, default ])
Argument Type Description
test_value RDF term The literal, URI, or blank node value to compare to the list of conditions (condition1-N).
condition1–N RDF term The conditions to be evaluated in the order that they are specified. Once a condition evaluates to true, the corresponding result is returned and the remaining conditions are not evaluated.
result1–N RDF term The results to return for the specified conditions.
default RDF term An optional value to be returned if none of the specified conditions pass.

Returns

Type Description
RDF term The specified result according to the evaluation of the conditions.

COALESCE

This function evaluates a number of expressions and returns the results for the first expression that is bound and does not raise an error.

Syntax

COALESCE(expression1 [, expression2 ] [, expressionN ] )
Argument Type Description
expression1–N RDF term The literal, URI, or blank node expressions to evaluate.

Returns

Type Description
RDF term The result of the first expression that is bound and does not error.

EQUAL

This function evaluates whether value1 is equal to value2.

Syntax

EQUAL(value1, value2)
Argument Type Description
value1 numeric, boolean, dateTime, RDF term The number, boolean, datetime, literal, URI, or blank node value to compare to value2.
value2 numeric, boolean, dateTime, RDF term The number, boolean, datetime, literal, URI, or blank node value to compare to value1.

Returns

Type Description
boolean True if the values are equal and false if they are not.

IF

This function evaluates a condition and returns the specified result depending on the outcome of the test. If the condition evaluates to true, the first result is returned. If the condition evaluates to false, the second result is returned. And if the condition results in an error, the third result is returned.

Syntax

IF(logical_expression, true_result, false_result [, error_result ])
Argument Type Description
logical_expression evaluates to boolean The condition that evaluates to true or false.
true_result RDF term The value that defines the result to return if the condition evaluates to true.
false_result RDF term The value that defines the result to return if the condition evaluates to false.
error_result RDF term An optional value that defines the result to return if the condition evaluates to an error. If the condition results in an error and error_result is not specified, logical_expression(error) is returned.

Returns

Type Description
RDF term The result based on the evaluation of the condition.

IFERROR

This function is a synonym for COALESCE.

IN

This function evaluates whether the specified RDF term type value is found in any of the given test values.

Syntax

IN(term, test_value1 [, test_value2 ] [, test_valueN])
Argument Type Description
term RDF term The literal, URI, or blank node value to look for in the test values.
test_value1–N RDF term The literal, URI, or blank node values to look for the specified term in.

Returns

Type Description
boolean True if the given term is found in the test values and false if it is not.

NOT

This function evaluates whether the specified logical expression is not true.

Syntax

NOT(logical_expression)
Argument Type Description
logical_expression evaluates to boolean The condition to evaluate.

Returns

Type Description
boolean True if the condition is false and false if it is true.

NOT_EQUAL

This function evaluates whether value1 is not equal to value2.

Syntax

NOT_EQUAL(value1, value2)
Argument Type Description
value1 numeric, boolean, dateTime, RDF term The number, boolean, datetime, literal, URI, or blank node value to compare to value2.
value2 numeric, boolean, dateTime, RDF term The number, boolean, datetime, literal, URI, or blank node value to compare to value1.

Returns

Type Description
boolean True if value1 is not equal to value2. False if they are equal.

NOT_IN

This function evaluates whether the specified RDF term type value is not found in any of the given test values.

Syntax

IN(term, test_value1 [, test_value2 ] [, test_valueN])
Argument Type Description
term RDF term The literal, URI, or blank node value to look for in the test values.
test_value1–N RDF term The literal, URI, or blank node values in which to look for the specified term.

Returns

Type Description
boolean True if the given term is not in the test values and false if it is found in the test values.

OR

This function evaluates two logical expressions. If at least one expression is true, the function returns true. If both expressions are false, the function returns false.

Syntax

OR(logical_expression1, logical_expression2)
Argument Type Description
logical_expression1 evaluates to boolean The first logical expression to evaluate.
logical_expression2 evaluates to boolean The second logical expression to evaluate.

Returns

Type Description
boolean True if one or both conditions are true and false if both conditions are false.

PARTITIONINDEX

This function returns the zero-based index of the bucket in which the specified value falls. Buckets start at the specified start value and are sized according to the specified interval. The first bucket is [start, start+interval). That means it is closed on the low end and open on the high end. PARTITIONINDEX returns less than 0 if the value does not fall into any bucket, such as when the given value is less than start or if the comparison is indeterminate for date and time data types.

Syntax

PARTITIONINDEX(value, start, interval)
Argument Type Description
value literal The literal value for which to determine the zero-based index.
start literal The literal value that indicates the start of the first bucket.
interval literal The literal value that specifies the size of the bucket.

Returns

Type Description
long The zero-based index of the bucket in which the specified value exists.

SAMETERM

This function evaluates whether two RDF term type values are the same.

Syntax

SAMETERM(term1, term2)
Argument Type Description
term1 RDF term The first literal, URI, or blank node value to compare.
term2 RDF term The literal, URI, or blank node value to compare to term1.

Returns

Type Description
boolean True if the terms are the same and false if they are not.

UNBOUND

This function is like the SPARQL UNDEF keyword but extends that functionality to enable users to include an undefined value as a function argument, as UNDEF is only supported in VALUES clauses.

Syntax

UNBOUND()

Example

The following example statement incorporates UNBOUND to return null if the specified condition (?x > 5) fails:

BIND(IF(?x > 5 , "Win", UNBOUND()) as ?testResult)

In this case, ?testResult is bound if ?x is greater than 5. If ?x is not greater than 5, ?testResult is not bound.

Returns

Type Description
RDF term The specified result according to the evaluation of the condition.