Python Client

The Client constructor.

Raise connection InterfaceError if not connected Defaults to check if a db is connected

Pack the specified commit info into a dict format expected by the server.

>>> client = Client("http://127.0.0.1:6363/")
>>> client._generate_commit("<message>", "<author>")
{'author': '<author>', 'message': '<message>'}

Get the prefixes for a given database

Get URL for prefix operations

Add a new prefix mapping.

>>> client.add_prefix("ex", "http://example.org/")
{'@type': 'api:PrefixAddResponse', 'api:status': 'api:success', ...}

Add a new role

>>> client = Client("http://127.0.0.1:6363")
>>> client.connect(key="root", team="admin", user="admin", db="example_db")
>>> role = {
    "name": "Grand Pubah",
    "action": [
        "branch",
        "class_frame",
        "clone",
        "commit_read_access",
        "commit_write_access",
        "create_database",
        "delete_database",
        "fetch",
        "instance_read_access",
        "instance_write_access",
        "manage_capabilities",
        "meta_read_access",
        "meta_write_access",
        "push",
        "rebase",
        "schema_read_access",
        "schema_write_access"
      ]
  }
>>> client.add_role(role)

Add a new user

Diff two different commits and apply changes on branch

Change the capabilities of a certain user

Change role actions for a particular role

>>> client = Client("http://127.0.0.1:6363")
>>> client.connect(key="root", team="admin", user="admin", db="example_db")
>>> role = {
    "name": "Grand Pubah",
    "action": [
        "branch",
        "class_frame",
        "clone",
        "commit_read_access",
        "commit_write_access",
        "create_database",
        "delete_database",
        "fetch",
        "instance_read_access",
        "instance_write_access",
        "manage_capabilities",
        "meta_read_access",
        "meta_write_access",
        "push",
        "rebase",
        "schema_read_access",
        "schema_write_access"
      ]
  }
>>> client.change_role(role)

Change user's password

Clone a remote repository and create a local copy.

>>> client = Client("http://127.0.0.1:6363/")
>>> client.clonedb("http://terminusdb.com/some_user/test_db", "my_test_db")

Undo connect and close the connection.

Not implementated: open transactions currently not suportted. Please check back later.

Connect to a Terminus server at the given URI with an API key.

>>> client = Client("http://127.0.0.1:6363")
>>> client.connect(key="root", team="admin", user="admin", db="example_db")

Create a deep copy of this client.

>>> client = Client("http://127.0.0.1:6363/")
>>> clone = client.copy()
>>> assert client is not clone

Create a branch starting from the current branch.

Create a TerminusDB database by posting a terminus:Database document to the Terminus Server.

>>> client = Client("http://127.0.0.1:6363/")
>>> client.create_database("someDB", "admin", "Database Label", "My Description")

Add a new organization

Delete a branch

Delete a TerminusDB database.

>>> client = Client("http://127.0.0.1:6363/")
>>> client.delete_database("<database>", "<team>")

Delete the specified document(s)

Deletes a specific organization

Delete a prefix mapping.

>>> client.delete_prefix("ex")
{'@type': 'api:PrefixDeleteResponse', 'api:status': 'api:success', ...}

Delete a user

DEPRECATED

>>> client = Client("http://127.0.0.1:6363/")
>>> client.connect(user="admin", key="root", team="admin", db="some_db")
>>> result = client.diff({ "@id" : "Person/Jane", "@type" : "Person", "name" : "Jane"}, { "@id" : "Person/Jane", "@type" : "Person", "name" : "Janine"})
>>> result.to_json = '{ "name" : { "@op" : "SwapValue", "@before" : "Jane", "@after": "Janine" }}'

Diff two different objects.

Diff two different versions. Can either be a branch or a commit

Fetch the branch from a remote repo

Get all the branches available in the database.

Retrieves all avalibale the documents

Get the available roles for the current authenticated user

Get the frame of the class of class_name. Provide information about all the avaliable properties of that class.

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: ``` { "commit_id": { "author": "commit_author", "message": "commit_message", "timestamp: <datetime object of the timestamp>" } } ```

Returns metadata (id, organization, label, comment) about the requested database Parameters ---------- dbid : str The id of the database team : str The organization of the database (default self.team)

Returns a list of database metadata records for all databases the user has access to

