AllegroGraph 6.1.1 Lisp Reference Guide

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

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

Returns a list of strings, naming triple-stores in a given catalog.

As in catalog-names, you can use the triple-store-class argument to specify the kind of store that should be listed. Like open-triple-store and create-triple-store, triple-store-names takes additional keyword arguments that vary depending on this class name. For example, querying catalogs containing remote-triple-stores may require specifying a username and password. See open-triple-store or create-triple-store for additional details.

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.

copy-triples adds each triple in source to the target-db and ensures that any strings in these triples are also interned in the target-db.

source can be a triple-store, a cursor that yields triples, a list or array of triples, or a single triple. If the source-db can be determined from source (e.g., if source is a triple-store or cursor), then source-db is ignored. Otherwise, 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. 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:[email protected]: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 with the given designator.

The designator can be a string naming a store, a string naming a catalog and store (separated by a slash character '/'), an existing triple-store instance, or a triple-store specification. For example:

;; open the store named 'example-store' in the root catalog  
(open-triple-store "example-store")  
 
;; open the store named 'data' in the catalog 'test'  
(open-triple-store "test/data")  
 
;; the above is equivalent to using the :catalog keyword argument:  
(open-triple-store "data" :catalog "test")  
 
;; create a federation of the triple stores named 'a' and 'b'  
(open-triple-store "<a>+<b>") 

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 requires a :user and :password (unless anonymous access is allowed) whereas a local triple-db does not.

For remote-triple-stores, :user, :password, :port, 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:[email protected]: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 allowed 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.

Prepare a store so that subsequent operations will be faster.

For example, bring as much of a disk-based store as possible into RAM.

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

• :attributes - specifies the attributes that will be associated with every triple being loaded. (Because in this file format attributes cannot be specified for individual triples, all triples loaded will have these attributes.) See the Triple Attributes document for more information on attributes.

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

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.

Add triples from source in NQX format to the repository. NQX format is N-Quad format plus optional attributes for each triple. 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 NQX 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 repository 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 added 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.

• :attributes - specifies the attributes that will be associated with every triple that does not have attributes specified in the file. See the Triple Attributes document for more information on attributes.

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

Add the triples in string (in NQX format) to the triple store.

See load-nqx 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. 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 into 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 added 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.

• :attributes - specifies the attributes that will be associated with every triple being loaded. (Because in this file format attributes cannot be specified for individual triples, all triples loaded will have these attributes.) See the Triple Attributes document for more information on attributes.

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

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

See load-ntriples for details on the parameters.

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

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.

• :attributes - specifies the attributes that will be associated with every triple being loaded. (Because in this file format attributes cannot be specified for individual triples, all triples loaded will have these attributes.) See the Triple Attributes document for more information on attributes.

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.

• :attributes - specifies the attributes that will be associated with every triple being loaded. (Because in this file format attributes cannot be specified for individual triples, all triples loaded will have these attributes.) See the Triple Attributes document for more information on attributes.

See load-trix for more details.

Add triples from the named Turtle source 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 added 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.

• :attributes - specifies the attributes that will be associated with every triple being loaded. (Because in this file format attributes cannot be specified for individual triples, all triples loaded will have these attributes.) See the Triple Attributes document for more information on attributes.

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

• :attributes - if supplied, this must be an alist of name and value pairs. Each name and value must be a string. Each name must refer to a previously defined attribute. An error will be signaled if any name refers to an undefined attribute or if any value does not conform to the named attribute's constraints.

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.

Interned strings are guaranteed to be persistent as long as both of the following are true:

• commit-triple-store is called

• At least one live triple references the UPI.

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.

Interned strings are guaranteed to be persistent as long as both of the following are true:

• commit-triple-store is called

• At least one live triple references the UPI.

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. The number of distinct strings that the template may match must be less than or equal to 10^18.

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.

• :complete? - controls whether the returned value is required to be a complete representation of the UPI. Currently it only affects dates and date-times for which the non-complete representation is a rational while the complete representation is a cons whose car is the same rational and whose cdr is a generalized boolean that's true if and only if the date or date-time has a timezone specified. Complete representations round-trip in the sense of: (upi= (value->upi (upi->value upi :complete? t) (upi-type-code upi)) upi).

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

