AllegroGraph Quick Start | AllegroGraph 9.0.1
Author: Franz Incorporated

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

# AllegroGraph 9.0.1 Quick Start

- 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
- Software Download
- WSL: downloading the installation file
- Hardware Considerations
  - Minimal Requirements
  - CPU Requirements
  - Memory Allocation
  - Storage Considerations
  - Scaling Guidelines
- Server Installation
  - Installation from the tar.gz File
  - Running the Configuration Script
  - Installing the License Key
- Starting the Server
  - The AllegroGraph is already running failure
- Connecting to the Server
- Using AGWebView
  - Logging in
  - Passwords and tokens
  - The tutorial directory
- Creating a repo
- Loading data
- The kennedy.ntriples file
- Backing up
  - Other operations on the repository
- Queries
- More queries
- Gruff
- Other documentation

Documentation Index

## 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 WebView doc).

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.

## Hardware Considerations

AllegroGraph performs optimally with hardware tailored to your specific workload and data size. Here are the key considerations:

### Minimal Requirements

- CPU: At least 2 CPU cores (multi-core recommended)
- Memory: Minimum 16GB RAM (32GB+ recommended for production)
- Disk Space: 10GB minimum for installation and initial data

### CPU Requirements

AllegroGraph's architecture utilizes multiple components:

- Frontend server: handles incoming connections on the main port
- Multiple backend servers: processes database operations within the AllegroGraph instance
- Session server: dedicated to individual user operations
- Helper processes: optimizer, checkpointer and others

For optimal performance, allocate at least one CPU core per concurrent active connection. Production deployments with multiple concurrent users benefit significantly from additional cores.

### Memory Allocation

AllegroGraph extensively uses shared memory and memory-mapped files, particularly for critical operations. It relies on the operating system to keep these mapped pages in memory, trusting the OS to manage them efficiently. A dedicated section on the Performance Tuning page addresses potential performance issues related to OS configuration.

Memory requirements scale with repository size and the number of unique repositories accessed concurrently. Multiple connections to the same repository share memory efficiently, while connections to different repositories each require their own memory allocation. As a guideline, each connection to a unique repository consumes shared memory as follows:

Repository Size | Approximate Shared Memory Per Unique Repository
--- | ---
≤100M triples | ~0.5GB
~300M triples | ~0.8GB
~600M triples | ~1.2GB
>1B triples | ~3GB+

For example:

- Opening 100 connections to a single 100M triple repository will use ~0.5GB shared memory total
- Opening 1 connection each to 100 different 100M triple repositories would require ~50GB shared memory

You can set expected store size through:

- Repository creation options:
  - the slider in WebView on creating a store.
  - `expectedSize` and `stringTableSize` options in REST API.
  - `expected-store-size`, `string-table-size` command line options in `agtool`.
- The global `ExpectedStoreSize` and `StringTableSize` server directives can be specified in the `agraph.cfg` file. These directives allow you to set default sizes for newly created repositories. Additionally, you can place these directives within `<catalog name>` and `</catalog>` tags to apply them specifically to newly created repositories within that catalog. Catalog-specific values will take precedence over global values for these settings.

Unix allows up to half of the physical memory to be used as shared memory and allows you to monitor shared memory usage via `df /dev/shm`.

### Storage Considerations

For optimal performance:

- SSD Storage: Strongly recommended, particularly for production systems.
- Temporary Directory: Ensure adequate space (minimum 10GB) on fast storage. The temporary directory location is controlled by the `TempDir` server directive (defaults to system temp directory).
- Swap Space: Configure a moderate swap space as a safety net, although the system performs best when swapping is minimal.

### Scaling Guidelines

For larger deployments:

- High-transaction workloads: Prioritize faster CPUs and additional cores
- Large triple stores: Prioritize memory capacity and SSD storage
- Many concurrent users: Increase both CPU cores and memory

For users looking to work with billions of RDF triples we encourage you to purchase as much hardware as your budget will permit. We can offer purchase references (info@franz.com) for hardware systems containing multiple CPU cores with 96GB RAM for ~$7,000 or less.

An ideal system for 2-3 billion triples would include 8 CPU cores, 96 GB of RAM, and solid state drives (SSDs). This type of system will optimize query performance as well providing rapid ingest speeds.

Your results will vary based on factors associated with your application, such as the number and size of unique strings found in the triples, etc.

For more details on performance tuning, please see Performance Tuning page or contact us if you have any questions related to hardware selection - info@franz.com.

## 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-9.0.1-linuxamd64.64.tar.gz

This creates the "agraph-9.0.1" subdirectory within the current working directory. The installation script is in that directory. The installation script is install-agraph.
As an argument to the script, you must provide the path to a writable directory (which will be created if necessary) where you want to install AllegroGraph. In this example, we assume */home/joe/tmp/ag 14}* is the desired location for the AllegroGraph server and associated files. Replace that location with the location you wish to use.

    $ agraph-9.0.1/install-agraph /home/joe/tmp/ag9.0.1

    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/ag9.0.1/lib/agraph.cfg]:
    Directory to store data and settings:
    [/home/joe/tmp/ag9.0.1/data]:
    Directory to store log files:
    [/home/joe/tmp/ag9.0.1/log]:
    Location of file to write server process id:
    [/home/joe/tmp/ag9.0.1/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 WebView, 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/ag9.0.1/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/ag9.0.1/bin/agraph-control --config /home/joe/tmp/ag9.0.1/lib/agraph.cfg start

    You can stop AllegroGraph by running:
    /home/joe/tmp/ag9.0.1/bin/agraph-control --config /home/joe/tmp/ag9.0.1/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/ag9.0.1/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 sales@franz.com 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/ag9.0.1/ 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.

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]/ag9.0.1/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 WebView: The USER menu, 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 WebView document for more information.

Note in particular the Query choice in the Repository 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 link `Untitled-1` at the top of the Query pane. It is the query just posed and you can recover it (later, it is visible now) by clicking on the link. It is not saved, but you can save it 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 specified limit (of 1) and a general limit (of 1000). This is not important because that is what we want. The remainder of the display (which we cropped) is the other query information.

You display the Query plan by hovering 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):

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

AllegroGraph supports a Natural Language to SPARQL Query (NLQ to SPARQL) tool, described in this document. The examples in that document use the kennedy database. Use that tool to create and try out new queries, usable even if you are a relative SPARQL novice.

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