Table of Contents

Introduction

Starting AGWebView

Logging in

Data Display Conventions

Managing Namespaces

Managing Users

Initial Superuser

Create a New User

Set Permissions

Access Control

Filtering out triples

Managing Roles

Anonymous Access

Self-Enrollment

SPARQL Queries

Prolog Queries

Session Specifications

Free-Text Indices

Google Maps Display

WebView User Interface

Banner

User Management Page

Root Catalog Page

Named Catalog Page

Repository Overview Page

Free-Text Indices Page

New Query Page

Saved Query Page

Recent Query Page

Text Query Page

Processes Page

Namespace Selection Page

Replication Page

Introduction

The AllegroGraph 4.7 Web View (AGWebView) is a graphical user interface for exploring, querying, and managing AllegroGraph triple stores. AGWebView uses AllegroGraph's HTTP interface to provide these services through a web browser.

Using AGWebView you can:

Starting AGWebView

AGWebView is a part of AllegroGraph server. When the server is running, AGWebView may be opened by typing the server's IP address and port number into the address field of a web browser:

http://localhost:10035 

Logging in

If there is an AllegroGraph server listening on that port, AGWebView will respond immediately with a login form:

Login Form

If you are exploring AGWebView for the first time, log in using the name and password of the AllegroGraph superuser you created during server installation. In Franz's documentation this user is usually described as "test" with password "xyzzy".

Once logged in you can create additional user accounts with different types of access and privileges.

Data Display Conventions

Much of the AGWebView interface is concerned with the "parts" of triples, which are composed of Uniform Resource Identifiers (URIs) and literal values.

In AGWebView, URIs consist of a namespace and a local name enclosed in angle-brackets <>.

<http://www.franz.com/examples#Alice> 

where http://www.franz.com/examples# is the namespace, and Alice is the local name.

By default, the AGWebView interface removes the namespace and displays only the local name. This produces query results that are easy to read:

Short parts display

For more detail, you can use a checkbox in the upper right corner of the AGWebView screen to turn on the "long parts" feature to see the full URIs:

Long parts display

AllegroGraph supports many types of literal values, as shown in our java tutorial. Literals generally appear as quoted strings in the AGWebView interface:

Short Literal Values

The "42" in the above image looks like a string but it is actually a xsd:long (a high-precision integer). To see the types of your literals, invoke the "long parts" feature again:

Long Literal Values

Managing Namespaces

The difference between the "short parts" and "long parts" displays shown above is the suppression of the URI namespace in the condensed displays. This makes the output easier to read.

We can also use namespaces for input. To make it easier to type in lengthy URIs, AllegroGraph provide a set of shared namespace abbreviations. These namespaces make it much easier to set up queries or to assert new triples by hand. These are the shared namespaces in AGWebView:

rdf:     http://www.w3.org/1999/02/22-rdf-syntax-ns#   
rdfs:    http://www.w3.org/2000/01/rdf-schema#  
owl:     http://www.w3.org/2002/07/owl#  
dc:      http://purl.org/dc/elements/1.1/  
dcterms: http://purl.org/dc/terms/  
foaf:    http://xmlns.com/foaf/0.1/  
fti:     http://franz.com/ns/allegrograph/2.2/textindex/  
skos:    http://www.w3.org/2004/02/skos/core# 

These namespaces are available to every user in every repository.

In addition to the shared namespaces, you can create custom namespaces in a repository. Some of these are shared, meaning that any user with access to the repository can use them. There are also private namespaces that are available only to a single user.

To create a namespace, simply click one of the "add namespace" links and then fill out the form:

Franz namespace defined

Then to use the namespace, type it into an input field with the required colon (:) and the local name of the resource.

Franz namespace in use

AGWebView will automatically expand the full URIs behind the scenes.

Managing Users

See Security for more information on this topic (the information about managing users is repeated in that document).

To open an AllegroGraph repository, you must supply an AllegroGraph user name and password. AllegroGraph users can differ in terms of repository access, ability to manage other user accounts, and permission to create sessions and to run arbitrary code.

This section describes user-related tasks and how to perform them. Many of these tasks can be performed on the User Management page. See the description of that page for a list of the controls found on it.

