Upgrading from AllegroGraph 3.2 to 3.3
Triple-stores created under AllegroGraph 3.2 will work with no changes in AllegroGraph 3.3.
Aside from enhancements and new features outlined in the Change History, AllegroGraph 3.2 programs should work without changes in 3.3.
Upgrading from AllegroGraph 2 to 3
There are two main issues in upgrading AllegoGraph.
- Upgrading your data
- Upgrading your code
We cover each of these issues below in the sections below.
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 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.
The command line tool
convertdb is located in root 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
source-db-directory is the directory where the 2.x triple-store that you wish to convert is located.
copy-db-directory is the directory where
convertdb will place the updated triple-store The
copy-db-directory must not exist before you run
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.3 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.
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.
 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.)
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 Server Edition
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 in the Server Installation document.
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:
- RDFSerializer, RDFManifestSerializer, etc.
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.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()
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-formatargument to continue to load non-7-bit ASCII files directly.
The deprecated accessor
property-mappinghas 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-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:
The optimized UPI hash-tables that AllegroGraph uses internally have been exported. See upi-hash-tables in the reference guide for more details.
*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.
:use-reasonerkeyword 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.