AllegroGraph 8.3.0 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 catalogs, and containing the value nil if there is a root catalog.

You can use the triple-store-class argument to specify the kind of store the named catalogs should contain. Like open-triple-store and create-triple-store, catalog-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.

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. Argument include-shards-p can be used to include the local shards of the distributed triple stores in the result. 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.

Return a list of property lists each of which describes a catalog on the server.

• server - Specifies a server spec or URL of the AG server on which to operate. "127.1:10035" is used if nil is passed for this argument.

• :repo-count - if true, return number of repositories for each catalog.

Return a list of property lists each of which describes a repository in the specified catalog.

• server - Specifies the server spec or URL of the AG server on which to operate. "127.1:10035" is used if nil is passed for this argument

• :catalog - catalog name. The default is the root catalog.

• :include-shards-p - if true then return the names of the shards of a distributed repo. The names of fedshard shards are always returned.

• :allp - if true, then all catalogs are considered and the :catalog argument ignored.

• :check-distributed-p - if true (default), only existing distributed stores will be returned. If false then all defined distributed store names are returned, even those store that haven't been created.

• :check-fedshard-p - if true (default), only existing fedshard stores will be returned. If false then all defined fedshard store names are returned, even those of store that haven't been created.

Close the triple-store db. Returns nil.

• :db - the triple-store to close (defaults to *db*).

• :if-closed - controls the behavior when the db provided is closed, or (without :db argument) when *db* is nil: If if-closed is :error then an error will be signaled in this situation. If it is :ignore (the default) then close-triple-store will return without signaling an error.

• If :commit is true, and the store is open, then commit-triple-store will be called before the store is closed. This defaults to nil.

• If :ensure-not-lingering is true, then ensure-not-lingering will be called after the store is closed.

If the triple store being closed is the same as *db*, then the new value of *db* depends on its type:

• in case of an encapsulated stream (like a reasoning store), *db* is afterwards set to the inner store (in a sense unwrapping the encapsulation);
• otherwise *db* is set to nil.

Request the server to immediately close down the resources related to the given repository as soon as there are no more active connections to it. This function returns nothing.

Normally after the last connection to a repository is closed, the server keeps resources (like processes and memory structures) active for the duration specified by InstanceTimeout in Server Configuration. This speeds up a subsequent open-triple-store call if it happens before the timeout.

Call this function to indicate you don't expect the repository to be opened again immediately, or if you wish to save on resources generally.

• name - the name of the triple-store
• :triple-store-class - symbol that indicates the kind of store that name is

Like open-triple-store and create-triple-store this function takes additional keyword arguments that vary depending on triple-store-class. For example for a remote-triple-store supplying username and password might be relevant.

See also the :ensure-not-lingering keyword argument to close-triple-store.

Applies outstanding changes to the repository. This ends the current transaction and begins a new one.

The durability, distributed-transaction-timeout, transaction-latency-count, and transaction-latency-timeout arguments relate to multi-master replication. See the Instance Settings section of the Multi-master Replication document for more information on those arguments.

The phase and xid arguments relate to the Two-phase Commit facility.

• :db - Specifies the triple store to operate on. Defaults to *db*.

• :durability - If durability is specified, it must be a positive integer, or :min, :max, or :quorum.

• :distributed-transaction-timeout - If distributed-transaction-timeout is specified, it must be a non-negative integer.

• :transaction-latency-count - If transaction-latency-count is specified, it must be a non-negative integer.

• :transaction-latency-timeout - If transaction-latency-timeout is specified, it must be a non-negative integer.

• :phase - If phase is specified, it must be :prepare or :commit. This is used for two phase commit (2PC) support.

• :xid - If xid is specified, it must be an XA Xid in string format. xid is required when phase is specified. Suitable strings are generated by the two-phase commit transaction coordinator.

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 repository (also called a triple store). designator can be a string naming a store or a ground store repo spec. The following characters cannot be used in a repository name:

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

create-triple-store takes numerous keyword arguments (and more via &allow-other-keys). The allowed arguments vary depending on the class of triple-store being created. For example, a remote-triple-store requires :server, :port, and :user and :password (unless anonymous access is allowed) whereas an instance of triple-db does not. :user, (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 (note some described arguments do not appear in the argument list but are allowed because additional keyword arguments are allowed):

• :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. Value :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 root catalog will be used. Users may not create repositories in the system catalog.

• :server - the server for a remote-triple-store. The default is "127.0.0.1" (which is the local machine).

• :port - the port to use to access the AllegroGraph server. The default is the value of default-ag-http-port

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

• :scheme - the protocol to use to access the server. May be :http or :https. The default is :http.

• :triple-store-class - the kind of triple-store to create. If left unspecified and a repo spec is being used the triple-store class will be automatically selected otherwise triple-db will be used.

• :params - If supplied, the value must be an alist of catalog configuration directives and values (both represented as strings). The catalog directives are documented in the Catalog directives section of the Server Configuration and Control document. Any catalog directive can be specified. The catalog defaults will be used for directives that are not specified by this argument. For example, suppose you want the new repository to have a string table size of 128 MB and use lzo string compression (rather than the default, which is no compression), then you would specify the following value

  (create-triple-store ...  
    :params '(("StringTableSize" . "128m")  
              ("StringTableCompression"  . "lzo"))) 

• :with-indices - a list of index flavors that this store will use. If left unspecified, the store will use the standard indices: (:gposi :gspoi :ospgi :posgi :psogi :spogi :i).

• :https-verification - the value should be a list of keywords and value pairs (see below);

• :proxy, :proxy-host, ... - HTTP proxy specification, only applicable if triple-store-class is remote-triple-store (see below).

The possible keys for :https-verification options are:

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

• :load-initfile - if true, and if a session on the server is created to open the repository, then re-load the initfile in the session process. This has no effect for a repo opened with the direct lisp interface.

• :scripts - a list of script file names to load when a session on the server is created to open the repository. This has no effect for a repo opened with the direct lisp interface.

Here is an example:

(create-triple-store "clienttest"  
   :triple-store-class 'remote-triple-store  
   :port 10398 :server "localhost" :scheme :https  
   :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")) 

The :proxy value must be a string of the form:

[<user>[:<password>]@]<host>[:<port>] 

that instructs HTTP client to send all requests through the HTTP proxy server at * :, optionally using * and * * for proxy authorization.

All components of the spec can be provided explicitly via :proxy-host, :proxy-port, :proxy-user and :proxy-password parameters, in which case they will override the components extracted from the :proxy string.

Additionally :proxy-bypass-list can provide a list of domain name suffix strings for which to bypass the proxy. It defaults to '("127.0.0.1" "::1" "localhost"). Note that a suffix like "localhost" will also match hosts "xyzlocalhost" and "xyz.localhost").

Examples of proxy settings:

(create-triple-store "clienttest"  
   :triple-store-class 'remote-triple-store  
   :proxy "localhost:12345"  
   :proxy-user "donny"  
   :proxy-password "iknowuknow")  
 
(create-triple-store  
   "clienttest"  
   :triple-store-class 'remote-triple-store  
   :proxy "donny:iknowuknow@localhost:12345"  
   :proxy-bypass-list '("internal.example.org")) 

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

Ensure that the given triple store that is the value of db (default *db*) contains a vector store. If db is already a vector triple store then it will not be modified if supersede is nil. If supersede is true then the existing vector store in db will be completely removed before creating a new vector store in db. Only vector store triples will be deleted, the other triples in the store will remain. The embedder, model and api-key arguments are the same as for create-triple-store.

• :db - Specifies the triple store to operate on. Defaults to *db*.

• embedder - name of the embedding service

• :model - model to be used in the embedding service

• :dimensions - length of embedding vector

• :embedding-api-key - api key, if any, need by the embedding service

• :supersede - Replace existing vector store (vectors and metadata only) if it exists

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 repository with the given designator.

The designator can be a string naming a store, an existing triple-store instance, or a repo spec. 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 form is equivalent to using the  
;; :catalog keyword argument:  
(open-triple-store "data" :catalog "test")  
 
;; Using a repo spec to open a remote store with username 'user',  
;; password 'pass', host 'myhost', port 12345, catalog 'cat',  
;; and repository 'repo'  
(open-triple-store "user:pass@myhost:12345/cat:repo")  
 
;; 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 :server, :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.

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

• :catalog - the catalog to use in the server's configuration file. The catalog may also be specified as part of the required designator argument, with the catalog name and store name separated by a slash or a colon. If the catalog is not specified as part of the designator and this argument is left unspecified, the root catalog will be used.

• :server - the server for a remote-triple-store. The default is "127.0.0.1" (which is the local machine).

• :port - the port to use to find the AllegroGraph server. The default is the value of default-ag-http-port.

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

• :scheme - the protocol to use to access the server. May be :http or :https. The default is :http.

• :triple-store-class - the kind of triple-store to open. If left unspecified, then designator will be treated as a triple-store specification and the triple store class will be determined based on the specification.

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

• :proxy - proxy specification for remote-triple-store. Alternatively, proxy settings can be passed via :proxy-host, :proxy-port, :proxy-user and :proxy-password parameters. For more details, see the documentation for create-triple-store.

• :proxy-bypass-list - list of domain name suffix strings for which to bypass the proxy. For more details, see the documentation for create-triple-store.

• :load-initfile - if true, and if a session on the server is created to open the repository, then re-load the initfile in the session process. This has no effect for a repo opened with the direct lisp interface.

• :scripts - a list of script file names to load when a session on the server is created to open the repository. This has no effect for a repo opened with the direct lisp interface.

• :if-does-not-exist - Similarly to the same argument for cl:open function, either :error (throw an error if there is no repository matching the spec; default) or :create (create repository given by the spec); nil value is not supported. Note that no locking is involved, so the :if-does-not-exist option is not safe for concurrent usage.

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.

Discards any local repository changes, then synchronize to the latest committed repository version on the server. Starts a new transaction.

• :db - Specifies the triple store to operate on. Defaults to *db*.

• :xid - xid, if supplied, must be the xid of a previously prepared commit

Returns the number of triples in a triple store.

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.

Note too the count of a multi-master repository may also be inaccurate. See Triple count reports may be inaccurate in the Multi-master Replication document.

• :db - Specifies the triple store to operate on. Defaults to *db*.

Returns true if the triple-store with the given name exists in the given catalog (optional).

Returns false if there is no such triple-store.

This function signals an error if communication with the server failed (e.g. due to an invalid value for port, user or password) or if the given catalog does not exist.

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.

Returns the ID of the triple-store. The ID is generated randomly when the triple-store is created. It is an array of four octets.

• :db - Specifies the triple store to operate on. Defaults to *db*.

Preloads portions of the repository into RAM for faster access.

• :db - Specifies the triple store to operate on. Defaults to *db*.

• :include-strings - If true, string table data will be warmed up.

• :include-triples - If true, triple indices will be warmed up. The :indices keyword is used to control which indices will be warmed up.

• :indices - indices must be a list of indices to warm up, or nil to warm up all indices.

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.

  • a list of the values described above.

• :override-graph - if true and graph is a list, add the triples to all graphs in it, otherwise all values in the list except the first one will be ignored.

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.

• :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. Default is nil.

• :relax-syntax - For N-Triples and N-Quad files, this flag tells AllegroGraph to be more liberal than standard RDF by accepting:

  • literals in the Graph position (for N-Quads), and
  • IRIs that do not include a colon (:).
• :default-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 the named Turtle-star 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.

  • a list of the values described above.

• :override-graph - if true and graph is a list, add the triples to all graphs in it, otherwise all values in the list except the first one will be ignored.

• :default-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-star data source and add it to the triple-store.

See load-turtle for details.

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.

  • a list of the values described above.

• :override-graph - if true and graph is a list, add the triples to all graphs in it, otherwise all values in the list except the first one will be ignored.

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

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.

  • a list of the values described above.

• :override-graph - if true, replace existing graph information with graph. If graph is a list, override-graph must be true to add the triples to all graphs in it, otherwise all values in the list except the first one will be ignored.

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.

• :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. Default is nil.

• :relax-syntax - For N-Triples and N-Quad files, this flag tells AllegroGraph to be more liberal than standard RDF by accepting:

  • literals in the Graph position (for N-Quads), and
  • IRIs that do not include a colon (:).
• :default-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.

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

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

graph can also be the symbol :source, in which case namestring is called on the source and treated as a URI, or a list of the values described above.

• :override-graph - if true, replace existing graph information with graph. If graph is a list, override-graph must be true to add the triples to all graphs in it, otherwise all values in the list except the first one will be ignored.

• :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. Default is nil.

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

• :graph - a future-part or UPI that identifies a graph, nil or a list of such values. 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.

• :override-graph - if true, replace existing graph information with graph. If graph is a list, override-graph must be true to add the triples to all graphs in it, otherwise all values in the list except the first one will be ignored.

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

• :default-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 TriG source to the triple-store. source can be a filename or a stream.

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

  • a list of the values described above.

• :override-graph - if true, replace existing graph information with graph. If graph is a list, override-graph must be true to add the triples to all graphs in it, otherwise all values in the list except the first one will be ignored.

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

• :default-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 TriG data source and add it to the triple-store.

See load-trig for details.

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.

  • a list of the values described above.

• :override-graph - if true, replace existing graph information with graph. If graph is a list, override-graph must be true to add the triples to all graphs in it, otherwise all values in the list except the first one will be ignored.

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.

• :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. Default is nil.

• :relax-syntax - For N-Triples and N-Quad files, this flag tells AllegroGraph to be more liberal than standard RDF by accepting:

  • literals in the Graph position (for N-Quads), and
  • IRIs that do not include a colon (:).
• :default-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.

Parse and load JSON-LD source to the triple store. Returns the number of triples added. Additional arguments are:

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

• :commit (positive integer) - when provided, commit triple-store after each commit triples added and at the end of the operation.

• :context (string) - when provided it is loaded first and used as top-level context.

• :graph and :default-attributes - usual arguments for any load function.

• :base-uri - when provided it is used as default @base property for the document.

• :resolve-external-references - when true, contexts referenced by URIs are also downloaded and processed. When false (default) an error is signalled when they are encountered.

• :external-reference-timeout - specifies the timeout for the HTTP request to fetch the context file.

Treat string as a JSON-LD source and load it into the triple store.

See load-json-ld 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).

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

• uri - can be a string, future-part or uri.

• :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. The characters + and * are not allowed in the template string (so, e.g., the string "[0-9]+" is illegal and will fail).

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 2^60. If the intention is to use next-encoded-upi-for-prefix in a multimaster replication cluster (see Multimaster replication), then the pattern must match 2^60 strings and we recommend using the "plain" format to achieve this goal. The value "plain" will produce integer values between 0 (inclusive) and 2^60 (exclusive), thus fulfilling the requirement. Note that the size of the range may change in later releases. Any such change will be noted in the Release Notes.

When not used for those purposes, templates that generate fewer strings are permitted.

See Encoded IDs for further information.

Examples:

;; These first examples use templates that will cause calls  
;; to next-encoded-upi-for-prefix to fail if the repository is  
;; or becomes a multi-master cluster instance.  
 
(register-encoded-id-prefix    
"http://www.franz.com/managers"      
"[0-9]{3}-[a-z]{3}-[0-9]{2}")  ;; not a suitable value for  
                                   ;; calls to next-encoded-upi-for-prefix  
                                   ;; in a multi-master cluster instance  
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}")  ;; not a suitable value for  
                                   ;; calls to next-encoded-upi-for-prefix  
                                   ;; in a multi-master cluster instance  
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   
                                  ;; not a suitable value for  
                                  ;; calls to next-encoded-upi-for-prefix  
                                  ;; in a multi-master cluster instance  
