Table of Contents

Converting AllegroGraph 3.x to AllegroGraph 4.13.1

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

Catalog Class

Repository Class

RepositoryConnection Class

Query Class

RepositoryResult Class

Statement Class

ValueFactory Class

Java Base API

Java Sesame API

Java Jena API

Converting AllegroGraph 3.x to AllegroGraph 4.13.1

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.

Database Conversion

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

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.13.1 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.13.1 database. Reads from stdin, the expected format is that printed by ag3-export. Status messages are printed to stderr during export.

AllegroGraph Server 4.13.1 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.

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:

add-geospatial-subtype-to-db subtype  &optional  db
function
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.

clear-type-mappings &key  db  keep-automatic-type-mappings
function

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-triple-stores
function
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-triple-store &key  db  if-closed  commit  ensure-not-lingering
function

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.

collect-cursor cursor  &key  transform  retain
function

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) 

The :retain keyword argument controls whether or not cursor will be discarded at the end of iteration. If it is false (which is the default) then the cursor will be discarded.

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-triple-store name  &rest  args  &key  if-exists  catalog  port  user  password  exclude-standard-ontology-uris  triple-store-class  with-indices
function

Create a new triple store with the given name. name must be a string. The following characters cannot be used in name:

\ / ~ : Space $ { } < > * + [ ] | 

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, :password, :port, and :server (except 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.

delete-triple id  &key  db
function

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-triple-store db-or-name  &rest  args  &key  if-does-not-exist  triple-store-class
function

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 &key  s  p  o  g  s-end  p-end  o-end  g-end  filter  db
function

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.

freetext-get-triples expression  &key  index  db  sorted-p
function

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.

freetext-get-unique-subjects expression  &key  db  index
function

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.

get-triple &key  s  p  o  g  db  return-encoded-triples  return-non-encoded-triples  filter  triple
function

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.

get-triples &key  s  p  o  g  s-end  p-end  o-end  g-end  db  return-encoded-triples  return-non-encoded-triples  filter
function

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.

get-triples-geospatial-bounding-box subtype  p  x-min  x-max  y-min  y-max  &key  db  use-g
function
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.

get-triples-geospatial-radius subtype  pred  x  y  radius  &key  db  use-g
function

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.

get-triples-haversine-km subtype  pred  lon  lat  radius-in-km  &key  db  use-g
function
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.

get-triples-haversine-miles subtype  pred  lon  lat  radius-in-miles  &key  db  use-g
function

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.

get-triples-haversine-radians subtype  pred  lon  lat  radius-in-radians  &key  db  use-g
function

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.

get-triples-inside-polygon subtype  predicate  polygon  &key  db  use-g
function
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.

get-triples-list &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  return-cursor
function

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.

  • return-cursor - if true or if a cursor is passed in using the cursor argument, then the cursor used by get-triples-list is returned as the second value. If nil (which is the default), then the cursor that get-triples-list creates will be discarded.

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

intern-literal value  &key  language  datatype  db  upi
function

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.

intern-resource uri  &key  namespace  db  upi
function

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.

See also resource.

3.x to 4.x code conversion notes:

3.x: (uri &key db upi) <br>  
4.x: (uri &key namespace db upi) 

namespace lets you supply the URI in two parts, a namespace and local name bound to uri.

load-nquads source  &rest  args  &key  db  graph  verbose  preserve-strings  external-format  relax-syntax  commit  continue-on-errorp  &allow-other-keys
function

Add triples from source (in N-Quads format) to the triple store.

Returns (as multiple values) the count of triples loaded and the UPI of the graph into which quads missing the graph field were loaded. (load-nquads is following load-ntriples here). If all nquads have a graph field specified, the second return value has no meaning, but the graph field is optional in nquads so some (or all) may be missing and the second return value is then relevant. See load-ntriples for more details on the second return value, particularly when the value of the graph argument is :source and some nquads do not have a graph specified.

  • source - can be a stream, a pathname to an N-Quads file, a file URI, an HTTP URI or a string that can be coerced into a pathname. Source can also be a list of any of these things. In this case, each item in the list will be imported in turn. When adding statements to a remote-triple-store, a URI source argument will be fetched directly by the server. All other source types are retrieved and delivered to the server via the client interface.

    In the case where a list of sources is being loaded and the graph argument is :source, each source in the list will be associated with the URI specifying that source, which will be used as the graph for nquads which do not have the graph specified. In this case, the second return value will be nil.

  • :db - specifies the triple-store into which nquads will be loaded. This defaults to the value of *db*.

  • :graph - for any nquads which do not have a graph specified (the graph is optional in a nquad), this argument specifies the graph to which they are loaded. The argument defaults to nil which is interpreted as db's default graph. This argument does not affect nquads which do have a graph specified. If supplied, it can be:

    • a string representing a URIref, or a UPI or future-part encoding a URIref, which adds the triples in source to a graph named by that URI

    • the keyword :source (in which case the source argument will be interned as a URI and the loaded nquads which do not have the graph specified will be added to a graph named by that URI). This has the effect of associating the file or URL of source with the incoming graphless nquads.

The following keyword parameters can be used to control the loading process:

  • :verbose - specifies whether or not progress information is printed as triples are loaded. It defaults to nil.

  • :preserve-strings - determine whether or not to save the strings of a triple's object field when the object can be encoded directly into the triple. If true (the default) then the strings will be saved. If false, then only the encoded values will be preserved (this may prevent exact round-trips if data is coerced during the encoding process).

  • :commit - controls whether and how often commit-triple-store is called while loading. This can be nil for no commit, t for commit at the end of the load or a whole number to commit whenever more than that number of triples have been added and again at the end of the load.

  • :continue-on-error-p - determine how the parser should behave if it encounters an error parsing or adding a triple. It can be one of:

    • nil - meaning to raise the error normally,

    • t - meaning to ignore the error and continue parsing with the next line in the source,

    • a function of four arguments: a parsing helper data structure, the line in the source where the problem was encountered, the condition that caused the error and the arguments (if any) to that condition.

  • You can use continue-on-error-p to print all of the problem lines in a file using something like

    (load-nquads  
     "source"  
     :continue-on-errorp  
     (lambda (helper source-line condition &rest args)  
       (declare (ignore helper args))  
       (format t "~&Error at line ~:6d - ~a" source-line condition)))  
     
    

3.x to 4.x code conversion notes:

3.x: (source &rest args &key (db \*db\*) (default-graph nil) (graph nil)  
     (verbose (ag-property verbose)) (always-save-string-literals t)  
     external-format (continue-on-errorp nil))  
4.x: (source &rest args &key (db \*db\*) (graph nil) (verbose nil)  
     (preserve-strings nil) external-format  
     relax-syntax-for-bogus-btc-data (continue-on-errorp nil) &allow-other-keys) 

Use graph nil instead of default-graph t to designate the default graph. always-save-string-literals has been replaced by preserve-strings_.
relax-syntax-for-bogus-btc-data has been added.

load-nquads-from-string string  &rest  args  &key  db  graph  verbose  preserve-strings  commit  continue-on-errorp
function

Add the triples in string (in N-Quads format) to the triple store.

Returns (as multiple values) the count of nquads loaded and the UPI of the graph into which the quads were loaded (for those quads which do not have the graph specified).

See load-nquads for details on the parameters.

3.x to 4.x code conversion notes:

3.x: (string &rest args &key db default-graph graph verbose  
     always-save-string-literals continue-on-errorp)  
4.x: (string &rest args &key db graph verbose  
     preserve-strings continue-on-errorp) 

Use graph nil instead of default-graph t to designate the default graph. always-save-string-literals has been replaced by preserve-strings_.

load-ntriples source  &rest  args  &key  db  graph  verbose  preserve-strings  external-format  relax-syntax  continue-on-errorp  commit  &allow-other-keys
function

Add triples from source (in N-Triples format) to the triple store.

Returns (as multiple values) the count of triples loaded and the UPI of the graph into which the triples were loaded.

  • source - can be a stream, a pathname to an N-Triples file, a file URI, an HTTP URI or a string that can be coerced into a pathname. Source can also be a list of any of these things. In this case, each item in the list will be imported in turn. When adding statements to a remote-triple-store, a URI source argument will be fetched directly by the server. All other source types are retrieved and delivered to the server via the client interface.

    In the case where a list of sources is being loaded and the graph argument is :source, each source in the list will be associated with the URI specifying that source, and that will be used as the graph of the triples loaded from that source. In this case, the second return value will be nil.

  • :db - specifies the triple-store into which triples will be loaded. This defaults to the value of *db*.

  • :graph - the graph to which the triples from source will be placed. It defaults to nil which is interpreted as db's default graph. If supplied, it can be:

    • a string representing a URIref, or a UPI or future-part encoding a URIref, which adds the triples in source to a graph named by that URI

    • the keyword :source (in which case the source argument will be interned as a URI and the loaded triples added to a graph named by that URI). This has the effect of associating the file or URL of source with the new triples.

The following keyword parameters can be used to control the loading process:

  • :verbose - specifies whether or not progress information is printed as triples are loaded. It defaults to nil.

  • :preserve-strings - determine whether or not to save the strings of a triple's object field when the object can be encoded directly into the triple. If true (the default) then the strings will be saved. If false, then only the encoded values will be preserved (this may prevent exact round-trips if data is coerced during the encoding process).

  • :commit - controls whether and how often commit-triple-store is called while loading. This can be nil for no commit, t for commit at the end of the load or a whole number to commit whenever more than that number of triples have been added and again at the end of the load.

  • :continue-on-error-p - determine how the parser should behave if it encounters an error parsing or adding a triple. It can be one of:

    • nil - meaning to raise the error normally,

    • t - meaning to ignore the error and continue parsing with the next line in the source,

    • a function of four arguments: a parsing helper data structure, the line in the source where the problem was encountered, the condition that caused the error and the arguments (if any) to that condition.

You can use continue-on-error-p to print all of the problem lines in a file using something like

    (load-ntriples  
     "source"  
     :continue-on-errorp  
     (lambda (helper source-line condition &rest args)  
       (declare (ignore helper args))  
       (format t "~&Error at line ~:6d - ~a" source-line condition)))  
 

3.x to 4.x code conversion notes:

3.x: (source &rest args &key (db \*db\*) (default-graph nil) (graph nil)  
     (verbose (ag-property verbose)) (always-save-string-literals t)  
     external-format nquads (continue-on-errorp nil))  
4.x: (source &rest args &key (db \*db\*) (graph nil) (verbose nil)  
     (preserve-strings nil) external-format relax-syntax-for-bogus-btc-data  
     (continue-on-errorp nil) &allow-other-keys) 

Use graph nil instead of default-graph t to designate the default graph. always-save-string-literals has been replaced by preserve-strings_.
relax-syntax-for-bogus-btc-data has been added.

load-ntriples-from-string string  &rest  args  &key  db  graph  verbose  preserve-strings  continue-on-errorp  commit
function

Add the triples in string (in N-Triples format) to the triple store.

See load-ntriples for details on the parameters.

3.x to 4.x code conversion notes:

3.x: (string &rest args &key db default-graph graph verbose  
     always-save-string-literals nquads continue-on-errorp)   
4.x: (string &rest args &key db graph verbose preserve-strings continue-on-errorp) 

Use graph nil instead of default-graph t to designate the default graph. always-save-string-literals has been replaced by preserve-strings_.

load-rdf/xml source  &rest  args  &key  db  base-uri  graph  verbose  commit  use-rapper-p  &allow-other-keys
function

Add triples from an RDF/XML file to a triple-store. The arguments are (some do not appear in the argument list but are accepted because &allow-other-keys is specified):

  • source: a string or pathname identifying an RDF/XML file, or a stream.

  • :db - specifies the triple-store into which triples will be loaded; defaults to the value of *db*.

  • :base-uri - this defaults to the name of the file from which the triples are loaded. It is used to resolve relative URI references during parsing. To use no base-uri, use the empty string "".

  • :graph - the graph to which the triples from source will be placed. It defaults to nil which is interpreted as db's default graph. If supplied, it can be:

    • a string representing a URIref, or a UPI or future-part encoding a URIref, which adds the triples in source to a graph named by that URI

    • the keyword :source (in which case the source argument will be interned as a URI and the loaded triples added to a graph named by that URI). This has the effect of associating the file or URL of source with the new triples.

  • :use-rapper-p - If use-rapper-p is true, then the RDF/XML file will be piped through the open source tool rapper using run-shell-command. Obviously, rapper must be both installed and in your path for this to work. If rapper is not in your path, you can supply it explicitly as the value of use-rapper-p.

  • :resolve-external-references - if true, the external references in source will be followed. The default is nil.

3.x to 4.x code conversion notes:

3.x: (source &rest args &key (db \*db\*) base-uri (default-graph nil)  
     graph (verbose (ag-property verbose)) use-rapper-p)  
4.x: (source &rest args &key (db \*db\*) base-uri graph (verbose nil)  
     use-rapper-p &allow-other-keys) 

Use graph nil instead of default-graph t to designate the default graph.

load-rdf/xml-from-string string  &rest  args  &key  db  base-uri  graph  commit
function

Treat string as an RDF/XML data source and add it to the triple-store. For example:

   (load-rdf/xml-from-string  
    "<?xml version=\"1.0\"?>  
<rdf:RDF xmlns:rdf=\"http://www.w3.org/1999/02/22-rdf-syntax-ns#\"  
         xmlns:ex=\"http://example.org/stuff/1.0/\">  
  <rdf:Description rdf:about=\"http://example.org/item01\">  
    <ex:prop rdf:parseType=\"Literal\"  
             xmlns:a=\"http://example.org/a#\"><a:Box required=\"true\">  
         <a:widget size=\"10\" />  
         <a:grommit id=\"23\" /></a:Box>  
    </ex:prop>  
  </rdf:Description>  
</rdf:RDF>  
") 

See load-rdf/xml for details on the parser and the other arguments to this function.

3.x to 4.x code conversion notes:

3.x: (string &rest args &key db base-uri default-graph graph)  
4.x: (string &rest args &key db base-uri graph) 

Use graph nil instead of default-graph t to designate the default graph.

make-tutorial-store &key  apply-reasoner-p
function

Close any current triple-store and create a new empty one.

  • :apply-reasoner-p - If true (the default), then the new triple-store will use RDFS++ reasoning. If nil, then the triple-store will have no reasoning enabled.

The new triple-store will be bound to *db* and is also returned by make-tutorial-store.

3.x to 4.x code conversion notes:

3.x: (&key temporary-directory apply-reasoner-p use-reasoner)  
4.x: (&key temporary-directory apply-reasoner-p) 

use-reasoner has been deprecated.

open-triple-store name  &rest  args  &key  read-only  catalog  port  user  password  triple-store-class
function

Open an existing triple store (previously created using create-triple-store) with the given name.

open-triple-store takes numerous keyword arguments. The allowed arguments vary depending on the class of triple-store being opened. For example, a remote-triple-store usually requires a :user and :password (though not for anonymous access if it is allowed) and perhaps a port and server (though those arguments do have defaults which may suffice) whereas a local triple-db does not. :user, :password, and :server can be specified with the individual arguments or combined in a :url argument.

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

  • :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.

  • :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).

  • :triple-store-class - the kind of triple-store to open. If left unspecified, then triple-db will be used. Depending on the class of the triple-store opened, other parameters may be possible or required.

  • :read-only - if true, then the triple-store will be opened read-only.

  • :https-verification - See the description of this argument in the documentation for create-triple-store.

Returns a triple store object and sets the value of the variable *db* to that object. If the named triple store is already open, open-triple-store returns a new object connected to the same store.

See Lisp Quick Start for an example of creating and opening triple stores.


3.x to 4.x code conversion notes:

3.x: (name &rest args &key directory read-only read-only-p)  
4.x: (name &rest args &key read-only catalog port user password triple-store-class) 

The function has a much-enlarged list of keyword arguments.

serialize-ntriples from  to  &key  nquads  base-uri  if-exists  if-does-not-exist
function

Write an N-Triples representation of from to to. from should be a triple store, a list of triples, or a cursor. to should be a stream, a file path to open for writing, t (meaning *standard-output*), or nil (return a string).

if-exists and if-does-not-exist are arguments to the Common Lisp open function which apply when to is a filename.

If base-uri is provided, it is used to generate a “baseURI:” comment at the start of the serialization. This comment is expected by TopBraid Composer.

base-uri can be t, in which case a generated UUID URN is used, or a string, UPI, or future-part naming a URI. It can also be a triple-store instance; in this case, a UUID URN associated with the store is used. For persistent stores this value should remain constant.

The nquads argument causes this function to emit N-Quads instead of N-Triples. It is used by the function serialize-nquads.

In other respects this function behaves like print-triples.

3.x to 4.x code conversion notes:

3.x: (from to &key base-uri if-exists if-does-not-exist)  
4.x: (from to &key nquads base-uri if-exists if-does-not-exist) 

nquads changes the output to nquads instead of ntriples.

triple-store-exists-p name  &rest  args  &key  triple-store-class
function

Returns true if the triple-store with the given name exists.

You can use the triple-store-class argument to specify the kind of store you are trying to check. Like open-triple-store and create-triple-store, triple-store-exists-p takes additional keyword arguments that vary depending on this class. For example, checking 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: (name &rest args &key directory triple-store-class)  
4.x: (name &rest args &key triple-store-class) 

name must now be the full directory path to the triple store.

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.

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:

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

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()