Navigation

Lisp Client API to Remote AllegroGraph

Table of Contents

Introduction

Starting the Server

Connecting to the Server

Using a Remote Triple Store

Creating triples

Querying for triples

Reference

Managing a Connection

Data Structures and Classes

Managing a Remote Triple-Store

Introduction

The AllegroGraph client API is yet another view of the triple store for a Lisp application. The triple store in this case is accessed through a server that runs in a another process and may be located on a separate host located far from the client. The same server is used by Lisp and Java clients. Therefore the facilities and operations are similar in both interfaces.

The AllegroGraph client API may be used exclusively or in combination with local triple stores. But it is important to note that triples and parts in local stores are not represented the same way as triples and parts in remote stores. Even UPI instances, although they may be identical in different stores, they are not always interchangeable because each triple store must have its own string table.

Starting the Server

The server is started in Lisp with a call to start-ag-server. We also distribute a stand-alone server executable described in Java Tutorial.

Connecting to the Server

Before any client interaction with a triple store, the client application must make a connection to the server: 

(setq agc (make-allegrograph-connection))  
(setf (client-slot agc :host) "notlocalhost")  
(enable-connection agc)

The first expression creates a connection instance but the instance is still disabled, but initialized with default values. The client-slot method may be used to modify any settings that must differ from the defaults. The third expression actually makes the connection and signals an error if the connection attempt fails.

The application must save the connection instance since it is a required argument to many subsequent operations.

Once a connection to the server is established, the application can connect to existing triple stores and create new ones: 

