Introduction
Namespaces
A namespace is a URL ending in / or # which, when combined with a value and wrapped with angle brackets specifies a URI such as
<http://host/name/VALUE> or
<http://host/name#VALUE> The namespaces in the examples above are
http://host/name/ and http://host/name# Namespaces however are often long and inconvenient to type. Prefixes can be defined which abbreviate namespaces. Prefixes can be defined in a SPARQL query with a PREFIX statements like:
PREFIX hn1: <http://host/name#>
PREFIX hn2: <http://host/name/> Then in a query the following URLs are equivalent:
hn1:VALUE and <http://host/name/VALUE>
hn2:VALUE and <http://host/name#VALUE> Query options
A query option provides control over SPARQL query execution. The list of available query options is found here in the SPARQL Reference document.
An option can be specified in a query with the following line above the actual query:
PREFIX franzOption_optionName: <franz:optionValue> (In the optionValue specification, franz: looks like a namespace prefix but it is just a marker used in parsing the value and is not related to namespaces.)
For example, in this query (from the kennedy example in AllegroGraph Quick Start):
PREFIX franzOption_engine: <franz:mjqe>
PREFIX o: <http://www.franz.com/simple#>
SELECT ?x ?p {
?x o:sex o:male ;
o:alma-mater o:Harvard ;
o:profession ?p .
}
ORDER BY ?p we have added
PREFIX franzOption_engine: <franz:mjqe> to specify the mjqe query engine (see the SPARQL Query Engines document).
Namespace/query option hierarchy
AllegroGraph allows namespace prefixes and query options to be defined in four locations:
In a SPARQL query with a PREFIX statement. (A query namespace/query option.)
Associated with a user and repo (A user namespace/query option, applied to every query run by that user on that repo but not seen or applied in other repos or by other users).
Associated with a repo (a repo namespace/query option prefix is visible to all users and applied to all queries run on the repo by any user).
Globally (a default namespace/query option, is visible to all users and applied to all queries run in any repos).
We will describe how to define each of these namespace/query option types below. In any query, a namespace prefix will be resolved to a namespace so long as it is defined in one of the four listed locations. A query option will be applied to a query so long as it is specified in one of the locations.
But what happens if the same namespace prefix is defined in two locations with different associated namespaces or the same query option is defined in two locations with different values? We describe below exactly how it is determined which is used. Here we just note that if two users pass queries around and also have different user query options/namespace prefixes, then one may see query errors where the other doesn't, or (and this is worse) the two users may see different results while they think they are doing the same thing. (All users see repo and default query options/namespace prefixes so those will not cause a problem as will not those specified in the query itself.)
Namespace and query option nomenclature
Namespaces
All URLs are wrapped in angle brackets. In this document and generally we use namespace to be the portion of the URL prior to the VALUE without the angle brackets. So in
<http://host/name/VALUE> the namespace is http://host/name/. Usually when entering a triple (without using a prefix) you must include the angle brackets.
All namespace prefixes, when used, have a : (colon) as a delimiter between the prefix and the value. In this document and generally we use namespace prefix (or just prefix where it is clear we are talking about namespaces) to be the portion prefix prior to the :. So in
hn1:VALUE the prefix is hn1. When angle brackets or colons must be included, we will say so.
Query options
A query option has the form
OPTION_NAME: <franz:VALUE> Like a namespace prefix, when specified the OPTION_NAME is followed by a : (colon) and the value is wrapped in angle brackets. By query option name we mean everything except the colon. By query option value, we mean just the value part, without the angle brackets or the franz:.
Namespace/query option hierarchy
Namespace prefixes and query options can be defined in four locations:
In a SPARQL query with a PREFIX statement. (A query namespace/query option.)
Associated with a user and repo (A user namespace prefix/query option, which is visible only to the user and only on that repo).
Associated with a repo (a repo namespace prefix/query option, which is visible to all users of the repo).
Globally (a default namespace prefix/query option, which is visible to all users in all repos).
We will describe how to define each of these namespace prefix/query option types below. In any query, a prefix will be resolved to a namespace or a query option will be applied so long as it is defined in one of the four listed locations.
But what happens if the same prefix is defined in two locations with different associated namespaces, or a query option is specified in two places with different values? Then the prefix is searched for in each location in order, and the first match is used. Query-defined prefixes/query options are used before user-defined ones, which are used before repo-defined ones, which are used before default ones.
Listing namespace prefixes/query options and defining new ones
Namespace prefixes and query options can be defined in queries. The definitions take the following form:
PREFIX hqurd: <http://www.ns/qurd/q#>
PREFIX franzOption_engine: <franz:mjqe>
SELECT ?o WHERE { hqurd:squrd keyword:is ?o .} All the query-defined prefixes and query options appear in the query. They take precedence over prefixes/query options defined elsewhere.
The AGWebView Utilities | Namespaces and Utilities | Query Options menu items
display, respectively, the namespaces and the query options associated with the current repository (the menu choice is grayed out and inactive if there is no current repo).
Namespaces display
Here is what is displayed when Namespaces is chosen (including some we have defined and without some default items deleted for space):
There are two user namespaces (hqurd and hurd), three repository namespaces (hrd along with repeats of the user namespaces), and six visible (and more cropped) default namespaces (the relevant for this discussion is hd and the three which are also repo namespaces).
Note some prefix/namespace combinations are grayed out. That is because they appear in higher lists. When seen in a query, it is the namespace in bold that is used (the user namespaces hqurd and hurd, the repo namespace hrd, and the default namespace hd) unless the prefix is also defined in the query, in which case the query definition is used. We are illustrating that when a prefix is multiply defined, precedence is query, user, repo, and finally default.
At the bottom of each grouping, there is a link to create new prefix/namespace combinations (there is also one below default namespaces but it is out of the picture). Clicking on that link produces the dialog at the top of the screen:
Enter the prefix (with or without the trailing colon, both work) and the URI (with or without the surrounding angle brackets, both work), and choose the namespace type (user, repository, or default) and click OK. You can define multiple prefixes of the same type with the Bulk Input button.
Query options display
Query options are displayed more or less the same as namespaces.
When specifying new query options, a dialog similar to that for mnamespaces shown above is displayed, with the same type choices (user, repo, and default). As with namespaces, material that is always present (like the colon and franzOption_ for the option name and the angle brackets and franz: for the value) may be included or left out.
agtool namespaces and agtool query-options
The agtool command tool has a namespaces command and a query-options command with options list, add, and remove (and help which explains usage).
There use is more or less identical, so we will describe namespaces, as that describes the behavior of query-options as well.
list lists prefixes/namespaces for a specific repo, with various display options and optionally restricted to a particular type. Here is the table output for any type (edited to save space):
% agtool namespaces list --output table --type any nstest
| PREFIX | IRI | TYPE | SHADOWED |
|---------|-------------------------------|------------|----------|
| baz | http://foo/baz# | user | false |
| hd | http://www/ns/d/d# | default | false |
| hqurd | http://www/ns/qurd/u# | user | false |
| hqurd | http://www/ns/qurd/r# | repository | true |
| hqurd | http://www/ns/qurd/d# | default | true |
| hrd | http://www/ns/rd/r# | repository | false |
| hrd | http://www/ns/rd/d# | default | true |
| hurd | http://www/ns/urd/u# | user | false |
| hurd | http://www/ns/urd/r# | repository | true |
| hurd | http://www/ns/urd/d# | default | true |
| keyword | http://franz.com/ns/keyword# | default | false | The prefixes are listed alphabetically, with the associated namespace (labeled IRI), type, and whether the prefix is shadowed. Shadowed is true when the same prefix has a definition in a type with higher precedence, so the prefix hqurd is defined as a user, repo, and default prefix. The user definition is not shadowed and the other are. (The user definition would be shadowed by a prefix definition in a query.)
Namespaces may be added or removed with agtool namespaces add and agtool namespaces remove. Multiple prefix/namespace pairs may be added or removed in one command, like this add command for a namespace of type user on the repository REPO-SPEC (which must specify both the user and the repo):
% agtool namespaces add --type user REPO-SPEC \
without http://foo/without# \
with: \<http://foo/with#\> For --type repository, REPO-SPEC must again specify the user and the repo as the user must have write access on the repo. For --type default a SERVER-SPEC must be specified identifying a user with superuser privileges.
As with the AGWebView dialog described above, the colon may be present or absent in the prefix specification and the angle brackets may be present or absent in the namespace specification (but must be escaped if present as otherwise they will be interpreted as shell redirection commands). --type defaults to user.
agtool namespaces remove has the following command form, with the namespaces having to be specified with the specified type, which defaults to user.
% agtool namespaces remove --type user REPO-SPEC \
without\
with: Adding and removing query-option
The command is agtool query-options add/remove but is otherwise essentially the same as for namespaces.
Who can add or remove namespaces and query options
Anyone who can pose a query can add PREFIXes specifying namespace prefixes and query options. (Some query options associated with attributes may require permission to specify, see the Triple Attributes document.)
Any user can add or remove user namespace prefixes and user query options.
A user with write permission on a repository can add or remove repository namespace prefixes and query options.
Only users with superuser priviliges can add or remove default namespace prefixes and query options.
Example illustrating namespace precedence
If queries are to be shared among users, careful management of prefixes is essential if different users are to see consistent results. Our example has prefixes defined in queries, for specific users, for repos, and as default. Prefixes may shadow those defined lower in the precedence list. (q, u, r, and d in a prefix means it is defined, respectively, in queries, for a user, for a repo, and by default.)
So with this data:
<http://www/ns/qurd/q#squrd> <http://franz.com/ns/keyword#is> "query" .
<http://www/ns/qurd/u#squrd> <http://franz.com/ns/keyword#is> "user" .
<http://www/ns/qurd/r#squrd> <http://franz.com/ns/keyword#is> "repo" .
<http://www/ns/qurd/d#squrd> <http://franz.com/ns/keyword#is> "default" .
<http://www/ns/urd/u#surd> <http://franz.com/ns/keyword#is> "user" .
<http://www/ns/urd/r#surd> <http://franz.com/ns/keyword#is> "repo" .
<http://www/ns/urd/d#surd> <http://franz.com/ns/keyword#is> "default" .
<http://www/ns/rd/r#srd> <http://franz.com/ns/keyword#is> "repo" .
<http://www/ns/rd/d#srd> <http://franz.com/ns/keyword#is> "default" .
<http://www/ns/d/d#sd> <http://franz.com/ns/keyword#is> "default" . These queries produce the results indicated:
PREFIX hqurd: <http://www/ns/qurd/q#>
SELECT ?o WHERE { hqurd:squrd <http://franz.com/ns/keyword#is> ?o . }
==> "query"
PREFIX hqurd: <http://www/ns/qurd/q#>
SELECT ?o WHERE { hurd:surd <http://franz.com/ns/keyword#is> ?o . }
==> "user"
PREFIX hqurd: <http://www/ns/qurd/q#>
SELECT ?o WHERE { hrd:srd <http://franz.com/ns/keyword#is> ?o . }
==> "repo"
PREFIX hqurd: <http://www/ns/qurd/q#>
SELECT ?o WHERE { hd:sd <http://franz.com/ns/keyword#is> ?o . }
==> "default" Query options can also be specified in various places with different values. Again, the specification in the query itself is used if present, and then the first of a user specification, a repository specification, and a default specification.
The REST interface
Listing, adding and removing namespace prefixes and query options can be done using the REST interface. Here are some examples:
curl -X PUT <repo>/namespaces/ns1?type=repository -d 'http://ns1/'
curl -X DELETE <repo>/namespaces/ns1?type=repository The prefix is ns1 and the namespace is http://ns1/.
curl -X PUT <repo>/query-options/engine?type=repository -d 'mjqe'
curl -X DELETE <repo>/query-options/engine?type=repository The query option name is franzOption_engine and the value is franz:mjqe. Redundant material need not be specified.
These command list current values:
$ curl -X GET <repo>/namespaces
prefix: dc
namespace: http://purl.org/dc/elements/1.1/
...
$ curl -X GET <repo>/query-options
name: engine
value: mjqe
... The addition of ?effective=false adds info about whether a setting is shadowed:
$ curl -X GET <repo>/namespaces?effective=false
prefix: dc
namespace: http://purl.org/dc/elements/1.1/
type: default
shadowed: false
...
$ curl -X GET <repo>/query-options?effective=false
name: engine
value: mjqe
type: user
shadowed: false
...