• value - a string, rational, float or cons representing the contents of the UPI. UPIs representing numeric types are converted into an object of the appropriate lisp type (integer, rational or float). Dates and date-times are by default converted into a single integer or rational respectively, standing for the number of seconds since January 1, 1900 GMT. See the :complete? parameter on how to recover the timezone information. Everything else is converted to a string.

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

Note that upi->value will signal an error if called on geospatial UPIs. Use upi->values instead.

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.

The allowable value for value varies depending on the type into which it is being encoded. If the type is numeric, then value may be either a string representing a number in XSD format or a number. If the type is a date, time or dateTime, then value may be a string representing an XSD value of the appropriate type, or a number in extended universal time (this number will be assumed to have its timezone in GMT), or a cons whose car is a number representing an extended universal time and whose cdr is either t, nil, or an integer representing the timezone offset in minutes from GMT. If the cdr is nil, then the date or time will have no timezone information; if it is t, then the date or time will be in GMT. Here are some examples:

> (part->string (value->upi 2 :byte))  
"2"^^<http://www.w3.org/2001/XMLSchema#byte>  
 
> (part->string (value->upi "23.5e2" :double-float))  
"2.35E3"^^<http://www.w3.org/2001/XMLSchema#double>  
 
> (part->string (value->upi (get-universal-time) :time))  
"18:36:54"^^<http://www.w3.org/2001/XMLSchema#time>  
 
> (part->string (value->upi (cons (get-universal-time) -300) :time))  
"13:37:08-05:00"^^<http://www.w3.org/2001/XMLSchema#time>  
 
> (part->string (value->upi (cons (get-universal-time) nil) :date-time))  
"2015-03-31T18:39:08"^^<http://www.w3.org/2001/XMLSchema#dateTime> 

Note the lack of timezone in the final example.

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.

Establishes or updates a triple attribute definition.

Attributes must be defined before they can be used. Defining an attribute establishes the name of an attribute and any constraints that should be placed on its use.

db defaults to *db*. name is a string naming the attribute. allowed-values must be a list of string values that this attribute is allowed to take on. If the list is empty/nil, then this attribute will allow any string value. If ordered is true, then the specified order of the allowed-values is significant. Ordered attributes can be compared to one another. See the triple attributes reference guide for more information. minimum-number specifies the minimum number of attributes of this type that must provided for each added triple. The default is 0. maximum-number specifies the maximum number of attributes of this type that may be provided for each added triple. The default when ordered is true is 1. When ordered is false, the default is 1,152,921,504,606,846,975 (the largest integer the system can represent in one word).

Returns the current static attribute filter for the triple store.

db defaults to *db*.

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

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.

Returns the number of triples remaining in a cursor and also exhausts cursor in the process.

The cursor will be discarded unless retain is true.

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 a cursor that applies transform to each row of inner before it is returned.

