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 <--
or <--
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
.