Table of Contents

Conventions

Finding catalogs

Catalogs

Repositories

Queries

Statements

Indexing

Namespaces and environments

This document describes the programming interface of the client library for the AllegroGraph HTTP server. The library is intentionally thin and primitive - a more convenient programming interface could be wrapped around it.

Conventions

Many functions return or expect as arguments RDF terms. For simplicity, these are represented as strings in a format that resembles N-triples, but allows non-ASCII characters. Examples of valid terms are <http://example.com/foo>, "literal value", "55"^^<http://www.w3.org/2001/XMLSchema#integer>. Strings starting with _: are used to represent blank nodes. In 'context' (graph name) positions, the string null is also a valid value, and denotes the default graph.

Triples are represented as lists of three or four terms, where the last one denotes the graph name. Triples without a graph name are assumed to belong to the default graph. Result-sets from, for example, SPARQL select queries are represented as jso objects with names and values fields. Names contains a list of strings naming the columns of the result, and values a list of lists of terms.

All symbols mentioned in this document are exported from the db.agraph.http.client package.

Finding catalogs

When the URL to the catalog you want to access is not known, and the server serves multiple catalogs, you can start by creating an object of type agraph-http-client...

make-instance 'agraph-http-client (&key url auth)  
→ agraph-http-client 

Objects of this type represent a handle to a server. The base URL of the server, as a string, without trailing slash, should be given as the url argument. auth can be a (username . password) cons to use as authorisation while accessing this server.

list-catalogs (client)  
→ list 

Returns a list of paths to the catalogs available on this server.

get-catalog (client path)  
→ catalog 

Create a new catalog object from a path as returned by list-catalogs

Catalogs

make-instance 'catalog (&key url auth)  
→ catalog 

A catalog takes the same initargs as an agraph-http-client object, except that the url should refer to a catalog's URL, rather than the top-level server URL.

list-triple-stores (catalog)  
→ list 

Returns a list of triple stores present in this catalog, by URL.

get-repository (catalog id &optional environment)  
→ repository 

Create a repository object from an ID or URL. When environment is given, it sets the active environment for the repository.

create-triple-store (catalog id)  
→ repository 

Creates a new repository with the given ID.

delete-triple-store (catalog id) 

Deletes a repository. id may be the ID or URL of the repository.

Repositories

make-instance 'repository (&key url auth environment)  
→ repository 

Objects of this type are handles to repositories / triple-stores on the server. url should hold a URL under which a repository is being served. auth has the same meaning as in agraph-http-client, and environment, which is optional, can be a string to set the current environment of the repository.

repository-environment (repository)  
→ string 

Accessor for getting and setting the current environment of the repository object. This environment is used when setting namespaces, Prolog functors, and when making queries. They can be used to isolate clients from each other's settings. Use create-environment before trying to use an environment. By default, repositories have no environment, and use the 'global' environment.

repository-size (rep &optional context)  
→ integer 

Retrieve the amount of triples in the repository, or, if context (an RDF term) is given, the amount of triples in a specific named graph.

repository-contexts (rep)  
→ list 

Fetch a list of named graphs (as RDF term strings) in this store.

Queries

sparql-query (rep query &optional infer contexts named-contexts)  
→ result  

Run a SPARQL query against the repository. When infer is true (defaults to false), reasoning will be turned on for the query. contexts and named-contexts can be lists of graph names that the query will be restricted to, where named-contexts preserves the names of the graphs.

The type of the result depends on the query. ASK queries will return a boolean, DESCRIBE and CONSTRUCT queries a list of triples, and SELECT queries return a result-set with a names and values field.

prolog-query (rep query &optional infer limit)  
→ result-set 

Evaluate a Prolog query, which should be in Lisp syntax, using the select or select-distinct operators. infer, a boolean, can be used to turn on reasoning, and limit, an integer, will set a maximum amount of rows to be returned.

define-prolog-functors (rep definitions) 

Defines the given Prolog functors in the current environment. definitions should be a string containing the functors in Lisp syntax - using the &lt;-- or &lt;-- operators.

delete-prolog-functor (rep &optional name) 

When name is given, deletes the functor with the given name from the current environment. When name is not given, all functors are deleted.

get-statements (rep &key subj subj-end pred pred-end obj obj-end contexts infer)  
→ triple-list 

Fetch a set of matching statements from the repository. infer is a boolean controlling whether triples deduced by reasoning should be included. When none of the optional arguments are given, all triples in the store are returned. Passing subj, pred, or obj restricts the result set to only triples that have the given term in the subject, predicate, or object field. Passing one of these parameters along with its *-end companion will turn the query into a range query, meaning all statements that have, for example, a subject that falls between subj and subj-end (ordering depends on term type) will be included. Finally, a list of contexts can be given to restrict the result to one or more named graphs.

Statements

add-statement (rep subj pred obj &optional context) 

Add a single statement to the store. context can be used to give the new statement a graph name.

add-statements (rep statements) 

Add a set of statements. statements should be a list of lists of three or four elements, (subj pred obj &optional graph).

add-ntriples-statements (rep &key file string) 

Upload N-triples data to the server, or load an N-triples file. If string is given, it is assumed to contain the data, otherwise it is loaded from the filename given as file.

delete-matching-statements (rep &key subj pred obj context) 

Deletes all statements matching the given restrictions. When no optional arguments are given, the store is cleared.

delete-statements (rep statements) 

statements should be a list of statements, as in add-statements. Each of these statements, if it exists, will be deleted from the store.

freetext-search (rep pattern &optional infer)  
→ triple-list 

Execute a text search for pattern on the store. Returns every triple that matches. If infer is true, reasoning is used.

repository-freetext-predicates (rep)  
→ list 

Retrieves a list of predicates (RDF terms) which are used for free-text indexing in this store.

freetext-register-predicate (rep predicate) 

Register a predicate for free-text indexing. Note that only triples added afterwards will be indexed.

Indexing

repository-indices (rep)  
→ list 

Retrieve a list of active 'spogi' indices. These are strings like spogi or posgi.

add-index (rep type) 

Add an index to the store. type is a string, for example gspoi.

delete-index (rep type) 

Drop an index.

repository-index-coverage (rep)  
→ float 

Finds out which portion of the store has been indexed. The returned value lies between 0.0 (nothing is indexed) and 1.0 (everything is indexed).

index-repository (rep &optional all) 

Index unindexed statements in the store. When all is true, all index chunks will be merged, which might take longer.

Namespaces and environments

repository-namespaces (rep)  
→ list 

Returns a list of namespaces defined in the current environment. Namespaces are represented as (prefix uri) lists.

define-namespace (rep prefix uri) 

Define a new namespace in the current environment. prefix should be a string giving the short name, and uri a URI.

delete-namespace (rep prefix) 

Delete the given namespace (in the current environment).

repository-environments (rep)  
→ list 

Returns a list of environments (strings) that exist for this repository.

create-environment (rep name) 

Create a new environment with the given name.

delete-environment (rep name) 

Delete the environment named name.