WOQL - TerminusDB

Search…
WOQL
WOQL
License: Apache Version 2
new WOQL()
The WOQL object is a wrapper around the WOQLQuery object Syntactic sugar to allow writing WOQL.triple()... instead of new WOQLQuery().triple() Every function matches one of the public api functions of the woql query object
using
WOQL.using(refPath, subquery) ⇒ WOQLQuery
Query running against any specific commit Id
Param
Type
Description
refPath
string
path to specific reference Id or commit Id
subquery
WOQLQuery
subquery for the specific commit point
Example
let [a, b, c] = vars("a", "b", "c")
WOQL.using("userName/dbName/local/commit|branch/commitID").triple(a, b, c)
comment
WOQL.comment(comment, subquery) ⇒ WOQLQuery
Adds a text comment to a query - can also be used to wrap any part of a query to turn it off
Param
Type
Description
comment
string
text comment
subquery
WOQLQuery
query that is "commented out"
select
WOQL.select(...varNames) ⇒ WOQLQuery
Param
Type
Description
...varNames
string
only these variables are returned
Example
let [a, b, c] = vars("a", "b", "c")
WOQL.select(a, triple(a, b, c))
Filters the query so that only the variables included in [V1...Vn] are returned in the bindings
distinct
WOQL.distinct(...varNames) ⇒ WOQLQuery
Filter the query to return only results that are distinct in the given variables
Param
Type
Description
...varNames
string
these variables are guaranteed to be unique as a tuple
and
WOQL.and(...subqueries) ⇒ WOQLQuery
Logical conjunction of the contained queries - all queries must match or the entire clause fails
Returns: WOQLQuery - - A WOQLQuery object containing the conjunction of queries
Param
Type
Description
...subqueries
WOQLQuery
A list of one or more woql queries to execute as a conjunction
Example
//find triples that are of type scm:Journey, and have
//a start_station Start, and that start_station is labeled Start_Label
let [Journey, Start, Start_Label] = vars("Journey", "Start", "Start_Label")
WOQL.and(
     WOQL.triple(Journey, "rdf:type", "@schema:Journey"),
     WOQL.triple(Journey, "start_station", Start),
     WOQL.triple(Start, "label", Start_Label))
read_object
WOQL.read_object()
Deprecated
Use read_document instead.
read_document
WOQL.read_document(IRI, output) ⇒ object
Read a node identified by an IRI as a JSON-LD document
Returns: object - WOQLQuery
Param
Type
Description
IRI
string
The document id or a variable to read
output
string
Variable which will be bound to the document.
Example
let [person] = vars("Person")
const query = WOQL.read_document(
     "Person/0b4feda109d9d13c9da809090b342ad9e4d8185545ce05f7cd20b97fe458f547",
    person
);
const res =  await client.query(query);
insert_document
WOQL.insert_document(docjson, [IRI]) ⇒ object
Insert a document in the graph.
Returns: object - WOQLQuery
Param
Type
Description
docjson
object
The document to insert. Must either have an '@id' or have a class specified key.
[IRI]
string
An optional identifier specifying the document location.
Example
const res = await client.query(
   WOQL.insert_document(WOQL.doc({ "@type" : "Person", "label": "John" }))
)
update_document
WOQL.update_document(docjson, [IRI]) ⇒ object
Update a document identified by an IRI
Returns: object - WOQLQuery
Param
Type
Description
docjson
object
The document to update. Must either have an '@id' or have a class specified key.
[IRI]
string
An optional identifier specifying the document location.
delete_document
WOQL.delete_document(IRI) ⇒ object
Delete a document from the graph.
Returns: object - WOQLQuery
Param
Type
Description
IRI
string
The document id or a variable
or
WOQL.or(...subqueries) ⇒ WOQLQuery
Creates a logical OR of the arguments
Returns: WOQLQuery - - A WOQLQuery object containing the logical Or of the subqueries
Param
Type
Description
...subqueries
WOQLQuery
A list of one or more woql queries to execute as alternatives
Example
let [Subject] = vars("Subject")
or(
  triple(Subject, 'label', "A"),
  triple(Subject, "label", "a")
 )
