# Common Lisp client library for the AllegroGraph HTTP server

# 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`.