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, see the new WebView doc) or the traditional AGWebView doc). The examples in this document use the New WebView.
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. You can also run AllegroGraph inside Windows Subsystem for Linux (WSL).
We assume in the rest of this document that the server installation file has been downloaded.
WSL: downloading the installation file
Because the directory structure of the Windows Subsystem for Linux (WSL) Unix can be hidden on Windows, it is easier to download the necessary files with curl or wget run in a UNIX shell. See the Server download section in the Server Installation document for information on getting the download link suitable as an argument to curl or wget.
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-8.1.0-linuxamd64.64.tar.gz This creates the "agraph-8.1.0" 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-8.1.0/install-agraph /home/joe/tmp/ag8.1.0
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/ag8.1.0/lib/agraph.cfg]:
Directory to store data and settings:
[/home/joe/tmp/ag8.1.0/data]:
Directory to store log files:
[/home/joe/tmp/ag8.1.0/log]:
Location of file to write server process id:
[/home/joe/tmp/ag8.1.0/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 traditional AllegroGraph WebView or the New 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 3600, which is 60 x 60 , that is one hour in seconds.
Instance timeout seconds:
[3600]: The value will be written into the agraph.cfg file like InstanceTimeout 3600. If you remove that line from the file, the timeout interval will be one hour (3600 seconds) as well.
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/ag8.1.0/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/ag8.1.0/bin/agraph-control --config /home/joe/tmp/ag8.1.0/lib/agraph.cfg start
You can stop AllegroGraph by running:
/home/joe/tmp/ag8.1.0/bin/agraph-control --config /home/joe/tmp/ag8.1.0/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/ag8.1.0/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 print an error message and the server will fail to start. Contact [email protected] if you have problems with your license key. Meanwhile, you can always run the free (five million triple limit) version by removing or commenting out the license portion of the configuration file.
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/ag8.1.0/ 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) Franz Inc. All Rights Reserved.
AllegroGraph contains patented technology.
Current time: [day, date, and time]
Daemonizing...
Server started normally: Running with free license of 5,000,000 triples; no-expiration.
Access AGWebView at http://127.0.0.1:10035 will be printed (if you installed a license key, the license message will be different). The AllegroGraph server is now running.
The AllegroGraph is already running failure
You can run multiple servers on a single machine, but they must use different ports and they must not use the same directory specified by the SettingsDirectory configuration parameter. See Server Configuration and Control for information on specifying parameters. If that directory is in use by another server process, when you try the start a server that will use that same directory, starting the server will fail with a message similar to (with values for PID and PORT):
Daemonizing...
Starting server failed:
There appears to already be an AllegroGraph server running (pid PID).
If it is your intention to run another AllegroGraph server
simultaneously,
please make a separate configuration file which has different values
for the following parameters:
Port PORT
SettingsDirectory /disk1/allegrograph/settings/ You can terminate that server (after ensuring that it is what you want to do and that you are not inconveniencing another user) with
agraph-control --config [path to agraph.cfg file of the running server] stop If you cannot determine where the appropriate agraph.cfg file is or if that command fails for some reason, you can (again, having ensured you are not interfering with other users) do
kill PID If the desired port is in use (presumably by a non-AllegroGraph process but perhaps by another AllegroGraph server not using the directory mentioned above), the server will not start and a message like the following will be printed:
Local socket address already in use" (errno 98) occurred while
creating a passive socket on any interface port PORT. To use the desired socket you must find and terminate the process using it. You can also modify the agraph.cfg file to specify another, unused port. See the Port parameter in Server Configuration and Control.
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 New WebView client. You may also use the traditional AGWebView client (Click on Traditional WebView on the menu to the left once New WebView has come up). Note the SPARQL Tutorial using AGWebView document uses Traditional WebView if you wish to see a demonstration of that tool.
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]/ag8.1.0/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.
Using AGWebView
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://mymachine.mynetwork.com:10035 If the browser is on the same machine as the server, this should work:
http://localhost:10035 localhost is interpreted as the machine which is running the browser.
Logging in
If there is an AllegroGraph server listening on that port, AGWebView will respond immediately with a login form:
For this simple tutorial, log in using the name and password of the AllegroGraph superuser you created during server installation. (The default username is super but we use test in most of our examples. There is no default password.) 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.
Passwords and tokens
AllegroGraph supports logging in using tokens as well as passwords. Tokens can be time limited and can expire as well as being deleted. They are useful, for example, when you want to provide temporary access to an account without revealing its permanent password. A token can be created with agtool tokens and with New WebView, among other ways. Once created and while in effect, tokens can be used interchangeably with passwords. Note that the complete token (which is many characters long) is only revealed at creation time and is never later accessible (from within AllegroGraph) so note it when created.
The tutorial directory
The tutorial directory is located in this subdirectory of the Franzinc allegrograph-examples github site. This directory contains various example files used in some of the examples found in the documention, including the kennedy.ntriples file (used below in this document) and the PhoneCalls.ttl.gz file used in the n-dimensional geospatial example in N-dimensional Geospatial Usage Guide and Example. Download files from that directory onto your local filesystem before loading them into AllegroGraph. Download kennedy.ntriples now.
Creating a repo
Once you have logged in, you will see the Catalog page displaying the contents of the root catalog (which has no repos yet):
Click on CREATE REPOSITORY (indicated by the red arrow) and enter kennedy in the pop-up dialog. Click Create and Open and you will see:
Note the Repository menu on the left has opened and the displayed page is the Query page.
Loading data
We assume you have copied the kennedy.ntriples file onto a local disk. Click on Add, delete, and import data in the Repository menu on the left and choose the Import RDF from an uploaded file action. You then will see:
Drag and drop kennedy.ntriples into the selection box or click and choose it from the file dialog.
When it is loaded you should see 1214 triples in the repo.
The kennedy.ntriples file
AllegroGraph supports various file formats for data (see agtool load). 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> . Backing up
Now that we have created a repository and loaded data, we should back it up. (This is not really necessary as the file is readily available in case anything happens but when you start working with your own data, backing up is strongly advised.)
Click on Repository control in the Repository menu. This submenu has many choices. Some (like Archive) are displayed immediately, others can be searched for (try attributes in the search box for example). Click on Archive and you will see:
You can either save a file locally or on the server machine (those two locations might be the same). You can also choose the format of the saved file.
Other operations on the repository
As the illustration shows, the Repository menu has several commands and the Repository control submenu has many more. See the New WebView document for more information.
Note in particular the Query choice in the Repositoy menu and the Gruff choice further down. We will say more about Gruff below.
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:
- Who among Joseph and his descendents are males and went to Harvard University and what are their professions?
- Who is the oldest living descendent (at least when the database was created)?
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. Choose Query from the Repository menu, click the + in the upper right, and paste the query in. Then click Execute. Here are the results:
Now, 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):
Note the two links Untitled-1 and Untitled-2 at the top of the Query pane. Those are the queries already posed and you can recover them by clicking on the links. They are not saved, but you can save then by clicking on the disk icon to their right and provided a name when asked. Unsaved queries may disappear when you do other things. Saved queries will survive even restarting the AllegroGraph server.
The menu on the right includes saved queries and various standard queries, like the query to view all triples. Other submenus on the right display various query options.
More queries
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
Since we are only interested in the oldest, we add a LIMIT 1 clause to the SPARQL query. We run the query and find the result is person10:
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 .
} Run this and you will see person10 is Robert Sargent Shriver, commonly known as Sargent Shriver, first director of the Peace Corps. (Mr. Shriver actually died in 2011, but that was after the database was constructed.)
Note the exclamation point in the triangle next Query information. Warnings about the query are displayed under Query information if there are any. If we look at Query information we see:
You are warned that the query has a cross product (which means a join with no common variables, which can take a long time and can produce voluminous results). The remainder of the display (which we cropped) is the other query information.
Though it is not obvious, technically it is true that the query has a cross product, as the plan for the query. You display the Query plan by howevering the mouse over the Execute button and clicking the Plan item that pops up (there is also a Log button which causes the query to be logged):
Indeed there are no shared variables. This is in fact not serious (in this case) because both the LHS or the RHS have only one row and in that case there is not likely to be a problem. But is is useful to understand that warnings can appear and they can be seen, if there are any, by clicking Plan prior to execution.
This has been a brief introduction to SPARQL but it does show its flexibility and power. There are more examples in the SPARQL Tutorial.
Gruff
There is a Gruff choice on the left menu.
Gruff is a very powerful data visualization tool. See Gruff in AllegroGraph for more information. Here we have opened Gruff (it will automatically open to the current repo if there is one) and selected Display | Display Some Random Triples. You can see Joseph Kennedy near the bottom.
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. See the documentation index to learn more about AllegroGraph.