WOQLClient

WOQLClient

License: Apache Version 2

new WOQLClient(serverUrl, [params])

The core functionality of the TerminusDB javascript client is defined in the WOQLClient class - in the woqlClient.js file. This class provides methods which allow you to directly get and set all of the configuration and API endpoints of the client. The other parts of the WOQL core - connectionConfig.js and connectionCapabilities.js - are used by the client to store internal state - they should never have to be accessed directly. For situations where you want to communicate with a TerminusDB server API, the WOQLClient class is all you will need.
Param
Type
Description
serverUrl
string
the terminusdb server url
[params]
typedef.ParamsObj
an object with the connection parameters
Example
//to connect with your local terminusDB
const client = new TerminusClient.WOQLClient(SERVER_URL,{user:"admin",key:"myKey"})
async function getSchema() {
client.db("test")
client.checkout("dev")
const schema = await client.getSchema()
}
//The client has an internal state which defines what
//organization / database / repository / branch / ref it is currently attached to
//to connect with your TerminusDB Cloud Instance
const client = new TerminusClient.WOQLClient('SERVER_CLOUD_URL/mycloudTeam',
{user:"[email protected]", organization:'mycloudTeam'})
client.setApiKey(MY_ACCESS_TOKEN)
//to get the list of all organization's databases
async function callGetDatabases(){
const dbList = await client.getDatabases()
console.log(dbList)
}
async function getSchema() {
client.db("test")
client.checkout("dev")
const schema = await client.getSchema()
}

TerminusDB Client API

Connect

woqlClient.connect([params]) ⇒ Promise
Deprecated
Connect to a Terminus server at the given URI with an API key Stores the system:ServerCapability document returned in the connection register which stores, the url, key, capabilities, and database meta-data for the connected server this.connectionConfig.server will be used if present, or the promise will be rejected.
Returns: Promise - the connection capabilities response object or an error object
Param
Type
Description
[params]
typedef.ParamsObj
TerminusDB Server connection parameters
Example
client.connect()

Create Database

woqlClient.createDatabase(dbId, dbDetails, [orgId]) ⇒ Promise
Creates a new database in TerminusDB server
Returns: Promise - A promise that returns the call response object, or an Error if rejected.
Param
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
Example
//remember set schema:true if you need to add a schema graph
client.createDatabase("mydb", {label: "My Database", comment: "Testing", schema: true})

Delete Database

woqlClient.deleteDatabase(dbId, [orgId], [force]) ⇒ Promise
Deletes a database from a TerminusDB server
Returns: Promise - A promise that returns the call response object, or an Error if rejected.
Param
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
Example
client.deleteDatabase("mydb")

Get Triples

woqlClient.getTriples(graphType) ⇒ Promise
Retrieve the contents of a graph within a TerminusDB as triples, encoded in the turtle (ttl) format
Returns: Promise - A promise that returns the call response object (with the contents being a string representing a set of triples in turtle (ttl) format), or an Error if rejected.
Param
Type
Description
graphType
typedef.GraphType
type of graph to get triples from, either “instance” or “schema”
Example
const turtle = await client.getTriples("schema", "alt")

Update Triples

woqlClient.updateTriples(graphType, turtle, commitMsg) ⇒ Promise
Replace the contents of the specified graph with the passed triples encoded in the turtle (ttl) format
Returns: Promise - A promise that returns the call response object, or an Error if rejected.
Param
Type
Description
graphType
string
type of graph
turtle
string
string encoding triples in turtle (ttl) format
commitMsg
string
Textual message describing the reason for the update
Example
client.updateTriples("schema", "alt", turtle_string, "dumping triples to graph alt")

Query

woqlClient.query(woql, [commitMsg], [allWitnesses], [lastDataVersion], [getDataVersion]) ⇒ Promise
Executes a WOQL query on the specified database and returns the results
Returns: Promise - A promise that returns the call response object or object having result and dataVersion object if getDataVersion parameter is true, or an Error if rejected.
Param
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.
Example
const result = await client.query(WOQL.star())

Clonedb