from
WOQL.from(graphRef-, [query]) ⇒ WOQLQuery
Specifies the database URL that will be the default database for the enclosed query
Returns: WOQLQuery - A WOQLQuery object containing the from expression
Param
Type
Description
graphRef-
typedef.GraphRef
A valid graph resource identifier string
[query]
WOQLQuery
The query
into
WOQL.into(graphRef-, subquery) ⇒ WOQLQuery
Specifies the graph resource to write the contained query into
Returns: WOQLQuery - A WOQLQuery which will be written into the graph in question
Param
Type
Description
graphRef-
typedef.GraphRef
A valid graph resource identifier string
subquery
WOQLQuery
The query which will be written into the graph
Example
//Subq is an argument or a chained query
using("admin/minecraft").into("instance/main").add_triple("a", "rdf:type", "@schema:X")
//writes a single tripe (doc:a, rdf:type, scm:X) into the main instance graph
triple
WOQL.triple(subject, predicate, object) ⇒ WOQLQuery
Creates a triple pattern matching rule for the triple [S, P, O] (Subject, Predicate, Object)
Param
Type
Description
subject
string
The IRI of a triple’s subject or a variable
predicate
string
The IRI of a property or a variable
object
string
The IRI of a node or a variable, or a literal
added_triple
WOQL.added_triple(subject, predicate, object) ⇒ WOQLQuery
Creates a triple pattern matching rule for the triple [S, P, O] (Subject, Predicate, Object) added in the current layer
Param
Type
Description
subject
string
The IRI of a triple’s subject or a variable
predicate
string
The IRI of a property or a variable
object
string
The IRI of a node or a variable, or a literal
removed_triple
WOQL.removed_triple(subject, predicate, object) ⇒ WOQLQuery
Creates a triple pattern matching rule for the triple [S, P, O] (Subject, Predicate, Object) added in the current commit
Param
Type
Description
subject
string
The IRI of a triple’s subject or a variable
predicate
string
The IRI of a property or a variable
object
string
The IRI of a node or a variable, or a literal
quad
WOQL.quad(subject, predicate, object, graphRef) ⇒ WOQLQuery
Creates a pattern matching rule for the quad [S, P, O, G] (Subject, Predicate, Object, Graph)
Param
Type
Description
subject
string
The IRI of a triple’s subject or a variable
predicate
string
The IRI of a property or a variable
object
string
The IRI of a node or a variable, or a literal
graphRef
typedef.GraphRef
A valid graph resource identifier string
added_quad
WOQL.added_quad(subject, predicate, object, graphRef-) ⇒ WOQLQuery
Creates a pattern matching rule for the quad [S, P, O, G] (Subject, Predicate, Object, Graph) removed from the current commit
Param
Type
Description
subject
string
The IRI of a triple’s subject or a variable
predicate
string
The IRI of a property or a variable
object
string
The IRI of a node or a variable, or a literal
graphRef-
typedef.GraphRef
A valid graph resource identifier string
removed_quad
WOQL.removed_quad(subject, predicate, object, graphRef-) ⇒ WOQLQuery
Creates a pattern matching rule for the quad [S, P, O, G] (Subject, Predicate, Object, Graph) removed from the current commit
Param
Type
Description
subject
string
The IRI of a triple’s subject or a variable
predicate
string
The IRI of a property or a variable
object
string
The IRI of a node or a variable, or a literal
graphRef-
typedef.GraphRef
A valid graph resource identifier string
sub
WOQL.sub(classA, classB) ⇒ boolean
Returns true if ClassA subsumes ClassB, according to the current DB schema
Returns: boolean - WOQLQuery
Param
Type
Description
classA
string
ClassA
classB
string
ClassB
eq
WOQL.eq(varName, varValue) ⇒ WOQLQuery
Matches if a is equal to b
Param
Type
Description
varName
string
literal, variable or id
varValue
string
literal, variable or id
substr
WOQL.substr(string, before, [length], [after], [substring]) ⇒ WOQLQuery
Substring
Param
Type
Description
string
string
String or variable
before
number
integer or variable (characters from start to begin)
[length]
number
integer or variable (length of substring)
[after]
number
integer or variable (number of characters after substring)
[substring]
string
String or variable
get
WOQL.get(asvars, queryResource) ⇒ WOQLQuery
Retrieves the exernal resource defined by QueryResource and copies values from it into variables defined in AsVars
Returns: WOQLQuery - A WOQLQuery which contains the get expression
Param
Type
Description
asvars
WOQLQuery
an array of AsVar variable mappings (see as for format below)
queryResource
WOQLQuery
an external resource (remote, file, post) to query
Example
let [a, b] = vars("a", "b")
get(as("a", a).as("b", b)).remote("http://my.url.com/x.csv")
//copies the values from column headed "a" into a variable a and from column
//"b" into a variable b from remote CSV
put
WOQL.put(varsToExp, query, fileResource) ⇒ WOQLQuery
Returns: WOQLQuery - A WOQLQuery which contains the put expression
Put: Outputs the results of a query to a file
Param
Type
Description
varsToExp
WOQLQuery
an array of AsVar variable mappings (see as for format below)
query
WOQLQuery
The query which will be executed to produce the results
fileResource
string
an file resource local to the server
Example
let [s, p, o] = vars("Subject", "Predicate", "Object")
WOQL.put(WOQL.as("s", s).as("p", p).as("o", o), WOQL.all())
.file({file:"/app/local_files/dump.csv"})
as
WOQL.as(source, target, [type]) ⇒ WOQLQuery
Imports the value identified by Source to a Target variable
Param
Type
Description
source
string | number
Source
target
string
Target
[type]
string
type to cast value to string
Example
let [First_Var, Second_Var] = vars('First_Var', 'Second_Var')
WOQL.as("first var", First_Var, "string").as("second var", Second_Var)
WOQL.as(["first var", First_Var, "string"], ["second var", Second_Var])
remote
WOQL.remote(remoteObj, [formatObj]) ⇒ WOQLQuery
Identifies a remote resource by URL and specifies the format of the resource through the options
Returns: WOQLQuery - A WOQLQuery which contains the remote resource identifier
Param
Type
Description
remoteObj
object
The URL at which the remote resource can be accessed
[formatObj]
typedef.DataFormatObj
The format of the resource data {}
Example
remote({url:"http://url.of.resource"}, {type: "csv"})
file
WOQL.file(url, [formatObj]) ⇒ WOQLQuery
Identifies a file resource as a path on the server and specifies the format through the options
Returns: WOQLQuery - A WOQLQuery which contains the file resource identifier
Param
Type
Description
url
object
The Path on the server at which the file resource can be accessed
[formatObj]
typedef.DataFormatObj
imput options
Example
file("/path/to/file", {type: 'turtle'} )
post
WOQL.post(url, [formatObj], [source]) ⇒ WOQLQuery
Identifies a resource as a local path on the client, to be sent to the server through a HTTP POST request, with the format defined through the options
Returns: WOQLQuery - A WOQLQuery which contains the Post resource identifier
Param
Type
Description
url
string
The Path on the server at which the file resource can be accessed
[formatObj]
typedef.DataFormatObj
imput options, optional
[source]
string
It defines the source of the file, it can be 'url','post'
Example
post("/.../.../", {type:'csv'})
delete_triple
WOQL.delete_triple(subject, predicate, object) ⇒ WOQLQuery
Deletes a single triple from the default graph of the database
Returns: WOQLQuery - - A WOQLQuery which contains the Triple Deletion statement
Param
Type
Description
subject
string
The IRI of a triple’s subject or a variable
predicate
string
The IRI of a property or a variable
object
string
The IRI of a node or a variable, or a literal
Example
delete_triple("john", "age", 42)
delete_quad
WOQL.delete_quad(subject, predicate, object, graphRef) ⇒ WOQLQuery
Deletes a single triple from the graph [Subject, Predicate, Object, Graph]
Returns: WOQLQuery - - A WOQLQuery which contains the Delete Quad Statement
Param
Type
Description
subject
string
The IRI of a triple’s subject or a variable
predicate
string
The IRI of a property or a variable
object
string
The IRI of a node or a variable, or a literal
graphRef
typedef.GraphRef
A valid graph resource identifier string
Example
remove the class Person from the schema graph
WOQL.delete_quad("Person", "rdf:type", "sys:Class", "schema")
add_triple
WOQL.add_triple(subject, predicate, object) ⇒ object
Adds triples according to the the pattern [subject,predicate,object]
Returns: object - WOQLQuery
Param
Type
Description
subject
string
The IRI of a triple’s subject or a variable
predicate
string
The IRI of a property or a variable
object
string
The IRI of a node or a variable, or a literal
add_quad
WOQL.add_quad(subject, predicate, object, graphRef-) ⇒ object
Adds quads according to the pattern [S,P,O,G]
Returns: object - WOQLQuery
Param
Type
Description
subject
string
The IRI of a triple’s subject or a variable
predicate
string
The IRI of a property or a variable
object
string
The IRI of a node or a variable, or a literal
graphRef-
typedef.GraphRef
A valid graph resource identifier string
trim
WOQL.trim(inputStr, resultVarName) ⇒ WOQLQuery
Remove whitespace from both sides of a string:
Returns: WOQLQuery - A WOQLQuery which contains the Trim pattern matching expression
Param
Type
Description
inputStr
string
A string or variable containing the untrimmed version of the string
resultVarName
string
A string or variable containing the trimmed version of the string
Example
let [trimmed] = vars("trimmed")
trim("hello   ", trimmed)
//trimmed contains "hello"
evaluate
WOQL.evaluate(arithExp, resultVarName) ⇒ WOQLQuery
Evaluates the passed arithmetic expression and generates or matches the result value
Returns: WOQLQuery - A WOQLQuery which contains the Arithmetic function
Param
Type
Description
arithExp
object | WOQLQuery | string
A WOQL query containing a valid WOQL Arithmetic Expression, which is evaluated by the function
resultVarName
string | number
Either a variable, in which the result of the expression will be stored, or a numeric literal which will be used as a test of result of the evaluated expression
Example
let [result] = vars("result")
evaluate(plus(2, minus(3, 1)), result)
eval
WOQL.eval(arithExp, resultVarName) ⇒ WOQLQuery
Evaluates the passed arithmetic expression and generates or matches the result value
Returns: WOQLQuery - WOQLQuery
Param
Type
Description
arithExp
object | WOQLQuery | string
query or JSON-LD representing the query
resultVarName
string
output variable
plus
WOQL.plus(...args) ⇒ WOQLQuery
Adds the numbers together
Returns: WOQLQuery - A WOQLQuery which contains the addition expression
Param
Type
Description
...args
string | number
a variable or numeric containing the values to add
Example
let [result] = vars("result")
evaluate(plus(2, plus(3, 1)), result)
minus
WOQL.minus(...args) ⇒ WOQLQuery
Subtracts Numbers N1..Nn
Returns: WOQLQuery - A WOQLQuery which contains the subtraction expression
Param
Type
Description
...args
string | number
variable or numeric containing the value that will be subtracted from
Example
let [result] = vars("result")
evaluate(minus(2.1, plus(0.2, 1)), result)
times
WOQL.times(...args) ⇒ WOQLQuery
Multiplies numbers N1...Nn together
Returns: WOQLQuery - A WOQLQuery which contains the multiplication expression
Param
Type
Description
...args
string | number
a variable or numeric containing the value
Example
let [result] = vars("result")
evaluate(times(10, minus(2.1, plus(0.2, 1))), result)
 //result contains 9.000000000000002y