Retrieves the document of the iri_id

Get the commit history for a specific document

Retrieves the documents by type

Get all the existing classes (only ids) in a database.

Returns a specific organization

Returns user info related to an organization.

Returns the databases available to a user which are inside an organization

Returns a list of users in an organization.

Returns a list of organizations in the database.

Get a single prefix IRI by name.

>>> client.get_prefix("schema")
'http://schema.org/'

Retrieves the contents of the specified graph as triples encoded in turtle format

Get a user

Get all users

Check whether a database exists

Check if a certain document exist in a database

Get info of a TerminusDB database server

Inserts the specified document(s)

Inserts into the specified graph with the triples encoded in turtle format.

Returns a list of database ids for all databases the user has access to

Get commit history of a database Parameters ---------- team : str, optional The team from which the database is. Defaults to the class property. db : str, optional The database. Defaults to the class property. start : int, optional Commit index to start from. Defaults to 0. count : int, optional Amount of commits to get. Defaults to -1 which gets all.

Check whether the TerminusDB server is still OK. Status is not OK when this function returns false or throws an exception (mostly ConnectTimeout)

Optimize the specified path.

>>> client = Client("http://127.0.0.1:6363/")
>>> client.optimize('admin/database') # optimise database branch (here main)
>>> client.optimize('admin/database/_meta') # optimise the repository graph (actually creates a squashed flat layer)
>>> client.optimize('admin/database/local/_commits') # commit graph is optimised

Apply the patch object to the before object and return an after object. Note that this change does not commit changes to the graph.