woqlClient.clonedb(cloneSource, newDbId, [orgId]) ⇒ Promise
Clones a remote repo and creates a local copy
Returns: Promise - A promise that returns the call response object, or an Error if rejected.
Param
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”)
Example
client.clonedb({remote_url: "https://my.terminusdb.com/myorg/mydb", label "Cloned DB", comment: "Cloned from mydb"}, newid: "mydb")

Branch

woqlClient.branch(newBranchId, [isEmpty]) ⇒ Promise
Creates a new branch with a TerminusDB database, starting from the current context of the client (branch / ref)
Returns: Promise - A promise that returns the call response object, or an Error if rejected.
Param
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.
Example
client.branch("dev")

Rebase

woqlClient.rebase(rebaseSource) ⇒ Promise
Merges the passed branch into the current one using the rebase operation
Returns: Promise - A promise that returns the call response object, or an Error if rejected.
Param
Type
Description
rebaseSource
object
json describing the source branch to be used as a base
Example
//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")

Pull

woqlClient.pull(remoteSourceRepo) ⇒ Promise
Pull changes from a branch on a remote database to a branch on a local database
Returns: Promise - A promise that returns the call response object, or an Error if rejected.
Param
Type
Description
remoteSourceRepo
typedef.RemoteRepoDetails
an object describing the source of the pull
Example
client.pull({remote: "origin", remote_branch: "main", message: "Pulling from remote"})

Push

woqlClient.push(remoteTargetRepo) ⇒ Promise
Push changes from a branch on a local database to a branch on a remote database
Returns: Promise - A promise that returns the call response object, or an Error if rejected.
Param
Type
Description
remoteTargetRepo
typedef.RemoteRepoDetails
an object describing the target of the push {remote: "origin", "remote_branch": "main", "author": "admin", "message": "message"}
Example
client.push({remote: "origin", remote_branch: "main", message: "Pulling from remote"})

Fetch

woqlClient.fetch(remoteId) ⇒ Promise
Fetch updates to a remote database to a remote repository with the local database
Returns: Promise - A promise that returns the call response object, or an Error if rejected.
Param
Type
Description
remoteId
string
if of the remote to fetch (eg: 'origin')

local_auth

woqlClient.local_auth
Deprecated
Use #localAuth instead.

remote_auth

woqlClient.remote_auth
Deprecated
Use #remoteAuth instead.

setApiKey

woqlClient.setApiKey(accessToken)
set the api key to access the cloud resources
Param
Type
accessToken
string

customHeaders

woqlClient.customHeaders(customHeaders) ⇒ object
add extra headers to your request
Param
Type
customHeaders
object

copy

woqlClient.copy() ⇒ WOQLClient
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
Returns: WOQLClient - new client object with identical state to original but which can be manipulated independently Example
let newClient = client.copy()

server

woqlClient.server() ⇒ string
Gets the current connected server url it can only be set creating a new WOQLCLient instance

api

woqlClient.api() ⇒ string
Retrieve the URL of the server’s API base that we are currently connected to
Returns: string - the URL of the TerminusDB server api endpoint we are connected to (typically server() + “api/”) Example
let api_url = client.api()

organization

woqlClient.organization([orgId]) ⇒ string | boolean
Gets/Sets the client’s internal organization context value, if you change the organization name the databases list will be set to empty
Param
Type
Description
[orgId]
string | boolean
the organization id to set the context to
Example
client.organization("admin")

getDatabases

woqlClient.getDatabases() ⇒ Promise
Gets the organization's databases list.
If no organization has been set up, the function throws an exception
Example
async function callGetDatabases(){
const dbList = await client.getDatabases()
console.log(dbList)
}

databases

woqlClient.databases([dbList]) ⇒ array
Set/Get the organization's databases list (id, label, comment) that the current user has access to on the server.
Returns: array - the organization's databases list
Param
Type
Description
[dbList]
array
a list of databases the user has access to on the server, each having:
Example
//to get the list of all organization's databases
async function callGetDatabases(){
await client.getDatabases()
console.log(client.databases())
}

user

woqlClient.user() ⇒ Object
Gets the current user object as returned by the connect capabilities response user has fields: [id, name, notes, author]

userOrganization

woqlClient.userOrganization() ⇒ string
Returns: string - the user organization name Desription: Gets the user's organization id

databaseInfo

woqlClient.databaseInfo([dbName]) ⇒ object
Gets the database's details
Returns: object - the database description object
Param
Type
Description
[dbName]
string
the datbase name

db

woqlClient.db([dbId]) ⇒ string | boolean
Sets / Gets the current database
Returns: string | boolean - - the current database or false
Param
Type
Description
[dbId]
string
the database id to set the context to
Example
client.db("mydb")

setSystemDb

woqlClient.setSystemDb()
Sets the internal client context to allow it to talk to the server’s internal system database

repo

woqlClient.repo([repoId]) ⇒ string
Gets / Sets the client’s internal repository context value (defaults to ‘local’)
Returns: string - the current repository id within the client context
Param
Type
Description
[repoId]
typedef.RepoType | string
default value is local
Example
client.repo("origin")

checkout

woqlClient.checkout([branchId]) ⇒ string
Gets/Sets the client’s internal branch context value (defaults to ‘main’)
Returns: string - the current branch id within the client context
Param
Type
Description
[branchId]
string
the branch id to set the context to

ref

woqlClient.ref([commitId]) ⇒ string | boolean
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
Returns: string | boolean - the current commit id within the client context
Param
Type
Description
[commitId]
string
the reference ID or commit ID
Example
client.ref("mkz98k2h3j8cqjwi3wxxzuyn7cr6cw7")

localAuth

woqlClient.localAuth([newCredential]) ⇒ typedef.CredentialObj | boolean
Sets/Gets set the database basic connection credential
Param
Type
[newCredential]
typedef.CredentialObj
Example
client.localAuth({user:"admin","key":"mykey","type":"basic"})

remoteAuth

woqlClient.remoteAuth([newCredential]) ⇒ typedef.CredentialObj | boolean
Sets/Gets the jwt token for authentication we need this to connect 2 terminusdb server to each other for push, pull, clone actions
Param
Type
[newCredential]
typedef.CredentialObj
Example
client.remoteAuth({"key":"dhfmnmjglkrelgkptohkn","type":"jwt"})

author

woqlClient.author() ⇒ string
Gets the string that will be written into the commit log for the current user
Returns: string - the current user Example
client.author()

set

woqlClient.set(params)
Param
Type
Description
params
typedef.ParamsObj
a object with connection params
Example
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"})

resource

woqlClient.resource(resourceType, [resourceId]) ⇒ string
Generates a resource string for the required context of the current context for "commits" "meta" "branch" and "ref" special resources
Returns: string - a resource string for the desired context
Param
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
Example
const branch_resource = client.resource("branch")

insertTriples

woqlClient.insertTriples(graphType, turtle, commitMsg) ⇒ Promise
Appends the passed turtle to the contents of a graph
Returns: Promise - A promise that returns the call response object, or an Error if rejected.
Param
Type
Description
graphType
string
type of graph
turtle
string
is a valid set of triples in turtle format (OWL)
commitMsg
string
Textual message describing the reason for the update

message

woqlClient.message(message, [pathname]) ⇒ Promise
Sends a message to the server
Returns: Promise - A promise that returns the call response object, or an Error if rejected.
Param
Type
Description
message
string
textual string
[pathname]
string
a server path to send the message to

action

woqlClient.action(actionName, [payload]) ⇒ Promise
Sends an action to the server
Returns: Promise - A promise that returns the call response object, or an Error if rejected.
Param
Type
Description
actionName
string
structure of the action
[payload]
object
a request body call

info

woqlClient.info() ⇒ Promise
Gets TerminusDB Server Information
Returns: Promise - A promise that returns the call response object, or an Error if rejected. Example
client.info()

squashBranch

woqlClient.squashBranch(branchId, commitMsg) ⇒ Promise
Squash branch commits
Returns: Promise - A promise that returns the call response object, or an Error if rejected.
Param
Type
Description
branchId
string
local identifier of the new branch
commitMsg
string
Textual message describing the reason for the update

resetBranch

woqlClient.resetBranch(branchId, commitId) ⇒ Promise
Reset branch to a commit id, Reference ID or Commit ID are unique hashes that are created whenever a new commit is recorded
Returns: Promise - A promise that returns the call response object, or an Error if rejected.
Param
Type
Description
branchId
string
local identifier of the new branch
commitId
string
Reference ID or Commit ID