Transform is a function of one argument (the inner cursor's row) and should return a single value (the transformed row). The transform function can perform arbitrary computation and mutation on the row but cannot assume that it will get the same (eq) row on each call.

The optional variables argument provides a means to set the new cursor's variables.

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.

• return-fat-triples - if true, the get-triples will iterate over fat-triples (i.e., triples that contain both SPOG data and attribute data).

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.

• return-fat-triples - if true, the get-triples will iterate over fat-triples (i.e., triples that contain both SPOG data and attribute data).

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

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:

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

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.

The static technique is not supported in this version of AllegroGraph. It may be reinstated in a future version.

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.

Deletes duplicated triples from a store inside the current transaction.

• :db - defaults to the value of *db*

• :mode - specifies how triple equality is determined. It can be :spog or :spo and defaults to :spog.

• :commit - if true then commit before and after duplicates are deleted. A true value allows this function to process a very large number of deletes efficiently.

Returns a keyword (or nil) specifying whether the store suppresses duplicate triples at commit time. setf may be used to change the strategy value:

(duplicate-suppression-strategy) => nil  
(setf (duplicate-suppression-strategy) :spo)  
(duplicate-suppression-strategy) => :spo 

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.

Returns a cursor of all duplicate triples visibile in db inside the current transaction.

• :db - defaults to the value of *db*

• :mode - specifies how triple equality is determined. It can be :spog or :spo and defaults to :spog.

Schedules a background operation to purge deleted triples from the specified indices.

db defaults to *db*. indices must be a list of indices to purge, or nil (the default) meaning purge all indices.

Cancels purge deleted triple job for the specified indices.

db defaults to *db*. indices must be a list of indices to cancel purge operations on, or nil (the default) meaning stop purge operations on all indices.

Returns the deleted triple purge operation rate limit (read IOs per second). (setf purge-rate-limit) may be used to change the value, with the change affecting ongoing purge operations. 0 means no limit. Note that the value is reset to 0 when the database instance is started (that is, a set value does not stick when a database instance is shut down). The maximum limit is 4,294,967,295.

db defaults to *db*.

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

Returns the triple printed unless stream is nil in which case it returns the string representation.

If stream is not nil, then a newline will also be printed.

The keyword argument :format, which defaults to :ntriples, specifies the syntax to be used when printing the triple. It can be one of:

• :ntriple or :ntriples - use N-Triples syntax,
• :nquad or :nquads - use N-Quads syntax (i.e., include the graph),
• :ntriple-ascii or ntriples-ascii - N-Triples with non-ASCII and control characters escaped.
• :nquad-ascii or nquads-ascii - N-Quads with non-ASCII and control characters escaped.
• :long - Synonym for :nquads.
• :concise or :terse - use a short or very short human readable but possibly ambiguous representation.

The default for error? is true; if error? is nil, then any UPIs which cannot be printed in humanly readable fashion will instead be printed in hex.

The stream argument can be used to send output to the stream of your choice. If left unspecified, then output will go to standard-output. It can be nil to indicate a string-stream.

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 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 table is built to store the mappings between resources in the store and string abbreviations. This 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 to to in Turtle format

From must be a triple-store, a list, or a cursor and to must 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.

If memoize-abbrev-lookups-p is t, a table is built to store the mappings between resources in the store and string abbreviations. This 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.

Write source, which should be a triple store, cursor, or list of triples, to to. to 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*. flavor is a symbol (typically a keyword) naming a type of index, like :psogi or :spogi. Indices are described in AllegroGraph Indices. That document describes how to construct the names of index types.

Style must be NIL, 0, 1, or 2.
NIL/0: Use the default chunk style for the index as determined by the Style2Indices configuration parameter (see Server Configuration and Control). 1: Use style 1 chunks. 2: Use style 2 chunks.

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

If an index of the specified flavor and style already exists, add-index does nothing. If an index of the specified flavor but different style already exists, then the index will be rebuilt using the specified style at commit time.

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

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

Dropping an index that does not exist has no effect.

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.

The parameters are:

• level: this must be a non-negative integer or nil:

  • 0 - Does a single round of optimization with standard parameters.

  • 1 - Does a single round of optimization with aggressive parameters.

  • 2 or nil - Writes out in-memory triple data and then performs a single very aggressive index optimization of all chunks.

  • 3 - Same as 2, but will process all chunks regardless of overlap.

• wait-p: if true, don't return until the operation is finished.

• indices: This can be one of

  • nil or :all to optimize all indices.

  • a single index, e.g., :spogi, to optimize just that index.

  • a list of index names, to optimize several indices.

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). For example: :index-literals (list !<http://www.w3.org/2001/XMLSchema#byte> !"en") will only index literals with XSD type "http://www.w3.org/2001/XMLSchema#byte" or language tag "en". 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)) 

If return-fat-triples is true, then the cursor will iterate over fat-triples rather than plain ones..

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.

• :complete? - controls whether the returned value is required to be a complete representation of the UPI. Currently it only affects dates and date-times for which the non-complete representation is a rational while the complete representation is a cons whose car is the same rational and whose cdr is a generalized boolean that's true if and only if the date or date-time has a timezone specified. Complete representations round-trip in the sense of: (upi= (value->upi (upi->value upi :complete? t) (upi-type-code upi)) upi).

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

• value - a string, rational, float or cons representing the contents of the UPI. UPIs representing numeric types are converted into an object of the appropriate lisp type (integer, rational or float). Dates and date-times are by default converted into a single integer or rational respectively, standing for the number of seconds since January 1, 1900 GMT. See the :complete? parameter on how to recover the timezone information. Everything else is converted to a string.

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

Note that upi->value will signal an error if called on geospatial UPIs. Use upi->values instead.

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.

The allowable value for value varies depending on the type into which it is being encoded. If the type is numeric, then value may be either a string representing a number in XSD format or a number. If the type is a date, time or dateTime, then value may be a string representing an XSD value of the appropriate type, or a number in extended universal time (this number will be assumed to have its timezone in GMT), or a cons whose car is a number representing an extended universal time and whose cdr is either t, nil, or an integer representing the timezone offset in minutes from GMT. If the cdr is nil, then the date or time will have no timezone information; if it is t, then the date or time will be in GMT. Here are some examples:

> (part->string (value->upi 2 :byte))  
"2"^^<http://www.w3.org/2001/XMLSchema#byte>  
 
> (part->string (value->upi "23.5e2" :double-float))  
"2.35E3"^^<http://www.w3.org/2001/XMLSchema#double>  
 
> (part->string (value->upi (get-universal-time) :time))  
"18:36:54"^^<http://www.w3.org/2001/XMLSchema#time>  
 
> (part->string (value->upi (cons (get-universal-time) -300) :time))  
"13:37:08-05:00"^^<http://www.w3.org/2001/XMLSchema#time>  
 
> (part->string (value->upi (cons (get-universal-time) nil) :date-time))  
"2015-03-31T18:39:08"^^<http://www.w3.org/2001/XMLSchema#dateTime> 

Note the lack of timezone in the final example.

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 geospatial)
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 namespace 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 or update command as input and returns bindings or new triples as output.

