WOQLQuery

terminusdb_client.woqlquery
terminusdb_client.woqlquery.woql_core
terminusdb_client.woqlquery.woql_query
WOQLQuery Objects
class WOQLQuery()
__init__
def __init__(query=None, graph="schema")
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__
def __add__(other)
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__
def __and__(other)
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__
def __or__(other)
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__
def __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
def execute(client, commit_msg=None, file_dict=None)
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
def to_json()
Dumps the JSON-LD format of the query in a json string
from_json
def from_json(input_json)
Set a query from a JSON-LD json string
to_dict
def to_dict()
Give the dictionary that represents the query in JSON-LD format.
from_dict
def from_dict(dictdata)
Set a query from a dictionary that represents the query in JSON-LD format.
load_vocabulary
def load_vocabulary(client)
Queries the schema graph and loads all the ids found there as vocabulary that can be used without prefixes ignoring blank node ids
using
def using(collection, subq=None)
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
def comment(comment, subq=None)
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
def select(*args)
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
def distinct(*args)
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
def woql_and(*args)
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
def woql_or(*args)
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
def woql_from(graph, query=None)
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
def into(graph_descriptor, query)
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
def triple(sub, pred, obj, opt=False)
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
def added_triple(sub, pred, obj, opt=False)
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
def removed_triple(sub, pred, obj, opt=False)
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
def quad(sub, pred, obj, graph, opt=False)
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
def added_quad(sub, pred, obj, graph, opt=False)
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
def removed_quad(sub, pred, obj, graph, opt=False)
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
def string(input_str)
Transforms the given string into the proper json-ld form
Arguments:
input_str (str): the given input string
Returns:
dict:
boolean
def boolean(input_bool)
Transforms the given bool object into the proper json-ld form
Arguments:
input_bool (bool): the given input string
Returns:
dict:
datetime
def datetime(input_obj)
Transforms the given datetime object into the proper json-ld form
Arguments:
input_obj (str): the given input dateTime object
Returns:
dict:
sub
def sub(parent, child)
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
def eq(left, right)
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
def update_document(docjson, json_or_iri=None)
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
def insert_document(docjson, json_or_iri=None)
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
def delete_document(json_or_iri)
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
def read_document(iri, output_var)
Read a document from the database
Parameters
iri : str object to be deleted output_var : str the document as JSON Returns
WOQLQuery object query object that can be chained and/or execute Example
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
def get(as_vars, query_resource=None)
Takes an as structure
put
def put(as_vars, query, query_resource=None)
Takes an array of variables, an optional array of column names
file
def file(fpath, opts=None)
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
def once(query=None)
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
def remote(uri, opts=None)
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
def delete_triple(subject, predicate, object_or_literal)
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
def add_triple(subject, predicate, object_or_literal)
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
def delete_quad(subject, predicate, object_or_literal, graph=None)
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
def add_quad(subject, predicate, object_or_literal, graph)
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
def trim(untrimmed, trimmed)
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
def eval(arith, res)
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
def plus(*args)
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
def minus(*args)
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
def times(*args)
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
def divide(*args)
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
def div(*args)
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
def exp(first, second)
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
def floor(user_input)
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
def isa(element, of_type)
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
def like(left, right, dist)
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
def less(left, right)
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
def greater(left, right)
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
def opt(query=None)
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
def unique(prefix, key_list, uri)
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
def idgen(prefix, input_var_list, output_var)
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
def random_idgen(prefix, key_list, uri)
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
def upper(left, right)
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
def lower(left, right)
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
def pad(user_input, pad, length, output)
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
def split(user_input, glue, output)
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
def dot(document, field, value)
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
def member(member, mem_list)
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
def concat(concat_list, result)