>>> client = Client("http://127.0.0.1:6363/")
>>> client.connect(user="admin", key="root", team="admin", db="some_db")
>>> patch_obj = Patch(json='{"name" : { "@op" : "ValueSwap", "@before" : "Jane", "@after": "Janine" }}')
>>> result = client.patch({ "@id" : "Person/Jane", "@type" : Person", "name" : "Jane"}, patch_obj)
>>> print(result)
'{ "@id" : "Person/Jane", "@type" : Person", "name" : "Janine"}'

Apply the patch object to the given resource

>>> client = Client("http://127.0.0.1:6363/")
>>> client.connect(user="admin", key="root", team="admin", db="some_db")
>>> patch_obj = Patch(json='{"name" : { "@op" : "ValueSwap", "@before" : "Jane", "@after": "Janine" }}')
>>> result = client.patch_resource(patch_obj,branch="main")
>>> print(result)
'["Person/Jane"]'

Pull updates from a remote repository to the current database.

>>> client = Client("http://127.0.0.1:6363/")
>>> client.pull()

Push changes from a branch to a remote repo

>>> Client(server="http://localhost:6363").push(remote="origin", remote_branch = "main", author = "admin", message = "commit message"})

Updates the contents of the specified graph with the triples encoded in turtle format Replaces the entire graph contents

>>> Client(server="http://localhost:6363").query(woql, "updating graph")

Retrieves all documents that match a given document template

Rebase the current branch onto the specified remote branch. Need to specify one of 'branch','commit' or the 'rebase_source'.

>>> client = Client("http://127.0.0.1:6363/")
>>> client.rebase("the_branch")

Updates the specified document(s)

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.

>>> client = Client("http://127.0.0.1:6363/")
>>> client.reset('234980523ffaf93')
>>> client.reset('admin/database/local/commit/234980523ffaf93', use_path=True)

Curently not implementated. Please check back later.

Set the connection to another database. This will reset the connection.

>>> client = Client("http://127.0.0.1:6363")
>>> client.set_db("database1")
'database1'

Squash the current branch HEAD into a commit

>>> client = Client("http://127.0.0.1:6363/")
>>> client.connect(user="admin", key="root", team="admin", db="some_db")
>>> client.squash('This is a squash commit message!')

Updates the specified document(s). Add the document if not existed.

Update an existing prefix mapping.

>>> client.update_prefix("ex", "http://example.com/")
{'@type': 'api:PrefixUpdateResponse', 'api:status': 'api:success', ...}

Updates the contents of the specified graph with the triples encoded in turtle format. Replaces the entire graph contents

Create or update a prefix mapping (upsert).

>>> client.upsert_prefix("ex", "http://example.org/")
{'@type': 'api:PrefixUpdateResponse', 'api:status': 'api:success', ...}

Creates a logical AND with the argument passed, for WOQLQueries.

Creates a logical AND with the argument passed, for WOQLQueries.

defines the internal functions of the woql query object - the language API is defined in WOQLQuery

Creates a logical Not with the argument passed, for WOQLQueries.

Creates a logical OR with the argument passed, for WOQLQueries.

Adds the query based on action given in builder context.

Internal library function which adds a subquery and sets the cursor

Wraps arithmetic operators in the appropriate json-ld

Wraps the elements of an AS variable in the appropriate json-ld

Transforms whatever is passed in as the object of a triple into the appropriate json-ld form (variable, literal or id)

Transforms whatever is passed in as the object of a triple into the appropriate json-ld form (variable, literal or id)

Transforms a graph filter by doing nothing

Transforms whatever is passed in as the object of a triple into the appropriate json-ld form (variable, literal or id)

Transforms whatever is passed in as the object of a triple into the appropriate json-ld form (variable, literal or id)

Transforms whatever is passed in as the predicate (id or variable) into the appropriate json-ld form

Transforms whatever is passed in as the subject into the appropriate json-ld for variable or id

Transforms a object representation of a query into a dictionary object if needs be

Turns a textual path pattern into a JSON-LD description

Does this query contain an update

takes input that can be either a string (variable name) or an array - each element of the array is a member of the list

DEPRECATED: Dead code - never called anywhere in the codebase.

Transforms strings that start with v: into variable json-ld structures

Finds the last woql property that has a subject in it and returns the json for that used for triplebuilder to chain further calls - when they may be inside ands or ors or subqueries

Finds the last woql element that has a subject in it and returns the json for that used for triplebuilder to chain further calls - when they may be inside ands or ors or subqueries

Function to get the object for the given subject and predicate.

Wraps the passed value in a json-ld literal carriage

converts back and forward from json if the argument is present, the current query is set to it, if the argument is not present, the current json version of this query is returned

A function to check the given two objects, which can be of different types (str, dict), are equal or not. When both the passed objects are dicts, deep comparison is done to check for the equality.

A function to check if the given string is present in the passed dict or not.

Called to inidicate that this query will cause an update to the DB

takes input that can be either a string (variable name) or an array - each element of the array is a member of the list

Wraps value lists in the appropriate json-ld

JSON LD Format Descriptor

Adds quads according to the pattern [subject, predicate, object, graph]

Adds triples according to the the pattern [subject, predicate, object]

This example adds a triple for a comment predicate and a certain value to the document identified by doc:X:
>>> update = WOQLQuery().add_triple("doc:X", "comment", "my comment")
>>> qry = WOQLQuery().when(True, update)
>>> client.update(qry.json(), 'MyDatabaseId')

Creates a pattern matching rule for the quad [S, P, O, G] (Subject, Predicate, Object, Graph) added to the current commit.

Creates a triple pattern matching rule for the triple [S, P, O] (Subject, Predicate, Object) added to the current commit.

Calls the star method and returns the result of the same.

Transforms the given bool object into the proper json-ld form

Changes the type of va to type and saves the return in vb

Collects all solutions of a sub-query into a list.

Adds a text comment to a query - can also be used to wrap any part of a query to turn it off

Concatenates the list of variables into a string and saves the result in v

Counds the number of solutions in the given query

Transforms the given date object into the proper json-ld form

Tri-directional duration arithmetic for dates and dateTimes. Given any two of start, end, and duration, computes the third. Uses EOM preservation: last day of month maps to last day of target month. Accepts xsd:date or xsd:dateTime for start/end, xsd:duration for duration.

Transforms the given datetime object into the proper json-ld form

Computes the calendar day after the given date. Bidirectional.

Computes the calendar day before the given date. Bidirectional.

Delete a document into the database

Deletes any quads that match the rule [subject, predicate, object, graph]

Deletes any triples that match the rule [subject, predicate, object]

Ensures that the solutions for the variables [V1...Vn] are distinct

Division - integer division - args are divided left to right

Divides numbers N1...Nn by each other left, to right precedence

Iterates through a list and returns a value for each member

Matches if a is equal to b Parameters ---------- left : str object in the graph right : str object in the graph Returns ------- WOQLQuery object query object that can be chained and/or execute

Evaluates the Arithmetic Expression Arith and copies the output to variable V

Executes the query using the passed client to connect to a server

Raises A to the power of B

Provides details of a file source in a JSON format that includes a URL property

The floor function of a real number x denotes the greatest integer less than or equal to x.

Set a query from a dictionary that represents the query in JSON-LD format.

Set a query from a JSON-LD json string

Takes an as structure

Used to specify that the rest of the query should use the graph g in calls to add_quad, quad, etc Parameters ---------- g : str target graph Returns ------- WOQLQuery object query object that can be chained and/or execute

Compares the value of v1 against v2 and returns true if v1 is greater than v2

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.

Compares two values using greater-than-or-equal ordering. Parameters ---------- left : str or number the greater or equal value right : str or number the lesser or equal value Returns ------- WOQLQuery object query object that can be chained and/or execute

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

Generates a unique ID with cryptographically secure random suffix.

Immediately runs side-effects without backtracking

Tests whether a value falls within a half-open range [start, end). Succeeds if start <= value < end.

Insert a document into the database

Constructs or deconstructs a half-open xdd:dateTimeInterval [start, end).

Relates an xdd:dateTimeInterval to its end endpoint and precise xsd:duration.

Allen's Interval Algebra: classifies or validates the relationship between two half-open intervals [x_start, x_end) and [y_start, y_end).

Allen's Interval Algebra on xdd:dateTimeInterval values.

Relates an xdd:dateTimeInterval to its start endpoint and precise xsd:duration.

Sets the current output graph for writing output to.

Matches if element is a member of a certain type, according to the current state of the DB

Computes the ISO 8601 week-numbering year and week number for a date. Accepts xsd:date or xsd:dateTime. Date must be ground. The ISO year may differ from the calendar year at year boundaries.

Joins a list variable together (input) into a string variable (output) by glueing the strings together with glue

Length Calculates the length of a list

Compares the value of v1 against v2 and returns true if v1 is less than v2

Returns the WOQL library instance for RDFList operations and other library functions.

Matches left string to right string with a distance

Specifies that only the first Number of rows will be returned

Converts a list to a set (removes duplicates and sorts)

Queries the schema graph and loads all the ids found there as vocabulary that can be used without prefixes ignoring blank node ids

Build a localized scope for variables to prevent leaking local variables to outer scope.

Changes a string to lower-case - input is in u, output in l

Compares two values using less-than-or-equal ordering. Parameters ---------- left : str or number the lesser or equal value right : str or number the greater or equal value Returns ------- WOQLQuery object query object that can be chained and/or execute

Iterates through a list and returns a value for each member

Adds numbers N1...Nn together

Computes the last day of the month for a given xsd:gYearMonth. Handles leap years correctly.

Generator: produces every last-of-month date in [start, end).

Computes the first day of the month for a given xsd:gYearMonth.

Generator: produces every first-of-month date in [start, end).

Obtains only one result from subquery

The Query in the Optional argument is specified as optional

Orders the results by the list of variables including in gvarlist, asc_or_desc is a WOQL.asc or WOQ.desc list of variables

Pads out the string input to be exactly len long by appending the pad character pad to form output

Create a path object constructed by the rules specified with pattern.

Adds numbers N1...Nn together

Specifies a file to be posted as part of the request for processing.

Takes an array of variables, an optional array of column names

Creates a pattern matching rule for the quad [S, P, O, G] (Subject, Predicate, Object, Graph)

Finds the next object value with an explicit graph selector.

Finds the previous object value with an explicit graph selector.

Creates a triple pattern matching rule for [S, P, O, G] with a half-open value range [low, high) on the object and an explicit graph selector.

Creates a triple pattern matching rule for [S, P, O, G] with a half-open value range [low, high) on the object in reverse order, with an explicit graph selector.

Generates a unique ID with cryptographically secure random suffix (alias for idgen_random).

Find the maximum value in a list using the standard ordering.

Find the minimum value in a list using the standard ordering.

Read a document from the database

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"])

Provides details of a remote data source in a JSON format that includes a URL property

Creates a pattern matching rule for the quad [S, P, O, G] (Subject, Predicate, Object, Graph) added to the current commit.

Creates a triple pattern matching rule for the triple [S, P, O] (Subject, Predicate, Object) added to the current commit.