«Running AG on AWS EC2 src »

AllegroGraph Python API Reference

This is a description of the Python Application Programmer’s Interface (API) to Franz Inc.’s AllegroGraph.

The Python API offers convenient and efficient access to an AllegroGraph server from a Python-based application. This API provides methods for creating, querying and maintaining RDF data, and for managing the stored triples.

Note

The Python API deliberately emulates the Eclipse RDF4J API (formerly Aduna Sesame) to make it easier to migrate from RDF4J to AllegroGraph.  The Python API has also been extended in ways that make it easier and more intuitive than the RDF4J API.

AllegroGraphServer class

class franz.openrdf.sail.allegrographserver.AllegroGraphServer(host=None, port=None, user=None, password=None, cainfo=None, sslcert=None, verifyhost=None, verifypeer=None, protocol=None, proxy=None, **options)

The AllegroGraphServer object represents a remote AllegroGraph server on the network. It is used to inventory and access the catalogs of that server.

Example:

server = AllegroGraphServer(host="localhost", port=8080,
                            user="test", password="pw")

__init__	Define the connection to the AllegroGraph HTTP server.
addRole	Creates a new role.
addRoleAccess	Grant read/write access to a role.
addRolePermission	Grants a role a certain permission.
addRoleSecurityFilter	Add a security filter for the user.
addScript	Create or replace a sitescript.
addUser	Create a new user.
addUserAccess	Grant read/write access to a user.
addUserPermission	Assigns the given permission to this user.
addUserRole	Add a role to a user.
addUserSecurityFilter	Add a security filter for the user.
changeUserPassword	Change the password for the given user.
deleteRole	Deletes a role.
deleteRoleAccess	Revoke read/write access for a role.
deleteRolePermission	Revokes a permission for a role.
deleteRoleSecurityFilter	Add a security filter for the user.
deleteScript	Delete a sitescript.
deleteUser	Delete a user.
deleteUserAccess	Takes the same parameters as PUT on this URL, but revokes the access instead of granting it.
deleteUserData	Remove user data from the server.
deleteUserPermission	Revokes the given permission for this user.
deleteUserRole	Remove a role from a user.
deleteUserSecurityFilter	Add a security filter for the user.
getInitfile	Retrieve the contents of the server initialization file.
getScript	Get the body of a sitescript.
getUserData	Retrieve user data value with given key.
listCatalogs	Get the list of catalogs on this server.
listRoleAccess	Query the access granted to a role.
listRolePermissions	Lists the permission flags granted to a role.
listRoleSecurityFilters	List security filters for user.
listRoles	Returns the names of all defined roles.
listScripts	Return the list of Sitescripts currently on the server.
listUserAccess	Retrieve the read/write access for a user.
listUserData	Get all used keys from the user data store on the server.
listUserEffectiveAccess	Like listUserAccess, but also includes the access granted to roles that this user has.
listUserEffectivePermissions	Retrieve the permission flags assigned to the user, or any of its roles.
listUserPermissions	List the permission flags that have been assigned to a user (any of super, eval, session, replication).
listUserRoles	Retrieves a list of role names for this user name.
listUserSecurityFilters	List security filters for user.
listUsers	Returns a list of names of all the users that have been defined.
openCatalog	Open a catalog by name.
openFederated	Open a session that federates several repositories.
openSession	Open a session on a federated, reasoning, or filtered store.
setInitfile	Replace the current initialization file contents with the content string or remove if None.
setUserData	Set user data with given key.

Catalog class

class franz.openrdf.sail.allegrographserver.Catalog(name, server, client)

Container of multiple repositories (triple stores).

Construct catalogs using the server object:

catalog = server.openCatalog('scratch')

createRepository	Creates a new repository with the given name.
deleteRepository	Delete a repository.
getName	Return the catalog name.
getRepository	Creates or opens a repository.
listRepositories	Return a list of names of repositories (triple stores) managed by this catalog.

Spec module

Helper functions for creating session specification strings. See openSession()