RETURNS   
3 ;; same value as before   
t ;; meaning made the change  
 
;; These examples will allow calls to next-encoded-upi-for-prefix  
;; in multi-master cluster instances since the templates  
;; generate 2^60 distinct strings.  
 
(register-encoded-id-prefix   
    "http://www.franz.com/managers"     
    "plain")         ;; Calls to  next-encoded-upi-for-prefix  
                        ;; will work in multi-master cluster instances  
RETURNS  
3 ;; you will likely see a different value  
t  
 
;; Another example that has the correct range, since the string  
;; has 15 elements and 16 choices for each element resulting in  
;; (2^4)^15 = 2^60 possibilities.  
 
   (register-encoded-id-prefix   
    "http://www.franz.com/managers"     
    "[a-p]{15}")  ;; Calls to  next-encoded-upi-for-prefix  
                        ;; will work in multi-master cluster instances  
RETURNS  
4 ;; you will likely see a different value 

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, symbol, 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. For a default graph upi, value is :default-graph. For a blank node, value is the blank node's integer representation (each unique blank node in a store gets a different number). 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. For some UPIs, including default graphs and blank nodes, the extra is an integer reserved for use by AllegroGraph.

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 the numeric value(s) encoded by upi.

The interpretation of this number varies with the UPI's type code:

