Table of Contents

Introduction

Software Download

Server Installation

Installation from the tar.gz File

Running the Configuration Script

Installing the License Key

Starting the Server

Connecting to the Server

Starting AGWebView and Creating a Database

Logging in

Creating a Database

Other operations on the repository

Queries

Other documentation

Introduction

This document guides you through getting started with AllegroGraph. AllegroGraph is a complex and powerful product, and so has many options. These options are described in detail in specialized documents dealing with specific aspects of AllegroGraph. In this Quick Start guide, we will suggest standard (often default) options and link to the more specialized documents. That should allow you to be up and running quickly.

Software Download

Download the AllegroGraph Server from the AllegroGraph Download page. There are various options for AllegroGraph clients. In this Quick Start document, we will assume you will use the AGWebView client (using a web browser as the interface). AGWebView is built into the AllegroGraph server. The server runs natively on Linux x86-64 bit machines. You can run it on a Mac or a Windows machine using a Linux virtual machine, as described on the AllegroGraph Download page.

We assume in the rest of this document that the server installation file has been downloaded.

Server Installation

Server installation is described in detail in Server Installation. There are two installation methods: using an RPM file or using a gzip'ed tar file. We will describe the installation from a tar.gz file here.

Installation from the tar.gz File

The commands in this section do not require "root" access.

Place the downloaded tar.gz file it in a directory of your choosing. Then extract the installation files with the following command:

$ tar zxf agraph-4.14-linuxamd64.64.tar.gz 

This creates the "agraph-4.14" subdirectory within the current working directory, where the installation script resides. The installation script is "install-agraph". You must provide the path to a writable directory (which will be created if necessary) where you want to install AllegroGraph.

$ agraph-4.14/install-agraph /home/joe/tmp/ag4.14  
 
Installation complete.  
Now running configure-agraph. 

Running the Configuration Script

The AllegroGraph installation script creates an AllegroGraph configuration file (agraph.cfg) with settings appropriate to your environment. The script creates the minimal configuration file to get you started. The configuration file may be edited later.

The configuration script runs automatically when installing from the tar.gz file. It asks several questions. The default answers are usually adequate, and can be reconfigured later if necessary.

Welcome to the AllegroGraph configuration program.  This script will  
help you establish a baseline AllegroGraph configuration.  
 
You will be prompted for a few settings.  In most cases, you can hit return  
to accept the default value.  
 
Location of configuration file to create:  
[/home/joe/tmp/ag4.14/lib/agraph.cfg]:  
Directory to store data and settings:  
[/home/joe/tmp/ag4.14/data]:  
Directory to store log files:  
[/home/joe/tmp/ag4.14/log]:  
Location of file to write server process id:  
[/home/joe/tmp/ag4.14/data/agraph.pid]:  
 

If you are installing as root (which is not necessary), you will be asked for a non-root user account for AllegroGraph to run under. (It would be a security risk to let AllegroGraph run as root.) This account defaults to "agraph" and is designated in agraph.cfg as "RunAs agraph". The "agraph" account has no password and is used only by AllegroGraph server. The system will determine you are logged in as root, and ask the following questions. You can usually take the default value:

User to run as:  
[agraph]:  
 
User 'agraph' doesn't exist on this system.  
Create agraph user:  
[y]: 

The configuration script will then ask for a user name and password to be your AllegroGraph superuser. This account is specific to AllegroGraph, and is not your operating system login account. The example below shows the user "test" with password "xyzzy". This is the account expected by the tutorial examples, so it is convenient to create that account now. User account management is easy to perform through the AllegroGraph WebView interface, so this initial user/password combination is easily changed later.

Now you must set up an initial user account for AllegroGraph.  This  
account will have "super user" privileges within AllegroGraph.  
 
SuperUser account name:  
[super]: test  
SuperUser account password:  
xyzzy 

Finally, you are asked for the instance timeout seconds. This is the length of time (in seconds) a database will stay open without being accessed. The default is 604800, which is 60 x 60 x 24 x 7, that is one week in seconds. In contrast, an hour is 3600.

Instance timeout seconds:  
[604800]: 

The value will be written into the agraph.cfg file like InstanceTimeout 604800. If you remove that line from the file, the timeout interval will be one hour (3600 seconds).

The script writes out the agraph.cfg file in the <yourInstallDirectory>/lib directory (the standard location for the TAR.GZ installation). Make a note of where your agraph.cfg file resides.

/home/joe/tmp/ag4.14/lib/agraph.cfg has been created.   
 
If desired, you may modify the configuration.  

The script concludes with a display of start and stop commands customized to your installation. Make a note of the start and stop commands for your installation.

You can start AllegroGraph by running:  
/home/joe/tmp/ag4.14/bin/agraph-control --config /home/joe/tmp/ag4.14/lib/agraph.cfg start  
 
You can stop AllegroGraph by running:  
/home/joe/tmp/ag4.14/bin/agraph-control --config /home/joe/tmp/ag4.14/lib/agraph.cfg stop  

Unless you are using the free version (which allows up to 5 million triples), you must add a license key to the configuration file. See below for more information. If you are using the free version, go to Starting the Server below.

Installing the License Key

When you download the free version of AllegroGraph, no License Key is provided or required. The free version lets you load a maximum of 5,000,000 triples, and has no expiration date.

Franz issues a special License Key to users of the paid version of AllegroGraph. The License Key defines a maximum number of triples and possibly an expiration date for the license, and is issued to an individual or client company. Your License Key will be issued by the Franz sales department, and will arrive in your email. A typical license key looks like this (non-working) example:

Licensee Customer Name  
LicenseLimit 1000000  
LicenseExpires 2010-06-16  
<LicenseCode>  
829P93952R9E8P7X4E8W565Z7A2A4Z592E4W5E49693P9K325X296S3R945A789D4  
S843K9455787K3R3A2K6Z6N8K8V6V658A3V3D293H8X5S7X3V9A4R6533979V246V  
6J8Y3T928MA69B928R7E4D8C7C4T6X9F28626Z448E986R6E9B6F4S9J9U6H8A7Q8  
S324C67783Y89495Q8W867B7S349Q6C6T5W42A59P8Q5M967R5B554C2K3Q424T  
</LicenseCode> 

The "License Key" consists of all four fields: the Licensee, LicenseLimit, LicenseExpires and LicenseCode. They must all be present in order for the Key to work. The first three values reflect the terms of your contract with Franz. The LicenseCode verifies the other values.

To install your License Key, copy the entire block of text (Licensee, LicenseLimit, LicenseExpires, and LicenseCode) and paste it into your agraph.cfg file. (In the tar.gz installation example above, the agraph.cfg file was located at /home/joe/tmp/ag4.14/lib/agraph.cfg.) The License Key can go into any part of the file as long as it is outside of a catalog definition. Save the file. The license will be effective when you start or restart the AllegroGraph server.

If there is any problem with your License Key, AllegroGraph will revert to the behavior of the free version. It will return an error when you first exceed 5 million triples and every time thereafter. Contact sales@franz.com if you have problems with your license key.

Starting the Server

The server is installed in the directory specified to the install command (see above). In the example above it was /home/joe/tmp/ag4.14/ but you likely chose a different directory. We will call that directory [ag-dir] in the examples below.

As noted above, when you complete the installation, a message is printed giving the commands to start and stop the AllegroGraph server. The command is agraph-control in the bin/ subdirectory of the [ag-dir] directory. Start the server with:

[ag-dir]/bin/agraph-control --config [ag-dir]/lib/agraph.cfg start 

A message similar to

AllegroGraph Server  
Copyright (c) 2005-2014 Franz Inc.  All Rights Reserved.  
AllegroGraph contains patented technology.  
No patches loaded.  
current-time: Tuesday, April 15, 2014 09:36:01 AM  
default-external-format: #<external-format :utf8 [(crlf-base-ef :utf8)]>  
 
Daemonizing...  
Server started normally: Running with free license of 5,000,000 triples; no-expiration. 

will be printed (if you installed a license key, the license message will be different). The AllegroGraph server is now running.

Connecting to the Server

There are a number of potential clients that can connect to the AllegroGraph server, either from the same machine as that running the server or from a different machine. The various clients and how they are downloaded (when necessary) and how they are installed and started are described in Server Installation, which has links to other documents about clients.

In this document, we describe connecting to the AllegroGraph server with the AGWebView client. This client uses a web browser and requires no (further) download or installation. The only information you need is the name of the machine running the server (which can be the same machine as the one running your browser) and the port number that the server is listening on. The default port number is 10035, and if you installed as described above, that will be the port number. If you have any difficulty with that port number (such as, for example, it is being used by another program), edit the config file ([path]/ag4.14/lib/agraph.cfg) modifying the line

Port 10035 

to specify a different, available port. If you do change that line, replace 10035 with the new number in the examples below in this document.

Starting AGWebView and Creating a Database

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

http://localhost:10035 

localhost refers to the machine which is running the browser (so both the server and the browser are running on the same machine).

Logging in

If there is an AllegroGraph server listening on that port, AGWebView will respond immediately with a login form (in this example, the server is running on host foray):

Login Form

For this simple tutorial, log in using the name and password of the AllegroGraph superuser you created during server installation. If you accepted the defaults when you installed AllegroGraph above, the user is "test" with password "xyzzy" (as shown in the illustration though the password is hidden).

Once logged in you can create additional user accounts with different types of access and privileges. See Managing Users for details.

Creating a Database

After you have successfully logged in, the browser will look like:

Initial Display

There are no repositories as we have just opened AllegroGraph for the first time (if data had been stored, we would see the one or more repositories holding the data).

Data are organized into repositories which are organized into catalogs. There is one initial catalog: the root catalog. We are going to create a respository named kennedy and populate it with data available in an example file included with the distribution. In the Create new repository field under Repositories, enter kennedy and click the Create button. The respository list will show the kennedy respository:

Kennedy repository added

Click on kennedy in the Repositories list and the screen changes to:

Kennedy repository

Displayed is information about the repository (such as there is no data -- 0 statements -- as yet) and various commands for managing the data. We want to load data from a file (the file doc/python-tutorial/python-kennedy.ntriples). AllegroGraph supports various file formats for data (see agload). The ntriples format has one triple (subject, predicate, object) per line, with each line ending in a period. Here are the first few lines:

<http://www.franz.com/simple#person1> <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <http://www.franz.com/simple#person> .  
<http://www.franz.com/simple#person1> <http://www.franz.com/simple#first-name> "Joseph" .  
<http://www.franz.com/simple#person1> <http://www.franz.com/simple#middle-initial> "Patrick" .  
<http://www.franz.com/simple#person1> <http://www.franz.com/simple#last-name> "Kennedy" .  
<http://www.franz.com/simple#person1> <http://www.franz.com/simple#suffix> "none" .  
<http://www.franz.com/simple#person1> <http://www.franz.com/simple#alma-mater> <http://www.franz.com/simple#Harvard> . 

We load this data by clicking on Load and Delete Data | Import RDF: | from an uploaded file. A dialog pane appears near the top of the WebView page allowing you to specify the file or files to be loaded.

Loading Kennedy data

Click on the Choose Files button and specify the file in the doc/python-tutorial/ subdirectory of the [ag-dir] named python-kennedy.ntriples. Then click the Ok button on the lower right of the dialog pane. (If you are running the browser on a different machine from the one that contains the [ag-dir], you will, of course, have to get to that machine in the file selection dialog or make the file accessible in some other fashion.)

Once the triples in the file are loaded, we see Repository kennedy now has 1,214 statements (triples).

Kennedy data loaded

Now we have created a repository and loaded data. We should now back it up. Choose Back-up this store from the Store Control options (circled in red in the illustration). The dialog pane shown at the top of the screen appears. Enter the path and filename (an absolute directory pathname leaves no ambiguity about where the file will be put; the file will be saved to the server machine) in the text box and click Ok.

Backing-up a database

Other operations on the repository

As the illustration shows, there are many commands you can invoke to manipulate the database and the data it contains. These are described in the Respository Overview Page section of AGWebView.

Queries

Once data is loaded, you want to query the database. The kennedy database contains public data on relationships among and characteristics of individuals in the family of Joseph Kennedy, father of US President John F. Kennedy. Queries might include the following:

Queries can be formulated using SPARQL, a query language adapted to RDF databases. Let us take a very simple query: the people described in the kennedy database are labeled <http://www.franz.com/simple#personN> and <http://www.franz.com/simple#person1> is Joseph Patrick Kennedy, the patriarch of the family. You can see this by examining the first lines of the data file.

So, what are the predicates and objects of all triples whose subject is <http://www.franz.com/simple#person1>? The SPARQL query

select ?p ?o WHERE {<http://www.franz.com/simple#person1> ?p ?o} 

will tell, as shown in the following illustration (we typed the query into the Edit Query box and clicked the Execute button; note we have broken the illustration into two images to save space).

image-agqs-sparql-1

Simple SPARQL query

Who are the males among Joseph Kennedy and his descendents that went to Harvard University and what are their respective professions? Here is the SPARQL query:

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  

And the answer is 13, as shown by the displayed query (we also display their professions):

image-agqs-sparql-harvard

Attended Harvard

Who is the oldest living person among Joseph Kennedy and his descendents (at the time the databse was created, several years ago)? Here is the SPARQL query. Note the use of an OPTIONAL clause. That produces result bindings for persons with a birth-year whether or not they also have a death-year. The FILTER clause then filters out any results which do have a death-year.

PREFIX o: <http://www.franz.com/simple#>  
  SELECT ?person ?birthYear {  
    ?person o:birth-year ?birthYear  
    OPTIONAL {  
      ?person o:death-year ?deathYear  
    }  
    FILTER( !bound( ?deathYear ) )  
  } order by ?birthYear  
  LIMIT 1 

We run the query and find the result is person10:

Oldest survivor

And who is person10? We could use the same query as we did above for person1:

select ?p ?o WHERE {<http://www.franz.com/simple#person10> ?p ?o} 

and get all the triples where person10 is the subject but we are only interested in the names (first, middle and last), so we restrict the query to that (the middle name is shown in the misnamed middle-initial field):

PREFIX o: <http://www.franz.com/simple#>  
  SELECT ?fn ?mn ?ln  
     WHERE {o:person10  
            o:first-name ?fn ;  
            o:middle-initial ?mn ;  
            o:last-name ?ln .} 

person10

person10 is Robert Sargent Shriver, commonly known as Sargent Shriver, first director of the Peace Corps.

This has been a brief introduction to SPARQL but it does show its flexibility and power. There are more examples in the SPARQL Tutorial.

Other documentation

If you have followed the steps in this document, you should have AllegroGraph installed, at least one database loaded, and should have asked and received answers about that database. The naviagtion bar to the right at the top of this (and most other) documents has links to the rest of the documentation. In particular note: