List the catalogs on the local AllegroGraph server running on port.

This function is deprecated, please refer to catalog-names instead.

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.

To conserve resources, makes the database instance and its child processes exit if the instance is unused (nobody has the corresponding triple store open). This function returns nothing.

Normally unused database instances linger for InstanceTimeout seconds to speed up subsequent open operations.

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, ensure-not-lingering 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. Also, see the ensure-not-lingering keyword argument to close-triple-store.

Copy triples from source to target-db.

source can be a triple-store, a cursor, a list or an array. If the source-db can be determined from source (e.g., if source is a triple-store or cursor), then source-db is ignored. If source is a list or array then the triples are assumed to exist in source-db, which defaults to *db*.

target-db should be an open and writable triple-store.

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.

The name of the triple-store db (read-only).

This is set when the triple-store is created or opened.

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.

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.

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.

Undo any local changes to db and synchronize with the most up-to-date server version.

• :db - the triple-store to rollback; defaults to the current value of *db*.

Returns the number of triples in a triple store. The :db keyword argument specifies the triple store to use, either by name or a triple store object. It defaults to the value of *db*.

Note that reasoning triple-stores do not report accurate triple-counts (doing so might take an inordinate amount of time!). The count returned will be a count of the triples in the ground store.

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.

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

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

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

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

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

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

• :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 this number of triples have been added.

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

See load-nquads for details on the parameters.

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.

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

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

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

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

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

• :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 this number of triples have been added.

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

See load-ntriples for details on the parameters.

Add triples from the named RDF/XML file to the triple-store. The additional arguments are:

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

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.

Load a TriX document into the triple store named by db.

• source - a string or pathname identifying a file, or a stream.

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

• :verbose - if true, information about the load progress will be printed to *standard-output*.

• :default-graph - a future-part or UPI that identifies a graph, or nil. If it is non-null, any graphs in the TriX document that are equal to the given URI will be treated as the default graph in db.

default-graph can also be the symbol :source, in which case namestring is called on the source and treated as a URI.

• :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 this number of triples have been added.

We have implemented a few extensions to TriX to allow it to represent richer data:

• Graphs can be named by <id>, not just <uri>. (A future revision might also permit literals.)

• The default graph can be denoted in two ways: by providing <default/> as the name for the graph; or by providing a graph URI as an argument to load-trix.

• In the interest of generality, the predicate position of a triple is not privileged: it can be a literal or blank node (just like the subject and object), not just a URI.

Load a string containing data in TriX format into db

• string - a string containing TriX data

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

• :verbose - if true, information about the load progress will be printed to *standard-output*.

• :default-graph - a future-part or UPI that identifies a graph, or nil. If it is non-null, any graphs in the TriX document that are equal to the given URI will be treated as the default graph in db.

• :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 this number of triples have been added.

See load-trix for more details.

Add triples from the named Turtle file to the triple-store. The additional arguments are:

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

Treat string as a Turtle data source and add it to the triple-store.

See load-turtle for details.

Add a triple to the db

The added triple will have the given subject, predicate and object.

• :db - the triple-store into which to add the triple; this defaults to *db*.

• :g - the graph for the new triple. If not specified, then the triple will be added to the default-graph (see default-graph-upi).

• :preserve-strings - controls whether typed-literals will have only their encoded value added to the store or whether an additional hashed version of the triple will also be added. The defaults to nil. For example, if I evaluate:

  (add-triple !ex:gary !ex:age !"46"^^xsd:byte) 

then only a single triple will be added to the store. If I instead

(add-triple !ex:gary !ex:age !"46"^^xsd:byte :preserve-strings t) 

then there will be two triples added: one whose object is the encoded value 46 and the other whose object is a hashed UPI which points to the string "46"^^<http://www.w3.org/2001/XMLSchema#byte>.

add-triple returns the triple-id of the new triple.

Create a new future-part with the provided values.

• string - the string out of which to create the part.

• :language - If provided, language should be a valid RDF language tag.

• :datatype - If provided, 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.

Return the provided string as a future-part naming a resource.

If namespace is provided, then string will be treated as a fragment and the future-part returned will be the URIref whose prefix is the string to which namespace maps and whose fragment is string. I.e., if the namespace prefix rdf maps to <http://www.w3.org/1999/02/22-rdf-syntax-ns#>, then the parts created by

(resource "Car" "rdf") 

and

(resource "http://www.w3.org/1999/02/22-rdf-syntax-ns#Car") 

will be the same.

Returns true if upi is a blank node and nil otherwise. For example:

> (blank-node-p (new-blank-node))  
t  
> (blank-node-p (literal "hello"))  
nil 

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.

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.

Sets up an encoding for prefix, which must be a string, using format, which should be a template (also a string) indicating with brackets, braces, etc. the allowable suffixes. Returns two values: the index of this encoding (a positive integer) and t or nil. t is returned if the encoded-id definition is registered or if the template is modified. nil is returned if the prefix is already registered and the template is unchanged. (This allows the same registration form to be evaluated more than once.) You can redefine the template by calling register-encoded-id-prefix with the same prefix and the new template. But an error will be signaled if you do that after triples have been created using an encoded-id from that prefix.

See Encoded IDs for further information.

Examples:

(register-encoded-id-prefix   
    "http://www.franz.com/managers"     
    "[0-9]{3}-[a-z]{3}-[0-9]{2}")  
RETURNS  
3 ;; you will likely see a different value  
t  
 
If you run the same form again:  
 
(register-encoded-id-prefix   
    "http://www.franz.com/managers"     
    "[0-9]{3}-[a-z]{3}-[0-9]{2}")  
RETURNS  
3 ;; same value as before  
nil ;; meaning no action was taken  
 
If you modify the template (you can only do this when no stored  
triple uses en encoded-id from the prefix):  
 
(register-encoded-id-prefix   
    "http://www.franz.com/managers"     
    "[0-9]{3}-[a-z]{3}-[0-9]{4}") ;; last value is 4 rather than 2  
RETURNS  
3 ;; same value as before  
t ;; meaning made the change 

Returns upi after modifying it to be the next id for the specified encoded-id prefix. The system maintains an internal order of encoded-ids for a prefix. (This order may not be the obvious one, but it will run over all possible ids for a prefix.) upi should be a upi and will be modified. If you do not want to modify an existing upi, create a new one with (make-upi). Do not use this function if you have created an id for prefix directly using the @# encoding as doing so may create duplicate ids (which you may think are distinct).