divide
WOQL.divide(...args) ⇒ WOQLQuery
Divides numbers N1...Nn by each other left, to right precedence
Returns: WOQLQuery - A WOQLQuery which contains the division expression let [result] = vars("result") evaluate(divide(times(10, minus(2.1, plus(0.2, 1))), 10), result) //result contains 0.9000000000000001
Param
Type
Description
...args
string | number
numbers to tbe divided
div
WOQL.div(...args) ⇒ WOQLQuery
Division - integer division - args are divided left to right
Returns: WOQLQuery - A WOQLQuery which contains the division expression
Param
Type
Description
...args
string | number
numbers for division
Example
let [result] = vars("result")
evaluate(div(10, 3), result)
//result contains 3
exp
WOQL.exp(varNum, expNum) ⇒ WOQLQuery
Exponent - raises varNum01 to the power of varNum02
Returns: WOQLQuery - A WOQLQuery which contains the exponent expression
Param
Type
Description
varNum
string | number
a variable or numeric containing the number to be raised to the power of the second number
expNum
number
a variable or numeric containing the exponent
Example
let [result] = vars("result")
evaluate(exp(3, 2), result)
//result contains 9
floor
WOQL.floor(varNum) ⇒ WOQLQuery
Generates the nearest lower integer to the passed number
Returns: WOQLQuery - A WOQLQuery which contains the floor expression
Param
Type
Description
varNum
string | number
Variable or numeric containing the number to be floored
Example
let [result] = vars("result")
evaluate(divide(floor(times(10, minus(2.1, plus(0.2, 1)))), 10), result)
//result contains 0.9 - floating point error removed
isa
WOQL.isa(instanceIRI, classId) ⇒ WOQLQuery
Tests whether a given instance IRI has type Class, according to the current state of the DB
Returns: WOQLQuery - A WOQLQuery object containing the type test
Param
Type
Description
instanceIRI
string
A string IRI or a variable that identify the class instance
classId
string
A Class IRI or a variable
Example
let [subject] = vars("subject")
isa(subject, "Person")
like
WOQL.like(stringA, stringB, distance) ⇒ WOQLQuery
Generates a string Leverstein distance measure between stringA and stringB
Returns: WOQLQuery - A WOQLQuery which contains the Like pattern matching expression
Param
Type
Description
stringA
string
string literal or variable representing a string to be compared
stringB
string
string literal or variable representing the other string to be compared
distance
number | string
variable representing the distance between the variables
Example
let [dist] = vars('dist')
like("hello", "hallo", dist)
//dist contains 0.7265420560747664
less
WOQL.less(varNum01, varNum02) ⇒ WOQLQuery
Compares the value of v1 against v2 and returns true if v1 is less than v2
Returns: WOQLQuery - A WOQLQuery which contains the comparison expression
Param
Type
Description
varNum01
string | number
a variable or numeric containing the number to be compared
varNum02
string | number
a variable or numeric containing the second comporator
Example
let [result] = vars("result")
less(1, 1.1).eq(result, literal(true, "boolean"))
//result contains true
greater
WOQL.greater(varNum01, varNum02) ⇒ WOQLQuery
Compares the value of v1 against v2 and returns true if v1 is greater than v2
Returns: WOQLQuery - A WOQLQuery which contains the comparison expression
Param
Type
Description
varNum01
string | number
a variable or numeric containing the number to be compared
varNum02
string | number
a variable or numeric containing the second comporator
Example
let [result] = vars("result")
greater(1.2, 1.1).eq(result, literal(true, "boolean"))
//result contains true
opt
WOQL.opt([subquery]) ⇒ WOQLQuery
Specifies that the Subquery is optional - if it does not match the query will not fail
Returns: WOQLQuery - A WOQLQuery object containing the optional sub Query
Param
Type
Description
[subquery]
WOQLQuery
A subquery which will be optionally matched
Example
let [subject] = vars("subject")
opt(triple(subject, 'label', "A"))
//Subq is an argument or a chained query
opt().triple(subject, 'label', "A")
unique
WOQL.unique(prefix, inputVarList, resultVarName) ⇒ WOQLQuery
Generate a new IRI from the prefix and a hash of the variables which will be unique for any given combination of variables
Returns: WOQLQuery - A WOQLQuery object containing the unique ID generating function
Param
Type
Description
prefix
string
A prefix for the IRI - typically formed of the doc prefix and the classtype of the entity (“doc:Person”)
inputVarList
array | string
An array of variables and / or strings from which the unique hash will be generated
resultVarName
string
Variable in which the unique ID is stored
Example
let [newid] = vars("newid")
unique("doc:Person", ["John", "Smith"], newid)
idgen
WOQL.idgen(prefix, inputVarList, resultVarName) ⇒ WOQLQuery
Generate a new IRI from the prefix and concatention of the variables
Returns: WOQLQuery - A WOQLQuery object containing the ID generating function
Param
Type
Description
prefix
string
A prefix for the IRI - typically formed of the doc prefix and the classtype of the entity (“doc:Person”)
inputVarList
array | string
An array of variables and / or strings from which the unique hash will be generated
resultVarName
string
Variable in which the unique ID is stored
Example
let [newid] = vars("newid")
idgen("doc:Person", ["John", "Smith"], newid)
upper
WOQL.upper(inputVarName, resultVarName) ⇒ WOQLQuery
Changes a string to upper-case
Returns: WOQLQuery - A WOQLQuery which contains the Upper case pattern matching expression
Param
Type
Description
inputVarName
string
string or variable representing the uncapitalized string
resultVarName
string
variable that stores the capitalized string output
Example
let [allcaps] = vars("allcaps")
upper("aBCe", allcaps)
//upper contains "ABCE"
lower
WOQL.lower(inputVarName, resultVarName) ⇒ 