(setq ag1 (connect-triple-store  
             agc "oldstore" :directory "/data/triplestores/"  
             :mode :open)  
(setq ag2 (connect-triple-store  
             agc "newstore" :directory "/data/triplestores/"  
             :mode :renew)

The first expression enables access to a triple store named "oldstore"; the mode argument :open specifies that if the store does not exist, then an error should be signaled. The second expression enables access to a triple store named "newstore"; the mode argument :renew specifies that a empty store be created and if one already exists, it is overwritten.

Once again, the application must save the object returned by the call to connect-triple-store since it is a required argument to many subsequent operations.

Using a Remote Triple Store

Creating triples

Triples can be created one at a time by naming the components with strings in ntriples syntax. 

(add-statement ag2 "<http://www.franz.com/things#Dog>"  
                   "<http://www.w3.org/1999/02/22-rdf-syntax-ns#type>"  
                   "<http://www.w3.org/2002/07/owl#Class>")

The application can also save the details of the newly created triple by specifying that a value should be returned: 

(setq newid  
  (add-statement ag2 "<http://www.franz.com/things#Dog>"  
                     "<http://www.w3.org/1999/02/22-rdf-syntax-ns#type>"  
                     "<http://www.w3.org/2002/07/owl#Class>"  
                     :return :id))

In this case, the value returned will be the id number of the new triple.

When many triples are created, it is more efficient to buffer the operation by grouping the triple components into sequences. The following statement creates three triples from corresponding elements of the sequences: 

(add-statements ag2  
  (list  
    "<http://www.franz.com/things#Cat>"  
    "<http://www.franz.com/things#Giraffe>"  
    "<http://www.franz.com/things#Lion>" )  
  (list  
    "<http://www.w3.org/1999/02/22-rdf-syntax-ns#type>"  
    "<http://www.w3.org/1999/02/22-rdf-syntax-ns#type>"  
    "<http://www.w3.org/1999/02/22-rdf-syntax-ns#type>" )  
  (list  
    "<http://www.w3.org/2002/07/owl#Class>"  
    "<http://www.w3.org/2002/07/owl#Class>"  
    "<http://www.w3.org/2002/07/owl#Class>" ))

When an sequence consists of identical elements, it can be shortened to a single element.
The following statement creates three triples where the predicate and object components are identical. 

(add-statements ag2  
  (list  
    "<http://www.franz.com/things#Cat>"  
    "<http://www.franz.com/things#Giraffe>"  
    "<http://www.franz.com/things#Lion>" )  
  "<http://www.w3.org/2000/01/rdf-schema#subClassOf>"  
  "<http://www.franz.com/things#Mammal>"}

Querying for triples

Triples are retrieved from the database with a client-cursor instance. The client-cursor instance can iterate through all the triples in the search result. The following statement will retrieve the four triples about subclasses of the "Mammal" class created earlier. 

(setq cc (get-statements ag2  
            :p "<http://www.w3.org/2000/01/rdf-schema#subClassOf>"  
            :o "<http://www.franz.com/things#Mammal>"))

When a client-cursor instance is created, it is not positioned at a result. The step-cursor function advances the client-cursor instance to the first or next result. When a client-cursor instance has been advanced, the default returned value is t. When a Cursor is exhausted, the returned value is nil. 

(when (step-cursor cc) (setq tr (client-get-triple cc)))

When the client-cursor instance is positioned at a result, we can retrieve the component of interest without creating a client-triple instance. 

(setq s (client-slot cc :subject))

We can also retrieve several results in one operation. The following statement retrieves a list of at most 6 elements: 

(setq trc (step-cursor-list cc 6))

The length of the list will be at most 6.

Reference

Symbols exported from db.agraph.client

Managing a Connection


make-allegrograph-connection &rest args &key default-command default-debug default-host default-poll-count default-poll-interval default-port default-server-keep command debug host poll-count poll-interval port server-keep enable
function

Create and return an instance of allegrograph-connection. This instance must be used when accessing the server.

The enable argument, when non-nil, causes the connection to be enabled. Otherwise the enable-connection method must be called before the connection can be used.

The other keyword arguments initialize slots in the instance.


enable-connection agc
function

Method (allegrograph-connection)

Enable a connection instance by connecting to the server. If the connection is already enabled return nil. If the connection is established during the call, return the allegrograph-connection instance.

The parameters of the connection are pre-set in the slots of the allegrograph-connection instance.


disable-connection agc &key (close-all t)
function

Method (allegrograph-connection)

Disable a connection. All allegrograph-client instances opened from this connection are invalidated by this call. The close-all argument should be specified as nil only when the application is such that any allegrograph-client instances opened from this connection will never be used again.


exists agc name &key directory
function

Method (allegrograph-connection t)

Return t if the specifed triple store is found.

  • name - the name of the triple store
  • directory - a string that specifies the pathname of the directory where the remote triple store is or will be located. The pathname is used in the server process environment (not the client's).

connect-triple-store agc name &key directory (mode :access)
function

Method (allegrograph-connection t)

Connect to a remote triple store and return an instance of allegrograph-client. This instance is a required argument to all operations on the triple store.

  • name - the name of the triple store
  • directory - a string that specifies the pathname of the directory where the remote triple store is or will be located. The pathname is used in the server process environment (not the client's).
  • mode - a keyword that specifies the access mode:
    • :open - open an existing triple store. Signal an error if one is not found.
    • :create - create a new triple store. Signal an error if one is found.
    • :access - open an existing triple store or create one.
    • :renew - replace an existing triple store or create one.
    • :replace - replace an existing triple store. Signal an error if one is not found.

namespaces agc &key register
function

Method (allegrograph-client): agc &key register

Without the keyword argument, return a list of namespace definitions associated with this triple store.
This is an alternating list of prefix string and namespace string.

If the keyword argument is specified, the namespace definitions are updated. The argument must be an alternating list of prefix strings and namespace string. If the namespace string id nil or the empty string, that entry is deleted.

Method (allegrograph-connection): agc &key register

Without the keyword argument, return a list of current global namespace definitions. This is an alternating list of prefix string and namespace string.

If the keyword argument is specified, the global namespace definitions are updated. The argument must be an alternating list of prefix strings and namespace string. If the namespace string id nil or the empty string, that entry is deleted.


expected-resources agc &optional value
function

Method (allegrograph-connection)

Query or set the default number of unique resources in each triple store.

  • value - If this argument is omitted or nil, return the current value in the server. If this argument is a positive integer, it specifies a new value.

This default value is used when a new triple store is created. It determines the initial size of some internal tables.


chunk-size agc &optional value
function

eval-in-server agc expression &optional env
function

Method (allegrograph-client t)

Like the method specialized on allegrograph-connection, but adds a binding of *db* to the environment. The variable is bound to the triple store identified by the first argument.

Method (allegrograph-connection t)

Evaluate an expression in the AllegroGraph server and return the values. The values must be suitable for restricted serialization: numbers, strings, UPIs, or sequences of these.

  • expression - this argument should be a string containing an expression to be evaluated.

  • env - If this argument is ommitted, the expression is evaluated in the default environment of this connection. If this argument is specified as nil, the expression is evaluated in the global server environment. Otherwise, the argument must be a string or symbol that names a server environment.

Each server environment has a separate binding of *package* and *readtable* and separate bindings for variables mentioned in bind-in-server calls. The initial binding of *package* is the db.agraph.user package. The initial binding of *readtable* is the value of (copy-readtable).


bind-in-server agc var value &optional env
function

Method (allegrograph-connection t t)

Bind a variable in the server.

  • var - a string that identifies the variable.

  • value - a string containing a Lisp expression. The expression is evaluated in the server and the result stored in the variable.

  • env - if ommitted, the operation is performed in the default environment associated with this allegrograph-connection instance. If a string, then the operation is performed in the environment identified by the string; a new environment is created if necessary. If specified as nil then the operation is performed in the global server environment.

See the description of eval-in-server for more details.


query-connection agc
function

Method (allegrograph-connection)

Query the state of a connection. Return one or two value:

  • :idle - the connection is ready. A new client call will be serviced immediately.

  • :busy - the connection is ready but actively servicing a client call. A new client call will be queued adn serviced in turn.

  • nil - the connection is not enabled. A second value provides more detail:
    • :not-connected - the connection has never been enabled.
    • :closed - the connection was enabled and then was disabled.

server-trace agc &optional onoff
function

Method (allegrograph-client)

Turn trace messages in the server on and off. With no keyword argument, query the state of tracing in the server. Tracing applies only to calls that involve this triple store.

Method (allegrograph-connection)

Turn trace messages in the server on and off. With no keyword argument, query the state of tracing in the server. Tracing applies to all calls to the server through this or any other connection.


server-level agc test-level
function

Method (allegrograph-connection)

Query the implementation level of the server. At times, we may publish integers that identify the availability of certain features. Return non-nil if the server level is at or above the specified integer.


stop-server agc
function

Method ()

Terminate the AllegroGraph server.


client-version ag &key all
function

Method (t)

Query the version.

Data Structures and Classes


allegrograph-connection
class

This class implements a connection to the AllegroGraph server. Class and instance slots specify how the connection is made and how it should behave. All the slots are accessed with the client-slot method.

One connection can access any number of triple stores.

The client-slot function can be used to query and update the following slots:

  • default-command - not implemented
  • default-debug - not implemented
  • default-host - default host name for all connections
  • default-poll-count - default poll count for all connections
  • default-poll-interval - default poll interval for all connections
  • default-port - default port number for all connections
  • default-server-keep - not implemented
  • debug - not implemented
  • host - host name for this connections
  • poll-count - poll count for this connections
  • poll-interval - poll interval for this connections
  • port - port number for this connections
  • server-keep - not implemented
  • verbose - not implemented

allegrograph-client
class

This class implements a connection to a specific triple store in the server.

The client-slot function can be used to query and update the following slots:

  • look-ahead - the default look-ahead value for new client-cursor instances. A zero value specified the default look-ahead value in the client-cursor class.
  • select-limit - the number of results in sequence returned by select-values or twinql-select

client-object
class
The superclass of all components of remote triple stores.

client-triple
class

A triple. Some slots are set when the triple is created; some slots are nil until the get-slot function is called.

The client-slot function can be used to query the following slots:

  • id - the integer id of the triple
  • s - the UPI of the subject component
  • p - the UPI of the predicate component
  • o - the UPI of the object component
  • g - the object of the graph component
  • subject - the client-value instance of the subject component
  • object - the client-value instance of the object component
  • predicate - the client-value instance of the predicate component
  • graph - the client-value instance of the object component
  • subject-label - the string label of the subject (Note that the label is normally not sufficient to identify the component completely)
  • predicate-label - the string label of the predicate
  • object-label - the string label of the object
  • graph-label - the string label of the graph

client-cursor
class

This class allows iteration through the results of a query.

The client-slot function can be used to query and update the following slots:

  • default-look-ahead - default look-ahead for all instances
  • look-ahead look-ahead value for this instance. This is the number of results that are cached in the client when a cursor is created or advanced.

The client-slot function can be used to query the following slots:

  • id - the is number of the current triple or nil
  • s - the subject UPI of the current triple or nil
  • p - the predicate UPI of the current triple or nil
  • o - the object UPI of the current triple or nil
  • g - the graph UPI of the current triple or nil
  • subject - the value-instance for the subject of the current triple or nil
  • predicate - the value-instance for the predicate of the current triple or nil
  • object - the value-instance for the object of the current triple or nil
  • graph - the value-instance for the graph of the current triple or nil
  • subject-label - the string label of the subject of the current triple or nil
  • predicate-label - the string label of the predicate of the current triple or nil
  • object-label - the string label of the object of the current triple or nil
  • graph-label - the string label of the graph of the current triple or nil

client-value
class

The superclass of all objects that can be components of a triple.

The client-slot function can be used to query and update the following slots:

  • upi - the UPI of this component
  • label - the string label of this component

client-literal
class

A literal component that can have any string content.

The client-slot function can be used to query and update the following slots:

  • datatype - the datatype of this literal. This may be a string uri or UPI or a client-uri instance.
  • language - a string language tag

encoded-client-literal
class
A literal component that is encoded directly into a UPI.

client-resource
class
A uri or a blank node.

client-blank-node
class
The triple store equivalent of a gensym.

client-uri
class
A named resource.


client-slot x name
function

Methods of this generic function allow query or update of certain slots of the object x. The name argument may be a string or a symbol in any package. If the named slot is not accessible, an error is signalled.

Some slots are maintained lazily and may not have a value when queried. In that case the result is nil. The function get-slots may be called to force an update of a lazy slot. Most updates require a round-trip to the AllegroGraph server.


get-slot x name
function
Methods of this generic function allow query of certain slots and make sure that the slot contains a valid value.
The name argument may be a string or a symbol in any package. If the named slot is not accessible, an error is signalled.

Managing a Remote Triple-Store

Adding Triples


add-literal ag label &key datatype language return
function

Method (allegrograph-client t)

Add a literal to the table in the triple store.

  • label - any string
  • datatype - a URL that identifies the datatype of the literal or a keyword that specifies an XML Schema type
    • :boolean
    • :byte
    • :short
    • :int
    • :float
    • :double
  • language - a string that specifies a language tag
  • return - specifies what kind of value to return:
    • nil - (the default) return nil
    • :upi - return the UPI of the literal
    • other-non-nil - return a client-literal instance

add-literals ag labels &key datatypes languages return
function

Method (allegrograph-client t)

Like add-literal, but the arguments may be sequences. If the sequences are not the same length, the last element of short sequences is repeated. A non-sequence argument is treated as a sequence of length one.


add-part ag part &key return
function

Method (allegrograph-client t)

Add a literal or a resource to the triple store.

  • part - a string in ntriples notation.
  • return - specifies the kind of value returned:
    • nil - (the default) return nil
    • :upi - return the UPI of the new entry
    • other-non-nil - return a client-value instance of the proper type

add-statement ag s p o &key g return
function

Method (allegrograph-client t t t)

Add a triple to the store.

  • s p o - specify the subject predicate and object of the triple. Each may be a string in ntriples notation, a UPI, or a client-value instance.
  • g - specifies the graph or context of the triple. Nil specifies the default graph of the triple store.
  • return - specifies the kind of value returned:
    • nil - (the default) return nil
    • :id - return the id number of the new triple
    • other-non-nil - return a client-triple instance

add-statements ag s p o &key g return
function

Method (allegrograph-client t t t)

Like add-statement, but each argument may be a sequence.


add-uri ag label &key return
function

Method (allegrograph-client t)

Add a uri to the triple store.

  • label - a string containing a URI
  • return - specifies what kind of value to return:
    • nil - (the default) return nil
    • :upi - return the UPI of the resource
    • other-non-nil - return a client-uri instance

add-uris ag label &key return
function

Method (allegrograph-client t)

Like add-uri but the label argument may be a sequence.


add-blank-node ag &key (return :upi) label
function

Method (allegrograph-client)

Create a blank node.

  • return - specifies what kind of value to return:
    • nil - return nil. Note that if nil is specifies, then there is no way to mention this blank node again.
    • :upi - (the default) return the UPI of the blank node
    • other-non-nil - return a client-blank-node instance

If a label is specified, it is saved in the client-blank-node instance only.


add-blank-nodes ag &key count labels (return :upi)
function

Method (allegrograph-client)

Create several blank-nodes.


create-b-node ag &rest args &key (return :upi) label
function

Method (allegrograph-client)

Create a blank node.

This method is present for consistency with the Java API. The preferred function is add-blank-node.


create-b-nodes ag &rest args &key count labels (return :upi)
function

Method (allegrograph-client)

Create several blank-nodes.

This method is present for consistency with the Java API. The preferred function is add-blank-nodes.


create-statement ag s p o &optional g
function

Method (allegrograph-client t t t)

Create a client-triple instance but do not add to the store.


create-uri ag label
function

Method (allegrograph-client t)

Create a client-uri instance but do not add to the store.

Bulk Loading


client-load-ntriples ag file-or-files &key default-graph from-string
function

Method (allegrograph-client t)

Load triple definitions from a file, a list of files or a string in ntriples syntax.

Load triples from a file or string in ntriples notation.


client-load-rdf ag file-or-files &key default-graph
function

Method (allegrograph-client t)

Load triple definitions from a file or a list of files in RDF/XML syntax.

Load triples from a file in RDF/XML syntax.

Queries


get-statements ag &key s p o g o-end g-end include-inferred look-ahead
function

Method (allegrograph-client)

Find triples in the triple store. The result is nil or a client-cursor instance.


cursor-next-p c
function

Method (client-cursor)

Return non-nil if the client-cursor instance can be advanced to a new result triple.


step-cursor c &key return
function

Method (client-cursor)

Advance a client-cursor instance to the next result triple.

Return nil if there are no more results. Otherwise, the returned value is specified by the return argument:

  • nil - return t (this is the default)
  • :id - return the id number of the new triple
  • :upi - return a list of 4 UPI insantces (s p o g)
  • parts - return a list of 4 client-value instances (subject predicate object graph)
  • other-non-nil - return a client-triple instance

step-cursor-list c n &key (return t)
function

Method (client-cursor t)

Return a list of at most n results.


has-statement ag &key s p o g include-inferred
function

Method (allegrograph-client)

Like get-statements, but returns only t or nil.


select-statements ag query &key values vars
function

Method (allegrograph-client t)

Query the triple store with a Prolog select expression. Only the triples located by the query are returned.

The result is nil or a client-cursor instance.


select-values ag query &key values variables
function

Method (allegrograph-client t)

Query the triple store with a Prolog select expression. All the Prolog variable values are returned.

The result is a sequence of ntuples.


twinql-ask ag query &key include-inferred
function

Method (allegrograph-client t)

Search the triple store with a SPARQL ASK query.

Return nil or non-nil.


twinql-count ag query &key include-inferred limit offset
function

Method (allegrograph-client t)

Search the triple store with a SPARQL SELECT query.

Return the number of succcesses.


twinql-find ag query &key include-inferred limit offset
function

Method (allegrograph-client t)

Search the triple store with a SPARQL DESCRIBE or CONSTRUCT query.

Return a client-cursor instance that will iterate over the results.


twinql-query ag query &key include-inferred format limit offset
function

Method (allegrograph-client t)

Search the triple store with a SPARQL query.

Return a string containing the serialized result.


twinql-select ag query &key include-inferred vars limit offset
function

Method (allegrograph-client t)

Search the triple store with a SPARQL SELECT query.

Return a sequence of result n-tuples.


select-more ag values-array
function

Method (allegrograph-client t)

Update the array of results returned by select-values or twinql-select with a new set of results.


more-values ag values-array
function

Method (allegrograph-client t)

Return the number of additional results available in the sequence returned by select-values or twinql-select.


value-names ag values-array
function

Method (allegrograph-client t)

Retrun the sequence of variable names represented in the n-tuples returned by twinql-select.

Miscellaneous Operations


number-of-triples ag
function

Method (allegrograph-client)

Returns the number of triples in the triple store.


clear-triple-store ag
function

Method (allegrograph-client)

Remove all the triples.


client-index-all-triples ag &key (wait t)
function

Method (allegrograph-client)

Index all the triples.


client-index-new-triples ag &key (wait t)
function

Method (allegrograph-client)

Index only the new unindexed triples.


remove-statement ag s p o &key g
function

Method (allegrograph-client t t t)

Remove one triple from a remote triple store.


remove-statements ag &key s p o g
function

Method (allegrograph-client)

Remove one or more triples from a remote triple store.


client-sync-triple-store ag
function

Method (allegrograph-client)

Synchronize the triple store in memory and on disk.


client-close-triple-store ag
function

Method (allegrograph-client)

Close a triple store.


get-triple-parts ag id
function

Method (allegrograph-client t)

Returns 4 values: the subject UPI, predicate UPI, object UPI and graph UPI.


get-parts ag upi-or-upis
function

Method (allegrograph-client t)

Get the type, label and modifier identified by a UPI.

If the upi-or-upis argument is a single UPI, return æ values:

  • a keyword that identifies the type
  • the label
  • a modifier, if applicable

If the upi-or-upis argument is a sequence,


data-mapping ag &key set add
function

Method (allegrograph-client)

Without keyword arguments, this method returns the data mappings in effect for this triple store. The value is a list of the form

([uri encoding-name kind] ...

where encoding-name is a string that identifies one of the AllegroGraph encoded UPI types and kind is the string "predicate" or "datatype".

  • set - If this argument is non-nil, it must be a list as above. The specified mappings replace any mappings in effect.

  • add - If this argument is non-nil, it must be a list as above. The specified mappings are added to any already in effect.

client-indexing ag &key set drop add unindexed-threshold unmerged-threshold flavors
function

Method (allegrograph-client)

Query or modify the indexing parameters of the triple store. If no keywords are specified, returns 4 values:

  • the number of unindexed triples
  • the number of unmerged index chunks
  • the unindexed triples threshold
  • the unmerged index chunk threshold

If the flavors keyword argument is non-nil, retrun a list of the currently activated index flavors in this triple store.

  • unindexed-threshold - set the unindexed triples threshold
  • unmerged-threshold - set the unmerged index chunk threshold
  • set - if non-nil, must be a list of index flavors. The list replaces the current setting in the triple store.
  • drop - if non-nil, must be a list of index flavors. The specified index flavors are dropped.
  • add - if non-nil, must be a list of index flavors. The specified index flavors are added.

client-equal x y
function
Generic comparator for client-value instances.