Namespaces and query options
Author: Franz Incorporated

Copyright (c) 2005 - 2026 Franz, Incorporated
Last updated 27 May 2026 at 10:34

# Namespaces, query options, IRI aliases, and typevars

- Documentation Index
  - Release Notes
  - Quick Start
  - SSL/TLS Quick Start
  - Introduction
  - Setup and Configuration
    - Download
    - Server Installation
    - Server Configuration and Control
    - WebView
    - Database Upgrading
    - Managing Users
  - Server Management
    - Performance Tuning
    - Deleting Duplicate Triples
    - Purging Deleted Triples
    - Auditing
    - Managing Users
    - Replication
    - Point-in-Time Recovery
    - Transaction Log Archiving
    - Security Overview
    - Security Implementation
  - Tools
    - agtool
    - Data Loading
    - Data Export
    - Backup and Restore
    - Querying
    - RDFS++
    - Materializer
    - Event Scheduler
    - SHACL
  - Details
    - Triple Indices
    - Freetext Indices
    - Encoded IDs
    - Connection Pooling
    - N-dimensional Geospatial Overview
    - 2-D Geospatial
    - Temporal
    - Social Network
    - JavaScript
    - Datatypes
    - Data Conversion (Rapper)
    - Stored Procedures
    - Triple Attributes
    - Lineparse Format
  - Querying
    - SPARQL documentation summary
    - SPARQL Reference
    - SPIN
    - SPARQL Magic Properties
    - Prolog
  - 3rd-party tools
    - Solr text Indices
    - MongoDB integration
    - TopBraid Composer Plugin
    - Cloudera
  - Client APIs
    - Gruff
    - GraphTalker
    - REST/HTTP interface
    - HTTP reference
    - Javadocs (Sesame and Jena)
    - Python API
    - Lisp Reference
    - JavaScript
  - Tutorials
    - N-dimensional Geospatial
    - SPARQL Tutorial
    - Java Sesame
    - Java Jena
    - Python Sesame
    - Lisp
    - Prolog
    - More...
  - Other
    - Conferences and Seminars
    - Source Code on Github
    - Amazon EC2
    - Copyrights
  - Franz, Inc.

- Introduction
- Namespace/query option hierarchy
- Namespace and query option nomenclature
- Namespace/query option hierarchy
- Listing namespace prefixes/query options and defining new ones
- agtool namespaces and agtool query-options
- Who can add or remove namespaces and query options
- Example illustrating namespace precedence
- The REST interface
- IRI aliases
- Typevars

Documentation Index

## Introduction

Namespaces, query options, IRI aliases, and typevars are all methods of simplifying SPARQL queries to make them more readable. While IRIs are well-defined and unambiguous, they are also hard to read. The tools defined in this document are all syntactic sugar, that is they make code easier for humans to read without (when implemented correctly) changing its meaning or effect. Namespaces are widely used. Query options abbreviations, IRI aliases, and typevars are AllegroGraph-specific.

Be aware that the simplified abbreviations for the objects discussed in this document may conflict if not implemented correctly. We will mention potential conflicts as they arise.

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

IRI alises

SPARQL IRI aliasing is an AllegroGraph SPARQL extension that allows users to create a virtual namespace in which IRIs are referred by short names and can be completely unrelated, meaning they don't have to share a common prefix.

For example the following query

    PREFIX franzOption_alias_Joe: <franz:http://malenames.org/Joe>
    PREFIX franzOption_alias_Mia: <franz:http://femalenames.org/Mia>

    SELECT ?p {
      alias:Joe ?p alias:Mia
    }

will be transformed into

    SELECT ?p {
      <http://malenames.org/Joe> ?p <http://femalenames.org/Mia>
    }

See IRI aliases for more information.

Typevars

Typevars are an AllegroGraph extension based on query options. They allow that certain variables in the query should always mean resources of certain type (i.e. having `rdf:type` relations).

Just as aliases, SPARQL typevars can be declared using the SPARQL query option syntax as well as REST API, `agtool` and Lisp interface.

## Namespace/query option hierarchy

AllegroGraph allows namespace prefixes and query options to be defined in four locations:

1. In a SPARQL query with a PREFIX statement. (A query namespace/query option.)

2. 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).

3. 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).

4. 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:

1. In a SPARQL query with a PREFIX statement. (A query namespace/query option.)

2. Associated with a user and repo (A user namespace prefix/query option, which is visible only to the user and only on that repo).

3. Associated with a repo (a repo namespace prefix/query option, which is visible to all users of the repo).

4. 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 Traditional WebView 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).

In WebView, Namespaces is an option on the Repository menu to the left and Query Options is on the Repository Control submenu.

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

## IRI aliases

SPARQL IRI alias functionality is an AllegroGraph SPARQL extension that allows users to create a virtual namespace in which IRIs are referred by short names and can be completely unrelated i.e. don't have to share a common prefix.

This is useful when multiple complex IRIs are used throughout the query but cannot be abbreviated via regular namespace declarations because they don't share a prefix.

SPARQL aliases can be declared using the SPARQL query option syntax, as well as other query option APIs (HTTP, agtool, and Lisp).

For example the following query

    PREFIX franzOption_alias_Joe: <franz:http://malenames.org/Joe>
    PREFIX franzOption_alias_Mia: <franz:http://femalenames.org/Mia>

    SELECT ?p {
      alias:Joe ?p alias:Mia
    }

will be transformed into

    SELECT ?p {
      <http://malenames.org/Joe> ?p <http://femalenames.org/Mia>
    }

during parsing.

Note that by default, the alias namespace uses prefix `alias:`, but this can be overriden by using the `aliasPrefix` query option

    PREFIX franzOption_aliasPrefix: <franz:names>
    PREFIX franzOption_alias_Joe: <franz:http://malenames.org/Joe>
    PREFIX franzOption_alias_Mia: <franz:http://femalenames.org/Mia>

    SELECT ?p {
      names:Joe ?p names:Mia
    }

IRI aliases are defined just like other query options, as described above in this document.

## Typevars

SPARQL typevars functionality is yet another AllegroGraph extension based on query options, similar to IRI aliases. These allow to declare that certain variables in the query should always mean resources of certain type (i.e. having `rdf:type` relations).

Just as aliases, SPARQL typevars can be declared using the SPARQL query option syntax as well as REST API, agtool and Lisp interface.

A typevar declaration defines a variable name prefix. Once defined, all variables that start with that typevar prefix will be interpreted as instances of the given typevar.

For example, the following query

    PREFIX franzOption_typevar_p: <franz:http://ex.org/Person>

    SELECT * {
      ?p1 <http://ex.org/knows> ?p2.
    }

is transformed into

    SELECT * {
      ?p1 <http://ex.org/knows> ?p2.
      ?p1 a <http://ex.org/Person>.
      ?p2 a <http://ex.org/Person>.
    }

during parsing.

If a variable matches multiple typevar definitions, the longest prefix will be chosen, for example the query

    PREFIX franzOption_typevar_p: <franz:http://ex.org/Person>
    PREFIX franzOption_typevar_pic: <franz:http://ex.org/PersonInCharge>

    SELECT * {
      ?pic1 <http://ex.org/supervises> ?p1.
    }

will be transformed into

    SELECT * {
      ?pic1 <http://ex.org/supervises> ?p1.
      ?pic1 a <http://ex.org/PersonInCharge>.
      ?p1 a <http://ex.org/Person>.
    }

because for the variable `?pic1`, the longest prefix is that of the `pic` typevar.

Typevars are defined just like other query options, as described above in this document.