Initial Superuser

An initial superuser is created during the AllegroGraph server installation. This user typically appears in Franz documentation as user "test", password "xyzzy".

This superuser can create and manage other users, can start sessions, can evaluate arbitrary code, and has read/write access to all repositories in all catalogs.

Note that you want to have at least one superuser at all times, because only an AllegroGraph superuser can manage permissions and access for other accounts. It is possible to delete the last superuser and lock yourself out of user management, which is embarrassing but not fatal. You can re-create the original superuser by re-running the AllegroGraph server configuration script. This step has no impact on other user accounts.

Create a New User

On the User Management page, click the "add a user" link. This opens a form for the user name and password of the new user. User names and passwords are case-sensitive. You are not allowed to create a user without also specifying a password.

Set Permissions

Click the "edit" link next to the new user's name on the User Management page. You will see four checkboxes:

User permissions

Access Control

You might want to limit a user's access to your repositories and catalogs. The Access Control form lets you do that.

Immediately under the permissions checkboxes you will find the Access Control form:

Access Control Form

Select the access (read, write or both) and then select the catalog and repository. Asterisk (*) behaves as a wildcard in these fields. The forward slash (/) designates the root catalog. Click the "OK" link to add this permission. You can use the form repeatedly to add multiple permissions.

You will see the new permissions listed on the screen, just above the Access Control form:

Access Control Form

The "remove" link deletes the permission.

Filtering out triples

You can set up filters which limit access to specific triples (those with specified subject, predicate, object, or graph). See the discussion of Security filtering in Security Implementation for more information.

Managing Roles

A "role" is a predefined set of permissions and access settings. Roles let us centrally manage the permissions and access of a class of users. Security experts prefer to manage access through roles because it lets them respond quickly to an emergency. A single mouse-click on a role can revoke permissions from scores of users at the same time. To make the same change in all the individual user accounts would take too much time.

To create a role, go to the User Management page and scroll down to the Roles section. Click the "add a role" link. Enter the name of the new role in the resulting form. Note that role names should be descriptive and specific, because they become entries on a potentially long list of available roles.

Once the role has been created, give it permissions and access just as if it were a user account.

Defining a Role

To apply a role to a user account, click the "edit" link for that account.

Giving a Role to a User

Select the role from the list and click the "OK" link. The user's local permissions and access indicators will not change, but he/she will have the full powers of the role.

Anonymous Access

If you create a user named "anonymous" (the case is significant, all lowercase), AGWebView will enable anonymous login. This is the only user account that can be created without a password.

On the User Management page, click the "add a user" link and type "anonymous" in the __Username__ field. Then click the "OK" button.

From this point on, AGWebView will automatically log in the anonymous user each time you connect to the server. This makes AGWebView available to anyone, but only within the limits imposed by the permissions and access settings of the anonymous account. Be sure to give the anonymous account read access to at least one repository or the visitors won't be able to see anything.

Anonymous access does not prevent you from logging in as another user. Look for the "User: anonymous > login" menu item in order to log in to your account.

Login from Anonymous

Self-Enrollment

AGWebView can permit otherwise anonymous users to self-enroll by registering usernames and passwords for themselves. These self-enrolled users have the same permissions and access as the anonymous user, but they can also have private namespaces and their own saved queries.

A superuser enables this feature in the Site Settings section of the Root Catalog page, by clicking the "Allow" link.

Allow Self-Enrollment

When self-registration is allowed, there is a "User anonymous > register" menu item in the page banner. This link opens a form for creating a new user. The new user is automatically logged in after registration.

Self-Enrollment

SPARQL Queries

The reader might appreciate some "seed" queries to help get started with SPARQL. Note the use of curly braces {} instead of parentheses () in SPARQL queries.

"Show the subject and object values from fifty rdf:type triples." This returns only the values you ask for.

select ?s ?o where {?s rdf:type ?o} limit 50 

"Construct fifty new triples from values found in existing triples." This returns a set of actual triples, sometimes called a "graph."

construct {?s ?p ?o} where {?s ?p ?o} limit 50 

"Describe a resource to me." Note that this query returns all triples that describe a specific resource, including those obtained by traversing a blank node.

describe ?s where {?s ?p ?o} limit 1 

Prolog Queries

The user account must have permission to "execute arbitrary code" in order to execute a Prolog query.

AllegroGraph provides "select" queries as an extension to its internal Prolog language. This is a simple Prolog query. Note the use of parentheses () instead of curly braces {}, and that the triple patterns begins with a "q". Also, namespace abbreviations must be preceeded by a bang (!) character.

(select (?s ?o) (:limit 10) (q ?s !rdf:type ?o) ) 

This query returns subject and object values for ten triples that contain an rdf:type predicate.

Prolog "select" queries are the portal to AllegroGraph's geospatial and social-network features.

Session Specifications

The AGWebView interface allows the advanced user to create a new "session." It offers you an empty text field (on the Root Catalog page) to enter your "session specification."

This is a powerful tool for creating complex federated triple stores, with reasoning and graph filtering applied to the individual stores of the federation.

For instance, this specification federates a reasoning version of store "A" in the root catalog with a reasoning version of the "http://example.com/graph1" graph of store "B" in the "public" catalog:

<A>[rdfs++] + <public:B>{<http://example.com/graph1>}[rdfs++] 

In a session specification, local stores are written as <catalog:name>, or just <name> for stores in the root catalog.

Remote stores are written by putting their URL between < and >.

Multiple stores can be federated by putting plus signs (+) between them. For example, <store1> + <store2>.

To apply a reasoner to a store, write [rdfs++] or [hasvalue] after it.

To create a filtered store, write the URIs of the participating graphs between braces {}, using null to indicate the default graph.

The Session Specification field has an "autocommit" checkbox next to it. Uncheck this box to create transaction semantics, where you can manually issue "commit" and "rollback" actions as needed. Look for them in the Session menu, up in the page banner.

Free-Text Indices

AllegroGraph supports multiple free-text indices, each targeted as narrowly as you like on specific fields of specific predicates.

The form for creating a free-text index is on the Free-Text Indices page.

Each free-text index has a name, so you can apply it to a query or perform maintenance on it.

Each index works with one or more specific predicates, including an option to index all predicates.

An index can include all literals, no literals, or specific types of literals.

An index can process the full URI of a resource, just the local name of the resource (after the # or /), or it can ignore resource URIs entirely.

An index can focus on any combination of the four parts of a "triple:" the subject, predicate, object, and graph.

Stop words (ignored words) may be specified, or the index can use a default list of stop words.

In addition, an index can make use of word filters such as stem.english or drop-accents.

Google Maps Display

If your query results are in AllegroGraph's geolocation format, and if you have provided AGWebView with a Google Maps key, then AGWebView will offer to display the results as a map, like this one:

Kennedy Locations

AllegroGraph geospatial coordinates generally resemble this example:

"+481200.00273+0162212.00273"^^<http://franz.com/ns/allegrograph/3.0/geospatial/spherical/degrees/-180.0/180.0/-90.0/90.0/1> 

AGWebView can map the results of any query that returns geospatial coordinates as the object values of the query.

WebView User Interface

This section provides a page-by-page summary of the AGWebView user interface.

Banner

There is a blue header across the top of most AGWebView pages. This banner displays the name of the logged-in user, and offers context-specific controls that let you "back out" to previous pages or to access general functions such as "logout". The illustration just shows a possible banner. Because available choices are displayed according to the context, not all choices are shown in this illustration, although you will see many in banners in other illustrations.

Page Banner

<<
The << symbol lets you go "back" a level in the hierarchy of AGWebView pages.
Admin
This is a drop-down menu offering three options to the AllegroGraph superuser:
  • processes: This link opens the Processes page.
  • users: This link opens the User Management page.
  • initfile: This link opens the Initfile editing page.
User
This is a menu that drops down from the name of the current user offering:
  • logout: The current user logs out.
  • delete: The current user has an opportunity to delete his/her own account.
Reasoning
If checked, turn on RDFS++ reasoning for queries on this repository.
Long parts
If checked, display fully-expanded URIs in the query results.
Contexts
If checked, display the graph URI as the fourth element of each returned "triple."
Overview
This link moves the focus to the Repository Overview page for the current repository.
Queries
When viewing a repository, query options appear as a menu in the banner.
  • new: Create a new query.
  • saved: Select from a list of saved queries.
  • recent: Re-run a recent query, whether saved or not.
  • text: Run a text query.
Namespaces
The namespaces link in the banner leads to the Namespace Selection page.
Session
When you have opened a transaction session in a repository, a session menu appears in the banner.
  • commit lets you take all of the triples you have loaded or created up to this point, and add them permanently to the repository.
  • rollback lets you discard all uncommitted triples, presumably because your load was interrupted and you want to start over.
  • close terminates the session.

User Management Page

From the top-level Root Catalog page of the AGWebView interface, scroll down to the Site Settings section. Click the "user accounts" link to open the User Management page. You must be logged in as an AllegroGraph superuser in order to view this page.

See the Managing Users section for a task-based explanation of user management.

Add a User
This link opens a form for the name and password of a new user.
Delete
You can delete a user account.
Edit
Each user account has an "edit" link that opens up controls for settings permissions and access.
Change Password
Click here to change the user's password.
Roles: Add
If user roles have been defined, you can use this control to associate the current user with a role. Select the role from the list and click the OK link.
Superuser
A superuser has full access to all repositories, can execute arbitrary code, and can manage user accounts.
Start sessions
This checkbox gives the account permission to start sessions. A "session" is an independent AllegroGraph back end that supports transaction semantics and Prolog queries.
Evaluate arbitrary code
This checkbox gives the account permission to execute Prolog queries, which opens a window to executing arbitrary code on the server.
Grant read/write on catalog/repository.
This group of controls lets you grant an account read and/or write access to specific repositories. "*" is a wildcard for "all". "/" means the root catalog.
Remove
The "remove" link lets you revoke repository access after it has been granted.
Add a Role
This link lets you name a new role.
Delete Role
Each role has a "delete" link that lets you remove the role.
Edit Role
You can edit a role to grant permissions and access to it, just like you would for a user account.

Root Catalog Page

The Root Catalog page is the top-level page for the AGWebView interface. We call it the "Root Catalog" page because it lists the repositories of the root catalog. It also lists the names of any named (non-root) catalogs that are present. This page lets you choose a triple store to manage.

Root Catalog Page

This is the page you see when you log into AGWebView. Later you can return to this page by clicking the "<<" link in the page banner until the focus returns to the top level.

Catalogs
These are the non-root catalogs of the system. Click on one to see the repositories it contains.
Repositories
These are the repositories of the root catalog.
Create a Repository
Create a new repository in the root catalog.
Open a session
This field lets you create an arbitrarily complex federated store. See Session Specification earlier in this document.
Site Settings
This section links to miscellaneous controls that are described individually below.
User Accounts
Follow this link to the User Management page for managing user accounts.
Allow/Disallow
This link is only visible to a superuser. It toggles, giving anonymous users the ability to create their own accounts. These accounts have the same privileges and access as the anonymous account. In this fashion, otherwise anonymous users can set up their own namespace lists, and can save their own queries.
Google Maps Key
This field lets you paste in a Google Maps key, which in turn lets AGWebView generate map displays of query results. This feature presumes that the triple store contains data that conforms to AllegroGraph's geospatial location format. (See the section on Google Maps.) Google requires that you provide a URL for the web site where the maps will appear. Use the URL that you use to open AGWebView. (The URL "localhost:10035" usually works.) Paste the resulting Google Maps key into this field.
Initfile
This feature is available only to superusers. The "Edit the site's initfile" link opens a large edit field containing the text of the AllegroGraph server's initialization file, which is /data/settings/initfile. This code is run by AllegroGraph server each time a new session is opened. It lets you load Prolog functor definitions to use with your Prolog queries.

Named Catalog Page

From the top-level Root Catalog page, click on any non-root catalog. This opens a Named Catalog page. This page lists all the repositories that are available within that catalog. Note that this page has the name of a specific catalog at the top.

Named Catalog Page

Repositories
These are the available repositories within this catalog. Click on one to see its Repository Overview page.
Create a Repository
Create a new repository in the current catalog.
Open a session
This field lets you create an arbitrarily complex federated store. See Session Specifications earlier in this document.

Repository Overview Page

The Repository Overview page gives you access to a specific repository within a specific catalog. The name of the repository is posted at the top of the page:

Repository Overview Page

Edit Description
This link lets you create a brief text description of the repository.
Load and Delete Data
This group of choices allows you to add or triples.
Add a Statement
This link opens a form to let you enter the subject, predicate, and object URIs of a new triple. You may optionally add a context (graph) URI.

Add Statement

Delete Statements
Enter any combination of URIs, wildcards, and literals into the fields of the form. Click OK to delete all matching statements from the triple store. Caution: There is no way to undo this action.
Import RDF
The choices allow you to select a file and load it into the repository. It can be a local file, a server-side file, or a file reached by a URL on the Internet.

Loading a File

Explore the Store
These choices allow you to view triples in the store.
View Statements
This link runs an unrestricted SPARQL query and returns the first 100 triples it finds. The purpose of this feature is to give you a quick look into the triple store.
List classes
This is another feature that lets you take a quick look at a new triple store. It runs a SPARQL query that lists the rdf:type classes in the repository.
View sample predicates
This feature runs a SPARQL query that lists the first 100 predicates found in the triple store.
Notable Nodes
You can enter the subject URI of a resource of special interest. The URI then appears as a link on the page. Clicking this link takes you to a query-results page that shows predicate-object pairs from the target resources, plus all triples that use this URI as a predicate, and all triples that contain this URI as the object.

Notable Node Form

Store Control
These choices allow you to manipulate a store.
Export
You can dump the triple store to a file, using any of these RDF formats:
  • N-Triples
  • N-Quads
  • RDF/XML
  • TriX
Start a Session
This link starts a dedicated session in this repository, which establishes transaction semantics. A Session menu will appear in the banner, offering Commit and Rollback links. Commit lets you take all of the triples you have loaded or created up to this point, and add them permanently to the repository. Rollback lets you discard all uncommitted triples, presumably because the load was interrupted and you want to start over. The menu also offers a Close link, which ends the session.
Control Replication
See the document on Replication and Warm Standby. This link opens the Replication page.
Active Indices
This is the list of active triple indices for this repository. Click on an "x" icon to delete an index, or use the Add Index link to add one.
Manage free-text indices
This link takes you to the Free-Text Indices page. See the section on Free-Text Indexing, above. Once you have created a free-text index, you can use the Queries menu to initiate a text search.
Manage external Solr free-text indexer
This link lets you set up a connection to the Apache Solr full-text indexer from an AllegroGraph repository. See Solr Text Index.
Manage external MongoDB connection
This link lets you set up a connection to a MongoDB from an AllegroGraph repository. See MongoDB interface.

Free-Text Indices Page

One reaches the Free-Text Indices page by clicking "View free-text indices for this store" on the Repository Overview page.

To create an index, type its name into the field. Remember that there might be many indexes, so the name should be fairly specific. Click the "Create" link.

Once you have named and created the index, you have to set a variety of options that tell AllegroGraph what to put in this index. See the Free-Text Indices section for a discussion of these options.

When you create a new index or edit the parameters of an old one, AllegroGraph will reload the triples to bring the index up to date.

New Query Page

From the Repository Overview page, click the New link in the Queries menu. This exposes a page where you can edit a SPARQL or Prolog query to run against this repository.

See the sections on SPARQL Queries and Prolog Queries for examples queries to get you started.

New Query Page

This page lets you edit a new SPARQL or Prolog query and test it against the triple store.

Query language
This page accepts SPARQL queries from all users. Users with permission to execute arbitrary code will be offered the option to use a Prolog query instead.
Show my namespaces
Click this link to view the table of namespaces that are available to the current query. This could be a mix of shared and private namespaces.
Add a namespace
This like lets you enter a new, private namespace to use in this query.
Bulk Input
When you click the "Add a namespace" link, one of your options is a "Bulk Input" button. Click this button to open an edit field where you can paste in many namespaces in one operation. Use one namespace per line, in a format like "ex http://example.com/" or "ex: http://example.com/". (Note that bulk is used by two utilities in different ways. In data loading (see Data Loading), bulk means loading data without transaction logging. In Sesame and Jena and also here it mean processing several statements at once but is not related to transaction logging or loading.)
Query Edit Field
This is the unlabeled field where you type in the text of your query. Note that you can adjust the size of the field by using the mouse to "grab" the handle at the lower right corner of the field.
Link to query
Click this link to generate a URL that invokes this query on this repository. You can publish this URL or embed it in software. Copy the URL from the browser's address field. Note that this URL requires anonymous access. If there is no anonymous account, AGWebView will require the user to log in.
Execute
The Execute button runs the query. A table of results will appear in the lower half of the page.
Save As
You can save a private copy of a query for later reuse. Give it a name and then click the Save button. To find this query again, click the saved link in the Queries menu in the page banner. (This feature is available to superusers, normal users, and self-registered users, but not to anonymous users.)
Add to Repository
You can also "save" a query by adding it to the Repository Overview page as a link to a "Pre-defined Query." To do this, give the query a name and click the "Add to Repository" button. (Superusers can add a query to the Repository Overview page. All users, including anonymous, can then use it.)
Edit Initfile
This feature is available only to superusers. The "edit initfile" link opens a large edit field containing the text of the AllegroGraph server's initialization file, which is /data/settings/initfile. This code is run by AllegroGraph server each time a new session is opened. It lets you load Prolog functor definitions to use with your Prolog queries.
Result
This is a table of search results. Each URI in the table is a link to a page of information about how that URI is used in the triple store.
Download as
If your query produced triples as output (such as a SPARQL "construct" or "describe" query does), then this feature lets you save the results in one of four formats: N-Triples, N-Quads, RDF/XML, or TriX. If the results are just a list of variable values, like a SPARQL "select" query creates, you can choose between the SPARQL XML Result format and a comma-separate list of values.
Display Geospatial Data on a Map
If the search results contain AllegroGraph geospatial coordinates, and if you have provided AGWebView with a Google Maps key, then AGWebView will offer to display the query results as a map. See the section about Google Maps.
View Results as Graph
When you execute a SPARQL "construct" or "describe" query, the result is a set of actual triples that can be displayed as a graph. Click this link to display the graph. In the graph, blue nodes are resources and green ones are literal values. Hover the mouse over a node to see a description of the node. (This description appears as text on the line above the graph, not directly above the node.) Similarly, the arrowheads on the lines between nodes reveal the name of a predicate. You can drag the nodes around on the screen and watch the graph adjust to a new equilibrium.

Graph of Results

Saved Query Page

If you have saved named queries on the New Query page, you can retrieve them by clicking the saved link of the Queries menu in the page banner. This produces a list of your saved queries.

Note that each query in the list is followed by a small "x" character. Click this "x" to delete the query.

Recent Query Page

The Recent Query page contains a list of your recently-executed queries, which includes your saved queries plus any other queries you ran. Click on an entry in the list to re-run the query.

Text Query Page

The Text Query page is a free-text search form. You get to select the text index to use. If you have not created any text indices, the page will prompt you to do so. Searching here produces a table of matching triples.

Processes Page

This page lists the AllegroGraph processes that are currently running. It is used for debugging AllegroGraph behavior.

To reach this page, click the "Processes" link in Admin menu of the page banner. AllegroGraph can create many subprocesses.

stacktrace
This link displays the stacktrace of the process.
kill
This link kills the process.
start telnet
This link opens a telnet port directly into the eval command loop of the process. This lets an engineer interact directly with the process for diagnostic purposes.

Namespace Selection Page

My namespaces
These are namespaces that you have entered in the current repository for your personal use. Add namespace lets you add another namespace to the repository. The "x" icon after a namespace name lets you delete it from the repository.
Standard namespaces
These are the namespaces for this repository that are shared among users. Use the checkboxes to the left to enable or disable individual namespaces for this repository.

Replication Page

See the document on Replication and Warm Standby. If there is an active replication server available, this page lets you connect to it and set up a warm-standby triple store on the local server.