Start with a Client API
A step-by-step guide with examples to install and get started with a JavaScript or Python client.
This guide demonstrates the basic use of the WOQLClient library to connect to TerminusX with a JavaScript or Python client. Refer to TerminusDB JavaScript Client or TerminusDB Python Client for detailed documentation. The code discussed on this page is also available in full:

Install WOQLClient

JavaScript
Python
Install the TerminusDB JavaScript client by adding it as a dependency in your Node project.
1
npm install --save @terminusdb/terminusdb-client
Copied!
Install the Python client using pip. Using a virtual environment is recommended - see Python documentation.
Create a new virtual environment named terminusdb-env
1
python3 -m venv terminusdb-env
Copied!
Activate terminusdb-env environment
Unix/macOS:
1
source terminusdb-env/bin/activate
Copied!
Windows:
1
.\terminusdb-env\Scripts\activate
Copied!
Install the Python client
1
python3 -m pip install terminusdb-client
Copied!

Connect with WOQLClient

A WOQLClient object enables connection to TerminusX (or TerminusDB.) To create a client object:
  • Copy the JavaScript/Python code snippet generated in the step above.
  • Provide the URL to a database server.

Define a WOQLClient

Define and initialize a WOQLClient, and connect to a database using the example below.

Code: Define and initialize a WOQLClient

JavaScript
Python
Use the package @terminusdb/terminusdb-client
1
const TerminusDBClient = require("@terminusdb/terminusdb-client");
2
3
// TODO: change the team name
4
const team = "TEAM_NAME";
5
const client = new TerminusDBClient.WOQLClient(`https://cloud.terminusdb.com/${team}/`, {
7
organization: team
8
});
9
10
//set the key as an environment variable.
11
client.setApiKey(process.env.TERMINUSDB_ACCESS_TOKEN)
Copied!
1
from terminusdb_client import WOQLClient
2
user = "jimbo"
3
team = "logicistics" # My team name.
4
endpoint = f"https://cloud.terminusdb.com/{team}/"
5
client = WOQLClient(endpoint)
6
7
client.connect(user=user, team=team, use_token=True)
Copied!

Use a WOQLClient

Common uses of a WOQLClient include Connecting to an existing database and creating a new database.

Code: Connect to a database

Connect to an existing database using the example below.
JavaScript
Python
1
client.db('ExampleDatabase');
Copied!
1
connect(team=team, user="admin", db="example_db", use_token=True)
Copied!

Code: Create a database

Create a new database using the example below.
JavaScript
Python
1
const createNewDB = async () => {
2
try {
3
4
await client.createDatabase('ExampleDatabase', {
5
label: "ExampleDatabase",
6
comment: "Created new ExampleDatabase",
7
});
8
9
console.log("Database created Successfully!")
10
11
} catch (err) {
12
console.error(err)
13
}
14
};
15
16
createNewDB();
Copied!
1
client.connect(team=team, user="admin", use_token=True)
2
client.create_database("example_db")
Copied!

Use the document interface

To use the TerminusX document interface, create a schema and add documents to the schema. Refer to Documents for an overview of the document interface. After creating or connecting to a database, create a schema to add and retrieve data. A simple player roster is used as an example. Using basic Player roster data, the steps below are demonstrated.

Data: Player roster

1
name | position
2
------ | --------
3
George | Center Back
4
Doug | Full Back
5
Karen | Center Forward
Copied!

Code: Create a schema

Create a schema object with properties name and position. The object is uniquely identified by name.
JavaScript
Python
1
const schema = { "@type" : "Class",
2
"@id" : "Player",
3
"@key" : { "@type": "Lexical", "@fields": ["name"] },
4
name : "xsd:string",
5
position: "xsd:string" };
Copied!
1
from terminusdb_client.woqlschema import WOQLSchema, DocumentTemplate, LexicalKey
2
3
schema = WOQLSchema()
4
5
class Player(DocumentTemplate):
6
_schema = schema
7
_key = LexicalKey(["name"])
8
name: str
9
position: str
Copied!