SELECT, ASK and UPDATE 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, an s-expression as produced by parse-sparql, or a query plan generated by a previous call to run-sparql. The s-expression syntax is described in greater detail in the reference. If you expect to run a query many times, you can avoid some parser overhead by parsing or planning 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. The former specifies a BASE when none is provided and the later specifies a set of namespace abbreviations to use when parsing. 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 namespace 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 (for output to *standard-output*), or nil (for output to a string) or a pathname. If a pathname is specified, then the if-exists and if-does-not-exist parameters will be as used to create an output stream.

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

• The using-named-graph-uri and using-graph-uri parameters are used similarly to the from and from-named parameters except that they are relevant only to SPARQL UPDATE commands.

• The remove-graph-uri and insert-graph-uri parameters are also used only in SPARQL update. The first specifies a graph or list of graphs from which each triple to be deleted should be removed whereas the second specifies a graph or list of graphs into which each triple to be inserted should be added.

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

• in-line-data provides another means to impose external data into a query. The format for the data is a list of two lists. The first list contains the list of variables to use and the second is a list of lists. Each sub-list must be the same length as the list of variables. nil can be used to specify that a binding should be undefined.

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

• basic-authorization is used when making SPARQL SERVICE calls. It must be a cons cell whose car is the user name and whose cdr is the password. For example: `("test" . "password").

• load-function must be nil or a function with signature (uri db type). 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.

• If cancel-query-on-warnings-p is true, then any warning found during query planning will immediately cancel the query. Setting this to true can help in query debugging.

• host can be used to specify the URL of a SPARQL endpoint. If host is given, then AllegroGraph will send the query to the endpoint, retrieve any results and emit them in the format specified by results-format or rdf-format as appropriate.

• timeout should be the number of seconds after which the query will be canceled. A value of nil means no timeout. Note that a query timeout does not interrupt the query immediately. Rather, the executing query will periodically check for timeouts and cancel itself. This allows for any query resources to be properly reclaimed.

• The engine keyword specifies which query engine to use. Allowable values keyword symbols returned by valid-query-engines. Note that depending on the version of AllegroGraph, there may be only a single engine available.

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, :describe, or :update.

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.

The fourth value will be a query-information structure which contains additional information AllegroGraph gathered while executing the query.

Individual results formats are permitted to return additional values.

The following parameters are used internally by AllegroGraph and should not be used: parsed-package, primary?, parent-executor, uuid, and service-db.

Note that the following arguments are deprecated and should no longer be used: permitted-verbs, extendedp and planner.

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.