db defaults to *db*.

Example:

triple-store-user(59): (register-encoded-id-prefix   
    "http://www.franz.com/department"     
    "[0-9]{4}-[a-z]{3}-[0-9]{2}")  
5  
t  
triple-store-user(60): (setq d1  
                            (next-encoded-upi-for-prefix  
                               "http://www.franz.com/department"  
                               (make-upi)))  
{http://www.franz.com/department@#0000-aaa-00}  
triple-store-user(61): (setq bu (make-upi))  
#(49 2 238 3 16 0 0 0 161 210 ...)  
triple-store-user(62): (setq d2  
                         (next-encoded-upi-for-prefix  
                            "http://www.franz.com/department" bu))  
{http://www.franz.com/department@#0000-aaa-01}  
triple-store-user(63): bu        ;; bu is modified  
{http://www.franz.com/department@#0000-aaa-01}  
triple-store-user(64): d2  
{http://www.franz.com/department@#0000-aaa-01}  
triple-store-user(65): (setq d3  
                          (next-encoded-upi-for-prefix  
                             "http://www.franz.com/department" bu))  
{http://www.franz.com/department@#0000-aaa-02}  
triple-store-user(66): bu  ;; bu is modified  
{http://www.franz.com/department@#0000-aaa-02}  
triple-store-user(67): d2  ;; so is d2.  
{http://www.franz.com/department@#0000-aaa-02} 

Gets the list of encoded ids (as returned by collect-encoded-id-prefixes) and applies fn to each element of that list. Since each list element is itself a list of three elements, fn must be or name a function that accepts three arguments.

Example:

(defun foo (&rest args)  
  (dolist (i args)  
  (print i)))  
 
(map-encoded-id-prefixes 'foo)  
 
"http://www.franz.com/employees"  
"[0-9]{3}-[a-z]{3}-[0-9]{2}"  
2  
"http://www.franz.com/managers"  
"[0-9]{4}-[a-z]{3}-[0-9]{2}"  
3  
nil 

Get the graph UPI of a triple.

Use (setf graph) to change the UPI. If the upi argument is supplied, then the triple's graph will be copied into it. If it is not supplied then a new UPI will be created.

Get the object UPI of a triple.

Use (setf object) to change the UPI. If the upi argument is supplied, then the triple's object will be copied into it. If it is not supplied then a new UPI will be created.

Get the predicate UPI of a triple.

Use (setf predicate) to change the UPI. If the upi argument is supplied, then the triple's predicate will be copied into it. If it is not supplied then a new UPI will be created.

Get the subject UPI of a triple.

Use (setf subject) to change the UPI. If the upi argument is supplied, then the triple's subject will be copied into it. If it is not supplied then a new UPI will be created.

Copy a triple.

• triple - the triple to copy

• new - (optional) If supplied, then this must be a triple and the copy of triple will be placed into it. Otherwise, a new triple will be created.

This function is useful if you want to keep a reference to a triple obtained from a cursor returned by query functions such as get-triples since the cursor reuses the triple data structure for efficiency reasons.

Create a copy of a UPI.

• upi - the UPI to copy.

Creates and returns a new triple data structure.

The subject, predicate, object and graph slots will have UPIs whose upi-type-code is +unencoded-upi+ and the triple-id will be zero.

Decodes UPI and returns the value, the type-code and any extra information as multiple values.

• upi - the UPI to decode

• :db - specifies the triple-store from which the UPI originates.

The value, type-code, and extra information are interpreted as follows:

• value - a string, integer, or float representing the contents of the UPI
• type-code - an integer corresponding to one of the defined UPI types (see supported-types for more information). You can use type-code->type-name to see the English name of the type.
• extra - There are three disjoint sets of literals in RDF:
  1. "simple literals" -- a string.
  2. literals with datatypes
  3. literals with language annotations.

A literal cannot have both a language and a datatype; if a literal has type-name :literal-typed (i.e., its type-code is 2), then the extra value is a datatype URI; if its type-code is 3, then extra will be the language code.

Examples:

> (upi->value (value->upi 22 :byte))  
22  
18  
nil  
 
> (upi->value (upi (literal "hello" :language "en")))  
"hello"  
3  
"en" 

See value->upi for additional information.

Returns true if upi has type-code type-code.

• upi - a UPI

• type-code - either a numeric UPI type-code or a keyword representing a type-code. See type-code->type-name and type-name->type-code for more information on type-codes and their translations.

Returns a UPI that encodes value using type encode-as.

encode-as can be a type-code or a type-name (see supported-types and type-name->type-code for details. If a upi keyword argument is not supplied, then a new UPI will be created. See upi->value for information on retrieving the original value back from an encoded UPI.

Note that value->upi can not create hashed UPIs (i.e., UPIs whose value must be stored in the string dictionary. To create these, use intern-resource and intern-literal.

Return whatever is extra in the string of the future-part. The meaning of extra depends on the type of the part:

• resource - the prefix (if applicable)
• literal-typed - the datatype
• literal-language - the language
• other - the value will always be nil

See future-part-type and future-part-value if you need to access the part's other parts.

Return the value of the future-part. The meaning of value depends on the type of the part:

• resource - the namespace (if any)
• literal-typed - the literal without the datatype
• literal-language - the literal without the language
• other - the value will always be nil

See future-part-type and future-part-extra if you need to access the others parts (no pun intended) of the part.

Create a 'future' part that will intern itself in new triple stores as necessary.

• :type - one of :node, :literal, :literal/lang or :literal-typed.

• :value and :extra - the contents of the part. Their meaning changes depending on type. If type is:

  • :node - value is the string representation of the URIref and extra must be nil.

  • :literal - value is the string contents of the literal and extra must be nil.

  • :literal/lang - value is the string contents of the literal and extra specifies the language.

  • :literal-typed - value is the string contents of the literal and extra specifies the datatype.

Returns the UPI associated with the future-part future-part.

If the future-part uses namespaces, then calling upi will resolve the namespace mapping. An error will be signaled if upi is called and there is no namespace mapping defined. You can use the errorp keyword parameter to disable the error and return nil instead.

Moves cursor forward to the next record in the collection.

Returns t if there was another row on which to move and nil if the cursor is exhausted. I.e., if cursor-next returns t, then cursor-row will return a record.

Note that cursor-row and cursor-next are lower-level cursor manipulation routines. You may be better served by using collect-cursor, count-cursor, map-cursor and iterate-cursor.

Returns the next record from the cursor. Data structures holding the record might be reused, so if you want to hold onto, for example, a triple for use after you advance the cursor, use the function copy-triple to make a copy of the value returned by cursor-next-row

Note that cursor-row, cursor-next and cursor-next-row are lower-level cursor manipulation routines. You may be better served by using collect-cursor, count-cursor, iterate-cursor and map-cursor.

Returns the record that cursor is currently pointing at.

If the cursor is exhausted, then cursor-row returns nil.

Note that cursor-row and cursor-next are lower-level cursor manipulation routines. You may be better served by using collect-cursor, count-cursor, map-cursor and iterate-cursor.

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.

Iterate over the triples in cursor while applying the function fn to each one. Use the count keyword to limit the maximum number of triples that map-cursor visits. In each iteration fn is applied to the current triple and to the list of arguments in args.

map-cursor reuses a single triple as it iterates so make sure to use copy-triple if you want to retain any of the triples you visit.

The function returns the number of triples visited.

Collect the triples from cursor into a list.

Uses collect-cursor with a transform of copy-triple to return a fresh list of the triples in cursor. collect-triples assumes that cursor iterates over triples. Returns the list.

Return the number of triples in db matching the query. db defaults to *db*.

The keyword arguments s, p, o, g, s-end, p-end, o-end and g-end are used as in get-triples.

Note that the count includes deleted triples, encoded triples and unencoded triples. Finally, no filter can be used with a count query.

Return an estimated count of the number of triples in db matching the query. db defaults to *db*.

The keyword arguments s, p, o, g, s-end, p-end, o-end and g-end are used as in get-triples.

Note that the estimated count may include deleted triples.

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

Locate the triple whose triple-id is id and return it. Return nil if there is no triple associated with id. The keyword argument db can be used to specify the triple-store in which to search. It defaults to the current triple-store, *db*. get-triple-by-id allocates a new triple (using make-triple). You can prevent this by passing in your own triple using the keyword argument :triple. The data in the triple you pass in will by overwritten.

Note that this function can return a triple and then later (after you've done a commit or rollback) return nil because another user removed it. These removals are transactional, which means the behavior can change (from returning a triple to returning nil) only after a commit or a rollback.

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.

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.

Print information about part down to a maximum depth of maximum-depth using the format format. Triples for which part is an object and their children will be printed. See part->string for information about part printing. See pprint-subject to display information based on objects rather than subjects.

Note that pprint-object is designed to show the actual triples in a store. It uses ground-triple-store to remove one layer of reasoning from db. db defaults to *db*.

Print information about part down to a maximum depth of maximum-depth using the format format. Triples for which part is a subject and their children will be printed. See part->string for information about part printing. See pprint-object to display information based on subjects rather than objects.

Note that pprint-subject is designed to show the actual triples in a store. It uses ground-triple-store to remove one layer of reasoning from db. db defaults to *db*.

Analyze the index usage for query using technique.

Determine which indices in query language language will access using technique technique.

Currently supports only SPARQL with one of the following techniques:

• static - analyze the query algebracially; fast but can be wrong.
• executed - execute the query and monitor actual index usage; correct but can be slow.

The results are returned as lists of sub-lists where each sub-list looks like:

(:desired (flavor mode) :actual (flavor mode)) 

where

• flavor - an index flavor
• mode - optimal, suboptimal or full

The first part of the list (:desired) is what AllegroGraph would most like assuming that every index flavor was available. The second part (:actual) is what AllegroGraph actually got given the current triple-store.

If supplied, duration specifies how long to run the analysis. The standard behavior is to run for as long as necessary.

Gets the size of the spogi cache. .

The cache size determines the maximum number of subjects that can be help in the cache at once. The value of *default-spogi-cache-size* is used for newly created triple-stores.

You can use (setf spogi-cache-size) to change the size of the cache. For example:

(setf (spogi-cache-size *db*) 10000) 

Returns true if the spogi cache is enabled for db.

You can use (setf spogi-cache-enabled-p) to turn caching on and off. When using the setf method, you can use a boolean or a whole number. If you use a whole number, it has the same effect as turning caching on and setting the spogi-cache-size to that value. For example:

(setf (spogi-cache-enable *db*) t)	;turn the cache on  
(setf (spogi-cache-enable *db*) 5000)	;turn the cache on and set it to 5000 

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.

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.

Returns a keyword (or nil) specifying whether the store suppresses duplicate triples at commit time.

This setting specifies the way AllegroGraph manages duplicates at commit time:

• nil - duplicate triples are not suppressed, they are committed as usual.

• :spo - do not commit any triples whose subject, predicate and object parts are duplicates of other triples.

• :spog - do not commit any triples whose subject, predicate, object and graph parts are duplicates of other triples.

With a non-nil setting, calling commit-triple-store will prevent any additional duplicate triples from being added to the store at commit time.

Changing this setting does not affect any potential duplicates that may already be present in the store. See delete-duplicate-triples.

Print a triple returned by cursor-next-row or get-triples-list.

Returns the triple printed.

The keyword argument :format, which defaults to :ntriples, specifies how the triple should be printed. The value :ntriples specifies that it should be printed in N-Triples syntax. The value :long indicates that the string value of the part should be used. And the value :concise causes it to use a more concise, but possibly ambiguous, human-readable format.

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.

Just like serialize-ntriples but emits quads in N-Quads format.

See serialize-ntriples for more information on the arguments to this function.

Write from, which should be a triple store, a list, or a cursor, to to, which should be a stream, file path, t (print to *standard-output*), or nil (return a string).

If from is a triple-store or a list of triples, and prepare-namespaces-p is t, it is first traversed to build a hash of namespaces to prefixes for all properties in the store. The value of db.agraph::*namespaces* is used as a seed.

If you can ensure that every property used in the triple-store has a defined prefix, you can pass nil for prepare-namespaces-p to gain a speed improvement from omitting this phase.

If error-on-invalid-p is t, the serializer will throw an error if it encounters a type or predicate that it cannot abbreviate for RDF/XML. Ordinarily a local namespace declaration is included in such a property element instead.

If a namespace prefix table is built, it will be returned as the second value.

If from is a cursor, it cannot be traversed multiple times, so prepare-namespaces-p is ignored. If a property is encountered that cannot be abbreviated with the current available prefixes, an error will be signaled or a local namespace declaration generated instead.

Such local namespace declarations are verbose, and so providing a thorough namespace hash is preferred.

If a predicate cannot be abbreviated as an XML QName, your graph cannot be serialized in RDF/XML. An error will be raised in this case.

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

xml-base can be t, in which case a generated UUID xml:base attribute is written into the serialized RDF/XML, 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.

If xml-base is nil, no xml:base attribute will appear in the output.

Note that xml-base values will be escaped, but they will not be checked for validity (i.e., you can successfully provide an invalid URI to this function).

If memoize-abbrev-lookups-p is t, a upi-hash-table is built to store the mappings between resources in the store and string abbreviations. This hash-table will contain as many entries as there are types and properties in the data to be serialized. For some datasets disabling this caching will yield a significant reduction in space usage in exchange for a possible loss of speed.

If indent is non-nil, then it specifies the initial indentation of elements.

If nestp is t, then (subject to the order of triples in the triple store) some nesting of RDF/XML elements will be applied. nestp of nil will cause a flat tree to be produced, where each resource is its own top-level element. You should not rely on this alone for the purposes of processing RDF data with XML tools.

If output-types-p is t, then additional queries will be performed for each resource to decorate the RDF/XML with types. If nil, then rdf:type elements alone will be used.

Because of rounding errors and other conversion issues, the RDF/XML serializer is not guaranteed to round-trip correctly with value-encoded literals (i.e. literals stored as encoded UPIs. See the reference guide section on type mapping for more information on encoded UPIs).

Serialize source according to exchange-of-named-rdf-graphs. Serialization will probably open at least as many files as there are graphs in the source.

Returns the manifest path and the number of graphs saved.

If single-stream-p only a single file is open at any one time. This is slower, but guaranteed not to fail with large numbers of graphs.

Write from, which should be a triple-store, a list, or a cursor, to to, which should be a stream, file path, t (print to *standard-output*), or nil (return a string).

• :if-exists and :if-does-not-exist - apply when from is a filename. They are passed along to the open function are used there.

• :indent - if non-nil, then this specifies the initial indentation of elements.

Write source, which should be a triple store, cursor, or list of triples, to output. output must be t (equivalent to *standard-output*), nil (which returns the serialization as a string), a string or pathname, which will be opened for output respecting the if-exists and if-does-not-exist arguments, or a stream.

The resulting output is produced according to the value of constraints. This must be one of the following symbols:

• :canonical: each graph appears once in the output. All graphs and triples are sorted lexicographically. All graphs are named, even when a name must be generated.

• :collated: each graph appears once in the output.

• :lenient (or nil, the default): graphs can appear multiple times in the output. No sorting occurs. load-trix can consume this, but not all other TriX parsers necessarily can.

The value of the default-graph argument applies when the default graph has to be serialized. If it is nil, the default, the AllegroGraph-specific <default/> element is used. If it is non-null, it should be a URI string or a valid part that will be substituted into the output.

Ensure that db indexes triples on flavor. db defaults to *db*.

Note that the new index will not be available until after commit (see commit-triple-store).

Ensure that db does not index triples on flavor. db defaults to *db*.

Note that the index will not be dropped until after commit.

Return a list of the index flavors currently active for db. db defaults to *db*.

Use add-index and drop-index to manipuate a store's active indices.

Optimize the indices in the db at aggressiveness level. level must be a non-negative integer or nil. nil means the same as not specifying a value: use the system default. A larger integer means be more aggressive, which can take more time. Specific integers translate to specific action, and currently only 0 and 1 are meaningful, with higher values being equivalent to 1.

If wait-p is true, don't return until the operation is finished.

db defaults to *db*.

Returns a list of namespace mappings.

filter can be nil or a string. If it is a string, then only namespaces that contain that string will be returned.

Print out all namespace mappings in a human-readable format.

filter can be nil or a string. If it is a string, then only namespaces that contain that string will be returned.

Applies fn to each namespace mapping. Fn must be a function of two arguments: the prefix and the uri.

filter can be nil to map all namespaces; a string to map only namespaces that include that string or a function to map only namespaces for which the function returns true.

Enables the use of the !-reader macro.

The !-reader makes it easier to type URIs and literals at the Read-Eval-Print-Loop.

enable-!-reader returns the previous definition of the #! in the current readtable.

Note: enable-!-reader modifies the readtable specified. If left unspecified, then enable-!-reader modifies the current *readtable*. There is no disable-!-reader command because Common Lisp does not provide a portable mechanism to cleanly compose and operate with multiple readtables. For information on working with readtables, please consult that Allegro Common Lisp reference.

Note: Because of its global effect, if enable-!-reader is called on the default readtable (*readtable*), then use of the exclamation mark character in other Lisp packages and systems may break. Generally speaking, it is possible to work around these issues. Please contact support for additional help.

Triples and parts are represented by (simple-array (unsigned-byte 8) 56) and (simple-array (unsigned-byte 8) 12) respectively. By default the Lisp printer prints these as vectors of bytes which is not very informative when using AllegroGraph interactively. This function modifies a pprint-dispatch table to print triples and parts interpretively if this can be done in the current environment. Specifically, the value of *db* must be an open triple store, and the vector being printed must print without error in the manner of print-triple or upi->value. If any of these conditions don't hold the vector is printed normally.

If the boolean argument is true, the informative printing is enabled, otherwise disabled. For example:

> (enable-print-decoded t)  
t  
> (upi !"Dürst"^^xsd:string)  
{Dürst}  
> (enable-print-decoded nil)  
nil  
> (upi !"Dürst"^^xsd:string)  
#(48 61 125 164 117 231 137 163 64 100 17 2) 

The :pprint-dispatch argument specifies the dispatch table to modify, by default the value of print-pprint-dispatch. Once enable-print-decoded has been turned on, you can also use the special-variable *print-decoded* to enable fine-grained control of triple and UPI printing. See the AllegroGraph tutorial for more information on the various notations AllegoGraph uses.

This creates a new index with the given name, which should be a string. The arguments have the following meaning:

predicates

A list of future-parts or UPIs that determine the predicates this index indexes. Default is (), which means index all predicates.

index-fields

A list containing any subset of (:subject :predicate :object :graph), which determines which fields of the triples are indexed. Default is (:object).

index-literals

Determines whether literals are indexed. Can be t (yes), nil (no), or a list of strings, UPIs or future-parts, each of which specifies either a type for typed-literals or a language (only indexes those literals whose type or language matches any of them). Default is t.

index-resources

Whether and how resources are indexed. The default is nil (don't index them). t means index resources fully, and :short means index only the part after the last # or /.

minimum-word-size

The minimum size a word must have to be indexed. Default is 3, which is suitable for European languages using the default tokenizer. If you use :simple-cjk or :japanese tokenizer, set this to 2 or 1.

stop-words

A list of strings, which indicates the set of words that should not be indexed. Defaults to a short list of English stop-words.

border-chars

If given, a freetext-charset object specifying characters that can appear at word boundaries. How this is used depends on the tokenizer; see tokenizer below.

inner-chars

If given, a freetext-charset object specifying characters that can appear within a word (but may not be at its boundaries). How this is used depends on the tokenizer; see tokenizer below.

word-filters

A list of string, naming filters that should be applied to words before they are indexed and before they are searched for, allowing terms to be normalized. Currently "stem.english", "drop-accents" and "soundex" are supported.

tokenizer

A keyword to name the tokenization scheme. Currently, :default, :japanese and :simple-cjk are supported. If unspecified, the the default tokenizer is used, which is sufficient for European languages. With the default tokenizer, each word begins with one of border-chars, followed by zero or more inner-chars, and ends with one of border-chars. The :simple-cjk tokenizer can be used to tokenize Chinese, Japanese or Korean text. This tokenizer first separates the text into sequences of CJK characters and sequences of other characters. For CJK parts, each bigram of characters is taken as a word; that is, if you have "XYZ" where X, Y and Z are CJK characters, then "XY" and "YZ" are indexed as words. The remaining non-CJK parts are tokenized with border-chars and inner-chars, as with the default tokenizer. Finally, the :japanese tokenizer uses a Japanese morphological analyzer to tokenize the Japanese sentences. Using an internal dictionary, it can extract Japanese words more precisely than the simple-cjk tokenizer. The border-chars and inner-chars are ignored.

Modify an existing freetext index. When not given, the configuration arguments retain their old value for this index. See create-freetext-index for the meaning of the settings.

If re-index-p is true, the index will be rebuilt, and existing triples will be re-indexed. If it is nil, the new settings will only be used for triples added afterwards.

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

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

Returns a list of the automatically mapped datatypes.

The list is a list of pairs where the first entry in each pair is the short type-name and the second entry is the XSD-type as a future-part. For example:

 (:unsigned-int !<http://www.w3.org/2001/XMLSchema#unsignedInt>) 

Returns the type encoding for part, an XML-Schema type designator. This can be a string, a UPI or a future-part. For example:

> (datatype-mapping "<http://www.w3.org/2001/XMLSchema#unsignedByte>")  
!xs:unsignedByte 

The scope of the mapping is the db (which defaults to
*db*). Use (setf datatype-mapping) to add an association between a datatype and an encoded UPI type

Returns a list of type names that can be used in value->upi to encode a string into an encoded UPI. To see the corresponding type code for a name, use the type-name->type-code function.

See the section on type mapping for more information.

Returns the type encoding for part. Part should be the URIref of a predicate. For example:

> (predicate-mapping !<http://www.example.org/property/height>)  
!xs:double 

The scope of the mapping is the db (which defaults to *db*). Use (setf predicate-mapping) to create a mapping between a URIref of a predicate and one of AllegroGraph's supported-types.

> (setf (predicate-mapping !<http://www.example.org/property/height>)  
        :double-float)  
:double-float 

Returns a list of all available type names. Use encoded-types to restrict the result to only those types that produce encoded UPIs. To see the corresponding type code for a name, use the type-name->type-code function.

See the section on type mapping for more information.

Returns the type code associated with the name. See type-code->type-name and supported-types. The name can be one of the supported-types or one of:

• :blank-node
• :resource
• :literal
• :literal-language
• :literal-short
• :literal-typed

The function returns nil if there is no type-code corresponding to name.

Decodes UPI and returns the value, the type-code and any extra information as multiple values.

• upi - the UPI to decode

• :db - specifies the triple-store from which the UPI originates.

The value, type-code, and extra information are interpreted as follows:

• value - a string, integer, or float representing the contents of the UPI
• type-code - an integer corresponding to one of the defined UPI types (see supported-types for more information). You can use type-code->type-name to see the English name of the type.
• extra - There are three disjoint sets of literals in RDF:
  1. "simple literals" -- a string.
  2. literals with datatypes
  3. literals with language annotations.

A literal cannot have both a language and a datatype; if a literal has type-name :literal-typed (i.e., its type-code is 2), then the extra value is a datatype URI; if its type-code is 3, then extra will be the language code.

Examples:

> (upi->value (value->upi 22 :byte))  
22  
18  
nil  
 
> (upi->value (upi (literal "hello" :language "en")))  
"hello"  
3  
"en" 

See value->upi for additional information.

Returns a UPI that encodes value using type encode-as.

encode-as can be a type-code or a type-name (see supported-types and type-name->type-code for details. If a upi keyword argument is not supplied, then a new UPI will be created. See upi->value for information on retrieving the original value back from an encoded UPI.

Note that value->upi can not create hashed UPIs (i.e., UPIs whose value must be stored in the string dictionary. To create these, use intern-resource and intern-literal.

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.

Return a list of the datatype and predicate mappings of db.

• :db - defaults to *db*.

Each item in the list returned consists of a list of three elements:

1. the URIref used for the mapping (predicate or datatype)
2. the type-code of the mapping
3. a keyword that indicates if the mapping is a :datatype or :predicate mapping.

Applies fn to each datatype and predicate mapping of db.

• :db - defaults to *db*.

fn should be a function of three arguments. For each mapping, it will called with

1. the URIref used for the mapping (predicate or datatype)
2. the type-code of the mapping (if simple) or the mapping identifier (if extended)
3. a keyword that indicates if the mapping is a :datatype or :predicate mapping.

(See collect-all-type-mappings if you just want a list of the mappings.).

Print the type mappings of db to *standard-output*.

If not specified, db defaults to *db*.

Create a new encapsulated-triple-store wrapping db and and return it.

The new store will be named name and will be of type wrapper-class (which must be a subclass of encapsulated-triple-store. The additional wrapper-initargs are passed along to the newly created store.

Create an encapsulated triple-store that allows only triples in specified graphs to be seen.

The encapsulated triple-store

• db - the store to be encapsulated. The default is taken from *db*.

• name - a unique name for the new store. The default is to prefix the name of the inner store with graph-filtered- and add a gensym suffix.

• graphs - A non-empty list of triple part specifiers. Only the triples in the graphs specified by this list are visible in the encapsulated store.

• cached-wrapper-key - If this argument is nil, the call creates a new instance of a filtering wrapper. If the argument is t, a new key is generated from the list of graphs. This key will be equalp to any other key generated from the same set of graphs. If the argument is any other non-nil value, it is used as a key in an equalp hash-table; if a previously created wrapper is found, the previous instance is returned. If no entry is found, a new wrapper is created and saved in the table. The default value is taken from the variable *cached-wrapper-key*. The initial value of this variable is nil.

This function returns a triple store that does not contain any inferred triples.

If the given triple store is not a reasoning store, then it is returned unchanged.

If the triple store is a reasoning encapsulation, then the inner triple store is returned.

In some cases, the function returns a new encapsulated store instance that represents the desired intent.

Parse a SPARQL query string into an s-expression.

This function is useful for three reasons: validation and inspection of queries, manual manipulation of query expressions without text processing, and performing parsing at a more convenient time than during query execution.

You do not need an open triple-store in order to parse a query. Any parse errors will signal a sparql-parse-error.

The optional arguments provide BASE and PREFIX arguments to the parser without inserting them textually into the query.

default-base

A string to use as the BASE for the SPARQL query.

default-prefixes

A hash-table mapping string prefixes to their expansions or a list of two element lists where each sublist contains the prefix and its expansion. For example:

(("rdf" "http://www.w3.org/1999/02/22-rdf-syntax-ns#")  
 ("rdfs" "http://www.w3.org/2000/01/rdf-schema#")  
 ("owl" "http://www.w3.org/2002/07/owl#")  
 ("xsd" "http://www.w3.org/2001/XMLSchema#")  
 ("xs" "http://www.w3.org/2001/XMLSchema#")  
 ("fn" "http://www.w3.org/2005/xpath-functions#")  
 ("err" "http://www.w3.org/2005/xqt-errors#")) 

This list uses the same format as db.agraph:standard-namespaces.

parse-sparql returns the s-expression representation of the query string.

run-sparql takes a SPARQL query as input and returns bindings or new triples as output.

Since AllegroGraph 3.0 it is a convenient wrapper for the db-run-sparql methods specialized on particular database classes and query engines. You might consider using those methods directly to gain more control over the execution of your queries.

You should consider specifying an engine argument in your invocations of run-sparql; the choice of default execution engine is not guaranteed to remain the same in future releases.

Allowable values for engine are keyword symbols returned by valid-query-engines.

The precise arguments supplied to run-sparql vary according to the query engine. These are the typical arguments expected by the default engines.

SELECT and ASK query results will be presented according to the value provided for results-format, whilst the RDF output of DESCRIBE and CONSTRUCT will be serialized according to rdf-format. Both of these arguments take keyword values.

If the format is programmatic (that is, it is intended to return values rather than print a representation; :arrays is an example) then any results will be returned as the first value, and nothing will be printed on output-stream.

• The query can be a string, which will be parsed by parse-sparql, or an s-expression as produced by parse-sparql. If you expect to run a query many times, you can avoid some parser overhead by parsing your query once and calling run-sparql with the parsed representation.

  If `query` is a string, then `default-base` and  
  `default-prefixes` are provided to [parse-sparql][]  
  to use when parsing the query. See the documentation  
  for that function for details. Parser errors signaled  
  within [parse-sparql][] will be propagated onwards by  
  `run-sparql`. 

• default-base A string to use as the BASE for the SPARQL query (only used when query is a string).

• default-prefixes A hash-table mapping string prefixes to their expansions or a list of two element lists where each sublist contains the prefix and its expansion (only used when query is a string; see parse-sparql for details).

• Results or new triples will be serialized to output-stream. If a programmatic format is chosen for output, the stream is irrelevant. An error will be signaled if output-stream is not a stream, t, or nil.

• If limit, offset, from, or from-named are provided, they override the corresponding values specified in the query string itself. As FROM and FROM NAMED together define a dataset, and the SPARQL Protocol specification states that a dataset specified in the protocol (in this case, the programmatic API) overrides that in the query, if either from or from-named are non-nil then any dataset specifications in the query are ignored. You can specify that the contents of the query are to be partially overridden by providing t as the value of one of these arguments. This is interpreted as 'use the contents of the query'. from and from-named should be lists of URIs: future-parts, UPIs, or strings.

• default-dataset-behavior controls how the query engine builds the dataset environment if FROM or FROM NAMED are not provided. Valid options are :all (ignore graphs; include all triples) and :default (include only the store's default graph).

• default-graph-uris allows you to specify a list of resources which, when encountered in the SPARQL dataset specification, are to be treated as the default graph of the store. Each resource can be a resource UPI, resource future-part, or a URI string. For example, specifying '("http://example.com/default") will cause a query featuring

  FROM <http://example.com/default>  
  FROM <http://example.com/baz> 

to execute against the union of the contents of the named graph <http://example.com/baz> and the store's default graph, as determined by (default-graph-upi db).

• with-variables should be an alist of variable names and values. The variable names can be strings (which will be interned in the package in which the query is parsed) or symbols (which should be interned in the package in which the query is to be, or was, parsed). The variable names can include or omit a leading '?'. Note that a query literal in code might be parsed at compile time. Using strings is the most reliable method for naming variables.

Before the query is executed, the variables named after symbols will be bound to the provided values.

This allows you to use variables in your query which are externally imposed, or generated by other queries. The format expected by with-variables is the same as that used for each element of the list returned by the :alists results-format.

• db (*db* by default) specifies the triple store against which queries should run.

• destination-db (db by default) specifies the triple store against which Update modifications should take place. This is primarily of use when db is a read-only wrapper around a writable store, such as when reasoning has been applied.

• If verbosep is non-nil, status information is written to *sparql-log-stream* (*standard-output* by default).

Three additional extensions are provided for your use.

• If extendedp is true (or *use-extended-sparql-verbs-p* is true, and the argument omitted) then extensions like AllegroGraph's GEO syntax are enabled. Extensions are enabled by default in all versions of AllegroGraph after 3.2.

• If memoizep is true (or *build-filter-memoizes-p* is true, and the argument omitted) calls to SPARQL query functions (such as STR, fn:matches, and extension functions) will be memoized for the duration of the query. For most queries this will yield speed increases when FILTER or ORDER BY are used, at the cost of additional memory consumption (and consequent GC activity). For some queries (those where repetition of function calls is rare) the cost of memoization will outweigh the benefits. In large queries which call SPARQL functions on many values, the size of the memos can grow large.

Memoization also requires that your extension functions do not depend on side-effects. The standard library is correct in this regard.

• In some circumstances you can achieve substantial speed increases by sharing your memos between queries. Create a normal eql hash-table with (make-hash-table), passing it as the value of the memos argument to run-sparql. This hash-table will gradually fill with memos for each used query function.

If you wish to globally enable memoization, set the variables as follows:

(progn  
  (setf *build-filter-memoizes-p* t)  
  (setf *sparql-sop-memos* (make-hash-table))) 

Be aware that the size of *sparql-sop-memos* could grow very large indeed. You might consider using a weak hash-table, or periodically discarding the contents of the hash-table.

• load-function is a function with signature (uri db &optional type) or nil. If it is a function, it is called once for each FROM and FROM NAMED parameter making up the dataset of the query. The execution of the query commences once each parameter has been processed. The type argument is either :from or :from-named, and the uri argument is a part (ordinarily a future-part) naming a URI. The default value is taken from *dataset-load-function*. You can use this hook function to implement loading of RDF before the query is executed.

• permitted-verbs is a keyword, either :all or :read-only. This defaults to :all, and will permit any kind of SPARQL or SPARQL/Update query. Use :read-only to allow only SELECT, ASK, DESCRIBE, and CONSTRUCT queries. Note that you must also enable extended mode (using :extendedp :update) to use SPARQL/Update operations.

The values returned by run-sparql are dependent on the verb used. The first value is typically disregarded in the case of results being written to output-stream. If output-stream is nil, the first value will be the results collected into a string (similar to the way in which cl:format operates).

The second value is the query verb: one of :select, :ask, :construct, or :describe. Other values are possible in extended mode.

The third value, for SELECT queries only, is a list of variables. This list can be used as a key into the values returned by the :arrays and lists results formats, amongst other things.

Individual results formats are permitted to return additional values.

Take a SPARQL query and return the corresponding algebra expression.

For example:

(sparql.algebra:sparql->algebra  
 "PREFIX fti: <http://franz.com/ns/allegrograph/2.2/textindex/>  
  SELECT ?g ?x { GRAPH ?g { ?x fti:match 'world' } FILTER ( <urn:x> = ?x ) }")  
==>  
(:filter  
 (:graph ?g  
  (:bgp  
   #(?x !<http://franz.com/ns/allegrograph/2.2/textindex/match> !"world")))  
 (= !urn:x ?x)) 

See the SPARQL documentation for more details on the SPARQL algebra.

If simplifyp is true (the default), the algebra expression is simplified according to the SPARQL algebra simplification rules. There should ordinarily be no reason to do otherwise.

If optimizep is true (the default), the query is optimized before being returned. This implies simplifyp.

If extendedp is true (the default), extended SPARQL syntax understood by AllegroGraph is accepted. If nil, only standard SPARQL is accepted.

Return a new reasoning-triple-store that encapsulates db and adds an rdfs++-reasoner.

• db - the triple-store to encapsulate. The defaults to the value of *db*.

• name - the name to give the encapsulated-triple-store. Defaults to the current db-name of the db prefixed with rdfs++- and with a generated suffix .

• restriction-reasoning-enabled - when true, enable OWL hasValue reasoning. The default is nil.

• inferred-graph - This argument specifies the graph component of all inferred triples. The default is to use the default graph of the specified triple store.

• cached-wrapper-key - If this argument is nil, the call creates a new instance of a reasoning wrapper; this instance will cause a new invocation of prepare-reasoning when the first query is issued. If the argument is not nil, it is used as a key in an equalp hash-table; if a previously created wrapper is found, the previous instance is returned. If no entry is found, a new wrapper is created and saved in the table. The default value is taken from the variable *cached-wrapper-key*. The initial value of this variable is nil.

• remote-reasoning - This argument is meaningful only when the db (or *db*) argument is a remote-triple-store instance. A non-nil value specified that the reasoning wrapper is created on the server side. The value returned by apply-rdfs++-reasoner is a new remote-triple-store instance pointing to the reasoner on the server side.

Returns whether or not restriction reasoning is enabled in the RDFS++ reasoner.

This includes reasoning about owl:hasValue, owl:someValuesFrom and owl:allValuesFrom.

You can control whether or not has-value reasoning is enabled when you use apply-rdfs++-reasoner.

This function has to be called before any inferences are made. It creates internal hash-tables to speed up the reasoner. In normal operation, AllegroGraph will call prepare-reasoning as necessary. You can see diagnostic messages by using the parameter verbose which defaults to the value of nil. You can also force the hash-tables to be regenerated using the force parameter. Finally, the show-progress keyword argument can be used to cause prepare-reasoning to print a message for each of the hash-tables it builds.

The function prepare-reasoning returns no value.

Lookup a registered sna-generator by name and return its associated function.

name can be:

• a generator function itself (in which case it is simply returned),

• a neighbor-matrix created via build-neighbor-matrix

• the name of a generator previously defined with the defsna-generator macro,

• the name of a neighbor-matrix previously defined with defneighbor-matrix, or

• a symbol naming an existing function which is assumed to act as a generator.

Lookup a registered neighbor-matrix by name and return it.

name should be a neighbor-matrix (in which case it is returned) or a symbol naming a previously registered neighbor-matrix. See defneighbor-matrix macro.

Associate the neighbor-matrix matrix with name.

To remove a matrix use register-neighbor-matrix with nil.

Search db in breadth first fashion starting at start and looking for end, using generator to expand the search space. Returns nil if no path can be found (within depth) and the first such path found otherwise. The arguments are:

• start - a UPI or future-part or string that can be converted into a UPI.
• end - a UPI, future-part or string that can be converted into a UPI.
• generator - a function of one argument or a generator name. See the description of generators for additional details.
• maximum-depth - If supplied, this restricts the length of the paths searched. Only paths (from start) less than or equal to this will be checked. If maximum-depth is not specified, it defaults to nil which means to search all paths. Warning in large graphs this can be very expensive.

Return a list of all (the shortest) paths between start and end using generator to determine adjacent nodes and breadth-first-search to find paths.

all-breadth-first-search-paths will search for a path no longer than maximum-depth. If maximum-depth is left unspecified, then the entire graph will be searched (obviously, this can be very expensive in large graphs). Note that once a path is found, no longer paths will be found (i.e., the maximum-depth becomes the length of the first path found.) Since breadth-first search is guaranteed to find the shortest path between start and end, this function actually returns a list of the shortest paths.

Please contact [email protected] if your path finding needs are not met by this algorithm so that we can work to make our SNA module more flexible.

Search db in depth first fashion starting at start and looking for end, using generator to expand the search space. Returns nil if no path can be found (within depth) and the first path found otherwise. The arguments are:

• start - a UPI, future-part or string that can be converted into a UPI.
• end - a UPI, future-part or string that can be converted into a UPI.
• generator - a function of one argument or a generator name. See the description of generators for additional details.
• maximum-depth - If supplied, this restricts the length of the paths searched. Only paths (from start) less than or equal to this will be checked. If maximum-depth is not specified, it defaults to nil which means to search all paths. Warning in large graphs this can be very expensive.

Return a list of all paths between start and end using generator to determine adjacent nodes and depth-first-search to find paths.

all-depth-first-search-paths will search for a path no longer than maximum-depth. If maximum-depth is left unspecified, then the entire graph will be searched (obviously, this can be very expensive in large graphs). Note that once a node appears in a path, it will not appear in any longer paths (though it may appear in paths of the same or shorter length depending on the order in which nodes are discovered.

Please contact [email protected] if your path finding needs are not met by this algorithm so that we can work to make our SNA module more flexible.

Return a list of all (shorter) paths between start and end using generator to determine adjacent nodes and bidirectional-search to find paths.

all-bidirectional-search-paths will search for a path no longer than maximum-depth. If maximum-depth is left unspecified, then the entire graph will be searched. Note that once a path is found, no longer paths will be searched. (Though some longer paths may appear in the results after a shorter one because of the recursive algorithm employed.)

Please contact [email protected] if your path finding needs are not met by this algorithm so that we can work to make our SNA module more flexible.

nodal-neighbors returns a list of other nodes that can be reached from node by following an edge. Node should be a vertex in the graph represented by the triple-store; See the description of generators for additional details.

Note that the nodal-degree of a node is the same as `(length (nodal-neighbors node)). See nodal-degree for additional details.

The nodal-degree of node is the total number of edges that connect it to other nodes in the graph. Edges are found using the generator. See the description of generators for additional details.

Note that the interpretation of nodal-degree depends entirely on the generator being using in the calculation. Suppose, for example, that we have a graph with three nodes and two edges:

 A --> B <-- C 

and that these are encoded in AllegroGraph as

!ex:A !ex:linksTo !ex:B  
!ex:C !ex:linksTo !ex:B 

If we define three generators:

(defsna-generator linksTo (node)  
  (:objects-of :p !ex:linksTo))  
 
(defsna-generator linksFrom (node)  
  (:subjects-of :p !ex:linksTo))  
 
(defsna-generator links (node)  
  (:undirected :p !ex:linksTo)) 

then we will find that

> (nodal-degree !ex:B 'linksTo)  
0  
 
> (nodal-degree !ex:B 'linksFrom)  
2  
 
> (nodal-degree !ex:B 'links)  
2 

Finally, note that nodal-degree is the same as the length of the list of nodes returned by nodal-neighbors.

The ego-group function returns a list of nodes in nodes ego group.

These are the other nodes in the graph (represented by the triple-store) that can be reached by following paths of at most length depth starting at node. The paths are determined using the generator to select neighbors of each node in the ego-group. See the description of generators for additional details.

An actor centrality measure provides insight into how central or important an actor is in the group. Closeness-centrality is the (normalized) inverse average path length of all the shortest paths between the actor and every other member of the group. (The inverse so that higher values indicate more central actors).

Actor is a node in the graph; group is a list of nodes (e.g., the actor's ego group) and generator is either a function or name. See the description of generators for additional details.

An actor centrality measure provides insight into how central or important an actor is in the group. Betweenness-centrality measures how much control an actor has over communication in the group.

The actor-betweenness-centrality of actor i is computed by counting the number of shortest paths between all pairs of actors (not including i) that pass through actor i. The assumption being that this is the chance that actor i can control the interaction between j and k.

Actor is a node in the graph; group is a list of nodes (e.g., the actor's ego group) and generator is either a function or name. See the description of generators for additional details.

Page-rank centrality is a specific implementation of a more general eigenvector centrality measure. Given a set of nodes in a graph, the page-rank-centrality function returns a vector representing the importance or influence of each node. Though it is not actually computed like this, you can imagine that we repeatedly pick a node at random and then execute a random walk following the edges of the graph while noticing which nodes our walker visits. The page-rank centrality is the probability that the walker will be on a particular node when it stops.

• group - a list of nodes in the triple-store
• generator - a generator describing how to get from one to another
• :dampening-factor - the effects how quickly the iterate algorithm stabilizes

Returns a vector of (unnormalized) page-ranks in the same order as the nodes in group.

Define a geospatial subtype. It returns two values: an opaque object representing the subtype and an mod 256 integer which is the subtype index within this running AllegroGraph image.

The arguments for this function are complicated. It is usually called from higher-level geospatial subtype definers such as register-cartesian-striping and the several spherical subtype definers, and would only be called in applications that need to define custom geospatial subtypes not covered by those existing functions. If your application requires such definitions, please contact Franz support.