AllegroGraph Code Conversion Notes

Converting AllegroGraph 3.x to AllegroGraph 4.7

The transition from AllegroGraph 3.x to 4.x involved many small changes to the AllegroGraph APIs, and several larger ones. There was also a change in database format that requires a conversion step. This document collects these changes into one location as a central reference. The document Database Upgrade describes how to update from a 4.x version to the latest version.

In the Lisp API to AllegroGraph, 76% of the 3.x API is unchanged in 4.x. Approximately 17% of the 3.x API is now obsolete. About 7% of the API has changed to accept new parameters. Another 7% is completely new.
The Python API changed in multiple ways in 4.x, but is fundamentally similar to 3.x. Conversion from 3.x to 4.x is relatively easy. See the Python Tutorial for examples of the Python API in use.
The Java APIs to AllegroGraph 3.x (the base API, the Sesame API and the Jena API) were completely re-implemented in 4.x.
AllegroGraph 3.2 and 3.3 databases must be exported from 3.x and then imported into 4.x using two utility functions that are provided in the 4.x distribution.

Database Conversion

AllegroGraph 3.2 and 3.3 databases must be exported and then imported into AllegroGraph 4.7. This step is relatively painless using the ag3-export and ag4-import command-line utilities provided with 4.7. The utilities will be found in the AllegroGraph /bin/ subdirectory.

ag3-export: Exports settings and data from AGraph v3.2 and v3.3 databases. Specify database directory as argument. This will be opened read-only. The AllegroGraph 3.x server should not be running during this operation and no other writes should be done to the database, or the export may be inaccurate. Writes export text to stdout, so should be redirected to a file or directly to ag4-import.
ag4-import: Imports settings and data into AllegroGraph 4.7 database. Specify database name and optional --supersede. AllegroGraph 4.7 must be running on localhost. Import text is read from stdin, so should be redirected from a file or directly from ag3-export. Reification is not supported by default; see --reification, below. Blank nodes keep the same triple-store-id; see help for --new-blanks.

These utilities are designed to pipe the output of ag3-export directly to ag4-import. This reads the 3.x database (non-destructively) and writes the data directly into a 4.7 database. The expected use case is similar to:

$ ./ag3-export /tmp/ag32/repo-directory/ | ./ag4-import --supersede repository-name

Note that ag3-export needs a directory, but ag4-import needs a repository name.

The full documentation for these utilities follows.

ag3-export

Exports data and settings from AllegroGraph 3.2 and 3.3 repositories. Data is printed to stdout, so should be piped to a file or to ag4-import. Status messages are printed to stderr during export.

Warning: AG 3.x Server should not be running during export.

Usage: ./ag3-export db-dir [-hv] [--cache n] [--limit n]

db-dir: Export the 3.2 or 3.3 database to stdout. Database is opened :read-only.
--cache n: Clears string cache when it reaches size n, to reduce memory for both export and import (default 10000). 0 for no hashing.
--limit n: Only export n triples. Default: all.
-v, --verbose: Prints extra information while exporting.
-h, --help: Print this usage message.

Examples:

ag3-export /ag3/repo/ | ag4-import repo  
ag3-export /ag3/repo/ > repo.export  
ag4-import repo < repo.export

The following commands are for testing. They do not perform any export:

--info db-dir: Prints information about the database.
--load-nt db-dir file*: Creates db-dir (ag-3.3), loading ntriples files.
--load-rdf db-dir file*: Creates db-dir (ag-3.3), loading rdf/xml files.
--load-test db-dir: Creates db-dir (ag-3.3), loading a small test DB.
--supersede: For load commands: if repo already exists, end with error, or supersede (overwrite) before importing. Default: error.
--export-nt db-dir: Export db in ntriples format to stdout.

ag4-import

The following section is the ag3-import help message:

Imports data into AllegroGraph 4.7 database. Reads from stdin, the expected format is that printed by ag3-export. Status messages are printed to stderr during export.

AllegroGraph Server 4.7 must be running for import to work.

There is no recovery option for a failed import: run again with --supersede.

Usage: ./ag4-import [--port p] [--cat catalog] [--supersede] db-name

db-name

Creates a new repository with the given name. Reads from stdin (output of ag3-export).

-p, --port p

Port on localhost. Default reads contents of file agraph.port, which defaults to 10035.

--cat catalog

Catalog name. Optional.

--supersede

If repo already exists, end with error, or supersede (overwrite) before importing. Default: error.

--commit n

Commit after adding n triples. Default on :reset-cache, which is the --cache option of ag3-import, 10000.

--new-blanks

By default, blank nodes keep the triple-store-id from which they were exported. With this option, new blank-nodes are created, with the new triple-stored-id, and new node ids.

Warning: this requires a lot of memory, so may fail for large triple-stores.

--reification { error | weak | strong }

See the general description of reification in the AllegroGraph Reference Guide . Importing reification requires a lot of memory to import. (Use --errors to print error instead of failing.)

error: if reification is detected, issue an error. (Default)
weak: use a weak-hash-map to make best effort at supporting without overloading memory (issue error if this fails).
strong: use as much memory as possible to fully support reification.

-v, --verbose

Prints extra information while running.

-h, --help

Print this usage message.

Examples:

ag3-export /ag3/repo/ | ag4-import repo  
ag3-export /ag3/repo/ > repo.export  
ag4-import repo < repo.export  
ag3-export /ag3/lubm-1000/ 2> export.log | ag4-import lubm-1000 2&> import.log

The following commands are for testing. They do not perform any import:

--info db: Prints various info about the db.
--load-nt db file*: Creates new db, loading ntriples files.
--load-rdf db file*: Creates new db, loading rdf/xml files.
--load-test db: Creates new db, loading a small test DB.
--compare db1 db2: Compares 2 repos. Only compares 1 to 2, not the reverse.
--export-nt db: Export db in ntriples format to stdout.

Lisp API

This section summarizes changes to the AllegroGraph Lisp API. It is organized into four sections:

Lisp API elements that changed
Lisp API elements that are obsolete in 4.x
Lisp API elements that are new in 4.x
Lisp API elements that are unchanged

Lisp API elements that changed.

These are the Lisp API elements that changed, generally because a function now has fewer or different parameters than it did before. The following entries consist of four elements:

The AllegroGraph 4.x documentation entry for the function, copied here from the Lisp Reference page.
The 3.x lambda list for the function.
The 4.x lambda list for direct comparison with the 3.x list.
A brief comment pointing out what changed.

Once a geospatial subtype has been defined in the executing AllegroGraph image, the subtype object must be added to the set of subtypes known to a specific triple-store before triples containing that subtype can be added to the store.

3.x to 4.x code conversion notes:

3.x: (subtype &optional db external-index)  
4.x: (subtype &optional db)

external-index has been deprecated.

Remove all type mappings from the triple store db.

Remove type mappings added with datatype-mapping and predicate-mapping from the triple-store db. If db is not specified, it defaults to the value of *db*.

keep-automatic-type-mappings controls whether or not the automatically mapped types stay mapped or if they are also cleared. This defaults to true. Use automatically-mapped-types to see which types are mapped automatically.

3.x to 4.x code conversion notes:

3.x: (&optional db)  
4.x: (&key db keep-automatic-type-mappings)

keep-automatic-type-mappings set to t lets us avoid deleting AllegroGraph's automatic mappings when we delete user mappings.

Close all open triple-stores.

3.x to 4.x code conversion notes:

3.x: (&key wait)  
4.x: nil

wait used to be passed to close-triple-store which no longer has that parameter.

Close the triple-store db