federate	Create a session spec for connecting to a federated store.
graphFilter	Create a graph-filtered session spec.
local	Create a session spec for connecting to a store on the local server.
reason	Create a session spec that adds reasoning support to another session.
remote	Create a session spec for connecting to a store on another server.
url	Create a session spec for connecting to a remote store with known URL.

Repository class

class franz.openrdf.repository.repository.Repository(catalog, database_name, repository)

A repository contains RDF data that can be queried and updated. Access to the repository can be acquired by opening a connection to it. This connection can then be used to query and/or update the contents of the repository.

Please note that a repository needs to be initialized before it can be used and that it should be shut down before it is discarded/garbage collected. Forgetting the latter can result in loss of data (depending on the Repository implementation)!

Construct instances using getRepository().

with catalog.getRepository("agraph_test", Repository.ACCESS) as repo:
    ...

__init__	Invoke through getRepository().
getConnection	Opens a connection to this store that can be used for querying and updating the contents of the store.
getDatabaseName	Return the name of the database (remote triple store) that this repository is interfacing with.
getSpec	Return a session spec string for this repository.
getValueFactory	Return a ValueFactory for this store.
initialize	Initializes this repository.
isWritable	Checks whether this store is writable, i.e. if the data contained in this store can be changed.
registerDatatypeMapping	Register an inlined datatype.
shutDown	Shuts the store down, releasing any resources that it keeps hold of.

Utility connection functions

Manually constructing server, catalog and repository objects is often tedious when only a simple connection to a single repository is needed. In that case the connection may be created directly using ag_connect().

ag_connect

Create a connection to an AllegroGraph repository.

RepositoryConnection class

class franz.openrdf.repository.repositoryconnection.RepositoryConnection(repository, close_repo=False, is_session=False)

The RepositoryConnection class is the main interface for updating data in and performing queries on a Repository. By default, a RespositoryConnection is in autoCommit mode, meaning that each operation corresponds to a single transaction on the underlying triple store. autoCommit can be switched off, in which case it is up to the user to handle transaction commit/rollback. Note that care should be taken to always properly close a RepositoryConnection after one is finished with it, to free up resources and avoid unnecessary locks.

Note that concurrent access to the same connection object is explicitly forbidden. The client must perform its own synchronization to ensure non-concurrent access.

Several methods take a vararg argument that optionally specifies a set of contexts on which the method should operate. (A context is the URI of a subgraph.) Note that a vararg parameter is optional, it can be completely left out of the method call, in which case a method either operates on a provided statement’s context (if one of the method parameters is a statement or collection of statements), or operates on the repository as a whole, completely ignoring context. A vararg argument may also be None, meaning that the method operates on those statements which have no associated context only.

RepositoryConnection objects should be constructed using getConnection(). To ensure that repository connections are closed, the best practice is to use a with statement:

with repository.getConnection() as conn:
    ...

__init__

Call through getConnection().

General connection methods

This section contains the RepositoryConnection methods that create, maintain, search, and delete triple stores.