• for numeric UPIs, the number is their value;
• for date, time, and date-time UPIs, the number is the extended universal time (time zone information is lost);
• for triple ID type UPIs, the number is the triple ID;
• for subscript UPIs, the number is the subscript value;
• for encoded IDs, the number is the encoded ID value as an integer;
• for blank nodes and other gensyms, the number is the UPI's value;
• for boolean UPIs, true will map to 1 and false will map to 0;
• for 2D Geospatial UPIs, the longitude and latitude are returned as two values of type double-float;
• other UPI types signal an error.

This decoding is independent from the value of db. That argument is accepted to be consistent with e.g. upi->value.

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, :resource, :literal, :literal/lang or :literal-typed. :resource will be replaced with :node`.

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

  • :node, :resource - 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 part.

part may be a UPI or a future-part. If part is a future-part that 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.

An error will also be signaled if upi is called on something other than a UPI or a future-part.

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 - Specifies the triple store to operate on. Defaults to *db*.

• name - name is a string naming the attribute.

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

• :ordered - If true, then the specified order of the allowed-values is significant. If 'false' or left unspecified then the order is not 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 - Optionally 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.

Returns the current static attribute filter for the triple store.

• :db - Specifies the triple store to operate on. Defaults to *db*.

Returns a subset of the store's metadata. Currently it returns the attribute definitions and static filter definition. The value may be saved or passed later to set-metadata; it must not be modified.

• :db - Specifies the triple store to operate on. Defaults to *db*.

Merge the metadata in the metadata argument into the current metadata for the database. It is not currently permitted to change an attribute definition and doing so will result in an error. The metadata value must have come from an earlier call to get-metadata. After calling this function a commit-triple-store must be done to make the changes persistent.

• :db - Specifies the triple store to operate on. Defaults to *db*.

• metadata - A string containing the metadata

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.

Call fn on each of the rows returned by cursor. If count is provided at most that many cursor rows are retrieved. The arguments to fn will be the cursor row, followed by all the args.

The function returns the number of triples visited.

This is equivalent to: (iterate-cursor (row cursor :count count) (apply fn tr args))

Note that typically cursors reuse their result rows, for example a triple cursor will return the same triple object every time, but the triple data (like the subject) will be different each time. To store the triple data you need to copy the row using e.g. copy-triple.

Collect the triples from triple-cursor into a list. The cursor might reuse the triple object, therefore each triple is copied before being collected.

This is equivalent to (collect-cursor triple-cursor :transform 'copy-triple).

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.

If variables is not provided, calls to cursor-variables will be forwarded to inner.

Return the number of triples in db matching the query.

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

This is equivalent to (count-cursor (get-triples ...)) but implemented more efficiently.

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.

This function returns two non-negative values, min and max, that indicate the range in which the actual number of matches is expected to lie.

Note that the estimate may be too high, as it may include deleted triples and does not take into account whether triples are hidden by a static filter.

Searches in db for a triple matching the search pattern specified by s, p, o and g. 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*.

In case db is a distributed repository, a matching triple in any of the shards will be returned. In no case will a triple from a knowledge base repository be returned.

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

If a matching triple is found, then its data is copied into triple (if provided) or returned in a newly allocated triple.

This function will signal an error if db is a distributed repository.

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. Returns a cursor.

The following example finds every triple with subject !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)  
#<db.agraph::storage-layer-cursor <{Kevin}#( MIN )#( MIN )#( MIN )> - <{Kevin}#( MAX )#( MAX )#( MAX )>  
   :variables (s p o g) :ordering () @ #x100089ef052>  
> (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 filters triples based on the part arguments:

• s, p, o, g - specify the query pattern. Each of these can be a UPI, a future-part, a string that can be converted into a part (like <ex:foo>), or nil which acts as wildcard.

• s-end, p-end, o-end, g-end - specify the end of a range query. The possible types are as for s et cetera.

The filtering semantics are as follows, taking the subject as example:

• If s is given, and s-end is not, then this imposes a filter where the triple's subject must match the s value.

• If both s and s-end are given (they must both be encoded UPIs) only triples whose subject is in this UPI range are returned.

• Start value s can be the keyword :minimum, if s-end is provided; this means a range from smallest possible UPI to the given s-end value.

• The end value s-end can be the keyword :maximum, if s is provided: this means a range from s to the highest possible UPI.

Furthermore get-triples takes the following arguments:

• 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-extended-triples - if true, then get-triples will iterate over extended-triples (i.e., triples that contain both SPOG data and attribute data).

• order-by - this argument is for internal use only. To retrieve ordered triples, consider e.g. a SPARQL query that does "order by".

The return value is a cursor object. The basic operations on a cursor are cursor-next and cursor-row, and the combined version cursor-next-row. The cursor should finally be closed by calling discard-cursor. Unreferenced cursors that have not yet been closed, will eventually be closed by an automatically created finalizer that is called by the garbage collector.

There are higher-level cursor operations that automatically close the cursor at the end, like iterate-cursor and collect-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 (a cursor that returns zero result rows) and :part-not-found as second value.

In case db is a distributed repository, matching triples in all the shards will be returned. Triples in the knowledge base repositories are never part of the result.

Note on tracing: get-triples can be inlined by the compiler; trace db.agraph::get-triples-real instead.

Query a triple store for triples matching the given subject, predicate, object, and graph. Returns a list of matching triples.

The keyword arguments db, s, p, o, g, s-end, p-end, o-end and g-end, return-extended-triples, filter, order-by are used as in get-triples.

The get-triples-list function also supports these options:

• 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. If supplied and not nil, then at most this many triples will be returned. (Retrieving all triples on a big store might lead to memory exhaustion.)

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

Function get-triples-list returns two values:

• a list of triples, and nil - if there are matching triples and return-cursor is false;
• a list of triples, and a cursor - if there are matching triples and return-cursor is true;
• nil, t - if the search parameters were already present (interned) in the store, and there are no matching triples;
• nil, :part-not-found - if one of the search parameters is not present (not interned) in the store, meaning there cannot be matching triples.

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

Returns true if a triple matching s, p and o (and optionally g) can be found in the designated triple-store. If left unspecified, the triple-store designated by *db* will be searched.

This is useful when you care only about the presence of a triple and not its contents. If you want to use the triple, then use get-triple instead.

In case db is a distributed repository, this checks if there is a matching triple in any of the shards. Triples in the knowledge base repositories are ignored.

Returns the triple attributes from an extended-triple structure.

The format can be one of

• :probe - returns true if the extended-triple has any attributes and nil if it does not.

• :json - returns a JSON representation of the attributes. The output parameter controls where the representation is printed. It can be a stream, a filename, t meaning to *standard-output*, or nil meaning to return a string (nil is the default).

• :alist - returns an association list representing the attributes. Each element of the list will be (name . value). If a name has multiple values associated with it, then then value will be a list.

• :attributes-bag - returns the raw data structure representing the attributes. This structure is not documented and is subject to change and therefore its use is discouraged. Note that :attributes-bag is not supported on the remote Lisp client.

Example:

> (setf et (first (get-triples-list :return-extended-triples t :limit 1)))  
(#<extended-triple <a b c G> {"rank": "Low", "label": "test 1"}>)  
 
> (extended-triple-attributes et :json)  
"{\"rank\": \"Low\", \"label\": \"test 1\"}"  
 
> (extended-triple-attributes et :alist)  
(("label" . "test 1") ("rank" . "Low")) 

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 given triple from the triple store. triple-or-triple-id can be a triple object, or the id of a triple as returned by triple-id.

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

delete-triple returns t if the deletion succeeded, and nil if the triple id was invalid or the triple already deleted.

In case db is a distributed repository, the argument must be a triple object (not the triple id as integer). Given a triple the partitioning key can be used to determine the relevant shard from which the triple must be removed. But a triple id is ambiguous because several shards might have a triple with that id.

A call to delete-triple with an integer value will be handled most efficiently if the :i index is active.

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.

In case db is a distributed repository, calling delete-triples will delete all matching triples from all the shards. In no case will delete-triples remove data from the knowledge base.

Deletes duplicate triples in repository.

The MODE argument determines the test used to determine equality when testing for duplicates. Options are quad-based equality (spog, the default) or triple-based equality (spo).

• :db - Specifies the triple store to operate on. Defaults to *db*.

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

• :filter - This argument is not currently supported in AGTOOL.

• :commit - if true then commit before and after duplicates are deleted. Enabling this will improve performance.

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.

Additionally, the setting value can be a list that contains attributes aggregation strategy specification:

(:spog  
 ((<attribute-1> . <operation-1>)  
  (<attribute-2> . <operation-2>)  
  ...)) 

where <operation-N> is one of the following:

• :retain - keep the attribute value of the existing triple,

• :override - replace the value of the existing tripole the new one,

• :collect - collect all attribute values into a single multiset,

• :union - compute a set union of all attribute values,

• :intersection - compute a set intersection of all attribute values,

• :min - treat values as integers and take the minimum,

• :max - treat values as integers and take the maximum,

• :sum - treat values as integers and compute their sum.

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

• :return-extended-triples - if true, each cursor result will be an extended-triple

In case db is a distributed repository, this will look for and return duplicate triples across shards. The knowledge base repositores are ignored.

• :db - Specifies the triple store to operate on. Defaults to *db*.

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

• :filter - This argument is not currently supported in AGTOOL.

• :return-extended-triples - if true then the triples returned by this call will contain any attached attributes.

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

• :db - Specifies the triple store to operate on. Defaults to *db*.

• :indices - indices must be a list of indices to purge, or nil (the default) meaning purge all indices.

• :shard - 0-based index of the shard of a distributed repo to purge. When unspecified all shards are purged.

Cancels purge deleted triple job for the specified indices.

• :db - Specifies the triple store to operate on. Defaults to *db*.

• :indices - 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 - Specifies the triple store to operate on. 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, serialize-nqx, and serialize-ntriples-ascii.

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.

Just like serialize-nquads but includes triple attributes.

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

Just like serialize-ntriples but escapes non-ascii characters.

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

XML 1.1 will be used for serialization unless the configuration option XMLVersion is set to 1.0 in the configuration file or the variable *serializer-xml-version* is set to "1.0".

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 current set of namespace abbreviations is used as a seed (see display-namespaces).

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.

Return a list of valid index flavors for db, regardless whether they are currently active. db defaults to *db*.

If called on a store type that does not support indices, like in-memory-triple-store, an error is signalled.

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

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

If called on a store type that does not support indices, like in-memory-triple-store, an error is signalled.

Add flavor as active index to store db. The actual creation of the index happens at the next commit.

• flavor is the index flavor as keyword, like :spogi. The possible flavors are given by valid-index-flavors.

• :db defaults to *db*.

• :style is for internal use only.

Calling add-index with an index flavor that is already currently active has no effect.

If called on a store type that does not support indices, like in-memory-triple-store, an error is signalled.

Remove flavor as active index from store db. The actual dropping of the index happens at the next commit.

• flavor is the index flavor as keyword, like :spogi. The currently active index flavors are given by triple-store-indices.

• :db defaults to *db*.

Calling drop-index with an index flavor that is not currently active has no effect.

If called on a store type that does not support indices, like in-memory-triple-store, an error is signalled.

Optimize the indices in the repository at the given effort level.

• :db - Specifies the triple store to operate on. Defaults to *db*.

• :level - Optimization effort level (integer). The values 0 and 1 are reserved for internal use; 2 (default) writes out in-memory triple data and then performs an index optimization of all overlapping chunks; 3 is as 2 but then optimizes all chunks regardless of overlap, purging deleted triples.

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

• :indices - A single index flavor or a list of flavors. Values nil and :all mean: all indices.

• :shard - 0-based index of the shard of a distributed repo to optimize. When unspecified all shards are optimized.

Returns a report on db's storage usage, detailing its total disk size, number of triples and active indices, as well as more detailed information about its flavors, memory chunks and obsolete chunks.

• :db - Specifies the triple store to operate on. Defaults to *db*.

• :chunks - If true then include information about each disk chunk

Write a human-readable summary of the given storage-report to the given stream.

The storage-report was returned by the storage-report function

Write a json version of the given storage-report to the given stream.

The storage-report was returned by the storage-report function

Write the given storage-report to the given stream.

The storage-report was returned by the storage-report function

Ensure that the given triple store that is the value of db (default *db*) contains a vector store. If db is already a vector triple store then it will not be modified if supersede is nil. If supersede is true then the existing vector store in db will be completely removed before creating a new vector store in db. Only vector store triples will be deleted, the other triples in the store will remain. The embedder, model and api-key arguments are the same as for create-triple-store.

• :db - Specifies the triple store to operate on. Defaults to *db*.

• embedder - name of the embedding service

• :model - model to be used in the embedding service

• :dimensions - length of embedding vector

• :embedding-api-key - api key, if any, need by the embedding service

• :supersede - Replace existing vector store (vectors and metadata only) if it exists

Compute the embedding for text and add the text and embedding to the vector store. properties is a property list where the keys are strings and the values are either literals or resources written in ntriple format. If a value isn't in ntriple syntax then it is considered to be a literal. The function returns the object id that object will have after a commit-triple-store is done.

• :db - Specifies the triple store to operate on. Defaults to *db*.

• text - The string to be added to the vector store

• :properties - plist of properties and their values

• :embedding - embedding to use instead of text

Delete objects from the vector store

• :db - Specifies the triple store to operate on. Defaults to *db*.

• :text - delete this string from the vector store

• :all - delete all objects from the vector store

• :property - indentify a property to check for value

• :value - value for property to indentify objects to delete

return the value of a given property for the object object-id in the vector store

• :db - Specifies the triple store to operate on. Defaults to *db*.

• object-id - The resource that identifies this object. It can be a string, upi or future-part.

• property - The name of the property

return the text for the object object-id from a vector store

• :db - Specifies the triple store to operate on. Defaults to *db*.

• object-id - The resource that identifies this object. It can be a string, upi or future-part.

return the embedding for the object object-id from a vector store

• :db - Specifies the triple store to operate on. Defaults to *db*.

• object-id - The resource that identifies this object. It can be a string, upi or future-part.

compute the semantically closest top N (top-n) strings from a vector triple store

• :db - Specifies the triple store to operate on. Defaults to *db*.

• text - the string to search for semantic matches in the database

• :min-score - minimum score to consider a match

• :top-n - Return the top top-n matches

• :selector - body of sparql to select objects to consider. Should bind ?id to objects to consider for nearest neighbor if all objects are not to be considered.

• :embedding - embedding to use instead of text

return true if store in a vector store

• :db - Specifies the triple store to operate on. Defaults to *db*.

Return the parameters of the embedder matching the arguments. If no embedder is specified then all embedders are returned

• server - Specifies the URL of the AG server to operate on. Required.

• :embedder - name of embedder

• :model - model to use if not default

• :dimensions - length of embedding vector which may not may not be specifiable

Return the parameters of the llm matching the arguments. If no vendor is specified then all llms are returned

• server - Specifies the URL of the AG server to operate on. Required.

• :vendor - name of vendor

Define one or more of fedshard repos

• server - Specifies the URL of the AG server to operate on. Required.

• :definitions - fedshard definitions in lisp or lineparse format

• :supersede - true means overwriting existing definitions is permitted. (default is false)

Delete the definition but not the files of the named repo in the fedshard catalog

• server - Specifies the URL of the AG server to operate on. Required.

• repo - The name of the fedshard repo in the fedshard catalog whose definition will be deleted.

Delete the metadata of the named repo in the fedshard catalog. The metadata are such things as query options and namespaces that are usually set using Webview.

• server - Specifies the URL of the AG server to operate on. Required.

• repo - The name of the fedshard repo in the fedshard catalog whose metadata will be deleted.

Return the compiled definitions of the given fedshard repo or of all repos

• server - Specifies the URL of the AG server to operate on. Required.

• :repo - The name of the repo whose compiled definition is returned or all definitions if repo is nil

Split a shard into two shards

• :db - Specifies the triple store to operate on. Defaults to *db*.

• shard-number - the shard number to split

• :to-servers - list of server ids for the new shards

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.

Return (as multiple values) part's namespace Prefixed Name and Local Part (see https://en.wikipedia.org/wiki/QName for details).

For example,

(part-to-namespace !rdf:type)  
==>  
"rdf"  
"type" 

part can be a UPI, a future-part, or string with or without angle-brackets. If no namespace abbreviation can be found for part then part-to-namespace will signal an if error is true or just return the part unchanged if it is
nil.

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 AllegroGraph 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". Passing :index-literals (list "http://www.w3.org/2001/XMLSchema#byte" "en") would do the same. 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. The function freetext-charset creates freetext-charsets.

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. The function freetext-charset creates freetext-charsets.

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.

Creates and returns a freetext-charset that consists of items given to chars. chars must be a list of the following type of items:

• character - the character itself.
• (start-character end-character) - a range of characters (inclusive). The range is calculated based on Unicode codepoints (that is (code-char char)). The code of start-character must be less than or equal to the code of end-character for this choice to have any effect.
• :alpha - Characters that satisfy alpha-char-p.
• :digit - Characters that satisfy digit-char-p.
• :alphanumeric - Characters that satisfy alphanumericp.

If base is given, it must be a freetext-charset object (such as created by this function). Characters in base are included in the resulting charset.

Here are some examples:

(freetext-charset '(#a (#x #z) :digit))  
   ;; (char-code #a) is 97, (char-code #x) is 120, and  
   ;; (char-code #z) is 122. So characters with codes  
   ;; 97, 120, 121, 122, and all that satisfy digit-char-p.  
(freetext-charset '(#a (#z #x) :digit))  
   ;; Because (char-code #z) is greater than (char-code #x),  
   ;; the (#x #z) has no effect, so this is character with  
   ;; code 97 and all that satisfy digit-char-p.  
(freetext-charset (list :alpha :digit))  
(freetext-charset '(:alpha) (freetext-charset '(:digit)))  
   ;; The last two examples result in the same charsets, all  
   ;; characters that satisfy alpha-char-p or digit-char-p. 

Takes a textual query, and converts it into a query s-expression. Textual queries consist of text blocks (strings that will later be tokenized, stemmed etc), quoted text blocks, wildcard patterns and fuzzy patterns.

• A sequence of expressions forms an (and ...) expression.

• Expressions appearing in a sequence separated with | form an (or ...) expression. AND binds more strongly than OR.

• Parentheses can be used to form subexpressions.

• Whitespace is ignored between tokens, but preserved in:

  • Quoted strings.

  • Fuzzy match patterns.

  • In text blocks, except for leading whitespace and the last trailing whitespace character IF the block is followed by a wildcard pattern (otherwise all trailing whitespace is preserved). Example: "a b? c " => (:and "a " (:match "b?") "c ").

• Quoted strings use double quotes. It is possible to use a backslash to escape any character (including a double quote). These result in a (phrase ...) expression.

• Match patterns cannot contain any whitespace. Any word that contains a * or ? character will be considered a match pattern, unless it is a part of a quoted string. These result in (match ...) expressions.

• Fuzzy patterns have the form TEXT~DISTANCE, where DISTANCE is optional. TEXT can contain whitespace characters, but not wildcard (?, *) characters.

• Tokens are always formed by choosing the rule that gives the longest match at the current position. Thus "a b c?" will be (and "a b" (match "c?")), while "a b c~1" will result in (fuzzy "a b c" 1).

• If the input is empty the result will be (:or).

There is NO error handling and the output for invalid input is undefined. For example ')a b )))) c' will result in "a b"

Example:

 "foo \"bar baz\" (quux|bug*)" 

becomes

'(and "foo" (phrase "bar baz") (or quux (match "bug*"))) 

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-extended-triples is true, then the cursor will iterate over extended-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, symbol, 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. For a default graph upi, value is :default-graph. For a blank node, value is the blank node's integer representation (each unique blank node in a store gets a different number). 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. For some UPIs, including default graphs and blank nodes, the extra is an integer reserved for use by AllegroGraph.

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. It may contain duplicates or future-parts. It is internally normalized to a UPI< sorted list without duplicates.

• 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 and return it as an s-expression.

Calling run-sparql repeatedly on an already parsed query avoids the parsing overhead.

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, as if they were inserted at the front of string.

default-base

A string to use as the BASE for the SPARQL query

default-prefixes

An alist mapping string prefixes to namespace expansions; it can be a hash-table mapping strings to strings, or a list of (prefix expansion) elements like:

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

default-query-options

A mapping from string query option name to its value.

Execute a SPARQL query, then print or return the results.

query can be:

• a string like: "select ?s ?p ?o { ?s ?p ?o }". It will be parsed by parse-sparql providing default-base and default-prefixes and then executed;

• a previously parsed query, meaning the s-expression returned by parse-sparql (default-base and default-prefixes are ignored).

The repository against which the parsed query is executed is determined as follows:

• If host is provided, it must be the URL of a SPARQL endpoint. The query will be sent to the endpoint over HTTP, and the results collected. The results are returned in the format specified by output-format (see below);

• Otherwise the query is run against the repository given by db which defaults to *db*. Both create-triple-store and open-triple-store set *db*.

• If neither host nor db are provided, and *db* is not set, an error is signaled.

There output-format parameter is used to control the format of the results, and the relevant one depends on the query verb:

• For SELECT, ASK and UPDATE the output format value must be one of get-allowed-results-formats (supplying the verb), for example :sparql-xml, :alists or :cursor.

• For DESCRIBE and CONSTRUCT queries the output format value must be one of get-allowed-rdf-formats (supplying the verb), for example :turtle, :rdf/xml, :arrays or :cursor.

The query results are either printed, returned as data structure, or returned as cursor, according to the specified format:

• for text-based formats (like :turtle, :rdf/xml or :sparql-xml) the results are written to output-stream which can be one of:
  • t, indicating *standard-output*;
  • an open stream, e.g. an open file;
  • a pathname, which will be opened providing if-exists and if-does-not-exist;
  • nil, indicating that output should be collected in a string, which will be returned as first value.

• for programmatic formats (like :alists or :arrays) the results are collected in a data structure (like a list of alists, or a list of arrays) that will be returned as first value;

• for the cursor format (:cursor) a cursor will be returned as first value. Operators like iterate-cursor can be used to iterate over the results. All the cursor handling code must be wrapped inside with-query-environment to ensure the cursor resources are properly released.

Function run-sparql returns four values: result, verb, variables, and metadata.

The first value, result, is one of:

• an error code (keyword) if the query execution failed, like :failed, :memory-exhausted, :timeout, :service-failure;
• the query results as data structure (for programmatic formats);
• the output as string (for text-based formats with :output-stream nil);
• a cursor (for the :cursor format);
• or nil (otherwise).

The second value is the query verb: one of :select, :ask, :construct, :describe, or :update.

The third value, variables, depends on the query verb:

• for SELECT queries: the list of query variables;
• for ASK queries: the list (?result);
• for DESCRIBE queries: nil
• for UPDATE queries:

  • If a SILENT clause failed: the error object. For example if LOAD SILENT <http://example.com/non-existing.ttl> fails, the first return value, result, will indicate success, and the third value will be the "HTTP error" object.

  • Otherwise: nil.

• for CONSTRUCT queries: the list of variables (?s ?p ?o).

The fourth value is a structure containing query execution metadata. In its printed representation it includes among others:

• any warnings that occured during query execution;
• how long the parsing, execution, and output of the query took;
• the number of rows returned.

The execution of the query can be influenced by the following options:

• The limit parameter acts as if the query contained that value as LIMIT. If the query already contains a LIMIT, the minimum of the two will be used.

• The offset paramter acts as if the query contained that value as OFFSET. If the query already contains an OFFSET, the sum of the two will be used.

• with-variables must 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 output-format.

The handling of graphs is influenced by the following options:

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

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

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

Relevant for UPDATE queries:

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

Miscellaneous options:

• If verbosep is t, a log of the query execution 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: '("user" . "password")

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

• timeout specifies the number of seconds after which query execution will be canceled. Timeout checks occur regularly during query computation, but not during result generation. A value of nil (the default) means no timeout.

• user-attributes-prefix-permission-p must be true in order to run queries that include "prefix franzOption_userAttributes"; otherwise such errors signal an error.

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

Returns a list of keyword symbols that are valid when applied as values of rdf-format to a query with the given verb. if verb is not provided, the intersection of :construct and :describe (the two permitted values) is returned. With AllegroGraph 3.0, an additional engine argument is available. In a similar manner to verb, omitting this restricts the returned values to those that apply to all built-in query engines.

Example:

• Get formats for CONSTRUCT queries executed by the algebra query engine.

  (get-allowed-rdf-formats :construct :algebra)

Parse and execute a graphql query, then return the results. query - a string to parse and execute. namespaces - an alist (("prefix" . "expansion") ....) to be merged with namespaces. default-prefix - a string to prepend to graphql fields when mapping them to URIs. variables - a list (("$varname" . value) ...) to give values to variables in a query output-format - :json, :list, :listupi verbose - see all the steps in the parsing and execution