Code: Add a schema

Add the schema object to the database.
JavaScript
Python
Add the schema object to a document using addDocument which returns a Promise.
1
await client.addDocument(schema, { graph_type: "schema" })
Copied!
Commit the schema object to the database.
1
schema.commit(client, commit_msg = "Adding Player Schema")
Copied!

Code: Add documents

Once a schema is added, add documents corresponding to the schema.
JavaScript
Python
Add documents to the schema using addDocument which returns a Promise.
1
const objects = [
2
{
3
"@type" : "Player",
4
name : "George",
5
position: "Center Back",
6
},
7
{
8
"@type" : "Player",
9
name : "Doug",
10
position: "Full Back",
11
},
12
{
13
"@type" : "Player",
14
name : "Karen",
15
position: "Center Forward"
16
}
17
];
18
19
await client.addDocument(objects);
Copied!
Add documents to the schema using insert_document.
1
objects = [
2
Player(name="George", position="Centre Back"),
3
Player(name="Doug", position="Full Back"),
4
Player(name="Karen", position="Centre Forward")
5
]
6
7
client.insert_document(objects, commit_msg = f"Inserting player data")
Copied!

Code: Get documents

Get a list of documents or specific documents added to the schema
JavaScript
Python
Get a list of documents using getDocument as_list. Results, stored in document, are shown further below.
1
const getDocs = async () => {
2
const documents = await client.getDocument({ as_list: "true" });
3
console.log("All Documents", documents)
4
}
Copied!
1
[
2
{
3
'@id' : 'Player/Doug',
4
'@type' : 'Player',
5
name : 'Doug',
6
position: 'Full Back'
7
},
8
{
9
'@id' : 'Player/George',
10
'@type' : 'Player',
11
name : 'George',
12
position: 'Center Back'
13
},
14
{
15
'@id' : 'Player/Karen',
16
'@type' : 'Player',
17
name : 'Karen',
18
position: 'Center Forward'
19
}
20
]
Copied!
Get a specific document using query_document. Results, stored in matches, are shown further below.
1
documents = client.get_all_documents()
2
3
# documents comes back as a iterable that can be convert into a list
4
print("All documents")
5
print(list(documents))
6
7
print("=============")
8
9
# getting a specific document by id
10
player_doug = client.get_document("Player/Doug")
11
print("Specific document")
12
print(player_doug)
Copied!
1
All documents
2
[
3
{
4
'@id' : 'Player_Doug',
5
'@type' : 'Player',
6
name : 'Doug',
7
position: 'Full Back'
8
},
9
{
10
'@id' : 'Player_George',
11
'@type' : 'Player',
12
name : 'George',
13
position: 'Center Back'
14
},
15
{
16
'@id' : 'Player_Karen',
17
'@type' : 'Player',
18
name : 'Karen',
19
position: 'Center Forward'
20
}
21
]
22
=============
23
Specific document
24
{
25
'@id' : 'Player_Doug',
26
'@type' : 'Player',
27
name : 'Doug',
28
position: 'Full Back'
29
}
Copied!

Code: Query documents

Get a list of documents that matches the query
JavaScript
Python
Get a list of documents using getDocument as_list. Results, stored in document, are shown further below.
1
const queryDocuments = async () => {
2
const query = {
3
"type": "Player",
4
"query": { "position": "Full Back" },
5
}
6
const result = await client.queryDocument(query,{"as_list":true});
7
console.log("Query Documents",result)
8
}
Copied!
1
[{"@type" : "Player",
2
"name" : "Doug",
3
"position" : "Full Back"}]
Copied!
Get a specific document using query_document. Results, stored in matches, are shown further below.
1
matches = client.query_document({"@type" : "Player",
2
"position": "Full Back"})
3
4
# matches comes back as a iterable that can be convert into a list
5
print(list(matches))
Copied!
1
[{"@type" : "Player",
2
"name" : "Doug",
3
"position" : "Full Back"}]
Copied!

Code: Query documents using WOQL

Query documents using Web Object Query Language (WOQL) to get the same result given by the above example. You can find more about WOQL here.
JavaScript
Python
Get documents using using WOQL.triple() to create a WOQL query then execute that query using client.query(). Results, stored in results, are shown further below
1
const queryDocuments = async () => {
2
const { WOQL } = TerminusDBClient;
3
const query = WOQL.triple(
4
"v:Player",
5
"position",
6
WOQL.string("Full Back")
7
).triple("v:Player", "position", "v:position");
8
const results = await client.query(query);
9
console.log("Query Documents using WOQL: ",results.bindings);
10
}
Copied!
1
[
2
{
3
Player: 'Player/Doug',
4
position: { '@type': 'xsd:string', '@value': 'Full Back' }
5
}
6
]
Copied!
Get documents using WOQLQuery() and WOQLQuery().triple() to create a WOQL query then execute that query using client.query(). Results, stored in results, are shown further below.
1
WOQL = WOQLQuery()
2
query = WOQL.triple("v:Player", "position", WOQL.string("Full Back")).triple(
3
"v:Player", "position", "v:position"
4
)
5
results = client.query(query)
6
print("Specific document using WOQL")
7
# results['bindings'] holds the query output as a list
8
print(results['bindings'])
Copied!
1
[
2
{
3
Player: 'Player/Doug',
4
position: { '@type': 'xsd:string', '@value': 'Full Back' }
5
}
6
]
Copied!
The following code segments demonstrate creating relationships or links between documents

Code: Create schema for team

The Team object is uniquely identified by the property name. The players property consists of a set of Player classes that create a link between theTeam and Player schema.
Javascript
Python
1
const team_schema = [
2
{
3
"@type" : "Class",
4
"@id" : "Team",
5
"@key" : {
6
"@type": "Lexical",
7
"@fields": ["name"]
8
},
9
name : "xsd:string",
10
players: { "@type" : "Set",
11
"@class" : "Player" },
12
}
13
];
Copied!
1
from typing import Set
2
3
class Team(DocumentTemplate):
4
_schema = schema
5
_key = LexicalKey(["name"])
6
name: str
7
players: Set['Player']
Copied!

Code: Add a schema

Add the schema object to the database.
JavaScript
Python
Add the schema object to a document using addDocument that returns a Promise.
1
await client.addDocument(team_schema, { graph_type: "schema" })
Copied!
Commit the schema object to the database.
1
schema.commit(client, commit_msg = "Adding Team Schema")
Copied!

Code: Add documents

Add documents corresponding to the Team schema.
JavaScript
Python
1
const team_instance = [
2
{
3
"@type" : "Team",
4
name : "Wildcats",
5
players: ["Player/Doug", "Player/Karen"],
6
},
7
{
8
"@type" : "Team",
9
name : "Donkeys",
10
players: ["Player/George"],
11
}
12
]
13
14
await client.addDocument(team_instance)
Copied!
1
doug_raw = client.get_document("Player/Doug")
2
karen_raw = client.get_document("Player/Karen")
3
george_raw = client.get_document("Player/George")
4
5
doug = schema.import_objects(doug_raw)
6
karen = schema.import_objects(karen_raw)
7
george = schema.import_objects(george_raw)
8
9
team_objects = [
10
Team(name="Wildcats", position={doug, karen}),
11
Team(name="Donkeys", position={george},
12
]
13
14
client.insert_document(team_objects, commit_msg = f"Inserting teams data")
Copied!

Code: Get all the teams

Get a list of Team documents.
JavaScript
Python
1
const getTeams = async () => {
2
const query = {
3
"type": "Team",
4
};
5
const result = await client.queryDocument(query, {"as_list":true});
6
console.log("Teams ",result)
7
}
Copied!
1
teams = client.query_document({"@type" : "Team"})
2
3
print(list(matches))
Copied!

See also

Client reference

JavaScript and Python client reference guides.

Tutorials