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-client1
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}/`, {
6
user: "[email protected]",
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
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 below1
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!
Create links between documents
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
Tutorials
Last modified 1mo ago