Python Client
A guide to provide the basic mechanics of the Python client.
This guide demonstrates the basic use of the WOQLClient library to connect to TerminusDB with the Python client. Refer to TerminusDB Python Client for detailed documentation. The code discussed on this page is also available in full:

Use a WOQLClient

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

Connect to a database

Connect to an existing database using the example below.
Python
connect(team=team, user="admin", db="example_db", use_token=True)

Create a database

Create a new database using the example below.
Python
client.create_database("example_db")

Basic Commands

Create schema and add documents to the schema by using the document interface. Refer to the Document Interface Reference Guide for more information. 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.
  • Create a schema
  • Add a schema
  • Add documents
  • Get documents
  • Query documents
Data: Player roster
name | position
------ | --------
George | Center Back
Doug | Full Back
Karen | Center Forward
Create a schema
Create a schema object with properties name and position. The object is uniquely identified by name.
Python
from terminusdb_client.woqlschema import WOQLSchema, DocumentTemplate, LexicalKey
schema = WOQLSchema()
class Player(DocumentTemplate):
_schema = schema
_key = LexicalKey(["name"])
name: str
position: str
Add a schema
Add the schema object to the database.
Python
Commit the schema object to the database.
schema.commit(client, commit_msg = "Adding Player Schema")
Add documents
Once a schema is added, add documents corresponding to the schema.
Python
Add documents to the schema using insert_document.
objects = [
Player(name="George", position="Centre Back"),
Player(name="Doug", position="Full Back"),
Player(name="Karen", position="Centre Forward")
]
client.insert_document(objects, commit_msg = f"Inserting player data")
Get documents
Get a list of documents or specific documents added to the schema
Python
Get a specific document using query_document. Results, stored in matches, are shown further below.
documents = client.get_all_documents()
# documents comes back as a iterable that can be convert into a list
print("All documents")
print(list(documents))
print("=============")
# getting a specific document by id
player_doug = client.get_document("Player/Doug")
print("Specific document")
print(player_doug)
All documents
[
{
'@id' : 'Player_Doug',
'@type' : 'Player',
name : 'Doug',
position: 'Full Back'
},
{
'@id' : 'Player_George',
'@type' : 'Player',
name : 'George',
position: 'Center Back'
},
{
'@id' : 'Player_Karen',
'@type' : 'Player',
name : 'Karen',
position: 'Center Forward'
}
]
=============
Specific document
{
'@id' : 'Player_Doug',
'@type' : 'Player',
name : 'Doug',
position: 'Full Back'
}

Query documents

Get a list of documents that matches the query
Python
Get a specific document using query_document. Results, stored in matches, are shown further below.
matches = client.query_document({"@type" : "Player",
"position": "Full Back"})
# matches comes back as a iterable that can be convert into a list
print(list(matches))
[{"@type" : "Player",
"name" : "Doug",
"position" : "Full Back"}]

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.
Python
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.
WOQL = WOQLQuery()
query = WOQL.triple("v:Player", "position", WOQL.string("Full Back")).triple(
"v:Player", "position", "v:position"
)
results = client.query(query)
print("Specific document using WOQL")
# results['bindings'] holds the query output as a list
print(results['bindings'])
[
{
Player: 'Player/Doug',
position: { '@type': 'xsd:string', '@value': 'Full Back' }
}
]
The following code segments demonstrate creating relationships or links between documents
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.
Python
from typing import Set
class Team(DocumentTemplate):
_schema = schema
_key = LexicalKey(["name"])
name: str
players: Set['Player']
Add a schema
Add the schema object to the database.
Python
Commit the schema object to the database.
schema.commit(client, commit_msg = "Adding Team Schema")
Add documents
Add documents corresponding to the Team schema.
Python
doug_raw = client.get_document("Player/Doug")
karen_raw = client.get_document("Player/Karen")
george_raw = client.get_document("Player/George")
doug = schema.import_objects(doug_raw)
karen = schema.import_objects(karen_raw)
george = schema.import_objects(george_raw)
team_objects = [
Team(name="Wildcats", position={doug, karen}),
Team(name="Donkeys", position={george},
]
client.insert_document(team_objects, commit_msg = f"Inserting teams data")
Get all the teams
Get a list of Team documents.
Python
teams = client.query_document({"@type" : "Team"})
print(list(matches))

See also

Export as PDF
Copy link
On this page
Use a WOQLClient
Connect to a database
Create a database
Basic Commands
Query documents
Query documents using WOQL
Create links between documents
See also