:db - defaults to the value of *db* and specifies which triple-store to close. If the db being closed is eq to *db*, then *db* is set to nil.
:if-closed - controls the behavior when the db is either not open or nil. If if-closed is :error then an error will be signaled in this situation. If it is :ignore, then close-triple-store will just return without signaling an error. The argument defaults to :ignore.
:commit is true, then commit-triple-store will be called before the store is closed. This defaults to nil
:ensure-not-lingering is true, then call ensure-not-lingering after the store is closed.

3.x to 4.x code conversion notes:

3.x: (&key db if-closed verbose wait)  
4.x: (&key db if-closed commit)

verbose is deprecated. commit has replaced wait.

Iterate over cursor and collect a list of its rows.

The :transform keyword can be used to modify the rows as they are collected. Rows may be re-used so the caller must ensure that copies are made if necessary. As an example, consider the difference between

(collect-cursor (get-triples))

and

(collect-cursor (get-triples) :transform #'copy-triple)

Because the rows are re-used, the former will return a list of the same triple repeated as many times as there are triples in the store. The later will return a list of all of the triples in the store (which is probably what you intend!).

Note that the idiom above is so common that collect-triples is already defined.

3.x to 4.x code conversion notes:

3.x: (cursor &key transform finishp)  
4.x: (cursor &key transform)

finishp has been removed.

Create a new triple store with the given name.

create-triple-store takes numerous keyword arguments (not all of which appear in the argument list, which does have an &allow-other-keys). The allowed arguments vary depending on the class of triple-store being created. For example, a remote-triple-store usually requires a :user a :password, a :port, and a :server (ecsept for anonymous access if it is allowed) whereas an instance of triple-db does not. :user, :password, and :server can be specified with the individual arguments or combined in a :url argument. (See Lisp Quick Start for an example of creating a remote triple store and other examples creating and opening triple stores.)

The possible arguments include (but are not limited to):

:if-exists - controls what to do if the triple-store already exists. The default value, :supersede, will cause create-triple-store to attempt to delete the old triple store and create a new one; :error causes create-triple-store to signal an error. If the triple-store is opened by another connection, then :supersede will fail because the store cannot be deleted.
:catalog - the catalog to use in the server's configuration file. If left unspecified, the RootCatalog will be used.
:port - the port to use to find the AllegroGraph server. The default is 10035.
:user - the username to use when accessing the server (anonymous access, if supported, does not require a user value)
:password - the password to use when accessing the server (anonymous access, if supported, does not require a password)
:server - the server for a remote-triple-store. The default is "127.0.0.1" (which is the local machine).
:url - this argument can combine username, password, server, and port, for example http:newuser:xyzzy@//mymachine.franz.com:10422/ (user newuser, password xyzzy, server mymachine.franz.com, port 10422).
:exclude-standard-ontology-uris - if true, then AllegroGraph will not add the set of usual strings to the triple-store at creation time. Examples of these strings are: rdf:type, owl:sameAs, owl:inverseOf, rdfs:subPropertyOf, rdfs:subClassOf, rdfs:range, rdfs:domain, owl:transitiveProperty. If not specified, then this will default to nil.
:triple-store-class - the kind of triple-store to create. If left unspecified, then triple-db will be used.
:with-indices - a list of index flavors that this store will use. If left unspecified, the store will use the standard indices of :gospi, :gposi, :gspoi, :ospgi, :posgi, :spogi, and :i.
:https-verification - the value should be a list of keywords and value pairs, as follows: :method allows control over the SSL protocol handshake process; can be: :sslv23 (the default), :sslv2, :sslv3, :sslv3+, :tlsv1; :certificate names a file which contains one or more PEM-encoded certificates. :key should be a string or pathname naming a file containing the private RSA key corresponding the the public key in the certificate. The file must be in PEM format. :certificate-password, if specified, should be a string. :verify: nil means that no automatic verification will occur, :optional means that the server's certificate (if supplied) will be automatically verified during SSL handshake, :required means that the server's certificate will be automatically verified during SSL handshake. :maxdepth must be an integer (which defaults to 10) which indicates the maximum allowable depth of the certificate verification chain; :ca-file specifies the name of a file containing a series of trusted PEM-encoded Intermediate CA or Root CA certificates that will be used during peer certificate verification; :ca-directory specifies the name of a directory containing a series of trusted Intermediate CA or Root CA certificate files that will be used during peer certificate verification; :ciphers should be a string which specifies an OpenSSL cipher list. these values are passed as arguments to the function socket:make-ssl-client-stream. Here is an example:
```
(create-triple-store "v4.4-clienttest"  
	 :triple-store-class 'remote-triple-store  
	 :port 10398 :server "localhost"  
	 :scheme :https  
	 ;; new options:  
	 :https-verification  
	 '(;; Server must identify to the client and must  
	   ;; pass certificate verification. Other sensible  
	   ;; option is :optional; :nil suppresses  
	   ;; verification altogether and should never be used.  
	   :verify :required  
 
	   ;; The CA certificate used to sign the server's  
	   ;; certificate.  
	   :ca-file "/path/to/ca.cert"  
 
	   ;; The certificate and key file to authenticate  
	   ;; this client with.  
	   :certificate "/path/to/test.cert")) 
```

Create-triple-store returns a triple-store object and sets the value of the variable *db* to that object.

3.x to 4.x code conversion notes:

3.x: (name &rest args &key if-exists triple-store-class)  
4.x: (name &rest args &key if-exists catalog port user password triple-store-class)

port, user, and password have been added to accomodate remote triple stores.

Deletes the triple whose id is id.

The :db keyword argument specifies the triple store in which the triple should be deleted. It defaults to *db*.

Note delete-triple requires the i index in order to run efficiently. See add-index for details on how to manage a triple-store's indices.

3.x to 4.x code conversion notes:

3.x: (id &key db)  
4.x: (triple &key db)

triple is the new name for id.

Delete an existing triple store. Returns t if the deletion was successful and nil if it was not.

The db-or-name argument can be either a triple store instance or the name of a triple store. If it is an instance, then the triple store associated with the instance will be closed if it is open and then it will be deleted (assuming that it is not open by any other processes). If db-or-name is eq to *db*, then *db* will be set to nil once the triple-store is deleted.

The :if-does-not-exist keyword argument specifies what to do if the triple-store does not exist. The default value, :error, causes delete-triple-store to signal an error. The value :ignore will cause delete-triple-store to do nothing and return nil.

You can use the triple-store-class argument to specify the kind of store you are trying to delete. Like open-triple-store and create-triple-store, delete-triple-store takes additional keyword arguments that vary depending on this class. For example, deleting a remote-triple-store may require specifying a username and password. See open-triple-store or create-triple-store for additional details.

3.x to 4.x code conversion notes:

3.x: (db-or-name &rest args &key directory if-does-not-exist if-open  
      triple-store-class)  
4.x: (db-or-name &rest args &key if-does-not-exist triple-store-class)

The directory parameter is now required to be part of the name used in the db-or-name parameter. if-open has been removed.

Delete triples matching the given triple-pattern.

The triple-pattern is specified as in get-triples where each of s, p, o, g, s-end, p-end, o-end and g-end may be specified as part IDs, strings in N-Triples format, or the wildcard nil. Returns the number of triples deleted.

The :db keyword argument specifies the triple store to query and defaults to the value of *db*.

The :filter keyword can be used to limit the triples deleted. If specified it should be a function predicate of one argument, a triple, which returns true if and only if the triple should be deleted.

3.x to 4.x code conversion notes:

3.x: (&rest args &key s p o g s-end p-end o-end g-end filter db)  
4.x: (&key s p o g s-end p-end o-end g-end filter db)

&rest args was deemed unnecessary and was removed.

Returns a cursor that iterates over the triples that match the expression. The index argument can be given to search only a single index. When not given, all available indices are used. The sorted-p argument, which defaults to nil, can be given a truth value to cause the results to come back sorted by relevance (most relevant triples first).

(iterate-cursor (triple (freetext-get-triples '(match "amsterd*")))  
    (print triple))

3.x to 4.x code conversion notes:

3.x: (expression &key db)  
4.x: (expression &key index db predicates)

This function has been extended to let you search a specific text index for specific predicates.

Returns all the unique subjects in triples whose objects contain expression. This is a useful function in prolog queries.

(select (?person)  
  (lisp ?list  
     (freetext-get-unique-subjects '(and "collection" "people")))  
  (member ?person ?list)  
  (q- ?person !rdfs:subClassOf !c:AsianCitizenOrSubject))

3.x to 4.x code conversion notes:

3.x: (expression &key db)  
4.x: (expression &key db index predicates)

This function has been extended to let you search a specific text index for specific predicates.

Searches in db for a triple matching the search pattern specified by s, p, o and g (perhaps restricting the search to encoded triples only if return-non-encoded-triples is nil, or to non-encoded triples only if return-encoded-triples is nil). filter, if supplied, should be a predicate of one parameter, a triple. If the filter function returns nil on a possible match, that match is skipped. Searching is stopped when a match (which passes the filter, if supplied) is found.

If a match is found and triple is supplied (it must be of type triple), the match is copied to triple and triple is returned. If triple is not supplied, a new triple is created (as if with make-triple), the match is copied onto the new triple and the new triple is returned.

If no match is found, nil is returned.

db defaults to *db*.

3.x to 4.x code conversion notes:

3.x: (&key s p o g db return-encoded-triples return-non-encoded-triples  
      include-deleted filter triple)  
4.x: (&key s p o g db return-encoded-triples return-non-encoded-triples  
      filter triple)

This function has been simplified by removing the include-deleted option.

Query a triple store for triples matching the given subject, predicate, object, and graph. These can be specified either as UPIs, future-parts, strings in N-Triple format, or the wildcard nil. Returns a cursor object that can be used with cursor-row, cursor-next-row and other cursor functions.

The following example finds every triple that starts with !ub:Kevin.

> (add-triple !ub:Kevin !ub:isa !"programmer")  
8523645  
> !ub:Kevin  
!<http://www.w3.org/1999/02/22-rdf-syntax-ns#Kevin>  
> (get-triples :s !ub:Kevin)  
#<row-cursor #<triple-record-file @ #x13c1a87a> 2019 [1 - 2018] @  
  #x14942bba>  
> (print-triples *)  
<http://www.w3.org/1999/02/22-rdf-syntax-ns#Kevin>  
  <http://www.w3.org/1999/02/22-rdf-syntax-ns#isa>  
  "programmer" .

The function get-triples takes the following arguments:

s, p, o, g - specify the query pattern. Use nil as a wildcard. Each of these can be a UPI, a future-part, or a string that can be converted into a part. These can also take on the value :minimum if a corresponding ?-end parameter is specified. If :minimum is used, then the range query will run from the smallest value up to the ending value.
s-end, p-end, o-end, g-end - Allows for range queries over encoded triples (triples whose parts are encoded UPIs). Each ?-end parameter may only be used in conjunction with its corresponding starting value parameter. Each of these can be a UPI, a future-part, or a string that can be converted into a part. These can also take on the value :maximum if a corresponding starting parameter is specified. If :maximum is used, then the range query will run from the starting value up to the maximum value in the triple-store.
The :db keyword argument specifies the triple store to query and defaults to the value of *db*.
filter - if supplied, the filter should be a predicate of one parameter, a triple. If the filter function returns nil, then the triple will not be included in the result set.
return-encoded-triples - If true, then get-triples returns triples with encoded parts; i.e., triples that use directly encoded UPIs rather than strings stored in the dictionary. The default value is true.
return-non-encoded-triples - if true, then get-triples will return triples all of whose UPIs are stored as strings. This is set to true unless overridden.

The return value is a cursor object. The functions collect-cursor, count-cursor and cursor-next-row can be used to step through the cursor.

If it can be determined that one of the search parameters is not interned in the triple-store, then get-triples will return a null-cursor (i.e., a cursor that has no rows) and a second value of :part-not-found.

Note on tracing: get-triples can be inlined by the compiler, so if you want to trace get-triples calls, you should declare the function notinline. Alternatively, you can trace db.agraph::get-triples-positional, the non-exported internal function, which the compiler macro uses.

3.x to 4.x code conversion notes:

3.x: (&key s p o g s-end p-end o-end g-end db  
      include-deleted return-encoded-triples return-non-encoded-triples filter  
      indexed-triples-only-p)  
4.x: (&key s p o g s-end p-end o-end g-end db  
      return-encoded-triples return-non-encoded-triples filter)

This function has been simplified by removing the indexed-triples-only-p and include-deleted options.

Returns a cursor that iterates through all the triples with predicate pred and an object UPI that is a geospatial UPI with the given subtype and within the specified Cartesian bounding box. If :use-g is true, the triple's graph slot is searched instead of the object. The units are implicit in the data.

3.x to 4.x code conversion notes:

3.x: (subtype p x-min x-max y-min y-max &key db use-g  
      indexed-triples-only-p include-deleted)  
4.x: (subtype p x-min x-max y-min y-max &key db use-g)

This function has been simplified by removing the indexed-triples-only-p and include-deleted options.

Returns a cursor that will iterate over the specified triples.

subtype is a geospatial-subtype object such as is returned by register-cartesian-striping.

pred is a UPI or future part specifying the predicate of triples to be matched. It must be supplied.

x and y are the coordinates around which to search, and radius is the search radius. The units of radius are implicit in the subtype. All matching triples with an object of the specified geospatial subtype and within the search radius will be returned by the cursor.

If the use-g argument is specified and is true, the graph part of triples is searched instead of the object. The other arguments are as for get-triples.

3.x to 4.x code conversion notes:

3.x: (subtype pred x y radius &key db use-g  
      indexed-triples-only-p include-deleted)  
4.x: (subtype pred x y radius &key db use-g)

This function has been simplified by removing the indexed-triples-only-p and include-deleted options.

Like get-triples-haversine-miles but the radius-in-km is given in kilometers.

3.x to 4.x code conversion notes:

3.x: (subtype pred lon lat radius-in-km &key db use-g  
      indexed-triples-only-p include-deleted)  
4.x: (subtype pred lon lat radius-in-km &key db use-g)

This function has been simplified by removing the indexed-triples-only-p and include-deleted options.

Returns a cursor that will return the specified triples.

subtype is a geospatial-subtype designator. It can be an object such as is returned by register-latitude-striping-in-miles or a string, future-part or UPI describing such a subtype

pred is a UPI or future part specifying the predicate of triples to be matched. It must be supplied.

lon and lat are the coordinates around which to search, and radius-in-miles is the search radius. All matching triples with an object of the specified geospatial subtype and within the search radius will be returned by the cursor.

If the use-g argument is specified and is true, the graph part of triples is searched instead of the object. The other arguments are as for get-triples.

3.x to 4.x code conversion notes:

3.x: (subtype pred lon lat radius-in-miles &key db use-g  
      indexed-triples-only-p include-deleted)  
4.x: (subtype pred lon lat radius-in-miles &key db use-g)

This function has been simplified by removing the indexed-triples-only-p and include-deleted options.

Like get-triples-haversine-miles but the radius-in-radians is given in radians.

This is incompletely implemented and nonfunctional in release 3.0.

3.x to 4.x code conversion notes:

3.x: (subtype pred lon lat radius-in-radians &key db use-g  
      indexed-triples-only-p include-deleted)  
4.x: (subtype pred lon lat radius-in-radians &key db use-g)

This function has been simplified by removing the indexed-triples-only-p and include-deleted options.

polygon must be a list representing a polygon such as is returned by polygon-vertexes. Returns a cursor that will return all triples with predicate predicate and an object that is a geospatial UPI of subtype subtype within the polygon. If use-g is supplied and true, the graph is used instead. Boundary cases for vertexes of points on the edges are indeterminate. The other arguments are as for get-triples-geospatial-bounding-box

3.x to 4.x code conversion notes:

3.x: (subtype predicate polygon &key db use-g indexed-triples-only-p include-deleted)  
4.x: (subtype predicate polygon &key db use-g)

This function has been simplified by removing the indexed-triples-only-p and include-deleted options.

Query a triple store for triples matching the given subject, predicate, object, and graph, specified either as part IDs (UPIs), future-parts, strings in N-Triples format, or the wildcard nil. Returns a list of matching triples. The get-triples-list function supports a multitude of options:

db - This keyword argument specifies the triple store to query and defaults to the value of *db*.
s, p, o, g - controls the actual query pattern. Use nil as a wildcard.
s-end, p-end, o-end, g-end - Allows for range queries over encoded triples (triples whose parts are encoded UPIs). Each ?-end parameter may only be used in conjunction with its corresponding starting value parameter and only one range may be specified per query.
cursor - if cursor is supplied then AllegroGraph will use it to return more triples rather than building a new cursor (i.e. the other query parameters will be ignored).
limit - This keyword argument can be used to place a cap on the maximum number of triples returned. It defaults to the value of the special variable *get-triples-list-limit*. If supplied, then
get-triples-list will return no more than :limit triples.
If it is nil, then get-triples-list will return all of the triples found by the query. Warning: setting limit to nil can cause get-triples-list to return every triple in the triple-store;
this will take a very long time if the triple-store is large.
return-encoded-triples - If true, then get-triples-list returns triples with encoded parts; i.e., triples that use directly encoded UPIs rather than strings stored in the dictionary. The is set to true unless overridden.
return-non-encoded-triples - if true, then get-triples-list will return triples all of whose UPIs are stored as strings. This is set to true unless overridden.

Note that most of the arguments to get-triples-list do not make sense when reasoning is turned on. AllegroGraph will signal an error if you try to combine reasoning with other parameters that it cannot use.

If it can be determined that one of the search parameters is not interned in the triple-store, then get-triples-list will return immediately return nil and :part-not-found as multiple values.

get-triples-list will return

a list and a cursor if triples are found.
nil and t as multiple values if all search parameters are interned and no triples are found.
nil and :part-not-found as multiple values if one of the search parameters is not interned in the triple-store.

If nil is returned, the second return value allows you to determine why.

3.x to 4.x code conversion notes:

3.x: (&rest args &key s p o g s-end p-end o-end g-end limit db  
     include-deleted return-encoded-triples return-non-encoded-triples  
     cursor if-fewer if-more use-reasoner filter)  
4.x: (&rest args &key s p o g s-end p-end o-end g-end limit db  
     return-encoded-triples return-non-encoded-triples cursor filter)

The function has been simplified by removing several options that were overloading it.

Compute the UPI of value treating it as an untyped literal, possibly with a language tag. Ensure that the literal is in the store's string dictionary and return the UPI.

:db - specifies the triple-store into which the uri will be interned. This defaults to the value of *db*.
:upi - if supplied, then this upi will be used to store the uri's UPI; otherwise, a new UPI will be created using make-upi.
:language - if supplied, then this language will be associated with the literal value. See rfc-3066 for details on language tags.
:datatype - If supplied, the datatype must be a resource. I.e., it can be a string representation of a URI (e.g., "http://foo.com/") or a future-part specifying a resource (e.g., !<http://foo.com>). If it does not specify a resource, a condition of type invalid-datatype-for-literal-error is signaled. An overview of RDF datatypes can be found in the W3C's RDF concepts guide.

Only one of datatype and language can be used at any one time. If both are supplied, a condition of type datatype-and-language-specified-error will be signaled.

3.x to 4.x code conversion notes:

3.x: (value &key language db upi)  
4.x: (value &key language datatype db upi)

Added the ability to specify an RDF datatype.

Compute the UPI of uri, make sure that it is stored in the string dictionary, and return the UPI.

:db - specifies the triple-store into which uri will be interned. This defaults to the value of *db*.
:upi - if supplied, then this upi will be used to store the uri's UPI; otherwise, a new UPI will be created using make-upi.
:namespace - If namespace is provided, then uri will be treated as a fragment and the UPI returned will encode the URIref whose prefix is the string to which namespace maps and whose fragment is uri.

Lisp API elements that are new in 4.x

These are the new Lisp elements in AllegroGraph 4.x. Each is linked to its documentation, typically, in The Lisp Reference Guide. Cases where a function has been removed or deprecated in some 4.x version (and after) are noted.

*default-ag-http-port* (variable)
automatically-mapped-types (function)
bidirectional-search-path (functor)
breadth-first-search-path (functor)
catalogs (function)
collect-triples (function)
commit-triple-store (function)
create-freetext-index (function)
delete-duplicates-during-merge-p is no longer supported. It is replaced (in version 4.2.1 and after) by duplicate-deletion-strategy. As of version 4.4, use the delete-duplicate-triples function.
depth-first-search-path (function)
drop-freetext-index (function)
ensure-not-lingering (function)
freetext-index-index-fields (function)
freetext-index-index-literals (function)
freetext-index-index-resources (function)
freetext-index-minimum-word-size (function)
freetext-index-predicates (function)
freetext-index-stop-words (function)
freetext-index-tokenizer (function)
freetext-index-word-filters (function)
in-memory-triple-store (class)
list-freetext-indices (function)
modify-freetext-index (function)
remove-namespace (function)
rollback-triple-store (function)
serialize-nquads (function)
text-index-already-exists-error (class)
text-index-not-found-error (class)
triple-db (class)
upi< (functor)
upi<= (function)
upi<= (functor)
with-temp-upis

Lisp API elements that became obsolete in 4.x

Eighty-six Lisp elements became obsolete in AllegroGraph 4.x.

(*agj-idle-life* variable)
(*agj-indexing* variable)
(*agj-timeout* variable)
(*default-expected-unique-resources* variable)
(*index-chunk-count-warning-limit* variable)
(*maximum-indexing-sort-chunk-size* variable)
(*print-triples-list-limit* variable)
(*synchronize-automatically* variable)
(*use-reasoner* variable)
(add-indexing-host function)
(add-indices function)
(add-standard-indices function)
(ag-disable-logging function)
(ag-enable-logging function)
(ag-property function)
(ag-property-names function)
(agraph-manager function)
(agraph-manager structure)
(agraph-manager type)
(ag-server-db function)
(ag-server-trace function)
(average-index-fragment-count function)
(chunk-count-to-merge-if-all-same function)
(chunk-count-to-merge-if-some-small function)
(close-triple-store class)
(create-triple-store class)
(cursor-next-p function)
(data-directory function)
(deleted-triple-p function)
(delete-triple-store class)
(drop-index function)
(drop-indices function)
(enable-lisp-in-client-select-queries function)
(estimate-required-space function)
(export-to-sesame function)
(find-cluster-code function)
(find-triple-store function)
(freetext-get-ids function)
(freetext-get-triples-list function)
(freetext-index-needs-updating-p function)
(freetext-predicate-p function)
(freetext-registered-predicates function)
(index-all-triples function)
(index-coverage-percent function)
(index-fragment-count function)
(indexing-needed-p function)
(indexing-status function)
(index-new-triples function)
(index-status-report function)
(inferred-triple-p class)
(intern-typed-literal function)
(invalid-uuid-string class)
(load-properties function)
(make-sesame-server function)
(manage-agraph function)
(manager-paused-p function)
(manager-period function)
(manage-triple-store function)
(merge-new-triples function)
(pause-agraph-manager function)
(qs functor)
(register-freetext-predicate function)
(reset-properties function)
(resume-agraph-manager function)
(save-properties function)
(sesame-server class)
(sesame-server function)
(sesame-server-port function)
(start-agraph-manager function)
(start-ag-server function)
(start-sesame-server function)
(stop-agraph-manager function)
(stop-ag-server function)
(stop-sesame-server function)
(sync-triple-store function)
(text-index-minimum-word-size function)
(text-index-parameters function)
(text-index-stop-words function)
(triple-store-exists-p class)
(triple-store-indices function)
(undelete-triple function)
(undelete-triples function)
(unindexed-triple-count-threshold function)
(unmerged-chunk-count-threshold function)
(unschedule-indexing function)
(update-freetext-index function)
(upgrade-triple-store function)
(upi-map-directory function)

Lisp API elements that did not change from 3.x to 4.x

The bulk of the AllegroGraph Lisp API did not change in the transition from 3.x to 4.x. The following is a condensed list of the elements that make the transition unchanged. Full documentation of these elements will be found on the Lisp Reference page.

(set-spherical-predicate-mapping function)
(set-spherical-datatype-mapping function)
(set-cartesian-predicate-mapping function)
(set-cartesian-datatype-mapping function)
(*agraph-version* variable)
(*db* variable)
(*default-spogi-cache-enabled* variable)
(*default-spogi-cache-size* variable)
(*get-triples-list-limit* variable)
(*last-query-plan* variable)
(*print-decoded* variable)
(*standard-namespaces* variable)
(+geospatial+ constant)
(+long-88+ constant)
(+rdf-blank-node+ constant)
(+rdf-boolean+ constant)
(+rdf-byte+ constant)
(+rdf-date+ constant)
(+rdf-date-time+ constant)
(+rdf-default-graph+ constant)
(+rdf-double-float+ constant)
(+rdf-gen-neg-number+ constant)
(+rdf-gen-pos-number+ constant)
(+rdf-gyear+ constant)
(+rdf-int+ constant)
(+rdf-latitude+ constant)
(+rdf-literal+ constant)
(+rdf-literal-language+ constant)
(+rdf-literal-short+ constant)
(+rdf-literal-typed+ constant)
(+rdf-long+ constant)
(+rdf-longitude+ constant)
(+rdf-resource+ constant)
(+rdf-short+ constant)
(+rdf-single-float+ constant)
(+rdf-telephone-number+ constant)
(+rdf-time+ constant)
(+rdf-unsigned-byte+ constant)
(+rdf-unsigned-int+ constant)
(+rdf-unsigned-long+ constant)
(+rdf-unsigned-short+ constant)
(+subscript+ constant)
(+telephone-number+ constant)
(+triple-id-tag+ constant)
(+unsigned-long-88+ constant)
(abstract-filter class)
(abstract-triple-store class)
(actor-betweenness-centrality functor)
(actor-betweenness-centrality function)
(actor-closeness-centrality functor)
(actor-closeness-centrality function)
(actor-degree-centrality functor)
(actor-degree-centrality function)
(add-triple function)
(agraph-application function)
(all-bidirectional-search-paths function)
(all-breadth-first-search-paths function)
(all-depth-first-search-paths function)
(allegrograph-version function)
(apply-rdfs++-reasoner function)
(bidirectional-distance function)
(bidirectional-search function)
(bidirectional-search-paths functor)
(blank-node-p function)
(breadth-first-distance function)
(breadth-first-search function)
(breadth-first-search-paths functor)
(build-neighbor-matrix function)
(clear-namespaces function)
(clique functor)
(cliquep functor)
(cliquep function)
(cliques function)
(collect-all-type-mappings function)
(collect-namespaces function)
(collect-open-triple-stores function)
(concrete-triple-store class)
(copy-triple function)
(copy-upi function)
(copy-upi-into function)
(count-cursor function)
(count-query function)
(cursor-next function)
(cursor-next-row function)
(cursor-row function)
(datatype-mapping function)
(date-string-to-upi functor)
(date-string-to-upi function)
(date-thing-to-upi functor)
(date-thing-to-upi function)
(datetime-after functor)
(datetime-after-value functor)
(datetime-before functor)
(datetime-before-value functor)
(datetime-increasing functor)
(datetime-increasing-value functor)
(datetime-simultaneous functor)
(datetime-simultaneous-value functor)
(db.agraph.sparql:*dataset-load-function* variable)
(db.agraph.sparql:*sparql-check-variable-errors-p* variable)
(db.agraph.sparql:*sparql-default-graph-behavior* variable)
(db.agraph.sparql:*sparql-table-width* variable)
(db.agraph.sparql:allowed-rdf-formats function)
(db.agraph.sparql:allowed-results-formats function)
(db.agraph.sparql:db-run-sparql function)
(db.agraph.sparql:get-allowed-rdf-formats function)
(db.agraph.sparql:get-allowed-results-formats function)
(db.agraph.sparql:get-sparql-query-engines function)
(db.agraph.sparql:get-variable-list function)
(db.agraph.sparql:run-sparql function)
(db.agraph.sparql:run-sparql-ask function)
(db.agraph.sparql:run-sparql-average function)
(db.agraph.sparql:run-sparql-construct function)
(db.agraph.sparql:run-sparql-correlation function)
(db.agraph.sparql:run-sparql-count function)
(db.agraph.sparql:run-sparql-describe function)
(db.agraph.sparql:run-sparql-median function)
(db.agraph.sparql:run-sparql-select function)
(db.agraph.sparql:run-sparql-stats function)
(db.agraph.sparql:run-sparql-sum function)
(db-name function)
(db-room function)
(db-room-list function)
(default-data-version-level function)
(default-graph-upi function)
(default-query-plan-option function)
(defined-query-plan-options function)
(defneighbor-matrix metabang.docudown::macro)
(defsna-generator metabang.docudown::macro)
(depth-first-distance function)
(depth-first-search function)
(depth-first-search-paths functor)
(display-namespaces function)
(drop-geospatial-subtype function)
(dump-namespaces function)
(ego-group functor)
(ego-group function)
(ego-group-layers function)
(ego-group-member functor)
(enable-print-decoded function)
(encapsulated-triple-store class)
(encapsulate-triple-store function)
(encoded-types function)
(estimated-count-query function)
(federated-triple-store class)
(federate-triple-stores function)
(filtered-triple-store class)
(find-sna-generator function)
(future-part structure)
(future-part type)
(future-part= function)
(future-part-extra function)
(future-part-type function)
(future-part-value function)
(geo-parts->upi function)
(geospatial->upi function)
(geospatial-subtype function)
(geospatial-subtype structure)
(geospatial-subtype type)
(geospatial-subtype-index-in-db function)
(geospatial-subtype-index-in-this-image function)
(geospatial-subtypes-in-db function)
(geospatial-x function)
(geospatial-y function)
(geospatial-y-strip function)
(gethash/upi function)
(get-triple-by-id function)
(graph functor)
(graph function)
(graph-density functor)
(graph-density function)
(graph-filter class)
(graph-filtered-triple-store class)
(graph-part= function)
(graph-upi= function)
(ground-only-triple-store class)
(ground-triple-store function)
(group-betweenness-centrality functor)
(group-betweenness-centrality function)
(group-closeness-centrality functor)
(group-closeness-centrality function)
(group-degree-centrality functor)
(group-degree-centrality function)
(hashed-upi-p function)
(hash-table-count/upi function)
(has-value-reasoning-enabled function)
(haversine-km function)
(haversine-miles function)
(haversine-r function)
(inferred-triple-p function)
(inner=triple=store metabang.docudown::macro)
(inner-triple-store metabang.docudown::macro)
(insert-triples metabang.docudown::macro)
(interval-after functor)
(interval-after-datetime functor)
(interval-after-datetimes functor)
(interval-before functor)
(interval-before-datetime functor)
(interval-before-datetimes functor)
(interval-contains functor)
(interval-contains-datetime functor)
(interval-contains-datetimes functor)
(interval-cotemporal functor)
(interval-cotemporal-datetimes functor)
(interval-during functor)
(interval-during-datetimes functor)
(interval-endtime functor)
(interval-finished-by functor)
(interval-finished-by-datetimes functor)
(interval-finishes functor)
(interval-finishes-datetimes functor)
(interval-meets functor)
(interval-meets-datetimes functor)
(interval-met-by functor)
(interval-met-by-datetimes functor)
(interval-overlapped-by functor)
(interval-overlapped-by-datetimes functor)
(interval-overlaps functor)
(interval-overlaps-datetimes functor)
(interval-started-by functor)
(interval-started-by-datetimes functor)
(interval-starts functor)
(interval-starts-datetimes functor)
(interval-starttime functor)
(iterate-cursor metabang.docudown::macro)
(literal function)
(longitude-latitude->upi function)
(lookup-namespace function)
(make-future-part function)
(make-graph-filtered-store function)
(make-triple function)
(make-upi function)
(make-upi-hash-table function)
(map-all-type-mappings function)
(map-bidirectional-search-paths function)
(map-bidirectional-search-paths-bipartite function)
(map-breadth-first-search-paths function)
(map-breadth-first-search-paths-bipartite function)
(map-cliques function)
(map-cursor function)
(map-depth-first-search-paths function)
(map-depth-first-search-paths-bipartite function)
(maphash/upi function)
(map-namespaces function)
(map-open-triple-stores function)
(new-blank-node function)
(next-largest-upi function)
(next-smallest-upi function)
(nodal-degree functor)
(nodal-degree function)
(nodal-neighbors functor)
(nodal-neighbors function)
(object functor)
(object function)
(object-part= function)
(object-upi= function)
(page-rank-centrality function)
(part= functor)
(part= function)
(part->concise function)
(part->long function)
(part->ntriples function)
(part->string function)
(part->terse function)
(part->value function)
(part-value function)
(point-after functor)
(point-after-datetime functor)
(point-after-interval functor)
(point-before functor)
(point-before-datetime functor)
(point-before-interval functor)
(point-datetime functor)
(point-during-interval functor)
(point-ends-interval functor)
(point-inside-polygon-p function)
(point-simultaneous functor)
(point-starts-interval functor)
(polygon-inside-polygon-p function)
(polygon-vertexes function)
(pprint-object function)
(pprint-subject function)
(predicate functor)
(predicate function)
(predicate-mapping function)
(predicate-part= function)
(predicate-upi= function)
(prepare-reasoning function)
(print-notification-message function)
(print-triple function)
(print-triples function)
(print-type-mappings function)
(q functor)
(q- functor)
(qd functor)
(rdfs++-reasoner class)
(reasoner function)
(reasoning-triple-store class)
(register-cartesian-striping function)
(register-geospatial-subtype function)
(register-latitude-striping-in-degrees function)
(register-latitude-striping-in-km function)
(register-latitude-striping-in-miles function)
(register-latitude-striping-in-radians function)
(register-namespace function)
(register-neighbor-matrix function)
(register-sna-generator function)
(register-standard-namespaces function)
(remhash/upi function)
(remote-triple-store class)
(report-loaded-geospatial-subtypes function)
(resource function)
(scale-latitude function)
(scale-longitude function)
(select metabang.docudown::macro)
(select/callback metabang.docudown::macro)
(select0 metabang.docudown::macro)
(select0/callback metabang.docudown::macro)
(select0-distinct metabang.docudown::macro)
(select0-distinct/callback metabang.docudown::macro)
(select-distinct metabang.docudown::macro)
(select-distinct/callback metabang.docudown::macro)
(serialize-rdf/xml function)
(serialize-rdf-manifest function)
(serialize-rdf-n3 function)
(serialize-trix function)
(set-cartesian-datatype-mapping function)
(set-cartesian-predicate-mapping function)
(set-spherical-datatype-mapping function)
(set-spherical-predicate-mapping function)
(sparql.parser:parse-sparql function)
(sparql.planner:bgp-planner function)
(sparql.sop:associate-function-with-uri function)
(sparql.sop:defurifun metabang.docudown::macro)
(sparql.sop:print-function-uri-mappings function)
(sparql.util:lexer-error-namespace function)
(sparql.util:lexer-error-qname function)
(sparql.util:parse-error-expected-terminals function)
(sparql.util:parse-error-terminal function)
(sparql.util:parse-error-value function)
(spogi-cache-enabled-p function)
(spogi-cache-size function)
(string+ function)
(subject functor)
(subject function)
(subject-part= function)
(subject-upi= function)
(supported-types function)
(triple= function)
(triple-spog= function)
(triple-count function)
(triple-exists-p function)
(triple-id functor)
(triple-id function)
(triple-id type)
(triple-inside-bounding-box functor)
(triple-inside-bounding-box-g functor)
(triple-inside-haversine-km functor)
(triple-inside-haversine-km-g functor)
(triple-inside-haversine-miles functor)
(triple-inside-haversine-miles-g functor)
(triple-inside-haversine-radians functor)
(triple-inside-haversine-radians-g functor)
(triple-inside-polygon functor)
(triple-inside-polygon-g functor)
(triple-inside-radius functor)
(triple-inside-radius-g functor)
(triple-part type)
(triple-store-id function)
(type-code->type-name function)
(type-name->type-code function)
(unscale-latitude function)
(unscale-longitude function)
(upi function)
(upi type)
(upi< function)
(upi= functor)
(upi= function)
(upi->geospatial function)
(upi->longitude-latitude function)
(upi->value function)
(upi->values function)
(upip function)
(upi-to-date-string functor)
(upi-to-date-string function)
(upi-to-date-time functor)
(upi-to-date-time function)
(upi-type-code function)
(upi-typep function)
(value->upi function)
(with-blank-nodes metabang.docudown::macro)
(with-data-version-level metabang.docudown::macro)
(with-temp-triple metabang.docudown::macro)
(with-temp-upi metabang.docudown::macro)
(with-triple-store metabang.docudown::macro)

Python API

There were several miscellaneous enhancements of the Python API in the transition from AllegroGraph 3.x to 4.x. Specific changes are called out in this section. See the Python API page for full documentation. There are also extensive programming examples in the Python Tutorial.

AllegroGraphServer Class

AllegroGraphServer has lost a dozen methods, has gained a few new methods, and there have been some changes to existing methods.

Obsolete Methods

The getHost() method is now obsolete.

Environments are no longer used in AllegroGraph. Therefore the following methods are now obsolete:

createEnviroment()
deleteEnvironment()
deleteRule()
listEnvironments()
setEnvironment()
setRuleLanguage()

The following methods relating to the management of Social Network Analysis neighbor matrices and generators are obsolete:

dropNeighborMatrix()
dropSNAGenerator()
listNeighborMatrices()
listSNAGenerators()
rebuildNeighborMatrix()

Changed Methods

The AllegroGraphServer constructor has new defaults and new arguments.

3.x: AllegroGraphServer(self, host, port=4567)  
4.x: AllegroGraphServer(self, host, port=10035, user=None, password=None)

user and password are AllegroGraph user credentials.

The openCatalog() method has a new default value.

3.x: openCatalog(self, shortName)  
4.x: openCatalog(self, name=None)

When name is None, AllegroGraph opens the root catalog.

New Methods

See the Python API page for full documentation of the following new methods.

The getInitFile(none) method has been added. It returns the contents of the server initialization file.

getInitFile(self)

The openFederated() method opens a session that federates multiple repositories. The repositories argument should be an array containing store designators, which can be Repository or RepositoryConnection objects, strings naming a store in the root catalog or the URL of a store, or (storename, catalogname) tuples.

openFederated(self, respoitories, autocommit=False, lifetime=None, loadinitfile=False)

The openSession() method opens a session (a dedicated back end) on a federated, reasoning, or filtered store. There are helper functions in franz.openrdf.sail.spec to help create the spec string.

openSession(self, spec, autocommit=False, lifetime=None, loadinitfile=False)

The new setInitFile() method replaces the current initialization file with the content string. The restart parameter forces running back ends to shut down and restart, loading the new init file before continuing.

setInitFile(self, content=None, restart=True)

The url() method returns the server's URL.

url(self)

The version() method returns the server's version as a string.

version(self)

Catalog Class

The Catalog class lost one method and gained two new ones in the transition from 3.x to 4.x.

Obsolete Methods

The close() method is now obsolete.

Changed Methods

There are no changed methods in the Catalog class.

New Methods

The createRepository() method creates a new repository within the Catalog.

createRepository(self, name)

The deleteRepository() method deletes an existing repository.

deleteRepository(self, name)

Repository Class

The Repository class has lost three methods due to changes in the mechanism of federated stores, triple indexing, and free-text indexing. There is one new method.

Obsolete Methods

The addFederatedTripleStore() method is now obsolete. See the AllegroGraphServer.openFederated() method instead.

The indexTriples() method is obsolete. In 4.x, triples are indexed as they are added to the system.

The registerFreeTextPredicate() method is obsolete. In 4.x you can create multiple text indices and assign them to specific predicates. See the RepositoryConnection.createFreeTextIndex() method for more information.

Changed Methods

There are no changed methods in the Repository class.

New Methods

The getSpec() method returns a string consisting of the catalog name concatenated with the repository name.

getSpec(self)

RepositoryConnection Class

The RepositoryConnection class in the Python API is the repository for most of the methods that build, manipulate, and search a triple store. There is a long list of methods in this class.

There are three obsolete methods, two methods that changed their parameter lists, and fourteen new methods that reflect new features of AllegroGraph in version 4.x.

Obsolete Methods

The indexTriples() method is obsolete. In most situations triples are indexed automatically as they enter the triple store. The exception is sessions that use transaction semantics, where the triples are indexed when they are committed.

The registerFreeTextPredicate() method is obsolete. In 4.x, AllegroGraph can have independent free-text indexes, each with associated with one or more predicates. See createFreeTextIndex().

The getJDBCStatements() is obsolete.

Changed Methods

The clear() method can now take a list of contexts to clear.

3.x: clear(self, contexts=None)  
4.x: clear(self, contexts=ALL_CONTEXTS)

In 3.x this method could clear a specific context or all contexts. In 4.x it can clear a specific list of contexts.

The getStatements() method has an additional parameter:

3.x: getStatements(self, subject, predicate, object, contexts=ALL_CONTEXTS,  
     includeInferred=False, limit=None)  
4.x: getStatements(self, subject, predicate, object, contexts=ALL_CONTEXTS,  
     includeInferred=False, limit=None, tripleIDs=False)

You may optionally return the tripleIDs.

New Methods

The getAddCommitSize() method returns the current setting ot he addcommitsize property. See setAddCommitSize().

getAddCommitSize(self)

The getSpec() method returns a string concatenating the catalog name and the repository name.

getSpec(self)

The setAddCommitSize() method sets the threshold for commit size during triple add operations.

setAddCommitSize(self, triple_count)

The createFreeTextIndex() method lets you set up multiple, independent free-text indices associated with specific fields of specific predicates. This approach is much more fine-grained than in 3.x which lumped all free-text predicates into one index.

createFreeTextIndex(self, predicates=None, indexLiterals=None, indexResources=None,  
    indexFields=None, minimumWordSize=None, stopWords=None, wordFilters=None)

See the Python API page for full documentation. There are also extensive programming examples in the Python Tutorial.

The getGeoType() method returns the type of a geospatial object.

getGeoType(self)

The setGeoType() method sets the type of a geospatial object.

setGeoType()

The openSession() method opens a dedicated session for transaction activity.

openSession(self)

The closeSession() method closes a dedicated session.

closeSession(self)

The session() method is a dedicated connection context manager for use with the 'with' statement. It automatically calls openSession() and block start and closeSession() and block end.

session(self, autocommit=False, lifetime=None, loadinitfile=False)

The commit() method takes triples from the dedicated session and loads them into the triple store.

commit(self)

The rollback() method rolls back changes that have been made in the dedicated session. For instance, uncommitted triples are removed by a rollback.

rollback(self)

The enableSubjectTriplesCache() can accelerate certain types of queries where the resouce appears in the subject position.

enableSubjectTriplesCache(self, size=None)

The disableSubjectTriplesCache() method turns off caching.

disableSubjectTriplesCache(self)

The getSubjectTriplesCache() method returns the size of the subject triples cache.

getSubjectTriplesCache(self)

Query Class

There was one change in the Query class. TupleQuery.evaluate() had a change in parameters:

3.x: TupleQuery.evaluate(self, jdbc=False)  
4.x: TupleQuery.evaluate(self, count=False)

If count is True, the query returns a count of results instead of the matching values.

RepositoryResult Class

Three were no changes in the RepositoryResult class.

Statement Class

There were no changes in the Statement class.

ValueFactory Class

There were no changes in the ValueFactory class.

Java Base API

Allegrograph 3.x contains a "base" API in Java called "agbase." This API was entirely replaced in Allegrograph 4.x by new Java classes and methods built on top of a Sesame HTTP protocol. These classes are documented in the AllegroGraph Java API documentation and are demonstrated in the Java Sesame Tutorial.

The following table shows the more common AllegroGraph "base" API methods, the corresponding AllegrpGraph 4.x methods, and the examples in the Java Sesame Tutorial that demonstrate the methods in context.

AllegroGraph 3.x	AllegroGraph 4.x	Java Tutorial Example
AllegroGraph.addStatement()	AGRepositoryConnection.add()	example2()
AllegroGraph.clear()	AGRepositoryConnection.clear()	example5()
AllegroGraph.closeTripleStore()	AGRepositoryConnection.close()	example5()
AllegroGraph.createBNode()	AGValueFactory.createBNode()	not illustrated
AllegroGraph.createLiteral()	AGValueFactory.createLiteral()	example5()
AllegroGraph.createStatement()	AGValueFactory.createStatement()	example5()
AllegroGraph.createTypedLiteral()	AGValueFactory.createLiteral()	example5()
AllegroGraph.createURI()	AGValueFactory.createURI()	example5()
AllegroGraph.getStatements()	AGRepositoryConnection.getStatements()	example2()
AllegroGraph.hasStatement()	AGBooleanQuery.evaluate()	example13()
AllegroGraph.indexAllTriples()	Obsolete - indexing is automatic in 4.x	obsolete
AllegroGraph.loadNTriples()	AGRepositoryConnection.add()	example6()
AllegroGraph.loadRDFXML()	AGRepositoryConnection.add()	example6()
AllegroGraph.registerFreetextPredicate()	Obsolete - see example12()	example12()
AllegroGraph.registerNamespace()	AGRepositoryConnection.setNamespace()	example11()
AllegroGraph.removeStatement()	AGRepositoryConnection.remove()	example2()
AllegroGraph.setSPOGICacheEnabled()	There is no analogous cache method.	obsolete
AllegroGraphConnection	AGRepositoryConnection	example1()
SPARQLQuery.ask()	AGBooleanQuery.evaluate()	example13()
SPARQLQuery.construct()	AGGraphQuery.evaluate()	example13()
SPARQLQuery.count()	AGTupleQuery.count()	not illustrated
SPARQLQuery.describe()	AGGraphQuery.evaluate()	example13()
SPARQLQuery.getDefaultDatasetBehavior()	Obsolete. This behavior can be set for individual queries.	example10()
SPARQLQuery.getResultCursor()	AGTupleQuery.evaluate()	example13()
SPARQLQuery.select()	AGTupleQuery.evaluate()	example13()
SPARQLQuery.setEngine()	Obsolete. AllegroGraph 4.x uses the Algebra engine only.	obsolete
SPARQLQuery.setFrom()	Use FROM in the SPARQL query.	example10()
SPARQLQuery.setFromNamed()	Use FROM NAMED in the SPARQL query.	example10()
SPARQLQuery.setIncludeInferred()	Reasoning is enabled/disabled per query,	example19()
SPARQLQuery.setOffset()	Use OFFSET in the SPARQL query.
SPARQLQuery.setQuery()	AGRepositoryConnection.prepareTupleQuery()	example3()
SPARQLQuery.setTripleStore()	The AGRepositoryConnection identifies the triple store.	example1()

Java Sesame API

AllegroGraph 3.x contained a limited Sesame 2 API that was implemented through a non-Sesame base API. In AllegroGraph 4.x we have replaced this limited capability with a new Java Sesame API that provides a full Sesame feature set built on top of a Sesame HTTP protocol.

Much of this conversion was accomplished by extending the Repository and supporting APIs from the OpenRDF Sesame Core API. In many cases an OpenRDF Sesame class, such as TupleQuery, has been extended by an AllegroGraph class like AGTupleQuery. The Java Tutorial examples use the OpenRDF classes and the AllegroGraph extensions almost interchangably, except where the "AG" version offers additional methods that are required by the example. For this reason you should refer to the OpenRDF Sesame Core API documentation as well as the AllegroGraph Java API documentation as you study the new classes and methods.

The AllegroGraph Java API supports transaction semantics, which is a new feature of 4.x. In addition, the Java API has been extended to include advanced free-text indexing features, and improved tools for federation. Triple indexing is now automatic, and the "XSD primitive datatypes" are now automatically encoded as appropriate literal value during loading.

The following table is a quick reference showing often-used 3.x methods, their 4.x equivalents, and the Java Sesame Tutorial examples that show the new methods in use.

AllegroGraph 3.x	AllegroGraph 4.x	Java Tutorial Example
BooleanQuery.evaluate()	AGBooleanQuery.evaluate()	example13()
GraphQuery.evaluate()	AGGraphQuery.evaluate()	example13()
RepositoryConnection.add()	AGRepositoryConnection.add()	example2()
RepositoryConnection.clear()	AGRepositoryConnection.clear()	example5()
RepositoryConnection.close()	AGRepositoryConnection.close()	example5()
RepositoryConnection.getStatements()	AGRepositoryConnection.getStatements()	example2()
RepositoryConnection.prepareTupleQuery()	AGRepositoryConnection.prepareTupleQuery()	example3()
RepositoryConnection.remove()	AGRepositoryConnection.remove()	example2()
RepositoryConnection.setNamespace()	AGRepositoryConnection.setNamespace()	example11()
TupleQuery.evaluate()	AGGraphQuery.evaluate()	example13()
ValueFactory.createBNode()	AGValueFactory.createBNode()	not illustrated
ValueFactory.createLiteral()	AGValueFactory.createLiteral()	example5()
ValueFactory.createStatement()	AGValueFactory.createStatement()	example5()
ValueFactory.createURI()	AGValueFactory.createURI()	example5()
Repository.getValueFatory()	AGRepository.getValueFactory()	example2()

Java Jena API

AllegroGraph 3.x contained a limited Jena API. In AllegroGraph 4.x we have replaced this limited capability with a new Java Jena API built on top of a Sesame HTTP protocol.

Much of this conversion was accomplished by extending the Repository and supporting APIs from OpenJena.org. In many cases an OpenJena class, such as Model, has been extended by an AllegroGraph class like AGModel. For this reason you should refer to the OpenJena API documentation and the OpenJena ARQ documentation as well as the AllegroGraph Jena API documentation as you study the new classes and methods.

The main difference between the 3.x Jena API and 4.x lies in setting up the connection to the triple store. This process is illustrated in [example(1)] of the Java Jena Tutorial.

The following table is a quick reference showing often-used 3.x Jena methods, their 4.x Jena equivalents, and the Java Jena Tutorial or Java Sesame Tutorial examples that show the new methods in use.

AllegroGraph 3.x	AllegroGraph 4.x	Jena Tutorial Example
AllegroGraph.closeTripleStore()	AGRepositoryConnection.close()	example1()
AllegroGraphGraphMaker()	AGGraphMaker()	example1()
AllegroGraphGraphMaker.close()	AGGraphMaker.close()	example1()
AllegroGraphGraphMaker.createGraph()	AGGraphMaker.getGraph()	example1()
AllegroGraphGraphMaker. setDefaultIsGraphOfAllGraphs()	Obsolete. Graph behavior is controlled by queries.	example10()
AllegroGraphModel.add()	AGModel.add()	example2()
AllegroGraphModel.close()	AGModel.close()	example2()
AllegroGraphModel.createLiteral()	AGModel.createLiteral()	example2()
AllegroGraphModel.createProperty()	AGModel.createProperty()	example2()
AllegroGraphModel.createResource()	AGModel.createResource()	not illustrated
AllegroGraphModel.createStatement()	AGModel.createStatement()	example5()
AllegroGraphModel.createTypedLiteral()	AGModel.createTypedLiteral()	example5()
AllegroGraphModel.indexTriples()	Obsolete. Indexing is automatic in 4.x	obsolete
AllegroGraphModel.listStatements()	AGModel.listStatements()	example2()
AllegroGraphModel.read()	AGModel.read()	example6()
AllegroGraphModel.remove()	AGModel.remove()	example2()
AllegroGraphModel.removeAll()	AGModel.removeAll()	example5()
AllegroGraphQueryExecutionFactory.create()	AGQueryFactory.create() AGQueryExecutionFactory.create()	example3()
AllegroGraphReasoner.bind()	AGReasoner.bind()	example19()
Graph.add()	AGGraph.add()	Not illustrated
Graph.contains()	AGGraph.contains()	Not illustrated
GraphMaker.createGraph()	AGGraphMaker.createGraph()	example6()
GraphMaker.getGraph()	AGGraphMaker.getGraph()	example2()
GraphMaker.listGraphs()	AGGraphMaker.listGraphs()	Not illustrated
QueryExecution.execSelect()	AGQueryExecution.execSelect()	example3()
ResultSet.hasNext()	AGResultSet.hasNext()	example3()

AllegroGraph Code Conversion Notes

Table of Contents

Converting AllegroGraph 3.x to AllegroGraph 4.7

Database Conversion

ag3-export

ag4-import

Lisp API

Lisp API elements that changed.

Lisp API elements that are new in 4.x

Lisp API elements that became obsolete in 4.x

Lisp API elements that did not change from 3.x to 4.x

Python API

AllegroGraphServer Class

Obsolete Methods

Changed Methods

New Methods

Catalog Class

Obsolete Methods

Changed Methods

New Methods

Repository Class

Obsolete Methods

Changed Methods

New Methods

RepositoryConnection Class

Obsolete Methods

Changed Methods

New Methods

Query Class

RepositoryResult Class

Statement Class

ValueFactory Class

Java Base API

Java Sesame API

Java Jena API