optimizeBranch

woqlClient.optimizeBranch(branchId) ⇒ Promise
Optimize db branch
Returns: Promise - A promise that returns the call response object, or an Error if rejected.
Param
Type
Description
branchId
string
local identifier of the new branch

deleteBranch

woqlClient.deleteBranch(branchId) ⇒ Promise
Deletes a branch from database
Returns: Promise - A promise that returns the call response object, or an Error if rejected.
Param
Type
Description
branchId
string
local identifier of the branch

reset

woqlClient.reset(commitPath) ⇒ Promise
Reset the current branch HEAD to the specified commit path
Returns: Promise - A promise that returns the call response object, or an Error if rejected.
Param
Type
Description
commitPath
string
The commit path to set the current branch to

dispatch

woqlClient.dispatch() ⇒ Promise
Common request dispatch function
Returns: Promise - A promise that returns the call response object, or an Error if rejected. Properties
Name
Type
Description
action
string
the action name
apiUrl
string
the server call endpoint
[payload]
object
the post body
[getDataVersion]
boolean
If true return response with data version
[compress]
boolean
If true, compress the data if it is bigger than 1024 bytes

generateCommitInfo

woqlClient.generateCommitInfo(msg, [author]) ⇒ object
Generates the json structure for commit messages
Param
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

generateCommitDescriptor

woqlClient.generateCommitDescriptor(commitId)
Generates the json structure for commit descriptor
Param
Type
Description
commitId
string
a valid commit id o

prepareRevisionControlArgs

woqlClient.prepareRevisionControlArgs([rc_args]) ⇒ object | boolean
Adds an author string (from the user object returned by connect) to the commit message.
Param
Type
[rc_args]
object

updateDatabase

woqlClient.updateDatabase(dbDoc) ⇒ Promise
update the database details
Returns: Promise - A promise that returns the call response object, or an Error if rejected.
Param
Type
Description
dbDoc
object
an object that describe the database details

addDocument

woqlClient.addDocument(json, [params], [dbId], [string], [lastDataVersion], [getDataVersion]) ⇒ Promise
to add a new document or a list of new documents into the instance or the schema graph.
Returns: Promise - A promise that returns the call response object or object having result and dataVersion object if getDataVersion parameter is true, or an Error if rejected.
Param
Type
Description
json
object
[params]
typedef.DocParamsPost
the post parameters #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.
Example
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")
// 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,
)

queryDocument

woqlClient.queryDocument(query, [params], [dbId], [branch], [lastDataVersion], [getDataVersion]) ⇒ Promise
Deprecated
Use #getDocument instead.
Returns: Promise - A promise that returns the call response object or object having result and dataVersion object if getDataVersion parameter is true, or an Error if rejected.
Param
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.
Example
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
);

getDocument

woqlClient.getDocument([params], [dbId], [branch], [lastDataVersion], [getDataVersion], [query]) ⇒ Promise
Returns: Promise - A promise that returns the call response object or object having result and dataVersion object if getDataVersion parameter is true, or an Error if rejected.
Param
Type
Description
[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.
[query]
object
If a query object is provided, the function will use it to query the database.
Example
//return the schema graph as a json array
client.getDocument({"graph_type":"schema","as_list":true})
//retutn the Country class document from the schema graph
client.getDocument({"graph_type":"schema","as_list":true,"id":"Country"})
// 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,
)

updateDocument

woqlClient.updateDocument(json, [params], [dbId], [message], [lastDataVersion], [getDataVersion], [create]) ⇒ Promise
Returns: Promise - A promise that returns the call response object or object having result and dataVersion object if getDataVersion parameter is true, or an Error if rejected.
Param
Type
Description
json
object
[params]
typedef.DocParamsPut
the Put parameters #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.
[create]
boolean
If true, the function will create a new document if it doesn't exist.
Example
client.updateDocument(
{
"@id": "Person",
"@key": {
"@type": "Random",
},
"@type": "Class",
label: "xsd:string",
},
{ graph_type: "schema"