@terminusdb/terminusdb-client
AccessControl
accessRequestsList(orgName)
-- TerminusX API -- Get all the access request list for a specify organization
Parameters
Name | Type | Description |
---|---|---|
orgName | string | The organization name. |
Examples
accessControl.accessRequestsList().then(result=>{
console.log(result)
})
createOrganization(orgName)
-- TerminusDB API --- This end point works in basic authentication, admin user Create an organization
Parameters
Name | Type | Description |
---|---|---|
orgName | string | The organization name to create |
Examples
accessControl.createOrganization("my_org_name").then(result=>{
console.log(result)
})
createOrganizationRemote(orgName)
-- TerminusX API --- IMPORTANT This does not work with the API-TOKEN. Create an organization
Parameters
Name | Type | Description |
---|---|---|
orgName | string | The organization name to create |
Examples
accessControl.createOrganization("my_org_name").then(result=>{
console.log(result)
})
createRole(name, actions)
--TerminusDB API --- basic authentication, admin user. Create a new role in the system database.
Parameters
Name | Type | Description |
---|---|---|
name | string | The role name. |
actions | typedef.RolesActions | A list of actions |
Examples
accessControl.createRole("Reader",[ACTIONS.INSTANCE_READ_ACCESS]).then(result=>{
console.log(result)
})
createUser(name, password)
-- TerminusdDB API --- basic Authentication, admin user. Add the user into the system database
Parameters
Name | Type | Description |
---|---|---|
name | string | the user name |
password | string | you need the password for basic authentication |
Examples
accessControl.deleteUser(userId).then(result=>{
console.log(result)
})
createUserRole(userId, scope, role, orgName)
-- TerminusX API -- Create a user's a role for a resource (organization/database)
Parameters
Name | Type | Description |
---|---|---|
userId | string | The user's id. |
scope | string | The resource name/id. |
role | string | The user role to be assigned. |
orgName | string | The organization name. |
Examples
const dbId = "UserDatabase/acfcc2db02b83792sssb15239ccdf586fc5b176846ffe4878b1aea6a36c8f"
accessControl.assignUserRole('User/auth0%7C61790e11a3966d006906596a',dbId,
"Role/collaborator").then(result=>{
console.log(result)
})
customHeaders(customHeaders)
add extra headers to your request
Parameters
Name | Type | Description |
---|---|---|
customHeaders | object |
deleteAccessRequest(orgName)
-- TerminusX API -- Delete an access request to join your team, only an admin user can delete it
Parameters
Name | Type | Description |
---|---|---|
orgName | string | The organization name. |
Examples
accessControl.deleteAccessRequest("djjdshhsuuwewueueuiHYHYYW.......").then(result=>{
console.log(result)
})
deleteOrgInvite(inviteId, orgName)
-- TerminusX API --- Delete an invitation
Parameters
Name | Type | Description |
---|---|---|
inviteId | string | The invite id to delete. |
orgName | string | The organization name. |
Examples
const fullInviteId="Organization/my_team_name/invitations/Invitation/7ad0c9eb82b6175bcda9
c0dfc2ac51161ef5ba7cb0988d992c4bce82b3fa5d25"
accessControl.deleteOrgInvite(fullInviteId).then(result=>{
console.log(result)
})
deleteOrganization(orgName)
-- TerminusDB API --- Delete an Organization
Parameters
Name | Type | Description |
---|---|---|
orgName | string | The organization name to delete |
Examples
accessControl.deleteOrganization("my_org_name").then(result=>{
console.log(result)
})
deleteRole(name)
-- TerminusdDB API --- basic Authentication, admin user. Delete role in the system database, (this api is enabled only in the local installation)
Parameters
Name | Type | Description |
---|---|---|
name | string | The role name. |
Examples
accessControl.deleteRole("Reader").then(result=>{
console.log(result)
})
deleteUser(userId)
-- TerminusdDB API --- basic Authentication, admin user. Remove the user from the system database.
Parameters
Name | Type | Description |
---|---|---|
userId | string | the document user id |
Examples
accessControl.deleteUser(userId).then(result=>{
console.log(result)
})
getAPIUrl(cloudAPIUrl)
Get a API url from cloudAPIUrl
Parameters
Name | Type | Description |
---|---|---|
cloudAPIUrl | string | The base url for cloud |
getAccessRoles()
--TerminusX and TerminusDB API --- Get all the system database roles types.
getAllOrganizations()
-- TerminusDB API --- This end point works in basic authentication, admin user Get list of organizations
getAllUsers()
-- TerminusdDB API --- basic Authentication, admin user. Return the list of all the users (this api is enabled only in the local installation)
Examples
accessControl.getAllUsers().then(result=>{
console.log(result)
})
getDatabaseRolesOfUser(userId, orgName)
-- TerminusX API -- Get the user's role for every databases under the organization
Parameters
Name | Type | Description |
---|---|---|
userId | string | The user's id. |
orgName | string | The organization name. |
Examples
accessControl.getDatabaseRolesOfUser('User/auth0%7C61790e366377Yu6596a').then(result=>{
console.log(result)
})
//this is a capabilities list of databases and roles
//[ {capability: "Capability/b395e8523d509dec6b33aefc9baed3b2e2bfadbd4c79d4ff9b20dce2b14e2edc"
//if there is an id we have a user specific capabality for this database
// name: {@type: "xsd:string", @value: "profiles_test"}
// role: "Role/dataUpdater"
// scope: "UserDatabase/7ebdfae5a02bc7e8f6d79sjjjsa4e179b1df9d4576a3b1d2e5ff3b4859"
// user: "User/auth0%7C61790e11a3966d006906596a"},
//{ capability: null
// if the capability id is null the user level of access for this database is the
same of the team
//name: {@type: "xsd:string", @value: "Collab002"}
//role: "Role/dataReader"
// scope: "UserDatabase/acfcc2db02b83792sssb15239ccdf586fc5b176846ffe4878b1aea6a36c8f"
//user: "User/auth0%7C61790e11a3966d006906596a"}]
getDefaultOrganization(params)
Get a organization from parameters.
Parameters
Name | Type | Description |
---|---|---|
params | object | The parameters |
getOrgInvite(inviteId, orgName)
-- TerminusX API --- Get the invitation info
Parameters
Name | Type | Description |
---|---|---|
inviteId | string | The invite id to retrieve. |
orgName | string | The organization name. |
Examples
const fullInviteId="Organization/my_team_name/invitations/Invitation/7ad0c9eb82b6175bcda9c0dfc
2ac51161ef5ba7cb0988d992c4bce82b3fa5d25"
accessControl.getOrgInvite(fullInviteId).then(result=>{
console.log(result)
})
getOrgUsers(orgName)
-- TerminusX and TerminusDB API -- Get all the organization's users and roles,
Parameters
Name | Type | Description |
---|---|---|
orgName | string | The organization name. |
Examples
accessControl.getOrgUsers().then(result=>{
console.log(result)
})
//this function will return an array of capabilities with users and roles
//-- TerminusX -- response array example
//[{capability: "Capability/3ea26e1d698821c570afe9cb4fe81a3......"
// email: {@type: "xsd:string", @value: "user@terminusdb.com"}
// picture: {@type: "xsd:string",…}
// role: "Role/dataReader"
// scope: "Organization/my_org_name"
// user: "User/auth0%7C613f5dnndjdjkTTT"}]
//
//
// -- Local Installation -- response array example
//[{ "@id":"User/auth0%7C615462f8ab33f4006a6bee0c",
// "capability": [{
// "@id":"Capability/c52af34b71f6f8916ac0115ecb5fe0e31248ead8b1e3d100852015...",
// "@type":"Capability",
// "role": [{
// "@id":"Role/admin",
// "@type":"Role",
// "action": ["instance_read_access"],
// "name":"Admin Role"
// }],
// "scope":"Organization/@team"}]]
getOrganization(organization)
-- TerminusDB API --- Get an organization from the TerminusDB API.
Parameters
Name | Type | Description |
---|---|---|
organization | string | The organization |
getPendingOrgInvites(orgName)
-- TerminusX API --- Get the pending invitations list.
Parameters
Name | Type | Description |
---|---|---|
orgName | string | The organization name. |
Examples
const invitationList = accessControl.getPendingOrgInvites().then(result=>{
console.log(invitationList)
})
//this will return an array of invitations object like this
//[{@id: "Organization/my_team_name/invitations/Invitation/7ad0c9eb82b6175bcda9c0dfc2ac51161ef5ba
cb0988d992c4bce82b3fa5d25"
// @type: "Invitation"
// creation_date: "2021-10-22T11:13:28.762Z"
// email_to: "new_user@terminusdb.com"
// invited_by: "User/auth0%7C6162f8ab33567406a6bee0c"
// role: "Role/dataReader"
// status: "needs_invite"}]
getTeamUserRole(orgName)
-- TerminusX API --- Get the user role for a given organization or the default organization The user is identified by the jwt or the access token
Parameters
Name | Type | Description |
---|---|---|
orgName | string | The organization name. |
Examples
accessControl.getTeamUserRole().then(result=>{
console.log(result)
})
//response object example
{"userRole":"Role/admin"}
getTeamUserRoles(userName, orgName)
-- TerminusX and TerminusDB API -- Get the user roles for a given organization or the default organization,
Parameters
Name | Type | Description |
---|---|---|
userName | string | The organization name. |
orgName | string | The organization name. |
Examples
accessControl.getTeamUserRole("myUser").then(result=>{
console.log(result)
})
//response object example
{
"@id": "User/myUser",
"capability": [
{
"@id":"Capability/server_access",
"@type":"Capability",
"role": [{
"@id":"Role/reader",
"@type":"Role",
"action": [
"instance_read_access",
],
"name":"reader"
}],
"scope":"Organization/myteam"
}
],
"name": "myUser"
}
getUserInfo(orgName)
-- TerminusX API -- Get the userinfo teams ownership and subscription
Parameters
Name | Type | Description |
---|---|---|
orgName | string | The organization name. |
Examples
accessControl.getUserInfo().then(result=>{
console.log(result)
})
ifOrganizationExists(orgName)
-- TerminusX API --- Check if the organization exists. it is a Head call . IMPORTANT This does not work with the API-TOKEN.
Parameters
Name | Type | Description |
---|---|---|
orgName | string | The organization name to check if exists. |
manageCapability(userName, resourceName, rolesArr, operation, scopeType)
-- TerminusdDB API --- Grant/Revoke Capability
Parameters
Name | Type | Description |
---|---|---|
userName | string | the document user id |
resourceName | string | the name of a (database or team) |
rolesArr | array | the roles name list |
operation | typedef.CapabilityCommand | grant/revoke operation |
scopeType | typedef.ScopeType | the resource type (database or organization) |
Examples
//we add an user to an organization and manage users' access
//the user myUser can access the Organization and all the database under the organization with "reader" Role
client.manageCapability(myUser,myteam,[reader],"grant","organization").then(result=>{
consol.log(result)
})
//the user myUser can access the database db__001 under the organization myteam
//with "writer" Role
client.manageCapability(myUser,myteam/db__001,[writer],"grant","database").then(result=>{
consol.log(result)
})
removeUserFromOrg(userId, orgName)
-- TerminusX API -- Remove an user from an organization, only an admin user can remove an user from an organization
Parameters
Name | Type | Description |
---|---|---|
userId | string | The id of the user to be removed. (this is the document user's @id) |
orgName | string | The organization name in which the user is to be removed. |
Examples
accessControl.removeUserFromOrg("User/auth0%7C613f5dnndjdjkTTT","my_org_name").then(result=>{
console.log(result)
})
sendAccessRequest(email, affiliation, note, orgName)
-- TerminusX API -- Get all the access request list for a specify organization
Parameters
Name | Type | Description |
---|---|---|
string | the user email. | |
affiliation | string | the user affiliation, company, university etc.. |
note | string | the message for the team admin |
orgName | string | The organization name. |
Examples
accessControl.sendAccessRequest("myemail@terminusdb.com",
"my_company",
"please add me to your team"
).then(result=>{
console.log(result)
})
sendOrgInvite(userEmail, role, note, orgName)
-- TerminusX API --- Send a new invitation
Parameters
Name | Type | Description |
---|---|---|
userEmail | string | The email of user. |
role | string | The role for user. (the document @id role like Role/collaborator) |
note | string | The note to send with the invitation. |
orgName | string | The organization name. |
Examples
accessControl.sendOrgInvite("new_user@terminusdb.com","Role/admin",
"please join myteam").then(result=>{
console.log(result)
})
setApiKey(atokenpi)
Sets the API token for the object, to request a token create an account in https://terminusdb.com/
Parameters
Name | Type | Description |
---|---|---|
atokenpi | string | The API token to use to connect with TerminusX |
setApiToken(atokenpi)
Sets the API token for the object, to request a token create an account in https://terminusdb.com/
Parameters
Name | Type | Description |
---|---|---|
atokenpi | string | The API token to use to connect with TerminusX |
setJwtToken(jwt)
Sets the Jwt token for the object
Parameters
Name | Type | Description |
---|---|---|
jwt | string | The jwt api token to use |
updateOrgInviteStatus(inviteId, accepted, orgName)
-- TerminusX API --- Accept /Reject invitation. if the invitation has been accepted we add the current user to the organization. the only user that can accept this invitation is the user registered with the invitation email, we indentify the user with the jwt token
Parameters
Name | Type | Description |
---|---|---|
inviteId | string | The invite id to updated. |
accepted | boolean | The status of the invitation. |
orgName | string | The organization name. |
Examples
const fullInviteId="Organization/my_team_name/invitations/Invitation/7ad0c9eb82b6175bcda9
c0dfc2ac51161ef5ba7cb0988d992c4bce82b3fa5d25"
accessControl.updateOrgInviteStatus(fullInviteId,true).then(result=>{
console.log(result)
})
updateUserRole(userId, capabilityId, scope, role, orgName)
-- TerminusX API -- Update user's a role for a resource (organization/database), (this api works only in terminusX)
Parameters
Name | Type | Description |
---|---|---|
userId | string | The user's id. |
capabilityId | string | The capability id. |
scope | string | The resource name/id. |
role | string | The user role to be updated. |
orgName | string | The organization name. |
Examples
const dbId = "UserDatabase/acfcc2db02b83792sssb15239ccdf586fc5b176846ffe4878b1aea6a36c8f"
const capId= "Capability/b395e8523d509dec6b33aefc9baed3b2e2bfadbd4c79d4ff9b20dce2b14e2edc"
accessControl.updateUserRole('User/auth0%7C61790e11a3966d006906596a',capId,dbId,
"Role/dataUpdater").then(result=>{
console.log(result)
})
View
matchCell()
Called to test whether a specific cell is matched by a set of rules returns array of rules that matched
matchColumn()
Called to test whether an entire column of results is matched by a set of rules returns array of rules that matched
matchEdge()
Called to test whether a specific edge (source -> target) is matched by a set of rules returns array of rules that matched
matchFrame()
Called to test whether a specific frame is matched by a set of rules
matchNode()
Called to test whether a specific node is matched by a set of rules returns array of rules that matched
matchRow()
Called to match an entire row of results is matched by a set of rules returns array of rules that matched
rule()
Shorthand functions for accessing the pattern matching capabilities
WOQL
Vars(varNames)
Parameters
Name | Type | Description |
---|---|---|
varNames | string |
Examples
const v = WOQL.Vars('var01', 'var02', 'var03');
triple(v.var01, v.var02, v.var03)
add_quad(subject, predicate, object, graphRef-)
Adds quads according to the pattern [S,P,O,G]
Parameters
Name | Type | Description |
---|---|---|
subject | string|Var | The IRI of a triple’s subject or a variable |
predicate | string|Var | The IRI of a property or a variable |
object | string|Var | The IRI of a node or a variable, or a literal |
graphRef- | typedef.GraphRef | A valid graph resource identifier string |
add_triple(subject, predicate, object)
Adds triples according to the the pattern [subject,predicate,object]
Parameters
Name | Type | Description |
---|---|---|
subject | string|Var | The IRI of a triple’s subject or a variable |
predicate | string|Var | The IRI of a property or a variable |
object | string|Var | The IRI of a node or a variable, or a literal |
added_quad(subject, predicate, object, graphRef-)
Creates a pattern matching rule for the quad [S, P, O, G] (Subject, Predicate, Object, Graph) removed from the current commit
Parameters
Name | Type | Description |
---|---|---|
subject | string|Var | The IRI of a triple’s subject or a variable |
predicate | string|Var | The IRI of a property or a variable |
object | string|Var | The IRI of a node or a variable, or a literal |
graphRef- | typedef.GraphRef | A valid graph resource identifier string |
added_triple(subject, predicate, object)
Creates a triple pattern matching rule for the triple [S, P, O] (Subject, Predicate, Object) added in the current layer
Parameters
Name | Type | Description |
---|---|---|
subject | string|Var | The IRI of a triple’s subject or a variable |
predicate | string|Var | The IRI of a property or a variable |
object | string|Var | The IRI of a node or a variable, or a literal |
all(subject, predicate, object, graphRef)
Generates a query that by default matches all triples in a graph - identical to star() except for order of arguments
Parameters
Name | Type | Description |
---|---|---|
subject | string|Var | The IRI of a triple’s subject or a variable |
predicate | string|Var | The IRI of a property or a variable |
object | string|Var | The IRI of a node or a variable, or a literal |
graphRef | typedef.GraphRef | the resource identifier of a graph possible value are schema/{main - myschema - *} | instance/{main - myschema - *} | inference/{main - myschema - *} |
and(subqueries)
Logical conjunction of the contained queries - all queries must match or the entire clause fails
Parameters
Name | Type | Description |
---|---|---|
subqueries | WOQLQuery | A list of one or more woql queries to execute as a conjunction |
Examples
//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))
as(source, target, type)
Imports the value identified by Source to a Target variable
Parameters
Name | Type | Description |
---|---|---|
source | string|number|Var | Source |
target | string|Var | Target |
type | string | type to cast value to string|number etc... |
Examples
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])
boolean(bool)
Generates explicitly a JSON-LD literal boolean from the input
Parameters
Name | Type | Description |
---|---|---|
bool | boolean | true | false |
Examples
boolean(true)
//returns { "@type": "xsd:boolean", "@value": true }
client(client)
Use instead to run your query woqlclient.query('myWOQLQuery')
Parameters
Name | Type | Description |
---|---|---|
client | WOQLClient |
comment(comment, subquery)
Adds a text comment to a query - can also be used to wrap any part of a query to turn it off
Parameters
Name | Type | Description |
---|---|---|
comment | string | text comment |
subquery | WOQLQuery | query that is "commented out" |
concat(varList, resultVarName)
takes a variable number of string arguments and concatenates them into a single string
Parameters
Name | Type | Description |
---|---|---|
varList | array|string|Var | a variable representing a list or a list of variables or strings - variables can be embedded in the string if they do not contain spaces |
resultVarName | string|Var | A variable or string containing the output string |
Examples
let [first_name, last_name, full_name] = vars("first_name", "last_name", "full_name")
concat([first_name, " ", last_name], full_name)
count(countVarName, subquery)
Creates a count of the results of the query
Parameters
Name | Type | Description |
---|---|---|
countVarName | string|number|Var | variable or integer count |
subquery | WOQLQuery |
Examples
let [count, Person] = vars("count", "Person")
WOQL.count(count).triple(Person, "rdf:type", "@schema:Person")
date(date)
Generates explicitly a JSON-LD literal date from the imput
Parameters
Name | Type | Description |
---|---|---|
date | string | any date format string (YYYY-MM-DD) |
Examples
date("2022-10-02")
//returns { "@type": "xsd:date", "@value": "2022-10-02" }
datetime(datetime)
Generates explicitly a JSON-LD literal datetime from the imput
Parameters
Name | Type | Description |
---|---|---|
datetime | string | any datetime format string (YYYY-MM-DDThh-mm-ssZ) |
Examples
datetime("2022-10-19T14:17:12Z")
//returns { "@type": "xsd:dateTime", "@value": "2022-10-19T14:17:12Z" }
delete_document(IRI)
Delete a document from the graph.
Parameters
Name | Type | Description |
---|---|---|
IRI | string | The document id or a variable |
delete_quad(subject, predicate, object, graphRef)
Deletes a single triple from the graph [Subject, Predicate, Object, Graph]
Parameters
Name | Type | Description |
---|---|---|
subject | string|Var | The IRI of a triple’s subject or a variable |
predicate | string|Var | The IRI of a property or a variable |
object | string|Var | The IRI of a node or a variable, or a literal |
graphRef | typedef.GraphRef | A valid graph resource identifier string |
Examples
remove the class Person from the schema graph
WOQL.delete_quad("Person", "rdf:type", "sys:Class", "schema")
delete_triple(subject, predicate, object)
Deletes a single triple from the default graph of the database
Parameters
Name | Type | Description |
---|---|---|
subject | string|Var | The IRI of a triple’s subject or a variable |
predicate | string|Var | The IRI of a property or a variable |
object | string|Var | The IRI of a node or a variable, or a literal |
Examples
delete_triple("john", "age", 42)
distinct(varNames)
Filter the query to return only results that are distinct in the given variables
Parameters
Name | Type | Description |
---|---|---|
varNames | string|Var | these variables are guaranteed to be unique as a tuple |
div(args)
Division - integer division - args are divided left to right
Parameters
Name | Type | Description |
---|---|---|
args | string|number|Var | numbers for division |
Examples
let [result] = vars("result")
evaluate(div(10, 3), result)
//result contains 3
divide(args)
Divides numbers N1...Nn by each other left, to right precedence
Parameters
Name | Type | Description |
---|---|---|
args | string|number|Var | numbers to tbe divided |
doc(object)
Produces an encoded form of a document that can be used by a WOQL operation such as `WOQL.insert_document`.
Parameters
Name | Type | Description |
---|---|---|
object | object | Document to encode |
Examples
const doc = WOQL.doc({ "@type": "Person", name: "Newperson" })
dot(document, field, value)
Extract the value of a key in a bound document.
Parameters
Name | Type | Description |
---|---|---|
document | string|Var | Document which is being accessed. |
field | string|Var | The field from which the document which is being accessed. |
value | string|Var | The value for the document and field. |
emerge(auto_eval)
query module allow you to use WOQL words as top level functions
Parameters
Name | Type | Description |
---|---|---|
auto_eval | * |
eq(varName, varValue)
Matches if a is equal to b
Parameters
Name | Type | Description |
---|---|---|
varName | string|Var | literal, variable or id |
varValue | string|Var | literal, variable or id |
eval(arithExp, resultVarName)
Evaluates the passed arithmetic expression and generates or matches the result value
Parameters
Name | Type | Description |
---|---|---|
arithExp | object|WOQLQuery|string | query or JSON-LD representing the query |
resultVarName | string|Var | output variable |
evaluate(arithExp, resultVarName)
Evaluates the passed arithmetic expression and generates or matches the result value
Parameters
Name | Type | Description |
---|---|---|
arithExp | object|WOQLQuery|string | A WOQL query containing a valid WOQL Arithmetic Expression, which is evaluated by the function |
resultVarName | string|number|Var | 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 |
Examples
let [result] = vars("result")
evaluate(plus(2, minus(3, 1)), result)
exp(varNum, expNum)
Exponent - raises varNum01 to the power of varNum02
Parameters
Name | Type | Description |
---|---|---|
varNum | string|number|Var | 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 |
Examples
let [result] = vars("result")
evaluate(exp(3, 2), result)
//result contains 9
floor(varNum)
Generates the nearest lower integer to the passed number
Parameters
Name | Type | Description |
---|---|---|
varNum | string|number|Var | Variable or numeric containing the number to be floored |
Examples
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
from(graphRef-, query)
Specifies the database URL that will be the default database for the enclosed query
Parameters
Name | Type | Description |
---|---|---|
graphRef- | typedef.GraphRef | A valid graph resource identifier string |
query | WOQLQuery | The query |
get(asvars, queryResource)
Use the document inteface to import documents
Parameters
Name | Type | Description |
---|---|---|
asvars | Vars|array.<Var> | an array of AsVar variable mappings (see as for format below) |
queryResource | WOQLQuery | an external resource (remote, file, post) to query |
Examples
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
graph(graphRef)
Sets the graph resource ID that will be used for subsequent chained function calls
Parameters
Name | Type | Description |
---|---|---|
graphRef | typedef.GraphRef | Resource String identifying the graph which will be used for subsequent chained schema calls |
Examples
WOQL.graph("schema")
//equivalent to add_quad("MyClass", "label", "My Class Label", "schema/main")
greater(varNum01, varNum02)
Compares the value of v1 against v2 and returns true if v1 is greater than v2
Parameters
Name | Type | Description |
---|---|---|
varNum01 | string|number|Var | a variable or numeric containing the number to be compared |
varNum02 | string|number|Var | a variable or numeric containing the second comporator |
Examples
let [result] = vars("result")
greater(1.2, 1.1).eq(result, literal(true, "boolean"))
//result contains true
group_by(varList, patternVars, resultVarName, subquery)
Groups the results of the contained subquery on the basis of identical values for Groupvars, extracts the patterns defined in PatternVars and stores the results in GroupedVar
Parameters
Name | Type | Description |
---|---|---|
varList | array|string|Var | Either a single variable or an array of variables |
patternVars | array|string|Var | Either a single variable or an array of variables |
resultVarName | string|Var | output variable name |
subquery | WOQLQuery | The query whose results will be grouped |
Examples
//subquery is an argument or a chained query
let [age, last_name, first_name, age_group, person] = vars("age", "last name", "first name",
"age group", "person")
group_by(age, [last_name, first_name], age_group)
.triple(person, "first_name", first_name)
.triple(person, "last_name", last_name)
.triple(person, "age", age)
idgen(prefix, inputVarList, resultVarName)
Generate a new IRI from the prefix and concatention of the variables
Parameters
Name | 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|Var | An array of variables and / or strings from which the unique hash will be generated |
resultVarName | string|Var | Variable in which the unique ID is stored |
Examples
let [newid] = vars("newid")
idgen("doc:Person", ["John", "Smith"], newid)
immediately(subquery)
Runs the query without backtracking on side-effects
Parameters
Name | Type | Description |
---|---|---|
subquery | string|WOQLQuery | WOQL Query objects |
insert(classId, classType, graphRef)
Inserts a single triple into the database declaring the Node to have type Type, optionally into the specified graph
Parameters
Name | Type | Description |
---|---|---|
classId | string|Var | IRI string or variable containing the IRI of the node to be inserted |
classType | string|Var | IRI string or variable containing the IRI of the type of the node (class/document name) |
graphRef | typedef.GraphRef | Optional Graph resource identifier |
Examples
insert("mydoc", "MyType")
//equivalent to add_triple("mydoc", "rdf:type", "@schema:MyType")
insert_document(docjson, IRI)
Insert a document in the graph.
Parameters
Name | 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. |
Examples
const res = await client.query(
WOQL.insert_document(WOQL.doc({ "@type" : "Person", "label": "John" }))
)
into(graphRef-, subquery)
Specifies the graph resource to write the contained query into
Parameters
Name | Type | Description |
---|---|---|
graphRef- | typedef.GraphRef | A valid graph resource identifier string |
subquery | WOQLQuery | The query which will be written into the graph |
Examples
//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
iri(val)
Explicitly sets a value to be an IRI - avoiding automatic type marshalling
Parameters
Name | Type | Description |
---|---|---|
val | string | string which will be treated as an IRI |
isa(instanceIRI, classId)
Tests whether a given instance IRI has type Class, according to the current state of the DB
Parameters
Name | Type | Description |
---|---|---|
instanceIRI | string|Var | A string IRI or a variable that identify the class instance |
classId | string|Var | A Class IRI or a variable |
Examples
let [subject] = vars("subject")
isa(subject, "Person")
join(varList, glue, resultVarName)
Joins a list variable together (Input) into a string variable (Output) by glueing the strings together with Glue
Parameters
Name | Type | Description |
---|---|---|
varList | string|array|Var | a variable representing a list or a list of strings and / or variables |
glue | string|Var | A variable (v:glue) or (glue) string representing the characters to put in between the joined strings in input |
resultVarName | string|Var | A variable or string containing the output string |
Examples
let [sentence] = vars("sentence")
join(["joe", "has", "a", "hat", " ", sentence)
json(JSON_LD)
Generates a WOQLQuery object from the passed WOQL JSON - if an argument is passed, the query object is created from it, if none is passed, the current state is returned as a JSON-LD
Parameters
Name | Type | Description |
---|---|---|
JSON_LD | object | JSON-LD woql document encoding a query |
length(inputVarList, resultVarName)
Calculates the length of the list in va and stores it in vb
Parameters
Name | Type | Description |
---|---|---|
inputVarList | string|array | Either a variable representing a list or a list of variables or literals |
resultVarName | string|Var | A variable in which the length of the list is stored or the length of the list as a non-negative integer |
Examples
let [count] = vars("count")
length(["john", "joe", "frank"], count)
less(varNum01, varNum02)
Compares the value of v1 against v2 and returns true if v1 is less than v2
Parameters
Name | Type | Description |
---|---|---|
varNum01 | string|number|Var | a variable or numeric containing the number to be compared |
varNum02 | string|number|Var | a variable or numeric containing the second comporator |
Examples
let [result] = vars("result")
less(1, 1.1).eq(result, literal(true, "boolean"))
//result contains true
lib()
get the predefined library query [WOQLLibrary](/api/woqlLibrary.js?id=WOQLLibrary)
Examples
//get commits older than the specified commit id
const query = WOQL.lib().previousCommits('m8vpxewh2aovfauebfkbzwmj4qwr5lb')
//return the commits of a specific branch starting from the head
//you can add the limit (how many results to return.) and the start point
//if a timestamp is given, gets the commits before the specified timestamp
//WOQL.lib().commits(branch='main',limit=0,start=0,timestamp=0)
const query = WOQL.lib().commits('main',10,2,1630683082.9278786)
//return the branches list with the timestamp and commits id
const query = WOQL.lib().branches()
like(stringA, stringB, distance)
Generates a string Leverstein distance measure between stringA and stringB
Parameters
Name | Type | Description |
---|---|---|
stringA | string|Var | string literal or variable representing a string to be compared |
stringB | string|Var | string literal or variable representing the other string to be compared |
distance | number|string|Var | variable representing the distance between the variables |
Examples
let [dist] = vars('dist')
like("hello", "hallo", dist)
//dist contains 0.7265420560747664
limit(limit, subquery)
Specifies a maximum number of results that will be returned from the subquery
Parameters
Name | Type | Description |
---|---|---|
limit | number|string | A variable that refers to an non-negative integer or a non-negative integer |
subquery | WOQLQuery | A subquery whose results will be limited |
Examples
let [a, b, c] = vars("a", "b", "c")
limit(100).triple(a, b, c)
//subquery is an argument or a chained query
limit(100,triple(a, b, c))
link(subject, predicate, object)
Creates a pattern matching rule for a triple [Subject, Predicate, Object]
Parameters
Name | Type | Description |
---|---|---|
subject | string|Var | The IRI of a triple’s subject or a variable |
predicate | string|Var | The IRI of a property or a variable |
object | string|Var | The IRI of a node or a variable, or a literal |
literal(val, type)
Generates explicitly a JSON-LD string literal from the input
Parameters
Name | Type | Description |
---|---|---|
val | string | any literal type |
type | string | an xsd or xdd type |
Examples
literal(1, "nonNegativeInteger")
//returns { "@type": "xsd:nonNegativeInteger", "@value": 1 }
lower(inputVarName, resultVarName)
Changes a string to lower-case
Parameters
Name | Type | Description |
---|---|---|
inputVarName | string|Var | string or variable representing the non-lowercased string |
resultVarName | string|Var | variable that stores the lowercased string output |
Examples
let [lower] = var("l")
lower("aBCe", lower)
//lower contains "abce"
member(element, list)
Matches if List includes Element
Parameters
Name | Type | Description |
---|---|---|
element | string|object|Var | Either a variable, IRI or any simple datatype |
list | string|array|Var | List ([string, literal] or string*) Either a variable representing a list or a list of variables or literals |
Examples
let [name] = vars("name")
member(name, ["john", "joe", "frank"])
minus(args)
Subtracts Numbers N1..Nn
Parameters
Name | Type | Description |
---|---|---|
args | string|number|Var | variable or numeric containing the value that will be subtracted from |
Examples
let [result] = vars("result")
evaluate(minus(2.1, plus(0.2, 1)), result)
node(nodeid, chainType)
Specifies the identity of a node that can then be used in subsequent builder functions. Note that node() requires subsequent chained functions to complete the triples / quads that it produces - by itself it only generates the subject.
Parameters
Name | Type | Description |
---|---|---|
nodeid | string|Var | The IRI of a node or a variable containing an IRI which will be the subject of the builder functions |
chainType | typedef.FuntionType | Optional type of builder function to build (default is triple) |
Examples
node("mydoc").label("my label")
//equivalent to triple("mydoc", "label", "my label")
not(subquery)
Logical negation of the contained subquery - if the subquery matches, the query will fail to match
Parameters
Name | Type | Description |
---|---|---|
subquery | string|WOQLQuery | A subquery which will be negated |
Examples
let [subject, label] = vars("subject", "label")
not().triple(subject, 'label', label)
nuke(graphRef)
Deletes all triples in the passed graph (defaults to instance/main)
Parameters
Name | Type | Description |
---|---|---|
graphRef | typedef.GraphRef | Resource String identifying the graph from which all triples will be removed |
Examples
nuke("schema/main")
//will delete everything from the schema/main graph
once(subquery)
Results in one solution of the subqueries
Parameters
Name | Type | Description |
---|---|---|
subquery | string|WOQLQuery | WOQL Query objects |
opt(subquery)
Specifies that the Subquery is optional - if it does not match the query will not fail
Parameters
Name | Type | Description |
---|---|---|
subquery | WOQLQuery | A subquery which will be optionally matched |
Examples
let [subject] = vars("subject")
opt(triple(subject, 'label', "A"))
//Subq is an argument or a chained query
opt().triple(subject, 'label', "A")
or(subqueries)
Creates a logical OR of the arguments
Parameters
Name | Type | Description |
---|---|---|
subqueries | WOQLQuery | A list of one or more woql queries to execute as alternatives |
Examples
let [Subject] = vars("Subject")
or(
triple(Subject, 'label', "A"),
triple(Subject, "label", "a")
)
order_by(varNames)
Orders the results of the contained subquery by a precedence list of variables
Parameters
Name | Type | Description |
---|---|---|
varNames | string|Var|array | A sequence of variables, by which to order the results, each optionally followed by either “asc” or “desc” to represent order as a list, by default it will sort the variable in ascending order |
Examples
let [A, B, C] = vars("A", "B", "C")
WOQL.order_by(A, [B, "asc"], [C, "desc"]).triple(A, B, C);
pad(inputVarName, pad, len, resultVarName)
Pads out the string input to be exactly len long by appending the pad character pad to form output
Parameters
Name | Type | Description |
---|---|---|
inputVarName | string|Var | The input string or variable in unpadded state |
pad | string|Var | The characters to use to pad the string or a variable representing them |
len | number|string|Var | The variable or integer value representing the length of the output string |
resultVarName | string|Var | stores output |
Examples
let [fixed] = vars("fixed length")
pad("joe", " ", 8, fixed)
//fixed contains "joe "
path(subject, pattern, object, resultVarName)
Performs a path regular expression match on the graph
Parameters
Name | Type | Description |
---|---|---|
subject | string|Var | An IRI or variable that refers to an IRI representing the subject, i.e. the starting point of the path |
pattern | string | (string) - A path regular expression describing a pattern through multiple edges of the graph (see: https://terminusdb.com/docs/path-query-reference-guide) |
object | string|Var | An IRI or variable that refers to an IRI representing the object, i.e. ending point of the path |
resultVarName | string|Var | A variable in which the actual paths traversed will be stored |
Examples
let [person, grand_uncle, lineage] = vars("person", "grand uncle", "lineage")
path(person, "((father|mother) {2,2}), brother)", grand_uncle, lineage)
plus(args)
Adds the numbers together
Parameters
Name | Type | Description |
---|---|---|
args | string|number|Var | a variable or numeric containing the values to add |
Examples
let [result] = vars("result")
evaluate(plus(2, plus(3, 1)), result)
post(url, formatObj, source)
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
Parameters
Name | 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' |
Examples
post("/.../.../", {type:'csv'})
put(varsToExp, query, fileResource)
Use the document inteface to import documents
Parameters
Name | Type | Description |
---|---|---|
varsToExp | Vars|array.<Var> | 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 |
quad(subject, predicate, object, graphRef)
Creates a pattern matching rule for the quad [S, P, O, G] (Subject, Predicate, Object, Graph)
Parameters
Name | Type | Description |
---|---|---|
subject | string|Var | The IRI of a triple’s subject or a variable |
predicate | string|Var | The IRI of a property or a variable |
object | string|Var | The IRI of a node or a variable, or a literal |
graphRef | typedef.GraphRef | A valid graph resource identifier string |
query()
Generates an empty WOQLQuery object
Examples
let q = query()
//then q.triple(1, 1) ...
re(pattern, inputVarName, resultVarList)
Matches the regular expression defined in Patern against the Test string, to produce the matched patterns in Matches
Parameters
Name | Type | Description |
---|---|---|
pattern | string | string or variable using normal PCRE regular expression syntax with the exception that special characters have to be escaped twice (to enable transport in JSONLD) |
inputVarName | string|Var | string or variable containing the string to be tested for patterns with the regex |
resultVarList | string|array|object|Var | variable representing the list of matches or a list of strings or variables |
Examples
let [All, Sub] = vars("All", "Sub")
WOQL.re("h(.).*", "hello", [All, Sub])
//e contains 'e', llo contains 'llo'
//p is a regex pattern (.*) using normal regular expression syntax, the only unusual
thing is that special characters have to be escaped twice, s is the string to be matched
and m is a list of matches:
read_document(IRI, output)
Read a node identified by an IRI as a JSON-LD document
Parameters
Name | Type | Description |
---|---|---|
IRI | string | The document id or a variable to read |
output | string | Variable which will be bound to the document. |
Examples
let [person] = vars("Person")
const query = WOQL.read_document(
"Person/0b4feda109d9d13c9da809090b342ad9e4d8185545ce05f7cd20b97fe458f547",
person
);
const res = await client.query(query);
read_object()
Use {@link #read_document|read_document} instead.
remote(remoteObj, formatObj)
Identifies a remote resource by URL and specifies the format of the resource through the options
Parameters
Name | Type | Description |
---|---|---|
remoteObj | object | The URL at which the remote resource can be accessed |
formatObj | typedef.DataFormatObj | The format of the resource data {} |
Examples
remote({url:"http://url.of.resource"}, {type: "csv"})
removed_quad(subject, predicate, object, graphRef-)
Creates a pattern matching rule for the quad [S, P, O, G] (Subject, Predicate, Object, Graph) removed from the current commit
Parameters
Name | Type | Description |
---|---|---|
subject | string|Var | The IRI of a triple’s subject or a variable |
predicate | string|Var | The IRI of a property or a variable |
object | string|Var | The IRI of a node or a variable, or a literal |
graphRef- | typedef.GraphRef | A valid graph resource identifier string |
removed_triple(subject, predicate, object)
Creates a triple pattern matching rule for the triple [S, P, O] (Subject, Predicate, Object) added in the current commit
Parameters
Name | Type | Description |
---|---|---|
subject | string|Var | The IRI of a triple’s subject or a variable |
predicate | string|Var | The IRI of a property or a variable |
object | string|Var | The IRI of a node or a variable, or a literal |
select(varNames)
Parameters
Name | Type | Description |
---|---|---|
varNames | string|Var | only these variables are returned |
Examples
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
size(resourceId, resultVarName)
Calculates the size in bytes of the contents of the resource identified in ResourceID
Parameters
Name | Type | Description |
---|---|---|
resourceId | string|Var | A valid resource identifier string (can refer to any graph / branch / commit / db) |
resultVarName | string|Var | The variable name |
Examples
let [varSize] = vars("varSize")
size("admin/minecraft/local/branch/main/instance/main", varSize)
//returns the number of bytes in the main instance graph on the main branch
split(inputVarName, separator, resultVarName)
Splits a string (Input) into a list strings (Output) by removing separator
Parameters
Name | Type | Description |
---|---|---|
inputVarName | string|Var | A string or variable representing the unsplit string |
separator | string|Var | A string or variable containing a sequence of charatcters to use as a separator |
resultVarName | string|Var | variable that stores output list |
Examples
let [words] = vars("words")
split("joe has a hat", " ", words)
star(graph, subject, predicate, object)
Generates a query that by default matches all triples in a graph identified by "graph" or in all the current terminusDB's graph
Parameters
Name | Type | Description |
---|---|---|
graph | string|boolean | false or the resource identifier of a graph possible value are schema/{main - myschema - *} | instance/{main - myschema - *} | inference/{main - myschema - *} |
subject | string|Var | The IRI of a triple’s subject or a variable, default value "v:Subject" |
predicate | string|Var | The IRI of a property or a variable, default value "v:Predicate" |
object | string|Var | The IRI of a node or a variable, or a literal, default value "v:Object" |
Examples
star("schema/main")
//will return every triple in schema/main graph
start(start, subquery)
Specifies an offset position in the results to start listing results from
Parameters
Name | Type | Description |
---|---|---|
start | number|string|Var | A variable that refers to an interger or an integer literal |
subquery | WOQLQuery | WOQL Query object, you can pass a subquery as an argument or a chained query |
Examples
let [a, b, c] = vars("a", "b", "c")
start(100).triple(a, b, c)
string(val)
Generates explicitly a JSON-LD string literal from the input
Parameters
Name | Type | Description |
---|---|---|
val | string|boolean|number | any primitive literal type |
Examples
string(1)
//returns { "@type": "xsd:string", "@value": "1" }
sub(classA, classB)
Returns true if ClassA subsumes ClassB, according to the current DB schema
Parameters
Name | Type | Description |
---|---|---|
classA | string | ClassA |
classB | string | ClassB |
substr(string, before, length, after, substring)
Substring
Parameters
Name | Type | Description |
---|---|---|
string | string|Var | String or variable |
before | number|Var | integer or variable (characters from start to begin) |
length | number|Var | integer or variable (length of substring) |
after | number|Var | integer or variable (number of characters after substring) |
substring | string|Var | String or variable |
sum(subquery, total)
computes the sum of the List of values passed. In contrast to other arithmetic functions, sum self-evaluates - it does not have to be passed to evaluate()
Parameters
Name | Type | Description |
---|---|---|
subquery | WOQLQuery | a subquery or ([string or numeric]) - a list variable, or a list of variables or numeric literals |
total | string|Var | the variable name with the sum result of the values in List |
Examples
let [total] = vars("total")
sum([2, 3, 4, 5], total)
times(args)
Multiplies numbers N1...Nn together
Parameters
Name | Type | Description |
---|---|---|
args | string|number|Var | a variable or numeric containing the value |
Examples
let [result] = vars("result")
evaluate(times(10, minus(2.1, plus(0.2, 1))), result)
//result contains 9.000000000000002y
trim(inputStr, resultVarName)
Remove whitespace from both sides of a string:
Parameters
Name | Type | Description |
---|---|---|
inputStr | string|Var | A string or variable containing the untrimmed version of the string |
resultVarName | string|Var | A string or variable containing the trimmed version of the string |
Examples
let [trimmed] = vars("trimmed")
trim("hello ", trimmed)
//trimmed contains "hello"
triple(subject, predicate, object)
Creates a triple pattern matching rule for the triple [S, P, O] (Subject, Predicate, Object)
Parameters
Name | Type | Description |
---|---|---|
subject | string|Var | The IRI of a triple’s subject or a variable |
predicate | string|Var | The IRI of a property or a variable |
object | string|Var | The IRI of a node or a variable, or a literal |
triple_count(resourceId, tripleCount)
Calculates the number of triples of the contents of the resource identified in ResourceID
Parameters
Name | Type | Description |
---|---|---|
resourceId | string|Var | A valid resource identifier string (can refer to any graph / branch / commit / db) |
tripleCount | string|number|Var | An integer literal with the size in bytes or a variable containing that integer |
Examples
let [count] = vars("count")
triple_count("admin/minecraft/local/_commits", count)
//returns the number of bytes in the local commit graph
true()
A function that always matches, always returns true
Examples
when(true()).triple("a", "b", "c")
type_of(elementId, elementType)
Returns true if 'elementId' is of type 'elementType', according to the current DB schema
Parameters
Name | Type | Description |
---|---|---|
elementId | string|Var | the id of a schema graph element |
elementType | string|Var | the element type |
typecast(varName, varType, resultVarName)
Casts the value of Input to a new value of type Type and stores the result in CastVar
Parameters
Name | Type | Description |
---|---|---|
varName | string|number|object|Var | Either a single variable or a literal of any basic type |
varType | string|Var | Either a variable or a basic datatype (xsd / xdd) |
resultVarName | string|Var | save the return variable |
Examples
let [time] = vars("time")
cast("22/3/98", "xsd:dateTime", time)
unique(prefix, inputVarList, resultVarName)
Generate a new IRI from the prefix and a hash of the variables which will be unique for any given combination of variables
Parameters
Name | 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|Var | An array of variables and / or strings from which the unique hash will be generated |
resultVarName | string|Var | Variable in which the unique ID is stored |
Examples
let [newid] = vars("newid")
unique("doc:Person", ["John", "Smith"], newid)
update_document(docjson, IRI)
Update a document identified by an IRI
Parameters
Name | 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. |
update_quad(subject, predicate, newObject, graphRef)
Update a pattern matching rule for the quad [S, P, O, G] (Subject, Predicate, Object, Graph)
Parameters
Name | Type | Description |
---|---|---|
subject | string|Var | The IRI of a triple’s subject or a variable |
predicate | string|Var | The IRI of a property or a variable |
newObject | string|Var | The value to update or a literal |
graphRef | typedef.GraphRef | A valid graph resource identifier string |
update_triple(subject, predicate, newObjValue, oldObjValue)
Update a pattern matching rule for the triple (Subject, Predicate, oldObjValue) with the new one (Subject, Predicate, newObjValue)
Parameters
Name | Type | Description |
---|---|---|
subject | string|Var | The IRI of a triple’s subject or a variable |
predicate | string|Var | The IRI of a property or a variable |
newObjValue | string|Var | The value to update or a literal |
oldObjValue | string|Var | The old value of the object |
upper(inputVarName, resultVarName)
Changes a string to upper-case
Parameters
Name | Type | Description |
---|---|---|
inputVarName | string|Var | string or variable representing the uncapitalized string |
resultVarName | string|Var | variable that stores the capitalized string output |
Examples
let [allcaps] = vars("allcaps")
upper("aBCe", allcaps)
//upper contains "ABCE"
using(refPath, subquery)
Query running against any specific commit Id
Parameters
Name | Type | Description |
---|---|---|
refPath | string | path to specific reference Id or commit Id |
subquery | WOQLQuery | subquery for the specific commit point |
Examples
let [a, b, c] = vars("a", "b", "c")
WOQL.using("userName/dbName/local/commit|branch/commitID").triple(a, b, c)
value(subject, predicate, objValue)
Creates a pattern matching rule for a triple [Subject, Predicate, Object] add extra information about the type of the value object
Parameters
Name | Type | Description |
---|---|---|
subject | string|Var | The IRI of a triple’s subject or a variable |
predicate | string|Var | The IRI of a property or a variable |
objValue | string|number|boolean|Var | an specific value |
vars(varNames)
Generates javascript variables for use as WOQL variables within a query
Parameters
Name | Type | Description |
---|---|---|
varNames | string |
Examples
const [a, b, c] = WOQL.vars("a", "b", "c")
//a, b, c are javascript variables which can be used as WOQL variables in subsequent queries
WOQLClient
action(actionName, payload)
Sends an action to the server
Parameters
Name | Type | Description |
---|---|---|
actionName | string | structure of the action |
payload | object | a request body call |
addDocument(json, params, dbId, string, lastDataVersion, getDataVersion)
to add a new document or a list of new documents into the instance or the schema graph.
Parameters
Name | Type | Description |
---|---|---|
json | object | |
params | typedef.DocParamsPost | the post parameters {@link #typedef.DocParamsPost} |
dbId | string | the dbid |
string | message | the insert commit message |
lastDataVersion | string | the last data version tracking id. |
getDataVersion | boolean | If true the function will return object having result and dataVersion. |
Examples
const json = [{ "@type" : "Class",
"@id" : "Coordinate",
"@key" : { '@type' : 'Hash',
'@fields' : ['x','y'] },
"x" : "xsd:decimal",
"y" : "xsd:decimal" },
{ "@type" : "Class",
"@id" : "Country",
"@key" : { '@type' : 'Lexical',
'@fields' : [name] },
"name" : "xsd:string",
"perimeter" : { "@type" : "List",
"@class" : "Coordinate" } }]
client.addDocument(json,{"graph_type":"schema"},"mydb","add new schema documents")
//if we would like to override the entire schema
const json = [
{"@base": "terminusdb:///data/",
"@schema": "terminusdb:///schema#",
"@type": "@context"
},
{
"@id": "Person",
"@key": {
"@type": "Random"
},
"@type": "Class",
"name": {
"@class": "xsd:string",
"@type": "Optional"
}
}]
// client.addDocument(json,{"graph_type":"schema","full_replace:true"},
"mydb","update the all schema");
// Here we will pass true to show how to get dataVersion
const response = await client.addDocument(json, {"graph_type": "schema"},
"mydb",
"add new schema", '',
true
)
console.log(response);
// This will output:
// {
// result: [ ...... ],
// dataVersion: 'branch:5fs681tlycnn6jh0ceiqcq4qs89pdfs'
// }
// Now we can use the data version we recieved as a response in previous
// function call and used it is next function call as lastDataVersion
const response1 = await client.addDocument(json, {"graph_type": "schema"},
"mydb",
"add new schema", response.dataVersion,
)
api()
Retrieve the URL of the server’s API base that we are currently connected to
Examples
let api_url = client.api()
apply(beforeVersion, afterVersion, message, matchFinalState, options)
Diff two different commits and apply changes on the current branch/commit. If you would like to change branch or commit before apply use client.checkout("branchName")
Parameters
Name | Type | Description |
---|---|---|
beforeVersion | string | Before branch/commit to compare |
afterVersion | string | After branch/commit to compare |
message | string | apply commit message |
matchFinalState | boolean | the default value is false |
options | object | {keep:{}} Options to send to the apply endpoint |
Examples
client.checkout("mybranch")
client.apply("mybranch","mybranch_new","merge main").then(result=>{
console.log(result)
})
author()
Gets the string that will be written into the commit log for the current user
Examples
client.author()
branch(newBranchId, isEmpty)
Creates a new branch with a TerminusDB database, starting from the current context of the client (branch / ref)
Parameters
Name | Type | Description |
---|---|---|
newBranchId | string | local identifier of the new branch the ID of the new branch to be created |
isEmpty | boolean | if isEmpty is true it will create a empty branch. |
Examples
client.branch("dev")
checkout(branchId)
Gets/Sets the client’s internal branch context value (defaults to ‘main’)
Parameters
Name | Type | Description |
---|---|---|
branchId | string | the branch id to set the context to |
clonedb(cloneSource, newDbId, orgId)
Clones a remote repo and creates a local copy
Parameters
Name | Type | Description |
---|---|---|
cloneSource | typedef.CloneSourceDetails | object describing the source branch to be used as a base |
newDbId | string | id of the new cloned database on the local server |
orgId | string | id of the local organization that the new cloned database will be created in (in desktop mode this is always “admin”) |
Examples
client.clonedb({remote_url: "https://my.terminusdb.com/myorg/mydb", label "Cloned DB", comment: "Cloned from mydb"}, newid: "mydb")
connect(params)
You can call this to get the server info or override the start params configuration, this.connectionConfig.server will be used if present, or the promise will be rejected.
Parameters
Name | Type | Description |
---|---|---|
params | typedef.ParamsObj | TerminusDB Server connection parameters |
Examples
client.connect()
copy()
creates a copy of the client with identical internal state and context useful if we want to change context for a particular API call without changing the current client context
Examples
let newClient = client.copy()
createDatabase(dbId, dbDetails, orgId)
Creates a new database in TerminusDB server
Parameters
Name | Type | Description |
---|---|---|
dbId | string | The id of the new database to be created |
dbDetails | typedef.DbDetails | object containing details about the database to be created |
orgId | string | optional organization id - if absent default local organization id is used |
Examples
//remember set schema:true if you need to add a schema graph
client.createDatabase("mydb", {label: "My Database", comment: "Testing", schema: true})
customHeaders(customHeaders)
add extra headers to your request
Parameters
Name | Type | Description |
---|---|---|
customHeaders | object |
databaseInfo(dbName)
Gets the database's details
Parameters
Name | Type | Description |
---|---|---|
dbName | string | the datbase name |
databases(dbList)
Set/Get the organization's databases list (id, label, comment) that the current user has access to on the server.
Parameters
Name | Type | Description |
---|---|---|
dbList | array | a list of databases the user has access to on the server, each having: |
Examples
//to get the list of all organization's databases
async function callGetDatabases(){
await client.getDatabases()
console.log(client.databases())
}
db(dbId)
Sets / Gets the current database
Parameters
Name | Type | Description |
---|---|---|
dbId | string | the database id to set the context to |
Examples
client.db("mydb")
deleteBranch(branchId)
Deletes a branch from database
Parameters
Name | Type | Description |
---|---|---|
branchId | string | local identifier of the branch |
deleteDatabase(dbId, orgId, force)
Deletes a database from a TerminusDB server
Parameters
Name | Type | Description |
---|---|---|
dbId | string | The id of the database to be deleted |
orgId | string | the id of the organization to which the database belongs (in desktop use, this will always be “admin”) |
force | boolean |
Examples
client.deleteDatabase("mydb")
deleteDocument(params, dbId, message, lastDataVersion, getDataVersion)
to delete the document
Parameters
Name | Type | Description |
---|---|---|
params | typedef.DocParamsDelete | |
dbId | string | the database id |
message | string | the delete message |
lastDataVersion | string | the last data version tracking id. |
getDataVersion | boolean | If true the function will return object having result and dataVersion. |
Examples
client.deleteDocument({"graph_type":"schema",id:['Country','Coordinate']})
// Here we will pass true to show how to get dataVersion
const response = await client.deleteDocument({"graph_type":"schema",id:['Country','Coordinate']},
"",
"",
"",
true
)
console.log(response);
// This will output:
// {
// result: [ ...... ],
// dataVersion: 'branch:5fs681tlycnn6jh0ceiqcq4qs89pdfs'
// }
// Now we can use the data version we recieved as a response in previous
// function call and used it is next function call as lastDataVersion
const response1 = await client.deleteDocument({"graph_type":"schema",
id:['Country','Coordinate']},
"",
"",
response.dataVersion,
)
dispatch()
Common request dispatch function
fetch(remoteId)
Fetch updates to a remote database to a remote repository with the local database
Parameters
Name | Type | Description |
---|---|---|
remoteId | string | if of the remote to fetch (eg: 'origin') |
generateCommitDescriptor(commitId)
Generates the json structure for commit descriptor
Parameters
Name | Type | Description |
---|---|---|
commitId | string | a valid commit id o |
generateCommitInfo(msg, author)
Generates the json structure for commit messages
Parameters
Name | Type | Description |
---|---|---|
msg | string | textual string describing reason for the change |
author | string | optional author id string - if absent current user id will be used |
getBranches(dbId)
get the database collections list
Parameters
Name | Type | Description |
---|---|---|
dbId | string | the database id |
Examples
client.getBranches()
getClassDocuments(dbId)
get all the Document Classes (no abstract or subdocument)
Parameters
Name | Type | Description |
---|---|---|
dbId | string |
Examples
client.getClassDocuments()
getClasses(dbId)
get all the schema classes (documents,subdocuments,abstracts)
Parameters
Name | Type | Description |
---|---|---|
dbId | string | the database id |
Examples
client.getClasses()
getCommitsLog(start, count)
get the database collections list
Parameters
Name | Type | Description |
---|---|---|
start | number | where to start printing the commit information in the log (starting from the head of the current branch) |
count | number | The number of total commit log records to return |
Examples
client.getCommitsLog(count=10)
getDatabases()
Gets the organization's databases list. If no organization has been set up, the function throws an exception
Examples
async function callGetDatabases(){
const dbList = await client.getDatabases()
console.log(dbList)
}
getDocument(params, dbId, branch, lastDataVersion, getDataVersion, query)
Parameters
Name | Type | Description |
---|---|---|
params | typedef.DocParamsGet | the get parameters, you can pass document query search template with the params |
dbId | string | the database id |
branch | string | the database branch |
lastDataVersion | string | the last data version tracking id. |
getDataVersion | boolean | If true the function will return object having result and dataVersion. |
query | object | document query search template |
Examples
//return the schema graph as a json array
client.getDocument({"graph_type":"schema","as_list":true}).then(result={
console.log(result)
})
//retutn the Country class document from the schema graph
client.getDocument({"graph_type":"schema","as_list":true,"id":"Country"}).then(result={
console.log(result)
})
//pass a document query template to query the document interface
const queryTemplate = { "name": "Ireland"}
client.getDocument({"as_list":true, "@type":"Country"
query:queryTemplate}).then(result=>{
console.log(result)
})
// Here we will pass true to show how to get dataVersion
const response = await client.getDocument({"graph_type":"schema","as_list":true},
"",
"",
"",
true
)
console.log(response);
// This will output:
// {
// result: [ ...... ],
// dataVersion: 'branch:5fs681tlycnn6jh0ceiqcq4qs89pdfs'
// }
// Now we can use the data version we recieved as a response in previous
// function call and used it is next function call as lastDataVersion
const response1 = await client.getDocument({"graph_type":"schema","as_list":true},
"",
"",
response.dataVersion,
)
getDocumentHistory(id, historyParams)
Get the document's history for a specific database or branch
Parameters
Name | Type | Description |
---|---|---|
id | string | id of document to report history of |
historyParams | typedef.DocHistoryParams |
Examples
//this will return the last 5 commits for the Person/Anna document
client.checkout("mybranch")
client.docHistory("Person/Anna",{start:0,count:5}).then(result=>{
console.log(result)
})
//this will return the last and the first commit for the Person/Anna document
client.docHistory("Person/Anna",{updated:true,created:true}).then(result=>{
console.log(result)
})
getEnums(dbId)
get all the Enum Objects
Parameters
Name | Type | Description |
---|---|---|
dbId | string |
Examples
client.getEnums()
getJSONDiff(before, after, options)
Get the patch of difference between two documents.
Parameters
Name | Type | Description |
---|---|---|
before | object | The current state of JSON document |
after | object | The updated state of JSON document |
options | object | {keep:{}} Options to send to the diff endpoint. The diff api outputs the changes between the input, in options you can list the properties that you would like to see in the diff result in any case. |
Examples
client.getJSONDiff(
{ "@id": "Person/Jane", "@type": "Person", name: "Jane" },
{ "@id": "Person/Jane", "@type": "Person", name: "Janine" }
).then(diffResult=>{
console.log(diffResult)
})
//result example
//{'@id': 'Person/Jane',
// name: { '@after': 'Janine', '@before': 'Jane', '@op': 'SwapValue' }}
getPrefixes(dbId)
get the database prefixes object
Parameters
Name | Type | Description |
---|---|---|
dbId | string | the database id |
Examples
client.getPrefixes()
//return object example
{
'@base': 'terminusdb:///data/',
'@schema': 'terminusdb:///schema#',
'@type': 'Context'}
getSchema(dbId, branch)
get the database schema in json format
Parameters
Name | Type | Description |
---|---|---|
dbId | string | the database id |
branch | string | specific a branch/collection |
Examples
client.getSchema()
getSchemaFrame(type, dbId)
The purpose of this method is to quickly discover the supported fields of a particular type.
Parameters
Name | Type | Description |
---|---|---|
type | string | If given, the type to get information for. If omitted, information for all types is returned |
dbId | string | the database id |
Examples
client.getSchemaFrame("Country")
getTriples(graphType)
Retrieve the contents of a graph within a TerminusDB as triples, encoded in the turtle (ttl) format
Parameters
Name | Type | Description |
---|---|---|
graphType | typedef.GraphType | type of graph to get triples from, either “instance” or “schema” |
Examples
const turtle = await client.getTriples("schema", "alt")
getUserOrganizations()
Get the list of the user's organizations and the database related
Examples
async funtion callGetUserOrganizations(){
await getUserOrganizations()
console.log(client.userOrganizations())
}
getVersionDiff(beforeVersion, afterVersion, id, options)
Get the patch of difference between branches or commits.
Parameters
Name | Type | Description |
---|---|---|
beforeVersion | string | Before branch/commit to compare |
afterVersion | string | After branch/commit to compare |
id | string | The document id to be diffed, if it is omitted all the documents will be compared |
options | typedef.DiffObject | {keep:{},count:10,start:0} Options to send to the diff endpoint. The diff api outputs the changes between the input (branches or commits), in options you can list the properties that you would like to see in the diff result in any case. |
Examples
//This is to view all the changes between two commits
const beforeCommit = "a73ssscfx0kke7z76083cgswszdxy6l"
const afterCommit = "73rqpooz65kbsheuno5dsayh71x7wf4"
client.getVersionDiff( beforeCommit, afterCommit).then(diffResult=>{
console.log(diffResult)
})
//This is to view the changes between two commits but only for the given document
client.getVersionDiff( beforeCommit, afterCommit, "Person/Tom").then(diffResult=>{
console.log(diffResult)
})
//This is to view the changes between a branch (head) and a commit for the given document
client.getVersionDiff("main", afterCommit, "Person/Tom" ).then(diffResult=>{
console.log(diffResult)
})
//This is to view the changes between two branches with the keep options
const options = {"keep":{"@id":true, "name": true}, start:0, count:10}
client.getVersionDiff("main","mybranch",options).then(diffResult=>{
console.log(diffResult)
})
getVersionObjectDiff(dataVersion, jsonObject, id, options)
Get the patch of difference between two documents.
Parameters
Name | Type | Description |
---|---|---|
dataVersion | string | The version from which to compare the object |
jsonObject | object | The updated state of JSON document |
id | string | The document id to be diffed |
options | object | {keep:{}} Options to send to the diff endpoint the diff api outputs the changes between the input, but you can list the properties that you would like to see in the diff result in any case. |
Examples
const jsonObj = { "@id": "Person/Jane", "@type": "Person", name: "Janine" }
client.getVersionObjectDiff("main",jsonObj
"Person/Jane").then(diffResp=>{
console.log(diffResp)
})
hasDatabase(orgName, dbName)
Checks if a database exists Returns true if a DB exists and false if it doesn't. Other results throw an exception.
Parameters
Name | Type | Description |
---|---|---|
orgName | string | the organization id to set the context to |
dbName | string | the db name to set the context to |
Examples
async function executeIfDatabaseExists(f){
const hasDB = await client.hasDatabase("admin", "testdb")
if (hasDB) {
f()
}
}
info()
Gets TerminusDB Server Information
Examples
client.info()
insertTriples(graphType, turtle, commitMsg)
Appends the passed turtle to the contents of a graph
Parameters
Name | Type | Description |
---|---|---|
graphType | string | type of graph |instance|schema|inference| |
turtle | string | is a valid set of triples in turtle format (OWL) |
commitMsg | string | Textual message describing the reason for the update |
localAuth(newCredential)
Sets/Gets set the database basic connection credential
Parameters
Name | Type | Description |
---|---|---|
newCredential | typedef.CredentialObj |
Examples
client.localAuth({user:"admin","key":"mykey","type":"basic"})
message(message, pathname)
Sends a message to the server
Parameters
Name | Type | Description |
---|---|---|
message | string | textual string |
pathname | string | a server path to send the message to |
optimizeBranch(branchId)
Optimize db branch
Parameters
Name | Type | Description |
---|---|---|
branchId | string | local identifier of the new branch |
organization(orgId)
Gets/Sets the client’s internal organization context value, if you change the organization name the databases list will be set to empty
Parameters
Name | Type | Description |
---|---|---|
orgId | string|boolean | the organization id to set the context to |
Examples
client.organization("admin")
patch(before, patch)
Apply a patch object to another object
Parameters
Name | Type | Description |
---|---|---|
before | object | The current state of JSON document |
patch | object | The patch object |
Examples
client.patch(
{ "@id" : "Person/Jane", "@type" : "Person", "name" : "Jane"},
{ "name" : { "@op" : "ValueSwap", "@before" : "Jane", "@after": "Janine" }}
).then(patchResult=>{
console.log(patchResult)
})
//result example
//{ "@id" : "Person/Jane", "@type" : "Person", "name" : "Jannet"}
patchResource(patch, message)
Apply a patch object to the current resource
Parameters
Name | Type | Description |
---|---|---|
patch | array | The patch object |
message | string | The commit message |
Examples
const patch = [
{
"@id": "Obj/id1",
"name": {
"@op": "SwapValue",
"@before": "foo",
"@after": "bar"
}
},
{
"@id": "Obj/id2",
"name": {
"@op": "SwapValue",
"@before": "foo",
"@after": "bar"
}
}
]
client.db("mydb")
client.checkout("mybranch")
client.patchResource(patch,"apply patch to mybranch").then(patchResult=>{
console.log(patchResult)
})
// result example
// ["Obj/id1",
// "Obj/id2"]
// or conflict error 409
// {
// "@type": "api:PatchError",
// "api:status": "api:conflict",
// "api:witnesses": [
// {
// "@op": "InsertConflict",
// "@id_already_exists": "Person/Jane"
// }
//]
//}
prepareRevisionControlArgs(rc_args)
Adds an author string (from the user object returned by connect) to the commit message.
Parameters
Name | Type | Description |
---|---|---|
rc_args | object |
pull(remoteSourceRepo)
Pull changes from a branch on a remote database to a branch on a local database
Parameters
Name | Type | Description |
---|---|---|
remoteSourceRepo | typedef.RemoteRepoDetails | an object describing the source of the pull |
Examples
client.pull({remote: "origin", remote_branch: "main", message: "Pulling from remote"})
push(remoteTargetRepo)
Push changes from a branch on a local database to a branch on a remote database
Parameters
Name | Type | Description |
---|---|---|
remoteTargetRepo | typedef.RemoteRepoDetails | an object describing the target of the push {remote: "origin", "remote_branch": "main", "author": "admin", "message": "message"} |
Examples
client.push({remote: "origin", remote_branch: "main", message: "Pulling from remote"})
query(woql, commitMsg, allWitnesses, lastDataVersion, getDataVersion)
Executes a WOQL query on the specified database and returns the results
Parameters
Name | Type | Description |
---|---|---|
woql | WOQLQuery | an instance of the WOQLQuery class |
commitMsg | string | a message describing the reason for the change that will be written into the commit log (only relevant if the query contains an update) |
allWitnesses | boolean | |
lastDataVersion | string | the last data version tracking id. |
getDataVersion | boolean | If true the function will return object having result and dataVersion. |
Examples
const result = await client.query(WOQL.star())
queryDocument(query, params, dbId, branch, lastDataVersion, getDataVersion)
Use {@link #getDocument} instead.
Parameters
Name | Type | Description |
---|---|---|
query | object | the query template |
params | typedef.DocParamsGet | the get parameters |
dbId | string | the database id |
branch | string | the database branch |
lastDataVersion | string | the last data version tracking id. |
getDataVersion | boolean | If true the function will return object having result and dataVersion. |
Examples
const query = {
"type": "Person",
"query": { "age": 42 },
}
client.queryDocument(query, {"as_list":true})
// Here we will pass true to show how to get dataVersion
const query = {
"type": "Person",
"query": { "age": 42 },
}
const response = await client.queryDocument(query, {"as_list": true}, '', '','',true);
console.log(response);
// This will output:
// {
// result: [
// {
// '@id': 'Person/052d60ffbd114bf5e7331b03f07fcb7',
// '@type': 'Person',
// age: 42,
// name: 'John',
// },
// ],
// dataVersion: 'branch:5fs681tlycnn6jh0ceiqcq4qs89pdfs'
// }
// Now we can use the data version we recieved as a response in previous
// query and used it is next query as lastDataVersion
const query = {
"type": "Person",
"query": { "age": 18 },
}
const response1 = await client.queryDocument(query, {"as_list": true}, '',
'',
response.dataVersion
);
rebase(rebaseSource)
Merges the passed branch into the current one using the rebase operation
Parameters
Name | Type | Description |
---|---|---|
rebaseSource | object | json describing the source branch to be used as a base |
Examples
//from the branch head
client.rebase({rebase_from: "admin/db_name/local/branch/branch_name", message:
"Merging from dev")
//or from a commit id
client.rebase({rebase_from: "admin/db_name/local/commit/9w8hk3y6rb8tjdy961de3i536ntkqd8",
message: "Merging from dev")
ref(commitId)
Sets / gets the current ref pointer (pointer to a commit within a branch) Reference ID or Commit ID are unique hashes that are created whenever a new commit is recorded
Parameters
Name | Type | Description |
---|---|---|
commitId | string | the reference ID or commit ID |
Examples
client.ref("mkz98k2h3j8cqjwi3wxxzuyn7cr6cw7")
remoteAuth(newCredential)
Sets/Gets the jwt token for authentication we need this to connect 2 terminusdb server to each other for push, pull, clone actions
Parameters
Name | Type | Description |
---|---|---|
newCredential | typedef.CredentialObj |
Examples
client.remoteAuth({"key":"dhfmnmjglkrelgkptohkn","type":"jwt"})
repo(repoId)
Gets / Sets the client’s internal repository context value (defaults to ‘local’)
Parameters
Name | Type | Description |
---|---|---|
repoId | typedef.RepoType|string | default value is local |
Examples
client.repo("origin")
reset(commitPath)
Reset the current branch HEAD to the specified commit path
Parameters
Name | Type | Description |
---|---|---|
commitPath | string | The commit path to set the current branch to |
resetBranch(branchId, commitId)
Reset branch to a commit id, Reference ID or Commit ID are unique hashes that are created whenever a new commit is recorded
Parameters
Name | Type | Description |
---|---|---|
branchId | string | local identifier of the new branch |
commitId | string | Reference ID or Commit ID |
resource(resourceType, resourceId)
Generates a resource string for the required context of the current context for "commits" "meta" "branch" and "ref" special resources
Parameters
Name | Type | Description |
---|---|---|
resourceType | typedef.ResourceType | the type of resource string that is required - one of “db”, “meta”, “repo”, “commits”, “branch”, “ref” |
resourceId | string | can be used to specify a specific branch / ref - if not supplied the current context will be used |
Examples
const branch_resource = client.resource("branch")
sendCustomRequest(requestType, customRequestURL, payload)
Call a custom Api endpoit
Parameters
Name | Type | Description |
---|---|---|
requestType | string | The current state of JSON document |
customRequestURL | string | The patch object |
payload | object | the request payload |
Examples
client.sendCustomRequest("GET", "http://localhost:3030/changes/").then(result=>{
console.log(result)
})
server()
Gets the current connected server url it can only be set creating a new WOQLCLient instance
set(params)
Parameters
Name | Type | Description |
---|---|---|
params | typedef.ParamsObj | a object with connection params |
Examples
sets several of the internal state values in a single call
(similar to connect, but only sets internal client state, does not communicate with server)
client.set({key: "mypass", branch: "dev", repo: "origin"})
setApiKey(accessToken)
set the api key to access the cloud resources
Parameters
Name | Type | Description |
---|---|---|
accessToken | string |
setSystemDb()
Sets the internal client context to allow it to talk to the server’s internal system database
squashBranch(branchId, commitMsg)
Squash branch commits
Parameters
Name | Type | Description |
---|---|---|
branchId | string | local identifier of the new branch |
commitMsg | string | Textual message describing the reason for the update |
updateDatabase(dbDoc)
Update a database in TerminusDB server
Parameters
Name | Type | Description |
---|---|---|
dbDoc | typedef.DbDoc | object containing details about the database to be updated |
Examples
client.updateDatabase({id: "mydb", label: "My Database", comment: "Testing"})
updateDocument(json, params, dbId, message, lastDataVersion, getDataVersion, compress, create)
Parameters
Name | Type | Description |
---|---|---|
json | object | |
params | typedef.DocParamsPut | the Put parameters {@link #typedef.DocParamsPut} |
dbId | * | the database id |
message | * | the update commit message |
lastDataVersion | string | the last data version tracking id. |
getDataVersion | boolean | If true the function will return object having result and dataVersion. |
compress | boolean | If true, the function will create a new document if it doesn't exist. |
create | boolean | Perform an *upsert* which inserts if the document is not present (also works on nested documents) |
Examples
client.updateDocument(
{
"@id": "Person",
"@key": {
"@type": "Random",
},
"@type": "Class",
label: "xsd:string",
},
{ graph_type: "schema" }
);
// Here we will pass true to show how to get dataVersion
const response = await client.updateDocument(
{
"@id": "Person",
"@key": {
"@type": "Random",
},
"@type": "Class",
label: "xsd:string",
},
{ graph_type: "schema" },
"",
"",
"",
true
);
console.log(response);
// This will output:
// {
// result: [ ...... ],
// dataVersion: 'branch:5fs681tlycnn6jh0ceiqcq4qs89pdfs'
// }
// Now we can use the data version we recieved as a response in previous
// function call and used it is next function call as lastDataVersion
const response1 = await client.updateDocument(
{
"@id": "Person",
"@key": {
"@type": "Random",
},
"@type": "Class",
label: "xsd:string",
},
{ graph_type: "schema" },
"",
"",
response.dataVersion
);
// update a document and create the linked document together
// we are update the document "Person/Person01"
// and create a new document {"@type": "Person","name": "child01"} at the same time
const response1 = await client.updateDocument(
{
"@id": "Person/Person01",
"@type": "Person",
"name": "Person01"
"children":[{"@type": "Person","name": "child01"}]
},{create:true})
updateTriples(graphType, turtle, commitMsg)
Replace the contents of the specified graph with the passed triples encoded in the turtle (ttl) format
Parameters
Name | Type | Description |
---|---|---|
graphType | string | type of graph |instance|schema|inference| |
turtle | string | string encoding triples in turtle (ttl) format |
commitMsg | string | Textual message describing the reason for the update |
Examples
client.updateTriples("schema", "alt", turtle_string, "dumping triples to graph alt")
user()
Gets the current user object as returned by the connect capabilities response user has fields: [id, name, notes, author]
userOrganization()
userOrganizations(orgList)
Get/Set the list of the user's organizations (id, organization, label, comment).
Parameters
Name | Type | Description |
---|---|---|
orgList | array | a list of user's Organization |
Examples
async funtion callGetUserOrganizations(){
await client.getUserOrganizations()
console.log(client.userOrganizations())
}
WOQLLibrary
branches()
General Pattern 4: Retrieves Branches, Their ID, Head Commit ID, Head Commit Time (if present, new branches have no commits)
commits(branch, limit, start, timestamp)
get all the commits of a specific branch if a timestamp is given, gets all the commits before the specified timestamp
Parameters
Name | Type | Description |
---|---|---|
branch | string | the branch name |
limit | number | the max number of result |
start | number | the start of the pagination |
timestamp | number | Unix timestamp in seconds |
first_commit()
Finds the id of the very first commit in a database's history This is useful for finding information about when, by who and why the database was created The first commit is the only commit in the database that does not have a parent commit
previousCommits(commit_id, limit)
get commits older than the specified commit id
Parameters
Name | Type | Description |
---|---|---|
commit_id | string | the commit id |
limit | number | the max number of result |
WOQLQuery
addSubQuery()
Internal library function which adds a subquery and sets the cursor
addSubQuery(Subq)
Parameters
Name | Type | Description |
---|---|---|
Subq | WOQLQuery |
add_quad(subject, predicate, object, graphRef)
Adds quads according to the pattern [S,P,O,G]
Parameters
Name | Type | Description |
---|---|---|
subject | string|Var | The IRI of a triple’s subject or a variable |
predicate | string|Var | The IRI of a property or a variable |
object | string|Var | The IRI of a node or a variable, or a literal |
graphRef | typedef.GraphRef | A valid graph resource identifier string |
add_triple(subject, predicate, object)
Adds triples according to the the pattern [subject,predicate,object]
Parameters
Name | Type | Description |
---|---|---|
subject | string|Var | The IRI of a triple’s subject or a variable |
predicate | string|Var | The IRI of a property or a variable |
object | string|Var | The IRI of a node or a variable, or a literal |
added_quad(subject, predicate, object, graphRef-)
Creates a pattern matching rule for the quad [S, P, O, G] (Subject, Predicate, Object, Graph) removed from the current commit
Parameters
Name | Type | Description |
---|---|---|
subject | string|Var | The IRI of a triple’s subject or a variable |
predicate | string|Var | The IRI of a property or a variable |
object | string|Var | The IRI of a node or a variable, or a literal |
graphRef- | typedef.GraphRef | A valid graph resource identifier string |
added_triple(subject, predicate, object)
Creates a triple pattern matching rule for the triple [S, P, O] (Subject, Predicate, Object) added in the current layer
Parameters
Name | Type | Description |
---|---|---|
subject | string|Var | The IRI of a triple’s subject or a variable |
predicate | string|Var | The IRI of a property or a variable |
object | string|Var | The IRI of a node or a variable, or a literal |
all(Subj, Pred, Obj, Graph)
Parameters
Name | Type | Description |
---|---|---|
Subj | string|Var | The IRI of a triple’s subject or a variable |
Pred | string|Var | The IRI of a property or a variable |
Obj | string|Var | The IRI of a node or a variable, or a literal |
Graph | typedef.GraphRef | the resource identifier of a graph possible |
all(Subj, Pred, Obj, Graph)
Parameters
Name | Type | Description |
---|---|---|
Subj | string|Var | The IRI of a triple’s subject or a variable |
Pred | string|Var | The IRI of a property or a variable |
Obj | string|Var | The IRI of a node or a variable, or a literal |
Graph | typedef.GraphRef | the resource identifier of a graph possible |
and(subqueries)
Logical conjunction of the contained queries - all queries must match or the entire clause fails
Parameters
Name | Type | Description |
---|---|---|
subqueries | WOQLQuery | A list of one or more woql queries to execute as a conjunction |
arop()
Wraps arithmetic operators in the appropriate json-ld
as(varList)
Parameters
Name | Type | Description |
---|---|---|
varList | array|string|Var | variable number of arguments |
asv()
Wraps the elements of an AS variable in the appropriate json-ld
boolean(tf)
Parameters
Name | Type | Description |
---|---|---|
tf | boolean |
boolean(tf)
Parameters
Name | Type | Description |
---|---|---|
tf | boolean |
cleanGraph()
Transforms a graph filter or graph id into the proper json-ld form
cleanObject()
Transforms whatever is passed in as the object of a triple into the appropriate json-ld form (variable, literal or id)
cleanPredicate()
Transforms whatever is passed in as the predicate (id or variable) into the appropriate json-ld form
cleanSubject()
Transforms whatever is passed in as the subject into the appropriate json-ld for variable or id
comment(comment, subquery)
Adds a text comment to a query - can also be used to wrap any part of a query to turn it off
Parameters
Name | Type | Description |
---|---|---|
comment | string | text comment |
subquery | WOQLQuery | query that is "commented out" |
compilePathPattern()
Turns a textual path pattern into a JSON-LD description
concat(varList, resultVarName)
takes a variable number of string arguments and concatenates them into a single string
Parameters
Name | Type | Description |
---|---|---|
varList | array|string|Var | a variable representing a list or a list of variables or strings - variables can be embedded in the string if they do not contain spaces |
resultVarName | string|Var | A variable or string containing the output string |
containsUpdate()
Does this query contain an update
context()
sets the value of the current json-ld context on a full query scope
count(countVarName, subquery)
Creates a count of the results of the query
Parameters
Name | Type | Description |
---|---|---|
countVarName | string|number|Var | variable or integer count |
subquery | WOQLQuery |
dataList()
takes input that can be either a string (variable name) or an array - each element of the array is a member of the list
dataValueList()
Wraps data values
delete_document(IRI)
Delete a document from the graph.
Parameters
Name | Type | Description |
---|---|---|
IRI | string | The document id or a variable |
delete_quad(subject, predicate, object, graphRef)
Deletes a single triple from the graph [Subject, Predicate, Object, Graph]
Parameters
Name | Type | Description |
---|---|---|
subject | string|Var | The IRI of a triple’s subject or a variable |
predicate | string|Var | The IRI of a property or a variable |
object | string|Var | The IRI of a node or a variable, or a literal |
graphRef | typedef.GraphRef | A valid graph resource identifier string |
delete_triple(subject, predicate, object)
Deletes a single triple from the default graph of the database
Parameters
Name | Type | Description |
---|---|---|
subject | string|Var | The IRI of a triple’s subject or a variable |
predicate | string|Var | The IRI of a property or a variable |
object | string|Var | The IRI of a node or a variable, or a literal |
distinct(varNames)
Filter the query to return only results that are distinct in the given variables
Parameters
Name | Type | Description |
---|---|---|
varNames | string|Var | these variables are guaranteed to be unique as a tuple |
div(args)
Division - integer division - args are divided left to right
Parameters
Name | Type | Description |
---|---|---|
args | string|number|Var | numbers for division |
divide(args)
Divides numbers N1...Nn by each other left, to right precedence
Parameters
Name | Type | Description |
---|---|---|
args | string|number|Var | numbers to tbe divided |
dot(document, field, value)
Extract the value of a key in a bound document.
Parameters
Name | Type | Description |
---|---|---|
document | string|Var | Document which is being accessed. |
field | string|Var | The field from which the document which is being accessed. |
value | string|Var | The value for the document and field. |
eq(varName, varValue)
Matches if a is equal to b
Parameters
Name | Type | Description |
---|---|---|
varName | string|Var | literal, variable or id |
varValue | string|Var | literal, variable or id |
eval(arithExp, resultVarName)
Evaluates the passed arithmetic expression and generates or matches the result value
Parameters
Name | Type | Description |
---|---|---|
arithExp | object|WOQLQuery|string | query or JSON-LD representing the query |
resultVarName | string|Var | output variable |
execute()
Use instead woqlclient.query('myWOQLQuery')
exp(varNum, expNum)
Exponent - raises varNum01 to the power of varNum02
Parameters
Name | Type | Description |
---|---|---|
varNum | string|number|Var | 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 |
expandVariable(varname)
Transforms strings that start with v: into variable json-ld structures
Parameters
Name | Type | Description |
---|---|---|
varname | unknown | will be transformed if it starts with v: |
findLastProperty(json)
Finds the last woql element that has a subject in that is a property id used for triplebuilder to chain further calls - when they may be inside ands or ors or subqueries
Parameters
Name | Type | Description |
---|---|---|
json | object |
findLastSubject(json)
Finds the last woql element that has a subject in it and returns the json for that used for triplebuilder to chain further calls - when they may be inside ands or ors or subqueries
Parameters
Name | Type | Description |
---|---|---|
json | object |
floor(varNum)
Generates the nearest lower integer to the passed number
Parameters
Name | Type | Description |
---|---|---|
varNum | string|number|Var | Variable or numeric containing the number to be floored |
from(graphRef-, query)
Specifies the database URL that will be the default database for the enclosed query
Parameters
Name | Type | Description |
---|---|---|
graphRef- | typedef.GraphRef | A valid graph resource identifier string |
query | WOQLQuery | The query |
get(asvars, queryResource)
Use the document inteface to import documents
Parameters
Name | Type | Description |
---|---|---|
asvars | Vars|array.<Var> | an array of AsVar variable mappings (see as for format below) |
queryResource | WOQLQuery | an external resource (remote, file, post) to query |
getContext()
Retrieves the value of the current json-ld context
getLimit()
Functions to manipulate and check the paging related properties of a query
getPagingProperty()
Returns the value of one of the 'paging' related properties (limit, start,...)
graph(graphRef)
Sets the graph resource ID that will be used for subsequent chained function calls
Parameters
Name | Type | Description |
---|---|---|
graphRef | typedef.GraphRef | Resource String identifying the graph which will be used for subsequent chained schema calls |
graph(graphRef)
Sets the graph resource ID that will be used for subsequent chained function calls
Parameters
Name | Type | Description |
---|---|---|
graphRef | typedef.GraphRef | Resource String identifying the graph which will be used for subsequent chained schema calls |
greater(varNum01, varNum02)
Compares the value of v1 against v2 and returns true if v1 is greater than v2
Parameters
Name | Type | Description |
---|---|---|
varNum01 | string|number|Var | a variable or numeric containing the number to be compared |
varNum02 | string|number|Var | a variable or numeric containing the second comporator |
group_by(gvarlist, groupedvar, output, groupquery)
Groups the results of the contained subquery on the basis of identical values for Groupvars, extracts the patterns defined in PatternVars and stores the results in GroupedVar
Parameters
Name | Type | Description |
---|---|---|
gvarlist | array|string|Var | Either a single variable or an array of variables |
groupedvar | array|string|Var | Either a single variable or an array of variables |
output | string|Var | output variable name |
groupquery | WOQLQuery | The query whose results will be grouped |
idgen(prefix, inputVarList, outputVar)
Generates the node's ID combined the variable list with a specific prefix (URL base). If the input variables's values are the same, the output value will be the same.
Parameters
Name | Type | Description |
---|---|---|
prefix | string | |
inputVarList | string|array | the variable input list for generate the id |
outputVar | string | the output variable name |
immediately(subquery)
Runs the query without backtracking on side-effects
Parameters
Name | Type | Description |
---|---|---|
subquery | string|WOQLQuery | WOQL Query objects |
insert(id, type, refGraph)
Parameters
Name | Type | Description |
---|---|---|
id | string|Var | IRI string or variable containing |
type | string|Var | IRI string or variable containing the IRI of the |
refGraph | typedef.GraphRef | Optional Graph resource identifier |
insert(id, type, refGraph)
Parameters
Name | Type | Description |
---|---|---|
id | string|Var | IRI string or variable containing |
type | string|Var | IRI string or variable containing the IRI of the |
refGraph | typedef.GraphRef | Optional Graph resource identifier |
insert_document(docjson, IRI)
Insert a document in the graph.
Parameters
Name | 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. |
into(graphRef-, subquery)
Specifies the graph resource to write the contained query into
Parameters
Name | Type | Description |
---|---|---|
graphRef- | typedef.GraphRef | A valid graph resource identifier string |
subquery | WOQLQuery | The query which will be written into the graph |
iri(s)
Parameters
Name | Type | Description |
---|---|---|
s | string |
iri(s)
Parameters
Name | Type | Description |
---|---|---|
s | string |
isa(instanceIRI, classId)
Tests whether a given instance IRI has type Class, according to the current state of the DB
Parameters
Name | Type | Description |
---|---|---|
instanceIRI | string|Var | A string IRI or a variable that identify the class instance |
classId | string|Var | A Class IRI or a variable |
jlt()
Wraps the passed value in a json-ld literal carriage
jobj()
Transforms a javascript representation of a query into a json object if needs be
join(varList, glue, resultVarName)
Joins a list variable together (Input) into a string variable (Output) by glueing the strings together with Glue
Parameters
Name | Type | Description |
---|---|---|
varList | string|array|Var | a variable representing a list or a list of strings and / or variables |
glue | string|Var | A variable (v:glue) or (glue) string representing the characters to put in between the joined strings in input |
resultVarName | string|Var | A variable or string containing the output string |
json(json)
converts back and forward from json if the argument is present, the current query is set to it, if the argument is not present, the current json version of this query is returned
Parameters
Name | Type | Description |
---|---|---|
json | object | a query in json format |
length(inputVarList, resultVarName)
Calculates the length of the list in va and stores it in vb
Parameters
Name | Type | Description |
---|---|---|
inputVarList | string|array | Either a variable representing a list or a list of variables or literals |
resultVarName | string|Var | A variable in which the length of the list is stored or the length of the list as a non-negative integer |
less(varNum01, varNum02)
Compares the value of v1 against v2 and returns true if v1 is less than v2
Parameters
Name | Type | Description |
---|---|---|
varNum01 | string|number|Var | a variable or numeric containing the number to be compared |
varNum02 | string|number|Var | a variable or numeric containing the second comporator |
like(stringA, stringB, distance)
Generates a string Leverstein distance measure between stringA and stringB
Parameters
Name | Type | Description |
---|---|---|
stringA | string|Var | string literal or variable representing a string to be compared |
stringB | string|Var | string literal or variable representing the other string to be compared |
distance | number|string|Var | variable representing the distance between the variables |
limit(limit, subquery)
Specifies a maximum number of results that will be returned from the subquery
Parameters
Name | Type | Description |
---|---|---|
limit | number|string | A variable that refers to an non-negative integer or a non-negative integer |
subquery | WOQLQuery | A subquery whose results will be limited |
link(subject, predicate, object)
Creates a pattern matching rule for triple [Subject, Predicate, Object]
Parameters
Name | Type | Description |
---|---|---|
subject | string|Var | The IRI of a triple’s subject or a variable |
predicate | string|Var | The IRI of a property or a variable |
object | string|Var | The IRI of a node or a variable, or a literal |
literal(s, t)
Parameters
Name | Type | Description |
---|---|---|
s | any | |
t | string |
literal(s, t)
Parameters
Name | Type | Description |
---|---|---|
s | any | |
t | string |
loadDefaultVocabulary()
vocabulary elements that can be used without prefixes in woql.js queries
lower(inputVarName, resultVarName)
Changes a string to lower-case
Parameters
Name | Type | Description |
---|---|---|
inputVarName | string|Var | string or variable representing the non-lowercased string |
resultVarName | string|Var | variable that stores the lowercased string output |
member(element, list)
Matches if List includes Element
Parameters
Name | Type | Description |
---|---|---|
element | string|object|Var | Either a variable, IRI or any simple datatype |
list | string|array|Var | List ([string, literal] or string*) Either a variable representing a list or a list of variables or literals |
minus(args)
Subtracts Numbers N1..Nn
Parameters
Name | Type | Description |
---|---|---|
args | string|number|Var | variable or numeric containing the value that will be subtracted from |
node(nodeid, chainType)
Specifies the identity of a node that can then be used in subsequent builder functions. Note that node() requires subsequent chained functions to complete the triples / quads that it produces - by itself it only generates the subject.
Parameters
Name | Type | Description |
---|---|---|
nodeid | string|Var | The IRI of a node or a variable containing an IRI which will be the subject of the builder functions |
chainType | typedef.FuntionType | Optional type of builder function to build (default is triple) |
node(node, type)
Parameters
Name | Type | Description |
---|---|---|
node | string|Var | The IRI of a node or a variable containing an IRI which will be the subject of the builder functions |
type | typedef.FuntionType | Optional type of builder function to build (default is triple) |
not(subquery)
Logical negation of the contained subquery - if the subquery matches, the query will fail to match
Parameters
Name | Type | Description |
---|---|---|
subquery | string|WOQLQuery | A subquery which will be negated |
nuke(graphRef)
Deletes all triples in the passed graph (defaults to instance/main)
Parameters
Name | Type | Description |
---|---|---|
graphRef | typedef.GraphRef | Resource String identifying the graph from which all triples will be removed |
nuke(graphRef)
Deletes all triples in the passed graph (defaults to instance/main)
Parameters
Name | Type | Description |
---|---|---|
graphRef | typedef.GraphRef | Resource String identifying the graph from which all triples will be removed |
Examples
nuke("schema/main")
//will delete everything from the schema/main graph
once(subquery)
Results in one solution of the subqueries
Parameters
Name | Type | Description |
---|---|---|
subquery | string|WOQLQuery | WOQL Query objects |
opt(subquery)
Specifies that the Subquery is optional - if it does not match the query will not fail
Parameters
Name | Type | Description |
---|---|---|
subquery | WOQLQuery | A subquery which will be optionally matched |
or(subqueries)
Creates a logical OR of the arguments
Parameters
Name | Type | Description |
---|---|---|
subqueries | WOQLQuery | A list of one or more woql queries to execute as alternatives |
order_by(orderedVarlist)
Orders the results of the contained subquery by a precedence list of variables
Parameters
Name | Type | Description |
---|---|---|
orderedVarlist | string|Var|array | A sequence of variables, by which to order the results, each optionally followed by either “asc” or “desc” to represent order as a list, by default it will sort the variable in ascending order |
pad(inputVarName, pad, len, resultVarName)
Pads out the string input to be exactly len long by appending the pad character pad to form output
Parameters
Name | Type | Description |
---|---|---|
inputVarName | string|Var | The input string or variable in unpadded state |
pad | string|Var | The characters to use to pad the string or a variable representing them |
len | number|string|Var | The variable or integer value representing the length of the output string |
resultVarName | string|Var | stores output |
parameterError()
Basic Error handling
parameterError(msg)
Parameters
Name | Type | Description |
---|---|---|
msg | string |
path(subject, pattern, object, resultVarName)
Performs a path regular expression match on the graph
Parameters
Name | Type | Description |
---|---|---|
subject | string|Var | An IRI or variable that refers to an IRI representing the subject, i.e. the starting point of the path |
pattern | string | (string) - A path regular expression describing a pattern through multiple edges of the graph (see: https://terminusdb.com/docs/path-query-reference-guide) |
object | string|Var | An IRI or variable that refers to an IRI representing the object, i.e. ending point of the path |
resultVarName | string|Var | A variable in which the actual paths traversed will be stored |
plus(args)
Adds the numbers together
Parameters
Name | Type | Description |
---|---|---|
args | string|number|Var | a variable or numeric containing the values to add |
post(url, formatObj, source)
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
Parameters
Name | 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' |
prettyPrint(clang)
Returns a script version of the query
Parameters
Name | Type | Description |
---|---|---|
clang | string | either "js" or "python" |
put(varsToExp, query, fileResource)
Use the document inteface to import documents
Parameters
Name | Type | Description |
---|---|---|
varsToExp | Vars|array.<Var> | 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 |
quad(subject, predicate, object, graphRef)
Creates a pattern matching rule for the quad [S, P, O, G] (Subject, Predicate, Object, Graph)
Parameters
Name | Type | Description |
---|---|---|
subject | string|Var | The IRI of a triple’s subject or a variable |
predicate | string|Var | The IRI of a property or a variable |
object | string|Var | The IRI of a node or a variable, or a literal |
graphRef | typedef.GraphRef | A valid graph resource identifier string |
re(pattern, inputVarName, resultVarList)
Matches the regular expression defined in Patern against the Test string, to produce the matched patterns in Matches
Parameters
Name | Type | Description |
---|---|---|
pattern | string | string or variable using normal PCRE regular expression syntax with the exception that special characters have to be escaped twice (to enable transport in JSONLD) |
inputVarName | string|Var | string or variable containing the string to be tested for patterns with the regex |
resultVarList | string|array|object|Var | variable representing the list of matches or a list of strings or variables |
read_document(IRI, output)
Read a node identified by an IRI as a JSON-LD document
Parameters
Name | Type | Description |
---|---|---|
IRI | string | The document id or a variable to read |
output | string | Variable which will be bound to the document. |
remote(remoteObj, formatObj)
Identifies a remote resource by URL and specifies the format of the resource through the options
Parameters
Name | Type | Description |
---|---|---|
remoteObj | object | The URL at which the remote resource can be accessed |
formatObj | typedef.DataFormatObj | The format of the resource data {} |
removed_quad(subject, predicate, object, graphRef-)
Creates a pattern matching rule for the quad [S, P, O, G] (Subject, Predicate, Object, Graph) removed from the current commit
Parameters
Name | Type | Description |
---|---|---|
subject | string|Var | The IRI of a triple’s subject or a variable |
predicate | string|Var | The IRI of a property or a variable |
object | string|Var | The IRI of a node or a variable, or a literal |
graphRef- | typedef.GraphRef | A valid graph resource identifier string |
removed_triple(subject, predicate, object)
Creates a triple pattern matching rule for the triple [S, P, O] (Subject, Predicate, Object) added in the current commit
Parameters
Name | Type | Description |
---|---|---|
subject | string|Var | The IRI of a triple’s subject or a variable |
predicate | string|Var | The IRI of a property or a variable |
object | string|Var | The IRI of a node or a variable, or a literal |
select(varNames)
Filters the query so that only the variables included in [V1...Vn] are returned in the bindings
Parameters
Name | Type | Description |
---|---|---|
varNames | string|Var | only these variables are returned |
setPagingProperty()
Sets the value of one of the paging_transitive_properties properties
setVocabulary()
Provides the query with a 'vocabulary' a list of well known predicates that can be used without prefixes mapping: id: prefix:id ...
size(resourceId, resultVarName)
Calculates the size in bytes of the contents of the resource identified in ResourceID
Parameters
Name | Type | Description |
---|---|---|
resourceId | string|Var | A valid resource identifier string (can refer to any graph / branch / commit / db) |
resultVarName | string|Var | The variable name |
split(inputVarName, separator, resultVarName)
Splits a string (Input) into a list strings (Output) by removing separator
Parameters
Name | Type | Description |
---|---|---|
inputVarName | string|Var | A string or variable representing the unsplit string |
separator | string|Var | A string or variable containing a sequence of charatcters to use as a separator |
resultVarName | string|Var | variable that stores output list |
star()
Simple composite functions which produce WOQL queries
star(graph, subject, predicate, object)
Generates a query that by default matches all triples in a graph identified by "graph" or in all the current terminusDB's graph
Parameters
Name | Type | Description |
---|---|---|
graph | string|boolean | false or the resource identifier of a graph possible value are schema/{main - myschema - *} | instance/{main - myschema - *} | inference/{main - myschema - *} |
subject | string|Var | The IRI of a triple’s subject or a variable, default value "v:Subject" |
predicate | string|Var | The IRI of a property or a variable, default value "v:Predicate" |
object | string|Var | The IRI of a node or a variable, or a literal, default value "v:Object" |
start(start, subquery)
Specifies an offset position in the results to start listing results from
Parameters
Name | Type | Description |
---|---|---|
start | number|string|Var | A variable that refers to an interger or an integer literal |
subquery | WOQLQuery | WOQL Query object, you can pass a subquery as an argument or a chained query |
string(s)
Parameters
Name | Type | Description |
---|---|---|
s | string |
string(s)
Parameters
Name | Type | Description |
---|---|---|
s | string |
sub(classA, classB)
Returns true if ClassA subsumes ClassB, according to the current DB schema
Parameters
Name | Type | Description |
---|---|---|
classA | string | ClassA |
classB | string | ClassB |
substr(string, before, length, after, subString)
Substring
Parameters
Name | Type | Description |
---|---|---|
string | string|Var | String or variable |
before | number|Var | integer or variable (characters from start to begin) |
length | number|Var | integer or variable (length of substring) |
after | number|Var | integer or variable (number of characters after substring) |
subString | string|Var | String or variable |
sum(subquery, total)
computes the sum of the List of values passed. In contrast to other arithmetic functions, sum self-evaluates - it does not have to be passed to evaluate()
Parameters
Name | Type | Description |
---|---|---|
subquery | WOQLQuery | a subquery or ([string or numeric]) - a list variable, or a list of variables or numeric literals |
total | string|Var | the variable name with the sum result of the values in List |
times(args)
Multiplies numbers N1...Nn together
Parameters
Name | Type | Description |
---|---|---|
args | string|number|Var | a variable or numeric containing the value |
trim(inputStr, resultVarName)
Remove whitespace from both sides of a string:
Parameters
Name | Type | Description |
---|---|---|
inputStr | string|Var | A string or variable containing the untrimmed version of the string |
resultVarName | string|Var | A string or variable containing the trimmed version of the string |
triple(subject, predicate, object)
Creates a triple pattern matching rule for the triple [S, P, O] (Subject, Predicate, Object)
Parameters
Name | Type | Description |
---|---|---|
subject | string|Var | The IRI of a triple’s subject or a variable |
predicate | string|Var | The IRI of a property or a variable |
object | string|Var | The IRI of a node or a variable, or a literal |
triple_count(resourceId, tripleCount)
Calculates the number of triples of the contents of the resource identified in ResourceID
Parameters
Name | Type | Description |
---|---|---|
resourceId | string|Var | A valid resource identifier string (can refer to any graph / branch / commit / db) |
tripleCount | string|number|Var | An integer literal with the size in bytes or a variable containing that integer |
true()
A function that always matches, always returns true
type_of(elementId, elementType)
Returns true if 'elementId' is of type 'elementType', according to the current DB schema
Parameters
Name | Type | Description |
---|---|---|
elementId | string|Var | the id of a schema graph element |
elementType | string|Var | the element type |
typecast(varName, varType, resultVarName)
Casts the value of Input to a new value of type Type and stores the result in CastVar
Parameters
Name | Type | Description |
---|---|---|
varName | string|number|object|Var | Either a single variable or a literal of any basic type |
varType | string|Var | Either a variable or a basic datatype (xsd / xdd) |
resultVarName | string|Var | save the return variable |
unique(prefix, inputVarList, resultVarName)
Generate a new IRI from the prefix and a hash of the variables which will be unique for any given combination of variables
Parameters
Name | 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|Var | An array of variables and / or strings from which the unique hash will be generated |
resultVarName | string|Var | Variable in which the unique ID is stored |
update_document(docjson, IRI)
Update a document identified by an IRI
Parameters
Name | 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. |
update_quad(subject, predicate, newObject, graphRef)
Update a pattern matching rule for the quad [S, P, O, G] (Subject, Predicate, Object, Graph)
Parameters
Name | Type | Description |
---|---|---|
subject | string|Var | The IRI of a triple’s subject or a variable |
predicate | string|Var | The IRI of a property or a variable |
newObject | string|Var | The value to update or a literal |
graphRef | typedef.GraphRef | A valid graph resource identifier string |
update_quad(subject, predicate, newObject, graph)
Update a pattern matching rule for the quad [S, P, O, G] (Subject, Predicate, Object, Graph)
Parameters
Name | Type | Description |
---|---|---|
subject | string | The IRI of a triple’s subject or a variable |
predicate | string | The IRI of a property or a variable |
newObject | string | The value to update or a literal |
graph | string | the resource identifier of a graph possible value are schema/{main - myschema - *} | instance/{main - myschema - *} | inference/{main - myschema - *} |
update_triple(subject, predicate, newObjValue, oldObjValue)
Update a pattern matching rule for the triple (Subject, Predicate, oldObjValue) with the new one (Subject, Predicate, newObjValue)
Parameters
Name | Type | Description |
---|---|---|
subject | string|Var | The IRI of a triple’s subject or a variable |
predicate | string|Var | The IRI of a property or a variable |
newObjValue | string|Var | The value to update or a literal |
oldObjValue | string|Var | The old value of the object |
update_triple(subject, predicate, newObjValue, oldObjValue)
Update a pattern matching rule for the triple (Subject, Predicate, oldObjValue) with the new one (Subject, Predicate, newObjValue)
Parameters
Name | Type | Description |
---|---|---|
subject | string|Var | The IRI of a triple’s subject or a variable |
predicate | string|Var | The IRI of a property or a variable |
newObjValue | string|Var | The value to update or a literal |
oldObjValue | string|Var | The old value of the object |
updated()
updated()
Called to inidicate that this query will cause an update to the DB
upper(inputVarName, resultVarName)
Changes a string to upper-case
Parameters
Name | Type | Description |
---|---|---|
inputVarName | string|Var | string or variable representing the uncapitalized string |
resultVarName | string|Var | variable that stores the capitalized string output |
using(refPath, subquery)
Query running against any specific commit Id
Parameters
Name | Type | Description |
---|---|---|
refPath | string | path to specific reference Id or commit Id |
subquery | WOQLQuery | subquery for the specific commit point |
value(subject, predicate, objValue)
Creates a pattern matching rule for triple [Subject, Predicate, Object] add extra information about the type of the value object
Parameters
Name | Type | Description |
---|---|---|
subject | string|Var | The IRI of a triple’s subject or a variable |
predicate | string|Var | The IRI of a property or a variable |
objValue | string|number|boolean|Var | an specific value |
valueList()
takes a list of input that can be any value
vlist()
creates an unadorned variable name list
wform(opts)
JSON LD Format Descriptor
Parameters
Name | Type | Description |
---|---|---|
opts | object |
wrapCursorWithAnd()
Contains definitions of the WOQL functions which map directly to JSON-LD types All other calls and queries can be composed from these