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
Example
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
Example
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.
Example
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.
Example
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.
Example
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.
Example
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.
Example
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.
Example
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.
Example
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.
Example
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.
Example
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.
Example
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.
woqlClient.local_auth
Deprecated
Use #localAuth instead.
woqlClient.remote_auth
Deprecated
Use #remoteAuth instead.
woqlClient.setApiKey(accessToken)
set the api key to access the cloud resources
woqlClient.customHeaders(customHeaders) ⇒ object
add extra headers to your request
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
woqlClient.server() ⇒ string
Gets the current connected server url it can only be set creating a new WOQLCLient instance
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
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
Example
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.
Example
woqlClient.getDatabases() ⇒ Promise
Gets the organization's databases list.
If no organization has been set up, the function throws an exception
Example
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
Example
woqlClient.user() ⇒ Object
Gets the current user object as returned by the connect capabilities response user has fields: [id, name, notes, author]
woqlClient.userOrganization() ⇒ string
Returns: string
- the user organization name
Desription: Gets the user's organization id
woqlClient.databaseInfo([dbName]) ⇒ object
Gets the database's details
Returns: object
- the database description object
woqlClient.db([dbId]) ⇒ string
| boolean
Sets / Gets the current database
Returns: string
| boolean
- - the current database or false
Example
woqlClient.setSystemDb()
Sets the internal client context to allow it to talk to the server’s internal system database
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
Example
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
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
Example
woqlClient.localAuth([newCredential]) ⇒ typedef.CredentialObj
| boolean
Sets/Gets set the database basic connection credential
Example
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
Example
woqlClient.author() ⇒ string
Gets the string that will be written into the commit log for the current user
Returns: string
- the current user
Example
woqlClient.set(params)
Example
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
Example
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.
Example
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.
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.
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.
woqlClient.info() ⇒ Promise
Gets TerminusDB Server Information
Returns: Promise
- A promise that returns the call response object, or an Error if rejected.
Example
woqlClient.squashBranch(branchId, commitMsg) ⇒ Promise
Squash branch commits
Returns: Promise
- A promise that returns the call response object, or an Error if rejected.
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.
woqlClient.optimizeBranch(branchId) ⇒ Promise
Optimize db branch
Returns: Promise
- A promise that returns the call response object, or an Error if rejected.
woqlClient.deleteBranch(branchId) ⇒ Promise
Deletes a branch from database
Returns: Promise
- A promise that returns the call response object, or an Error if rejected.
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.
woqlClient.dispatch() ⇒ Promise
Common request dispatch function
Returns: Promise
- A promise that returns the call response object, or an Error if rejected.
Properties
woqlClient.generateCommitInfo(msg, [author]) ⇒ object
Generates the json structure for commit messages
woqlClient.generateCommitDescriptor(commitId)
Generates the json structure for commit descriptor
woqlClient.prepareRevisionControlArgs([rc_args]) ⇒ object
| boolean
Adds an author string (from the user object returned by connect) to the commit message.
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.
Example
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.
Example
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.
Example
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.
Example
woqlClient.deleteDocument([params], [dbId], [message], [lastDataVersion], [getDataVersion]) ⇒ Promise
to delete the document
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.
Example
woqlClient.getSchemaFrame([type], [dbId]) ⇒ Promise
The purpose of this method is to quickly discover the supported fields of a particular type.
Returns: Promise
- A promise that returns the call response object, or an Error if rejected.
Example
woqlClient.getSchema([dbId], [branch]) ⇒ Promise
get the database schema in json format
Returns: Promise
- A promise that returns the call response object, or an Error if rejected.
Example
woqlClient.getClasses([dbId]) ⇒ Promise
get all the schema classes (documents,subdocuments,abstracts)
Returns: Promise
- A promise that returns the call response object, or an Error if rejected.
Example
woqlClient.getEnums([dbId]) ⇒ Promise
get all the Enum Objects
Returns: Promise
- A promise that returns the call response object, or an Error if rejected.
Example
woqlClient.getClassDocuments([dbId]) ⇒ Promise
get all the Document Classes (no abstract or subdocument)
Returns: Promise
- A promise that returns the call response object, or an Error if rejected.
Example
woqlClient.getBranches([dbId]) ⇒ Promise
get the database collections list
Returns: Promise
- A promise that returns the call response object, or an Error if rejected.
Example
woqlClient.getCommitsLog([dbId]) ⇒ Promise
get the database collections list
Returns: Promise
- A promise that returns the call response object, or an Error if rejected.
Example
woqlClient.getPrefixes([dbId]) ⇒ Promise
get the database prefixes object
Returns: Promise
- A promise that returns the call response object, or an Error if rejected.
Example
woqlClient.getUserOrganizations() ⇒ Promise
Get the list of the user's organizations and the database related
Returns: Promise
- A promise that returns the call response object, or an Error if rejected.
Example
woqlClient.userOrganizations([orgList]) ⇒ array
Get/Set the list of the user's organizations (id, organization, label, comment).
Returns: array
- the user Organizations list
Example
woqlClient.getJSONDiff(before, after, [options]) ⇒ Promise
Get the patch of difference between two documents.
Returns: Promise
- A promise that returns the call response object, or an Error if rejected.
Example
woqlClient.getVersionObjectDiff(dataVersion, jsonObject, id, [options]) ⇒ Promise
Get the patch of difference between two documents.
Returns: Promise
- A promise that returns the call response object, or an Error if rejected.
Example
woqlClient.getVersionDiff(beforeVersion, afterVersion, [id], [options]) ⇒ Promise
Get the patch of difference between branches or commits.
Returns: Promise
- A promise that returns the call response object, or an Error if rejected.
Example
woqlClient.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")
Example
woqlClient.patch(before, patch) ⇒ Promise
Patch the difference between two documents.
Returns: Promise
- A promise that returns the call response object, or an Error if rejected.
Example
woqlClient.sendCustomRequest(requestType, customRequestURL, [payload]) ⇒ Promise
Call a custom Api endpoit
Returns: Promise
- A promise that returns the call response object, or an Error if rejected.
Example
Param | Type | Description |
---|---|---|
Param | Type | Description |
---|---|---|
Param | Type | Description |
---|---|---|
Param | Type | Description |
---|---|---|
Param | Type | Description |
---|---|---|
Param | Type | Description |
---|---|---|
Param | Type | Description |
---|---|---|
Param | Type | Description |
---|---|---|
Param | Type | Description |
---|---|---|
Param | Type | Description |
---|---|---|
Param | Type | Description |
---|---|---|
Param | Type | Description |
---|---|---|
Param | Type | Description |
---|---|---|
Param | Type |
---|---|
Param | Type |
---|---|
Param | Type | Description |
---|---|---|
Param | Type | Description |
---|---|---|
Param | Type | Description |
---|---|---|
Param | Type | Description |
---|---|---|
Param | Type | Description |
---|---|---|
Param | Type | Description |
---|---|---|
Param | Type | Description |
---|---|---|
Param | Type | Description |
---|---|---|
Param | Type |
---|---|
Param | Type |
---|---|
Param | Type | Description |
---|---|---|
Param | Type | Description |
---|---|---|
Param | Type | Description |
---|---|---|
Param | Type | Description |
---|---|---|
Param | Type | Description |
---|---|---|
Param | Type | Description |
---|---|---|
Param | Type | Description |
---|---|---|
Param | Type | Description |
---|---|---|
Param | Type | Description |
---|---|---|
Param | Type | Description |
---|---|---|
Param | Type | Description |
---|---|---|
Name | Type | Description |
---|---|---|
Param | Type | Description |
---|---|---|
Param | Type | Description |
---|---|---|
Param | Type |
---|---|
Param | Type | Description |
---|---|---|
Param | Type | Description |
---|---|---|
Param | Type | Description |
---|---|---|
Param | Type | Description |
---|---|---|
Param | Type | Description |
---|---|---|
Param | Type | Description |
---|---|---|
Param | Type | Description |
---|---|---|
Param | Type | Description |
---|---|---|
Param | Type |
---|---|
Param | Type |
---|---|
Param | Type | Description |
---|---|---|
Param | Type | Description |
---|---|---|
Param | Type | Description |
---|---|---|
Param | Type | Description |
---|---|---|
Param | Type | Description |
---|---|---|
Param | Type | Description |
---|---|---|
Param | Type | Description |
---|---|---|
Param | Type | Description |
---|---|---|
Param | Type | Description |
---|---|---|
Param | Type | Description |
---|---|---|
serverUrl
string
the terminusdb server url
[params]
typedef.ParamsObj
an object with the connection parameters
[params]
typedef.ParamsObj
TerminusDB Server connection parameters
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
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
graphType
typedef.GraphType
type of graph to get triples from, either “instance” or “schema”
graphType
string
type of graph
turtle
string
string encoding triples in turtle (ttl) format
commitMsg
string
Textual message describing the reason for the update
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.
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”)
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.
rebaseSource
object
json describing the source branch to be used as a base
remoteSourceRepo
typedef.RemoteRepoDetails
an object describing the source of the pull
remoteTargetRepo
typedef.RemoteRepoDetails
an object describing the target of the push {remote: "origin", "remote_branch": "main", "author": "admin", "message": "message"}
remoteId
string
if of the remote to fetch (eg: 'origin')
accessToken
string
customHeaders
object
[orgId]
string
| boolean
the organization id to set the context to
[orgName]
string
the organization id to set the context to
[dbName]
string
the db name to set the context to
[dbList]
array
a list of databases the user has access to on the server, each having:
[dbName]
string
the datbase name
[dbId]
string
the database id to set the context to
[repoId]
typedef.RepoType
| string
default value is local
[branchId]
string
the branch id to set the context to
[commitId]
string
the reference ID or commit ID
[newCredential]
typedef.CredentialObj
[newCredential]
typedef.CredentialObj
params
typedef.ParamsObj
a object with connection params
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
dbDoc
typedef.DbDoc
object containing details about the database to be updated
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
string
textual string
[pathname]
string
a server path to send the message to
actionName
string
structure of the action
[payload]
object
a request body call
branchId
string
local identifier of the new branch
commitMsg
string
Textual message describing the reason for the update
branchId
string
local identifier of the new branch
commitId
string
Reference ID or Commit ID
branchId
string
local identifier of the new branch
branchId
string
local identifier of the branch
commitPath
string
The commit path to set the current branch to
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
msg
string
textual string describing reason for the change
[author]
string
optional author id string - if absent current user id will be used
commitId
string
a valid commit id o
[rc_args]
object
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.
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.
[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
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.
[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.
[type]
string
If given, the type to get information for. If omitted, information for all types is returned
[dbId]
string
the database id
[dbId]
string
the database id
[branch]
string
specific a branch/collection
[dbId]
string
the database id
[dbId]
string
[dbId]
string
[dbId]
string
the database id
[dbId]
string
the database id
[dbId]
string
the database id
[orgList]
array
a list of user's Organization
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.
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.
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]
object
{keep:{}} 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.
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
before
object
The current state of JSON document
patch
object
The patch object
requestType
string
The current state of JSON document
customRequestURL
string
The patch object
[payload]
object
the request payload