WOQLClient

WOQLClient
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.
License: Apache Version 2
new WOQLClient(serverUrl, [params])
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 TerminusCMS 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")
hasDatabase
woqlClient.hasDatabase([orgName], [dbName]) ⇒ Promise
Checks if a database exists
Returns true if a DB exists and false if it doesn't. Other results throw an exception.
Param
Type
Description
[orgName]
string
the organization id to set the context to
[dbName]
string
the db name to set the context to
Example
async function executeIfDatabaseExists(f){
     const hasDB = await client.hasDatabase("admin", "testdb")
     if (hasDB) {
         f()
     }
}
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")
updateDatabase
woqlClient.updateDatabase(dbDoc) ⇒ Promise
Update a database in TerminusDB server
Returns: Promise - A promise that returns the call response object, or an Error if rejected.
Param
Type
Description
dbDoc
typedef.DbDoc
object containing details about the database to be updated
Example
client.updateDatabase({id: "mydb", label: "My Database", comment: "Testing"})
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

Param	Type	Description
serverUrl	`string`	the terminusdb server url
[params]	`typedef.ParamsObj`	an object with the connection parameters

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

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`

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

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.

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”)

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.

Param	Type	Description
[orgName]	`string`	the organization id to set the context to
[dbName]	`string`	the db name to set the context to

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

Param	Type	Description
message	`string`	textual string
[pathname]	`string`	a server path to send the message to

Param	Type	Description
actionName	`string`	structure of the action
[payload]	`object`	a request body call

Param	Type	Description
branchId	`string`	local identifier of the new branch
commitMsg	`string`	Textual message describing the reason for the update

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