Python API Reference for AllegroGraph 4.2

This is a description of the Python Application Programmer's Interface (API) to AllegroGraph RDFStore™ version 4.2 from Franz Inc.

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.

Contents

• AllegroGraphServer Class
• Catalog Class
• Repository Class
• RepositoryConnection Class
• Query Class
• Subclass TupleQuery
• Subclass GraphQuery
• Subclass BooleanQuery
• RepositoryResult Class
• Statement Class
• ValueFactory Class

AllegroGraphServer Class   Return to Top

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

Source: /AllegroGraphDirectory/src2/franz/openrdf/sail/allegrographserver.py.

Constructor

AllegroGraphServer(self, host, port=10035,user=None,password=None)

• host is a string describing the network path to the AllegroGraph server. No default.
• port is the AllegroGraph HTTP port on the server. It is an integer that defaults to 10035.
• user is an AllegroGraph user name.
• password is the user's password.

Example:

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

Methods

Catalog Class   Return to Top

A Catalog object is a container for multiple repositories. 

Source: /AllegroGraphDirectory/scr2/franz/openrdf/sail/allegrographserver.py.

Constructor

Invoke the Catalog constructor using the AllegroGraphServer.openCatalog() method.

    catalog = server.openCatalog('scratch') 

Methods

Repository Class   Return to Top

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. Depending on the implementation of the repository, it may or may not support multiple concurrent connections.

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)!

Source: /AllegroGraphDirectory/scr2/franz/openrdf/repository/repository.py.

Constructor

Invoke the Repository constructor using the AllegroGraphServer.getRepository() method.

    myRepository = catalog.getRepository("agraph_test", accessMode)

Methods

RepositoryConnection Class   Return to Top

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.

Several methods take a vararg argument that optionally specifies a (set of) context(s) 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 null (cast to Resource) meaning that the method operates on those statements which have no associated context only.

Source: /AllegroGraphDirectory/scr2/franz/openrdf/repository/repositoryconnection.py.

Constructor

RepositoryConnection(self, repository)

where repository is the Repository object that created this RepositoryConnection.

Example: The best practice is to use the Repository.getConnection() method, which supplies the repository parameter to the construction method. .

    connection = myRepository.getConnection()

General Connection Methods

This table contains the repositoryConnection methods that create, maintain, search, and delete triple stores. There are following tables that list special methods for Free Text Search, Prolog Rule Inference, Geospatial Reasoning, Social Network Analysis, Transactions and Subject Triples Caching.

Triple Index Methods

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

Free Text Search Methods

The following repositoryConnection method supports free-text indexing in AllegroGraph.

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 dedicated session to run them in.

Geospatial Reasoning Methods

These repositoryConnection methods support geospatial reasoning.

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.

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 deletes all uncommitted triples, 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.

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 rolls over as that limit is exceeded.

Query Class (and Subclasses)  Return to Top

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). It allows one to predefine bindings in the query to be able to reuse the same query with different bindings.  

Source: /AllegroGraphDirectory/scr2/franz/openrdf/query/query.py.

Constructor

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

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

Methods

Subclass TupleQuery   Return to Top

This subclass is used with SELECT queries.  Use the RepositoryConnection object's prepareTupleQuery() method to create a TupleQuery object. The results of the query are returned in a RepositoryResult iterator that yields a sequence of bindingSets.

Methods

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

Subclass GraphQuery   Return to Top

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

Methods

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

Subclass BooleanQuery    Return to Top

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

Methods

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

RepositoryResult Class   Return to Top

A RepositoryResult object is a result collection of objects (for example, Statement objects) 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 needs to be closed after use to free up any resources (open connections, read locks, etc.) it has on the underlying repository.

Source: /AllegroGraphDirectory/scr2/franz/openrdf/repository/repositoryresult.py.

Constructor

Best practice is to allow a querySubclass.evaluate() method to create and return the RepositoryResult object. There is no reason for the Python application programmer to create a RepositoryResult object directly. 

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

Methods

Statement Class   Return to Top

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.

Source: /AllegroGraphDirectory/scr2/franz/openrdf/model/statement.py.

Constructor

Statement(self, subject, predicate, object, context=None)

• subject, predicate, object are the values of a typical triple.
• context is the optional URI of the subgraph of the repository.

Example:  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)

Methods

ValueFactory Class   Return to Top

A ValueFactory is a factory for creating URIs, blank nodes, literals and Statements.  In the AllegroGraph Python interface, the ValueFactory class would be regarded as obsolete.  Its functions have been subsumed by the expanded capability of the RepositoryConnection class. It is documented here for the convenience of the person who is porting an application from Aduma Sesame.  

Source: /AllegroGraphDirectory/scr2/franz/openrdf/model/valuefactory.py.

Constructor

ValueFactory(self, store)

• store is the Repository object that generated this ValueFactory.

Example:  Best practice is to allow the Repository constructor to generate the ValueFactory automatically at the same time that the Repository object is created.  There is no reason for a Python application programmer to attempt this step manually. 

Methods