add	Calls addTriple(), addStatement(), or addFile().
addData	Adds data from a string to the repository.
addFile	Loads a file into the triple store.
addStatement	Add the supplied statement to the specified contexts in the repository.
addTriple	Add a single triple to the repository.
addTriples	Add the supplied triples or quads to this repository.
clear	Removes all statements from designated contexts in the repository.
clearNamespaces	Delete all namespaces in this repository for the current user.
close	Close the connection.
createBNode	Create a new blank node.
createLiteral	Create a new literal with value value.
createRange	Create a compound literal representing a range from lowerBound to upperBound.
createStatement	Create a new Statement object.
createURI	Creates a new URI from the supplied string-representation(s).
deleteDuplicates	Delete duplicate triples from the store.
executeBooleanQuery	Prepare and immediately evaluate a query that returns a boolean.
executeGraphQuery	Prepare and immediately evaluate a query that returns RDF.
executeTupleQuery	Prepare and immediately evaluate a query that returns tuples.
executeUpdate	Prepare and immediately evaluate a SPARQL update query.
export	Export all explicit statements in the specified contexts to a file.
exportStatements	Export statements to a file.
getAddCommitSize	Get the current value of add_commit_size.
getContextIDs	Return a list of context resources, one for each context referenced by a quad in the triple store.
getDuplicateStatements	Return all duplicates in the store.
getNamespace	Get the namespace that is associated with the specified prefix, if any.
getNamespaces	Get all declared prefix/namespace pairs.
getSpec	Get the session specification string for this repository.
getStatements	Get all statements with a specific subject, predicate and/or object from the repository.
getStatementsById	Return all statements whose triple ID matches an ID in the list 'ids'.
getValueFactory	Get the ValueFactory associated with this repository.
isEmpty	Return True if this repository does not contain any (explicit) statements.
namespace	Creates an object that allows for simple creation of URIs in given namespace.
prepareBooleanQuery	Parse query into a boolean query object which can be executed against the triple store.
prepareGraphQuery	Parse query into a graph query object which can be executed against the triple store.
prepareTupleQuery	Parse query into a tuple query object which can be executed against the triple stroe.
prepareUpdate	Parse query into an update query object which can be executed against the triple store.
registerDatatypeMapping	Register an inlined datatype.
remove	Call removeTriples() or removeStatement().
removeNamespace	Remove a namespace declaration by removing the association between a prefix and a namespace name.
removeQuads	Remove enumerated quads from this repository.
removeQuadsByID	Remove all quads with matching IDs.
removeStatement	Remove the supplied statement from the specified contexts in the repository.
removeTriples	Remove the statement(s) with the specified subject, predicate and object from the repository, optionally restricted to the specified contexts.
setAddCommitSize	Set the value of add_commit_size.
setNamespace	Define or redefine a namespace mapping in the repository.
size	Returns the number of (explicit) statements that are in the specified contexts in this repository.
warmup	Warm up specified parts of the repository in order to speed up access.
add_commit_size	The threshold for commit size during triple add operations.

Vector Repository Methods

These methods operation on vector triple stores

add_objects	Compute the embedding for the given text string and add it to the repository.
convert_to_vector_store	Convert an existing normal repo to a vector store by setting the embedder and optionally the api-key and model.
nearest_neighbor	An embedding is computed for the given text string and the closest embeddings to that embedding are computed.
object_embedding	Return the embedding for the given object_id.
object_property_value	Return the value of the given property of the given object_id.
object_text	Return the text of the object denoted by object_id.
remove_objects	Remove zero or more objects.

Triple Index Methods

These RepositoryConnection methods support user-defined triple indices. See AllegroGraph Triple Indices for more information on this topic.

listIndices	Return the list of the current set of triple indices.
listValidIndices	Return the list of valid index names.
addIndex	Add a specific type of index to the current set of triple indices.
dropIndex	Removes a specific type of index to the current set of triple indices.
optimizeIndices	Optimize indices.

Free Text Indexing Methods

The following RepositoryConnection methods support free-text indexing in AllegroGraph.

createFreeTextIndex	Create a free-text index with the given parameters.
deleteFreeTextIndex	Delete a free-text index from the server.
evalFreeTextSearch	Return a list of statements for the given free-text pattern search.
getFreeTextIndexConfiguration	Get the current settings of a free-text index.
listFreeTextIndices	Get the names of currently defined free-text indices.
modifyFreeTextIndex	Modify parameters of a free-text index.

Note that text search is implemented through a SPARQL query using a “magic” predicate called fti:search. See the AllegroGraph Python API Tutorial for an example of how to set up this search.

Prolog Rule Inference Methods

These RepositoryConnection methods support the use of Prolog rules in AllegroGraph. Any use of Prolog rules requires that you create a transaction to run them in.

addRules	Add Prolog functors to the current session.
loadRules	Add Prolog rules from file to the current session.

Geospatial Reasoning Methods

These RepositoryConnection methods support geospatial reasoning.

createBox	Create a rectangular search region (a box) for geospatial search.
createCircle	Create a circular search region for geospatial search.
createCoordinate	Create an x, y or latitude, longitude coordinate in the current coordinate system.
createLatLongSystem	Create a spherical coordinate system and use it as the current coordinate system.
createPolygon	Define a polygonal region with the specified vertices.
createRectangularSystem	Create a Cartesian coordinate system and use it as the current coordinate system.
getGeoType	Get the current geospatial coordinate system.
setGeoType	Set the current geospatial coordinate system.

Social Network Analysis Methods

The following RepositoryConnection methods support Social Network Analysis in AllegroGraph. The Python API to the Social Network Analysis methods of AllegroGraph requires Prolog queries, and therefore must be run in a dedicated session.

registerNeighborMatrix	Construct a neighbor matrix named name.
registerSNAGenerator	Create a new SNA generator named name.

Transactions

AllegroGraph lets you set up a special RepositoryConnection (a “session”) that supports transaction semantics. You can add statements to this session until you accumulate all the triples you need for a specific transaction. Then you can commit the triples in a single act. Up to that moment the triples will not be visible to other users of the repository.

If anything interrupts the accumulation of triples building to the transaction, you can roll back the session. This discards all of the uncommitted triples and resynchronizes the session with the repository as a whole.

Closing the session discards all uncommitted triples and all rules, generators, and matrices that were created in the session. Rules, generators, and matrices cannot be committed. They persist as long as the session persists.

openSession	Open a session.
closeSession	Close a session.
session	A session context manager for use with the with statement:
commit	Commit changes on an open session.
rollback	Roll back changes on open session.

Subject Triples Caching

You can enable subject triple caching to speed up queries where the same subject URI appears in multiple patterns. The first time AllegroGraph retrieves triples for a specific resource, it caches the triples in memory. Subsequent query patterns that ask for the same subject URI can retrieve the matching triples very quickly from the cache. The cache has a size limit and automatically discards old entries as that limit is exceeded.

enableSubjectTriplesCache	Maintain a cache of size size that caches, for each accessed resource, quads where the resource appears in subject position.
disableSubjectTriplesCache	Disable the subject triples cache (see enableSubjectTriplesCache()).
getSubjectTriplesCacheSize	Return the current size of the subject triples cache.

Query Class (and Subclasses)

Note

The Query class is non-instantiable. It is an abstract class from which the three query subclasses are derived. It is included here because of its methods, which are inherited by the subclasses.

A query on a Repository that can be formulated in one of the supported query languages (for example SPARQL). The query can be parameterized, to allow one to reuse the same query with different parameter bindings.

The best practice is to allow the RepositoryConnection object to create an instance of one of the Query subclasses (TupleQuery, GraphQuery, BooleanQuery, UpdateQuery). There is no reason for the Python application programmer to create such objects directly.

tupleQuery = conn.prepareTupleQuery(QueryLanguage.SPARQL, queryString)
result = tupleQuery.evaluate()

evaluate_generic_query	Evaluate a SPARQL or PROLOG query, which may be a 'select', 'construct', 'describe' or 'ask' query (in the SPARQL case).
getBindings	Retrieve the bindings that have been set on this query.
getDataset	Get the dataset against which this query will operate.
getIncludeInferred	Check whether this query will return inferred statements.
removeBinding	Removes a previously set binding on the supplied variable.
setBinding	Binds the specified variable to the supplied value.
setBindings	Set multiple variable bindings.
setCheckVariables	Determine whether the presence of variables in the select clause not referenced in a triple is flagged.
setConnection	Internal call to embed the connection into the query.
setContexts	Assert a set of contexts (named graphs) that filter all triples.
setDataset	Select the dataset against which to evaluate this query, overriding any dataset that is specified in the query itself.
setIncludeInferred	Determine whether evaluation results of this query should include inferred statements.

Subclass TupleQuery

This subclass is used with SELECT queries. Use the prepareTupleQuery() method to create a TupleQuery object. The results of the query are returned in a QueryResult iterator that yields a sequence of binding sets.

TupleQuery uses all the methods of the Query class, plus two more:

evaluate	Execute the embedded query against the RDF store.
analyze	Analyze the query.

Subclass GraphQuery

This subclass is used with CONSTRUCT and DESCRIBE queries. Use the prepareGraphQuery() method to create a GraphQuery object. The results of the query are returned in a GraphQueryResult iterator that yields a sequence of statements.

GraphQuery implements all the methods of the Query class, plus one more:

evaluate

Execute the embedded query against the RDF store.

Subclass BooleanQuery

This subclass is used with ASK queries. Use the prepareBooleanQuery() method to create a BooleanQuery object. The results of the query are True or False.

BooleanQuery implements all the methods of the Query class, plus one more:

evaluate

Execute the embedded query against the RDF store.

Subclass UpdateQuery

This subclass is used for DELETE and INSERT queries. The result returned when the query is evaluated is a boolean that can be used to tell if the store has been modified by the operation. Use the prepareUpdate() method to create an UpdateQuery object.

UpdateQuery implements all the methods of the Query class, plus one more:

evaluate

Execute the embedded update against the RDF store.

QueryResult Class

A QueryResult object is simply an iterator that also has a close() method that must be called to free resources. Such objects are returned as a result of SPARQL and PROLOG query evaluation and should not be constructed directly. Result objects are context managers and can be used in the with statement. The recommended usage looks like this:

tupleQuery = conn.prepareTupleQuery(QueryLanguage.SPARQL, queryString)
with tupleQuery.evaluate() as results:
   for result in results:
       print result

It is also possible to use one of the execute*Query methods (e.g. executeTupleQuery()) to prepare and execute a query in a single call:

with conn.executeTupleQuery(queryString) as results:
   for result in results:
       print result

close	Release resources used by this query result.
__next__	Return the next result item if there is one.

Subclass TupleQueryResult

A QueryResult subclass used for queries that return tuples.

getBindingNames	Get the names of the bindings, in order of projection.
getMetadata	Get a nested dictionary containing query result metadata.

Subclass GraphQueryResult

A QueryResult subclass used for queries that return statements. Objects of this class are also RepositoryResult instances.

RepositoryResult class

A RepositoryResult object is a result collection of statements that can be iterated over. It keeps an open connection to the backend for lazy retrieval of individual results. Additionally it has some utility methods to fetch all results and add them to a collection.

By default, a RepositoryResult is not necessarily a (mathematical) set: it may contain duplicate objects. Duplicate filtering can be switched on, but this should not be used lightly as the filtering mechanism is potentially memory-intensive.

A RepositoryResult must be closed after use to free up any resources (open connections, read locks, etc.) it has on the underlying repository. To make this easier it is a context manager and can be used in the with statement.

graphQuery = conn.prepareGraphQuery(QueryLanguage.SPARQL, queryString)
with graphQuery.evaluate() as results:
    for result in results:
        print result

close	Shut down the iterator to be sure the resources are freed up.
__next__	Return the next Statement in the answer, if there is one.
enableDuplicateFilter	Switch on duplicate filtering while iterating over objects.
asList	Returns a list containing all objects of this RepositoryResult in order of iteration.
addTo	Add all objects of this RepositoryResult to the supplied collection.
rowCount	Get the number of statements in this result object.

Statement Class

A Statement is a client-side triple. It encapsulates the subject, predicate, object and context (subgraph) values of a single triple and makes them available.

Best practice is to allow the RepositoryConnection.createStatement() method to create and return the Statement object. There is no reason for the Python application programmer to create a Statement object directly.

stmt1 = conn.createStatement(alice, age, fortyTwo)

getContext	Get the graph (the fourth, optional element of the statement).
getObject	Get the object (the third element of the statement).
getPredicate	Get the predicate (the second element of the statement).
getSubject	Get the subject (the first element of the statement).

ValueFactory Class

A ValueFactory is a factory for creating URIs, blank nodes, literals and Statement objects. In the AllegroGraph Python interface, the ValueFactory class is regarded as obsolete. Its functions have been subsumed by the expanded capability of the RepositoryConnection class. It is documented here for the convenience of users porting an application from Eclipse RDF4J.

createBNode	See RepositoryConnection.createBNode().
createLiteral	See RepositoryConnection.createLiteral().
createStatement	See RepositoryConnection.createStatement().
createURI	See RepositoryConnection.createURI().

«Running AG on AWS EC2 src »