Generating ID with SHA256 using provided keys
Generating ID with urllib.parse.quote using provided keys
Generating ID with SHA256
Generating ID with UUID4
add_enum_class
Construct a TerminusDB Enum class by provideing class name and member values then add into the schema.
Arguments:
class_name
(str
): Name of the class object constructed.
class_values
(list
): A list of values in this Enum.
Returns:
EnumMetaTemplate
: A Enum object with the sepcified name and members
commit
Commit the schema to database
Arguments:
client
(Client
): A client that is connected to a database.
commit_msg
(str
): Commit message.
full_replace
(bool
): Does the commit fully wiped out the old shcema graph. Default to be False.
from_db
Load classes in the database schema into schema
Arguments:
client
(Client
): Client that is connected to the database
select
(list of str
): The classes (and depended classes) that will be imported, default to None which will import all classes
import_objects
Import a list of documents in json format to Python objects. The schema of those documents need to be in this schema.
from_json_schema
Load class object from json schema (http://json-schema.org/) and, if pipe mode is off, add into schema. All referenced object will be treated as subdocuments.
Arguments:
name
(str
): Name of the class object.
json_schema
(dict or str or StringIO
): Json Schema in dictionary or jsonisable string format or json file stream.
pipe
(bool
): Pipe mode, if True will return the schema in TerminusDB dictionary format (just like calling to_dict) WITHOUT loading the schema into the schema object. Default to False.
subdoc
(bool
): If not in pipe mode, the class object will be added as a subdocument class.
to_dict
Return the schema in the TerminusDB dictionary format
to_json_schema
Return the schema in the json schema (http://json-schema.org/) format as a dictionary for the class object.
Arguments:
class object
(str or dict
): Name of the class object or the class object represented as dictionary.
Get all documents in the database, use –schema to specify schema, –type to select type and -q to make queries (e.g. -q date=2021-07-01)`
If using –type and not –schema, can export using -e with options: –keepid, –maxdep and –filename
Options
-s, --schema()
Specify if getting schema object instead
-t, --type <type_>
Type of the objects to be getting back
-q, --query <query>
Use query to filter out objects getting back. Need to be used with -t/–type
-h, --head <head>
Show/ export only set number of documents max
-e, --export()
Specify if the result to be export as CSV. Only usable when using –t/–type and not -s/-–schema
--keepid()
Option for export: if the id of the object is to be kept in the CSV
--maxdep <maxdep>
Option for export: specify the depth of the embedding operation
Default
2
--filename <filename>
Option for export: file name if the exported file
Create or list branch.
Options
-d, --delete <delete>
Branch(es) to be deleted
Arguments
BRANCH_NAME()
Optional argument
Switch branches. Use -b to create and switch to new branch.
Options
-b, --branch()
Arguments
BRANCH_NAME()
Required argument
Push the current schema plan in schema.py to database.
Options
-m, --message <message>
Commit message for the commit
Show or set config.json of the project. To set a config, use =, e.g. streams=MyClass or streams=[Class1, Class2]
Options
-d, --delete <delete>
Keys of items in the config.json to be deleted
Arguments
SET_CONFIG()
Optional argument(s)`
Delete the database in this project.
Export all documents in a TerminusDB class into a flatten CSV file.
Options
--keepid()
If used, the id of the object and the other meta (@) is to be kept as is in the CSV
--maxdep <maxdep>
Specify the depth of the embedding operation. When maximum is hit, the values will be kept as object ids
Default
2
--filename <filename>
File name if the exported file, if not specify it will use the name of the class e.g. ‘ClassName.csv’
Arguments
CLASS_OBJ()
Required argument
Import CSV file into pandas DataFrame then into TerminusDB, with read_csv() options. Options like chunksize, sep etc
Options
--classname <class_name>
Customize the class name that the data from the CSV will be import as
--chunksize <chunksize>
Large files will be load into database in chunks, size of the chunks
Default
1000
--schema()
Specify if schema to be updated if existed, default False
--na <na>
Specify how to handle NAs: ‘skip’ will skip entries with NAs, ‘optional’ will make all properties optional in the database, ‘error’ will just throw an error if there’s NAs
Options
skip | optional | error
--id <id_>
Specify column to be used as ids instead of generated ids
-e, --embedded <embedded>
Specify embedded columns
-m, --message <message>
Commit message for the import
--sep <sep>
Specify separator character in the CSV
Default
,
Arguments
CSV_FILE()
Required argument
KEYS()
Optional argument(s)`
Show commit log of the project.
Reapply commits on top of another base tip on another branch.
Arguments
BRANCH_NAME()
Required argument
Reset the head of the commit to a certain commit with id as input. Default to be a hard reset (newer commit will be wipped, not reversible). If no commit is is provided, it will reset to the newest commit.
Options
--soft()
Soft reset (referencing that commit) instead of hard reset (default, reset the state of the commit for the database, not reversible)`
Arguments
COMMIT()
Optional argument
Create the template files into current working directory
Show the working status of the project.
Pull the current schema plan in database to schema.py
__init__
defines the internal functions of the woql query object - the language API is defined in WOQLQuery
Arguments:
query
(dict
): json-ld query for initialisation
graph
(str
): graph that this query is appled to, default to be schema/main
__add__
Creates a logical AND with the argument passed, for WOQLQueries.
Arguments:
other
(WOQLQuery object
): None
Returns:
WOQLQuery object
: query object that can be chained and/or execute
__and__
Creates a logical AND with the argument passed, for WOQLQueries.
Arguments:
other
(WOQLQuery object
): None
Returns:
WOQLQuery object
: query object that can be chained and/or execute
__or__
Creates a logical OR with the argument passed, for WOQLQueries.
Arguments:
other
(WOQLQuery object
): None
Returns:
WOQLQuery object
: query object that can be chained and/or execute
__invert__
Creates a logical Not with the argument passed, for WOQLQueries.
Arguments:
other
(WOQLQuery object
): None
Returns:
WOQLQuery object
: query object that can be chained and/or execute
execute
Executes the query using the passed client to connect to a server
Arguments:
client
(Client object
): client that provide connection to the database for the query to execute.
commit_msg
(str
): optional, commit message for this query. Recommended for query that carrries an update.
file_dict
(``): File dictionary to be associated with post name => filename, for multipart POST
to_json
Dumps the JSON-LD format of the query in a json string
from_json
Set a query from a JSON-LD json string
to_dict
Give the dictionary that represents the query in JSON-LD format.
from_dict
Set a query from a dictionary that represents the query in JSON-LD format.
load_vocabulary
Queries the schema graph and loads all the ids found there as vocabulary that can be used without prefixes ignoring blank node ids
using
Use a specific data product for the enclosed query
Arguments:
collection
(str
): the name of the data product
Returns:
WOQLQuery object
: query object that can be chained and/or execute
comment
Adds a text comment to a query - can also be used to wrap any part of a query to turn it off
Arguments:
comment
(str
): text comment
Returns:
WOQLQuery object
: query object that can be chained and/or execute
select
Filters the query so that only the variables included in [V1...Vn] are returned in the bindings
Arguments:
args
: only these variables are returned
Returns:
WOQLQuery object
: query object that can be chained and/or execute
distinct
Ensures that the solutions for the variables [V1...Vn] are distinct
Arguments:
args
: The variables to make distinct with the final argument being a query.
Returns:
WOQLQuery object
: query object that can be chained and/or execute
woql_and
Creates a logical AND of the arguments
Commonly used to combine WOQLQueries.
Arguments:
args
(WOQLQuery objects
): None
Returns:
WOQLQuery object
: query object that can be chained and/or execute
woql_or
Creates a logical OR of the arguments
Arguments:
args
(WOQLQuery objects
): None
Returns:
WOQLQuery object
: query object that can be chained and/or execute
woql_from
Specifies the database URL that will be the default database for the enclosed query
Arguments:
graph
(str
): url of the database
query
(WOQLQuery object
): None
Returns:
WOQLQuery object
: query object that can be chained and/or execute
into
Sets the current output graph for writing output to.
Arguments:
graph_descriptor
(str
): output graph
query
(WOQLQuery object
): None
Returns:
WOQLQuery object
: query object that can be chained and/or execute
triple
Creates a triple pattern matching rule for the triple [S, P, O] (Subject, Predicate, Object)
Arguments:
sub
(str
): Subject, has to be a node (URI)
pred
(str
): Predicate, can be variable (prefix with "v:") or node
obj
(str
): Object, can be variable or node or value
opt
(bool
): weather or not this triple is optional, default to be False
Returns:
WOQLQuery object
: query object that can be chained and/or execute
added_triple
Creates a triple pattern matching rule for the triple [S, P, O] (Subject, Predicate, Object) added to the current commit.
Arguments:
sub
(str
): Subject
pred
(str
): Predicate
obj
(str
): Object
opt
(bool
): weather or not this triple is optional, default to be False
Returns:
WOQLQuery object
: query object that can be chained and/or execute
removed_triple
Creates a triple pattern matching rule for the triple [S, P, O] (Subject, Predicate, Object) added to the current commit.
Arguments:
sub
(str
): Subject
pred
(str
): Predicate
obj
(str
): Object
opt
(bool
): weather or not this triple is optional, default to be False
Returns:
WOQLQuery object
: query object that can be chained and/or execute
quad
Creates a pattern matching rule for the quad [S, P, O, G] (Subject, Predicate, Object, Graph)
Arguments:
sub
(str
): Subject
pre
(str
): Predicate
obj
(str
): Object
gra
(str
): Graph
opt
(bool
): weather or not this quad is optional, default to be False
Returns:
WOQLQuery object
: query object that can be chained and/or execute
added_quad
Creates a pattern matching rule for the quad [S, P, O, G] (Subject, Predicate, Object, Graph) added to the current commit.
Arguments:
sub
(str
): Subject
pre
(str
): Predicate
obj
(str
): Object
gra
(str
): Graph
opt
(bool
): weather or not this quad is optional, default to be False
Returns:
WOQLQuery object
: query object that can be chained and/or execute
removed_quad
Creates a pattern matching rule for the quad [S, P, O, G] (Subject, Predicate, Object, Graph) added to the current commit.
Arguments:
sub
(str
): Subject
pre
(str
): Predicate
obj
(str
): Object
gra
(str
): Graph
opt
(bool
): weather or not this quad is optional, default to be False
Returns:
WOQLQuery object
: query object that can be chained and/or execute
string
Transforms the given string into the proper json-ld form
Arguments:
input_str
(str
): the given input string
Returns:
dict
:
boolean
Transforms the given bool object into the proper json-ld form
Arguments:
input_bool
(bool
): the given input string
Returns:
dict
:
datetime
Transforms the given datetime object into the proper json-ld form
Arguments:
input_obj
(str
): the given input dateTime object
Returns:
dict
:
sub
Returns true if child is a sub-class of parent, according to the current DB schema
Arguments:
parent
(str
): the parent class to be checked
child
(str
): the child class to be checked
Returns:
bool
:
eq
Matches if a is equal to b
Arguments:
left
(str
): object in the graph
right
(str
): object in the graph
Returns:
WOQLQuery object
: query object that can be chained and/or execute
update_document
Update a document in the database
Arguments:
docjson
(JSON
): object to be updated
json_or_iri
(str
): the output ID, or a JSON to compare the ID against
Returns:
WOQLQuery object
: query object that can be chained and/or execute
insert_document
Insert a document into the database
Arguments:
docjson
(JSON
): object to be inserted
json_or_iri
(str
): the output ID, or a JSON to compare the ID against
Returns:
WOQLQuery object
: query object that can be chained and/or execute
delete_document
Delete a document into the database
Arguments:
docjson
(JSON
): object to be deleted
json_or_iri
(str
): the output ID, or a JSON to compare the ID against
Returns:
WOQLQuery object
: query object that can be chained and/or execute
read_document
Read a document from the database
query = (WOQLQuery().triple('v:TermId', 'rdf:type', '@schema:Term') & WOQLQuery().triple('v:TermCountId','term','v:TermId') & WOQLQuery().triple('v:DocumentId', 'terms', 'v:TermCountId') & WOQLQuery().read_document('v:TermId','v:TermDoc'))
get
Takes an as structure
put
Takes an array of variables, an optional array of column names
file
Provides details of a file source in a JSON format that includes a URL property
Arguments:
fpath
(dict
): file data source in a JSON format
opts
(input options
): optional
Returns:
WOQLQuery object
: query object that can be chained and/or execute
once
Obtains only one result from subquery
Arguments:
query
(WOQLQuery object
): None
Returns
: None
----------
: None
WOQLQuery object
: query object that can be chained and/or executed
remote
Provides details of a remote data source in a JSON format that includes a URL property
Arguments:
uri
(str
): remote data source
opts
(input options
): optional
Returns:
WOQLQuery object
: query object that can be chained and/or execute
delete_triple
Deletes any triples that match the rule [subject, predicate, object]
Arguments:
subject
(str
): Subject
predicate
(str
): Predicate
object_or_literal
(str
): Object or Literal
Returns:
WOQLQuery object
: query object that can be chained and/or execute
add_triple
Adds triples according to the the pattern [subject, predicate, object]
Arguments:
subject
(str
): Subject
predicate
(str
): Predicate
object_or_literal
(str
): Object or Literal
Returns:
WOQLQuery object
: query object that can be chained and/or execute
delete_quad
Deletes any quads that match the rule [subject, predicate, object, graph]
Arguments:
subject
(str
): Subject
predicate
(str
): Predicate
object_or_literal
(str
): Object or Literal
graph
(str
): Graph
Returns:
WOQLQuery object
: query object that can be chained and/or execute
add_quad
Adds quads according to the pattern [subject, predicate, object, graph]
Arguments:
subject
(str
): Subject
predicate
(str
): Predicate
object_or_literal
(str
): Object or Literal
graph
(str
): Graph
Returns:
WOQLQuery object
: query object that can be chained and/or execute
trim
A trimmed version of untrimmed (with leading and trailing whitespace removed) is copied into trimmed
Arguments:
untrimmed
(str
): original string
trimmed
(str
): WOQL varible storing the result string
Returns:
WOQLQuery object
: query object that can be chained and/or execute
eval
Evaluates the Arithmetic Expression Arith and copies the output to variable V
Arguments:
arith
(WOQLQuery or dict
): query or JSON-LD representing the query
res
(str
): output variable
Returns:
WOQLQuery object
: query object that can be chained and/or execute
plus
Adds numbers N1...Nn together
Arguments:
args
(int or float
): numbers to add together
Returns:
WOQLQuery object
: query object that can be chained and/or execute
minus
Adds numbers N1...Nn together
Arguments:
args
(int or float
): numbers to add together
Returns:
WOQLQuery object
: query object that can be chained and/or execute
times
Multiplies numbers N1...Nn together
Arguments:
args
(int or float
): numbers to be multiplied
Returns:
WOQLQuery object
: query object that can be chained and/or execute
divide
Divides numbers N1...Nn by each other left, to right precedence
Arguments:
args
(int or float
): numbers to be divided
Returns:
WOQLQuery object
: query object that can be chained and/or execute
div
Division - integer division - args are divided left to right
Arguments:
args
(int or float
): numbers for division
Returns:
WOQLQuery
: query object that can be chained and/or execute
exp
Raises A to the power of B
Arguments:
first
(int or float
): base number
second
(int or float
): power of
Returns:
WOQLQuery object
: query object that can be chained and/or execute
floor
The floor function of a real number x denotes the greatest integer less than or equal to x.
Arguments:
user_input
(int or float
): number whose floor needs to be calculated
Returns:
WOQLQuery object
: query object that can be chained and/or execute
isa
Matches if element is a member of a certain type, according to the current state of the DB
Arguments:
element
(str
): element to be checked
of_type
(str
): type to be checked
Returns:
bool
:
like
Matches left string to right string with a distance
Arguments:
left
(str
): first string to compare
right
(str
): second string to compare
dist
(str
): Hamming distance between left and right
Returns:
WOQLQuery object
: query object that can be chained and/or execute
less
Compares the value of v1 against v2 and returns true if v1 is less than v2
Arguments:
left
(str
): first variable to compare
right
(str
): second variable to compare
Returns:
WOQLQuery object
: query object that can be chained and/or execute
greater
Compares the value of v1 against v2 and returns true if v1 is greater than v2
Arguments:
left
(str
): first variable to compare
right
(str
): second variable to compare
Returns:
WOQLQuery object
: query object that can be chained and/or execute
opt
The Query in the Optional argument is specified as optional
Arguments:
query
(WOQLQuery object
): None
Returns:
WOQLQuery object
: query object that can be chained and/or execute
unique
Generates an ID for a node as a function of the passed VariableList with a specific prefix (URL base)(A.K.A Hashing) If the values of the passed variables are the same, the output will be the same
Arguments:
prefix
(str
): prefix for the id
key_list
(str
): variable to generate id for
uri
(str
): the variable to hold the id
Returns:
WOQLQuery object
: query object that can be chained and/or execute
idgen
Generates an ID for a node as a function of the passed VariableList with a specific prefix (URL base). If the values of the passed variables are the same, the output will be the same
Arguments:
prefix
(str
): prefix for the id
input_var_list
(str or list
): variable to generate id for
output_var
(str
): the variable to hold the id
Returns:
WOQLQuery object
: query object that can be chained and/or execute
random_idgen
Randomly generates an ID and appends to the end of the key_list.
Arguments:
prefix
(str
): prefix for the id
key_list
(str
): variable to generate id for
uri
(str
): the variable to hold the id
Returns:
WOQLQuery object
: query object that can be chained and/or execute
upper
Changes a string to upper-case - input is in left, output in right
Arguments:
left
(str
): input string
right
(str
): stores output
Returns:
WOQLQuery object
: query object that can be chained and/or execute
lower
Changes a string to lower-case - input is in u, output in l
Arguments:
left
(str
): input string
right
(str
): stores output
Returns:
WOQLQuery object
: query object that can be chained and/or execute
pad
Pads out the string input to be exactly len long by appending the pad character pad to form output
Arguments:
user_input
(str
): input string
pad
(str
): padding character(s)
length
(int
): length to pad
output
(str
): stores output
Returns:
WOQLQuery object
: query object that can be chained and/or execute
split
Splits a variable apart (input) into a list of variables (output) by separating the strings together with separator
Arguments:
user_input
(str
): input string or WOQL variable "v:"
glue
(str
): character string to separate string into list
output
(str
): WOQL variable that stores output list
Returns:
WOQLQuery object
: query object that can be chained and/or execute
dot
Iterates through a list and returns a value for each member
Arguments:
dictionary
: a WOQL dictionary or variable representing a dictionary
field
(str
): a string representing the field or key to access the dictionary
value
: a WOQL value representing the result
Returns:
WOQLQuery object
: query object that can be chained and/or execute
member
Iterates through a list and returns a value for each member
Arguments:
member
(str
): a WOQL variable representing an element of the list
mem_list
(str
): a WOQL list variable
Returns:
WOQLQuery object
: query object that can be chained and/or execute
concat
Concatenates the list of variables into a string and saves the result in v
Arguments:
concat_list
(list
): list of variables to concatenate
result
(str
): saves the results
Returns:
WOQLQuery object
: query object that can be chained and/or execute
join
Joins a list variable together (input) into a string variable (output) by glueing the strings together with glue
Arguments:
user_input
(list
): a list of variables
glue
(str
): jioining character(s)
output
(str
): variable that sotres output
Returns:
WOQLQuery object
: query object that can be chained and/or execute
sum
Joins a list variable containing numbers together (input) into a single number
containing the sum.
Arguments:
user_input
(list
): a variable containing a list of numbers
output
(str
): a variable that stores the output
Returns:
WOQLQuery object
: query object that can be chained and/or execute
start
Specifies that the start of the query returned
Arguments:
start
(int
): index of the frist result got returned
query
(WOQLQuery object
): None
Returns:
WOQLQuery object
: query object that can be chained and/or execute
limit
Specifies that only the first Number of rows will be returned
Arguments:
limit
(int
): number of maximum results returned
query
(WOQLQuery object
): None
Returns:
WOQLQuery object
: query object that can be chained and/or execute
regexp
Regular Expression Call
pattern is a regex pattern (.) using normal regular expression syntax, the only unusual thing is that special characters have to be escaped twice, s is the string to be matched and m is a list of matches: e.g. WOQLQuery().regexp("(.).", "hello", ["v:All", "v:Sub"])
Arguments:
pattern
(str
): regex pattern
reg_str
(str
): string to be matched
reg_list
(str or list or dict
): store list of matches
Returns:
WOQLQuery object
: query object that can be chained and/or execute
length
Length
Calculates the length of a list
Arguments:
var_list
(list
): list of elements
var_len
(num
): number of eleemnts
Returns:
WOQLQuery object
: query object that can be chained and/or execute
woql_not
Creates a logical NOT of the arguments
Arguments:
query
(WOQLQuery object
): None
Returns
: None
----------
: None
WOQLQuery object
: query object that can be chained and/or executed
immediately
Immediately runs side-effects without backtracking
Arguments:
query
(WOQLQuery object
): None
Returns
: None
----------
: None
WOQLQuery object
: query object that can be chained and/or executed
count
Counds the number of solutions in the given query
Arguments:
result
(A variable or non-negative integer with the count
): None
query
(The query from which to count the number of results
): None
Returns
: None
----------
: None
WOQLQuery object
: query object that can be chained and/or executed
cast
Changes the type of va to type and saves the return in vb
Arguments:
val
(str
): original variable
user_type
(str
): type to be changed
result
(str
): save the return variable
literal_type
(str
): literal type ofval
, can be used to treat val
as a literal rather than an object or variable in the WOQL query. If literal type is "owl:Thing" or "node", val
will be treated as object in the graph
Returns:
WOQLQuery object
: query object that can be chained and/or execute
type_of
Sets the given value and type for cursor.
Arguments:
value
(str
): Value which needs to be set
vtype
(type
): Type which needs to be set
Returns:
WOQLQuery object
: query object that can be chained and/or execute
order_by
Orders the results by the list of variables including in gvarlist, asc_or_desc is a WOQL.asc or WOQ.desc list of variables
Arguments:
gvarlist
(list or dict of WOQLQuery().asc or WOQLQuery().desc objects
): None
query
(WOQLQuery object
): None
Returns:
WOQLQuery object
: query object that can be chained and/or execute
group_by
Groups the results of groupquery together by the list of variables group_vars, using the variable template as a grouping and saves the result into variable output.
Arguments:
group_vars
(list or str or Var object
): list of variables to group
template
(dict or list or str
): template of data to group with free variable(s)
output
(str
): output variable
groupquery
(dict
): None
Returns:
WOQLQuery object
: query object that can be chained and/or execute
true
Sets true for cursor type.
Returns:
WOQLQuery object
: query object that can be chained and/or execute
path
Create a path object constructed by the rules specified with pattern.
Arguments:
subject
(str
): a woql subject, the node that the path started
pattern
(str
): a pattern which specified the edges the path is consisted of. It uses pattern construction syntax such as:
'(scm:edge1, scm:edge2)+' for repeated pattern,
'scm:edge1|scm:edge2' for 'or' pattern,
'<scm:edge' for reverse pattern, and
'(scm:edge1)[n,m] for pattern between n and m times'
obj
(str
): a woql object, the node that the path ended
path
(str
): output variable
Returns:
WOQLQuery object
: query object that can be chained and/or execute
size
Sets the given graph and size for cursor.
Arguments:
graph
(Graph which needs to be set as resource
): None
size
(Size which needs to be set
): None
Returns:
WOQLQuery object
: query object that can be chained and/or execute
triple_count
Sets the given triple count and size for cursor.
Arguments:
graph
(Graph which needs to be set as resource
): None
triple_count
(Triple count which needs to be set
): None
Returns:
WOQLQuery object
: query object that can be chained and/or execute
star
Selects everything as triples in the graph identified by GraphIRI into variables Subj, Pred, Obj - by default they are "v:Subject", "v:Predicate", "v:Object"
Arguments:
GraphIRI
(str
): graphIRI
Subj
(str
): target subject
Pred
(str
): target predicate
Obj
(str
): target object
Returns:
WOQLQuery object
: query object that can be chained and/or execute
all
Calls the star method and returns the result of the same.
Arguments:
subj
(str
): target subject
pred
(str
): target predicate
obj
(str
): target object
graph
(str
): graphIRI
Returns:
WOQLQuery object
: query object that can be chained and/or execute
graph
Used to specify that the rest of the query should use the graph g in calls to add_quad, quad, etc
Arguments:
g
(str
): target graph
Returns:
WOQLQuery object
: query object that can be chained and/or execute
vars
Generate variables to be used in WOQLQueries
Arguments:
args
: string arguments
Returns:
tuple/string
: args prefixed with "v:"
variables
Generate variables to be used in WOQLQueries
Arguments:
args
: string arguments
Returns:
tuple/string
: args prefixed with "v:"
Client.py Client is the Python public API for TerminusDB
Class for JWT Authentication in requests
Class for API Token Authentication in requests
Enum for the different TerminusDB resources
Client for TerminusDB server.
Arguments:
server_url
(str
): URL of the server that this client connected.
api
(str
): API endpoint for this client.
team
(str
): Team that this client is using. "admin" for local dbs.
db
(str
): Database that this client is connected to.
user
(str
): TerminiusDB user that this client is using. "admin" for local dbs.
branch
(str
): Branch of the database that this client is connected to. Default to "main".
ref
(str, None
): Ref setting for the client. Default to None.
repo
(str
): Repo identifier of the database that this client is connected to. Default to "local".
Undo connect and close the connection.
The connection will be unusable from this point forward; an Error (or subclass) exception will be raised if any operation is attempted with the connection, unless connect is call again.
Get commit history of a database
Arguments:
team
(str
): The team from which the database is. Defaults to the class property.
db
(str
): The database. Defaults to the class property.
start
(int
): Commit index to start from. Defaults to 0.
count
(int
): Amount of commits to get. Defaults to -1 which gets all.
Returns:
list
: List of the following commit objects:
Get the whole commit history.
Commit history - Commit id, author of the commit, commit message and the commit time, in the current branch from the current commit, ordered backwards in time, will be returned in a dictionary in the follow format:
Arguments:
max_history
(int
): maximum number of commit that would return, counting backwards from your current commit. Default is set to 500. It needs to be nop-negative, if input is 0 it will still give the last commit.
Examples:
Returns:
list
:
Get all the branches available in the database.
Curently not implementated. Please check back later.
NotImplementedError Since TerminusDB currently does not support open transactions. This method is not applicable to it's usage. To reset commit head, use Client.reset
Create a deep copy of this client.
Examples:
Returns:
Client
: The copied client instance.
Set the connection to another database. This will reset the connection.
Arguments:
dbid
(str
): Database identifer to set in the config.
team
(str
): Team identifer to set in the config. If not passed in, it will use the current one.
Examples:
Returns:
str
: The current database identifier.
Create a resource identifier string based on the current config.
Arguments:
ttype
(ResourceType
): Type of resource.
val
(str
): Branch or commit identifier.
Examples:
Returns:
str
: The constructed resource string.
Create a TerminusDB database by posting
a terminus:Database document to the Terminus Server.
Arguments:
dbid
(str
): Unique identifier of the database.
team
(str
): ID of the Team in which to create the DB (defaults to 'admin')
label
(str
): Database name.
description
(str
): Database description.
prefixes
(dict
): Optional dict containing "@base"
and "@schema"
keys.
@base (str) IRI to use when doc:
prefixes are expanded. Defaults to terminusdb:///data
. @schema (str) IRI to use when scm:
prefixes are expanded. Defaults to terminusdb:///schema
.
include_schema
(bool
): If True
, a main schema graph will be created, otherwise only a main instance graph will be created.
Raises:
InterfaceError
: if the client does not connect to a server
Examples:
Delete a TerminusDB database.
If team
is provided, then the team in the config will be updated and the new value will be used in future requests to the server.
Arguments:
dbid
(str
): ID of the database to delete
team
(str
): the team in which the database resides (defaults to "admin")
force
(bool
): None
Raises:
UserWarning
: If the value of dbid is None.
InterfaceError
: if the client does not connect to a server.
Examples:
Retrieves the contents of the specified graph as triples encoded in turtle format
Arguments:
graph_type
(str
): Graph type, either "instance" or "schema".
Raises:
InterfaceError
: if the client does not connect to a database
Returns:
str
:
Updates the contents of the specified graph with the triples encoded in turtle format Replaces the entire graph contents
Arguments:
graph_type
(str
): Graph type, either "instance" or "schema".
turtle
: Valid set of triples in Turtle format.
commit_msg
(str
): Commit message.
Raises:
InterfaceError
: if the client does not connect to a database
Inserts into the specified graph with the triples encoded in turtle format.
Arguments:
graph_type
(str
): Graph type, either "instance" or "schema".
turtle
: Valid set of triples in Turtle format.
commit_msg
(str
): Commit message.
Raises:
InterfaceError
: if the client does not connect to a database
Retrieves all documents that match a given document template
Arguments:
document_template
(dict
): Template for the document that is being retrived
graph_type
(str
): Graph type, either "instance" or "schema".
as_list
(bool
): If the result returned as list rather than an iterator.
get_data_version
(bool
): If the data version of the document(s) should be obtained. If True, the method return the result and the version as a tuple.
Raises:
InterfaceError
: if the client does not connect to a database
Returns:
Iterable
:
Retrieves the document of the iri_id
Arguments:
iri_id
(str
): Iri id for the docuemnt that is retriving
graph_type
(str
): Graph type, either "instance" or "schema".
get_data_version
(bool
): If the data version of the document(s) should be obtained. If True, the method return the result and the version as a tuple.
kwargs
(``): Additional boolean flags for retriving. Currently avaliable: "prefixed", "minimized", "unfold"
Raises:
InterfaceError
: if the client does not connect to a database
Returns:
dict
:
Retrieves the documents by type
Arguments:
doc_type
(str
): Specific type for the docuemnts that is retriving
graph_type
(str
): Graph type, either "instance" or "schema".
skip
(int
): The starting posiion of the returning results, default to be 0
count
(int or None
): The maximum number of returned result, if None (default) it will return all of the avalible result.
as_list
(bool
): If the result returned as list rather than an iterator.
get_data_version
(bool
): If the version of the document(s) should be obtained. If True, the method return the result and the version as a tuple.
kwargs
(``): Additional boolean flags for retriving. Currently avaliable: "prefixed", "unfold"
Raises:
InterfaceError
: if the client does not connect to a database
Returns:
iterable
: Stream of dictionaries
Retrieves all avalibale the documents
Arguments:
graph_type
(str
): Graph type, either "instance" or "schema".
skip
(int
): The starting posiion of the returning results, default to be 0
count
(int or None
): The maximum number of returned result, if None (default) it will return all of the avalible result.
as_list
(bool
): If the result returned as list rather than an iterator.
get_data_version
(bool
): If the version of the document(s) should be obtained. If True, the method return the result and the version as a tuple.
kwargs
(``): Additional boolean flags for retriving. Currently avaliable: "prefixed", "unfold"
Raises:
InterfaceError
: if the client does not connect to a database
Returns:
iterable
: Stream of dictionaries
Get all the existing classes (only ids) in a database.
Inserts the specified document(s)
Arguments:
document
(dict or list of dict
): Document(s) to be inserted.
graph_type
(str
): Graph type, either "inference", "instance" or "schema".
full_replace
(: bool
): If True then the whole graph will be replaced. WARNING: you should also supply the context object as the first element in the list of documents if using this option.
commit_msg
(str
): Commit message.
last_data_version
(str
): Last version before the update, used to check if the document has been changed unknowingly
compress
(str or int
): If it is an integer, size of the data larger than this (in bytes) will be compress with gzip in the request (assume encoding as UTF-8, 0 = always compress). If it is never
it will never compress the data.
raw_json
(bool
): Update as raw json
Raises:
InterfaceError
: if the client does not connect to a database
Returns:
list
: list of ids of the inseted docuemnts
Updates the specified document(s)
Arguments:
document
(dict or list of dict
): Document(s) to be updated.
graph_type
(str
): Graph type, either "instance" or "schema".
commit_msg
(str
): Commit message.
last_data_version
(str
): Last version before the update, used to check if the document has been changed unknowingly
compress
(str or int
): If it is an integer, size of the data larger than this (in bytes) will be compress with gzip in the request (assume encoding as UTF-8, 0 = always compress). If it is never
it will never compress the data.
create
(bool
): Create the document if it does not yet exist.
raw_json
(bool
): Update as raw json
Raises:
InterfaceError
: if the client does not connect to a database
Updates the specified document(s). Add the document if not existed.
Arguments:
document
(dict or list of dict
): Document(s) to be updated.
graph_type
(str
): Graph type, either "instance" or "schema".
commit_msg
(str
): Commit message.
last_data_version
(str
): Last version before the update, used to check if the document has been changed unknowingly
compress
(str or int
): If it is an integer, size of the data larger than this (in bytes) will be compress with gzip in the request (assume encoding as UTF-8, 0 = always compress). If it is never
it will never compress the data.
Raises:
InterfaceError
: if the client does not connect to a database
Delete the specified document(s)
Arguments:
document
(str or list of str
): Document(s) (as dictionary or DocumentTemplate objects) or id(s) of document(s) to be updated.
graph_type
(str
): Graph type, either "instance" or "schema".
commit_msg
(str
): Commit message.
last_data_version
(str
): Last version before the update, used to check if the document has been changed unknowingly
Raises:
InterfaceError
: if the client does not connect to a database
Check if a certain document exist in a database
Arguments:
doc_id
(str
): Id of document to be checked.
graph_type
(str
): Graph type, either "instance" or "schema".
returns
: None
-------
: None
Bool
: if the document exist
Get the frame of the class of class_name. Provide information about all the avaliable properties of that class.
Arguments:
class_name
(str
): Name of the class
returns
: None
-------
: None
dict
: Dictionary containing information
Not implementated: open transactions currently not suportted. Please check back later.
Updates the contents of the specified graph with the triples encoded in turtle format Replaces the entire graph contents
Arguments:
woql_query
(dict or WOQLQuery object
): A woql query as an object or dict
commit_mg
(str
): A message that will be written to the commit log to describe the change
get_data_version
(bool
): If the data version of the query result(s) should be obtained. If True, the method return the result and the version as a tuple.
last_data_version
(str
): Last version before the update, used to check if the document has been changed unknowingly
file_dict
(**deprecated**
): File dictionary to be associated with post name => filename, for multipart POST
Raises:
InterfaceError
: if the client does not connect to a database
Examples:
Returns:
dict
:
Create a branch starting from the current branch.
Arguments:
new_branch_id
(str
): New branch identifier.
empty
(bool
): Create an empty branch if true (no starting commit)
Raises:
InterfaceError
: if the client does not connect to a database
Delete a branch
Arguments:
branch_id
(str
): Branch to delete
Raises:
InterfaceError
: if the client does not connect to a database
Pull updates from a remote repository to the current database.
Arguments:
remote
(str
): remote to pull from, default "origin"
remote_branch
(str
): remote branch to pull from, default to be your current barnch
message
(str
): optional commit message
author
(str
): option to overide the author of the operation
Raises:
InterfaceError
: if the client does not connect to a database
Examples:
Returns:
dict
:
Fatch the brach from a remote
Arguments:
remote_id
(str
): id of the remote
Raises:
InterfaceError
: if the client does not connect to a database
Push changes from a branch to a remote repo
Arguments:
remote
(str
): remote to push to, default "origin"
remote_branch
(str
): remote branch to push to, default to be your current barnch
message
(str
): optional commit message
author
(str
): option to overide the author of the operation
Raises:
InterfaceError
: if the client does not connect to a database
Examples:
Returns:
dict
:
Rebase the current branch onto the specified remote branch. Need to specify one of 'branch','commit' or the 'rebase_source'.
Arguments:
branch
(str
): the branch for the rebase
rebase_source
(str
): the source branch for the rebase
message
(str
): the commit message
author
(str
): the commit author
Raises:
InterfaceError
: if the client does not connect to a database
Examples:
Returns:
dict
:
Reset the current branch HEAD to the specified commit path. If soft
is not True, it will be a hard reset, meaning reset to that commit in the backend and newer commit will be wipped out. If soft
is True, the client will only reference to that commit and can be reset to the newest commit when done.
Arguments:
commit
(string
): Commit id or path to the commit (if use_path is True), for instance '234980523ffaf93' or 'admin/database/local/commit/234980523ffaf93'. If not provided, it will reset to the newest commit (useful when need to go back after a soft reset).
soft
(bool
): Flag indicating if the reset if soft, that is referencing to a previous commit instead of resetting to a previous commit in the backend and wipping newer commits.
use_path
(bool
): Wheather or not the commit given is an id or path. Default using id and use_path is False.
Raises:
InterfaceError
: if the client does not connect to a database
Examples:
Optimize the specified path.
Arguments:
path
(string
): Path to optimize, for instance admin/database/_meta for the repo graph.
Raises:
InterfaceError
: if the client does not connect to a database
Examples:
Squash the current branch HEAD into a commit
Arguments:
message
(string
): Message for the newly created squash commit
author
(string
): Author of the commit
reset
(bool
): Perform reset after squash
Raises:
InterfaceError
: if the client does not connect to a database
Examples:
Returns:
str
: commit id to be reset
Diff two different commits and apply changes on branch
Arguments:
before_version
(string
): Before branch/commit to compare
after_object
(string
): After branch/commit to compare
branch
(string
): Branch to apply to. Optional.
Diff two different objects.
Arguments:
before_object
(string
): Before object to compare
after_object
(string
): After object to compare
Diff two different versions. Can either be a branch or a commit
Arguments:
before_version
(string
): Commit or branch of the before version to compare
after_version
(string
): Commit or branch of the after version to compare
DEPRECATED
Perform diff on 2 set of document(s), result in a Patch object.
Do not connect when using public API.
Examples:
Returns:
obj
: Patch object
Apply the patch object to the before object and return an after object. Note that this change does not commit changes to the graph.
Do not connect when using public API.
Examples:
Returns:
dict
: After object
Clone a remote repository and create a local copy.
Arguments:
clone_source
(str
): The source url of the repo to be cloned.
newid
(str
): Identifier of the new repository to create.
Description
(str
): Optional description about the cloned database.
Raises:
InterfaceError
: if the client does not connect to a database
Examples:
Add a new organization
Arguments:
org
(str
): The id of the organization
Raises:
InterfaceError
: if the client does not connect to a server
Returns:
dict or None if failed
:
Returns a list of users in an organization.
Arguments:
org
(str
): None
Raises:
InterfaceError
: if the client does not connect to a server
Returns:
dict or None if not found
:
Returns user info related to an organization.
Arguments:
org
(str
): None
username
(str
): None
Raises:
InterfaceError
: if the client does not connect to a server
Returns:
dict or None if not found
:
Returns the databases available to a user which are inside an organization
Arguments:
org
(str
): None
username
(str
): None
Raises:
InterfaceError
: if the client does not connect to a server
Returns:
dict or None if not found
:
Returns a list of organizations in the database.
Raises:
InterfaceError
: if the client does not connect to a server
Returns:
dict or None if not found
:
Returns a specific organization
Arguments:
org
(str
): The id of the organization
Raises:
InterfaceError
: if the client does not connect to a server
Returns:
dict or None if not found
:
Deletes a specific organization
Arguments:
org
(str
): The id of the organization
Raises:
InterfaceError
: if the client does not connect to a server
Returns:
dict or None if request failed
:
Change the capabilities of a certain user
capability_change: dict Dict for the capability change request.
Example:
{
"operation"
- "revoke",
"scope"
- "UserDatabase/f5a0ef94469b32e1aee321678436c7dfd5a96d9c476672b3282ae89a45b5200e",
"user"
- "User/admin",
Add a new role
Arguments:
role
(dict
): The role dict
Raises:
InterfaceError
: if the client does not connect to a server
Examples:
Returns:
dict or None if failed
:
Change role actions for a particular role
Arguments:
role
(dict
): Role dict
Raises:
InterfaceError
: if the client does not connect to a server
Examples:
Returns:
dict or None if failed
:
Get the available roles for the current authenticated user
Raises:
InterfaceError
: if the client does not connect to a server
Returns:
dict or None if failed
:
Add a new user
Arguments:
username
(str
): The username of the user
password
(str
): The user's password
Raises:
InterfaceError
: if the client does not connect to a server
Returns:
dict or None if failed
:
Get a user
Arguments:
username
(str
): The username of the user
Raises:
InterfaceError
: if the client does not connect to a server
Returns:
dict or None if failed
:
Get all users
Raises:
InterfaceError
: if the client does not connect to a server
Returns:
dict or None if failed
:
Delete a user
Arguments:
username
(str
): The username of the user
Raises:
InterfaceError
: if the client does not connect to a server
Returns:
dict or None if failed
:
Change user's password
Arguments:
username
(str
): The username of the user
password
(str
): The new password
Raises:
InterfaceError
: if the client does not connect to a server
Returns:
dict or None if failed
:
Returns metadata (id, organization, label, comment) about the requested database
Arguments:
dbid
(str
): The id of the database
team
(str
): The organization of the database (default self.team)
Raises:
InterfaceError
: if the client does not connect to a server
DatabaseError
: if the database can't be found
Returns:
dict
:
Check whether a database exists
Arguments:
dbid
(str
): The id of the database
team
(str
): The organization of the database (default self.team)
Raises:
InterfaceError
: if the client does not connect to a server
Returns:
True or False if not found
:
Returns a list of database metadata records for all databases the user has access to
Raises:
InterfaceError
: if the client does not connect to a server
Returns:
list of dicts
:
Returns a list of database ids for all databases the user has access to
Raises:
InterfaceError
: if the client does not connect to a server
Returns:
list of dicts
: