Upgrading from AllegroGraph 2 to 3

There are two main issues in upgrading AllegoGraph.

1. Upgrading your data
2. Upgrading your code

We cover each of these issues below in the sections below.

Upgrading Triple-stores

The data format for triples, indices and strings in AllegroGraph 2.2 and AllegroGraph 3.0 is similar but not the same. The main differences are:

• AllegroGraph 3 keeps track of the metadata associated with a triple-store using a different format.

• AllegroGraph 3.0 includes information about the originating triple-store in blank node UPIs, the default-graph-upi and in the portion of each triple used to store the triple-id.

• AllegroGraph 3.0 has extended the string dictionary format to accommodate triple-stores with up to 4-GB of string data (up from 2-GB in AllegroGraph 2.2)

In order to include this additional information and make a triple-store fully usable in 3.0, a conversion must be made to upgrade 2.x triple-stores into the new format. This conversion can be done from the command-line (recommended) or directly within the Lisp application.

Command-line tool

The command line tool convertdb is located in bin directory of your distribution. It can be used to upgrade 2.x triple-stores into 3.0's new format. convertdb takes two command line arguments:

$ convertdb source-db-directory copy-db-directory 

The source-db-directory is the directory where the 2.x triple-store that you wish to convert is located.

The copy-db-directory is the directory where convertdb will place the updated triple-store The copy-db-directory must not exist before you run convertdb.

If you execute convertdb with the wrong number of arguments, it will display brief usage information:

[misterx:] gwking% convertdb  
too few arguments  
Usage: source-db-directory copy-db-directory 

If you provide a valid set of arguments, then it will make the conversion and provide progress information as it goes.

[misterx:] gwking% convertdb home/agraph225-small/ small-30  
converting home/agraph225-small/ to version 3.0;  
  backup is home/small-30  
  Copying string  
  Updating triples.data....  
  Updating index: index-gposi.1.4.idx....  
  Updating index: index-posgi.1.4.idx.... 

When complete, the upgraded AllegroGraph 3.0 triple-store will be in copy-db-directory. Once you are sure that all is well, you can remove the original 2.x triple-store.

Lisp tool

While we recommend using the command line convertdb tool to upgrade from one version to the next, Lisp users have the option of running the conversion directly in the Lisp session.

If you open a 2.x triple-store in AllegroGraph 3.0, you will get a continuable error:

triple-store-user(2): (open-triple-store "agraph225-store")  
Error: The triple-store /home/gwking/agraph225/  
       must be upgraded before it can be used with this version of  
       AllegroGraph. The upgrade requires examining every triple and  
       every index in the store and can take a long time if the store  
       is large. You can update triple-stores outside of AllegroGraph  
       using the command line tool convertdb. See the reference-guide  
       for more details.  
  [condition type: must-update-triple-store-to-level-4-error]  
 
  Restarts:  
0: [upgrade-now] Upgrade the triple-store now. This will:  
 
   1. leave the data in /home/gwking/agraph225-store/ as is;  
   2. create an upgraded copy of the triple-store in /home/gwking/agraph225-store-0/; and  
   3. open the new copy in agraph225-store-0  
 
1: [abort-request] Abort handling SLIME request.  
2: [abort] Abort entirely from this (lisp) process. 

If we select the upgrade restart, AllegroGraph will upgrade the triple-store by creating a new directory (which will be a sibling of the current directory) and copying / updating the 2.x files into it.

[1] triple-store-user(3): :cont 0  
  Updating triples.data....  
  Updating index: index-gposi.1.4.idx....  
  Updating index: index-posgi.1.4.idx....  
#<db.agraph::triple-db  
  /home/gwking/agraph225-store-0, open  
  @ #x1133bf02> 

As you can see from the return value, the new triple-store in agraph225-store-0 has been opened. The original 2.x store in agraph225-store remains unchanged.

(Notice that this method is not as flexible as using the command line tool since you are not able to specify the location of the new upgraded triple-store.)

Important!

It is not currently possible to re-open a converted AllegroGraph triple-store in AllegroGraph 2.2.5. We recommend that you make a backup of your original triple-store while you work with the new one. Please contact Franz if you need additional support working withe the new triple-store format and the conversion tools.

Upgrading your code

Notes on the Java Edition server

In AllegroGraph 2.x, the server executable took many command-line arguments related to AllegroGraph options. In AllegroGraph 3.x these options have been moved to a configuration file, named agraph.cfg, which lives in the AllegroGraph installation directory. The details are here.

Also note that on Windows, AllegroGraph now runs as a Windows service.

Notes on the Java API

There are many new classes to support geospatial, temporal and social networking applications and to provide improved support for the options and parameters of the AllegroGraph database engine. These classes include:

• GeoExtension
• GeoSpatialSubtype
• SNAExtension
• DefaultGraph
• RDFSerializer, RDFManifestSerializer, etc.
• NamespaceRegistry

There are also new methods in many of the existing classes. There include (but are not limited to):

• AllegroGraph.addEncodedLiteral( string, "date-time" )
• AllegroGraph.selectValues(boolean, boolean, ...)
• AllegroGraph.selectStatements(boolean, boolean, ...) --
• AllegroGraph.getSNAExtension()
• AllegroGraph.getGeoExtension()
• AllegroGraph.closeTripleStore(boolean) to request true closing of store if only one ref (this is the default)
• AllegroGraph.getSyncEveryTime() and AllegroGraph.setSyncEveryTime() to control synchronization in AllegroGraph.addStatement() and AllegroGraph.addStatements().

• AllegroGraph.setAttribute() allows Java application to control all triple store access parameters.

• AllegroGraphConnection.federate(), AllegroGraphConnection.getStores(), AllegroGraphConnection.findStore() to create and access federated triple stores.

• added AllegroGraphConnection.deleteStore()

See the change-history and the Javadocs for more details.

Notes on Lisp API

Aside from changes required to support new features, most of AllegroGraph's interface remains the same in 3.0 as it was in 2.2.5. There are, however, several items to note when updating your code. We've tried to gather these together here to make things as easy as possible for you. If something surprises you, please contact Franz immediately so that we can assist you.

• load-ntriples is much stricter regarding the N-Triples specification both in its rejection (by default) of non-7-bit ASCII and in its internal validation. You can use the new :external-format argument to continue to load non-7-bit ASCII files directly.

• The deprecated accessor property-mapping has been removed, use predicate-mapping instead.

• The q functor has been renamed q- and the qs functor has been renamed q. q queries the current triple-store (i.e., *db*) whereas q- queries the current triple-store's inner-triple-store. If you are working with a non-encapsulated triple-store, then q and q- will behave the same. Note that since only non-encapsulated stores support range-queries (at this time), you must use the q- functor to make range-queries in Prolog.

• There are many new functions and macros that may make your life easier. These include:

  • subject-upi=, predicate-upi=, etc
  • subject-part=, predicate-part=, etc.
  • upi-typep
  • with-temp-upi
  • with-temp-triple

• The optimized UPI hash-tables that AllegroGraph uses internally have been exported. See upi-hash-tables in the reference guide for more details.

• Both load-ntriples* and load-rdf/xml* have been removed in favor of letting load-ntriples and load-rdf/xml accept lists of sources

• *use-reasoner* - reasoning functions very differently in AllegroGraph 3.0 and this variable no longer makes sense. See the reasoner tutorial for a good overview of the changes.

• Similarly, the :use-reasoner keyword argument of get-triples-list has been deprecated.

• With the advent of the remote-triple-store class, it is no longer necessary to use the Lisp client commands. Because of this, the Lisp client command set has been removed. Of course, the commands used to connect to remote AllegroGraph servers has been retained. Details can be found in the Lisp client guide.

Please contact Franz if you have additional questions or come across items that we may have missed.