Search for an open triple-store named by designator. Designator can be one of the following:

• An object of type triple-db
• A pathname which is the directory of a triple-store (cf. data-directory)
• A string which can be coerced into a pathname which is the directory of a triple-store
• A string which is the name of an open triple-store.

Note that it is possible that two or more triple-stores are open which have the same naem. In this case find-triple-store will signal an error of type ambiguous-triple-store-designator.

Close the triple store, after saving all persistent data to disk as if by sync-triple-store. Close-triple-store has the following keyword arguments:

• :db - defaults to the value of *db* and specifies which triple-store to close. *db* is set to nil after the triple store is closed. A triple-store only needs to be closed once regardless of how many times open-triple-store has been called on it.

• :if-closed - controls the behavior when the db is either not open or nil. If if-closed is :error then an error will be signaled in this situation. If it is :ignore, then close-triple-store will just return without signaling an error. The argument defaults to :ignore.

• :verbose is true, then a message will be printed to *debug-io* before the triple store is closed.

• :wait is true then close-triple-store will not return until all of its concurrent activity is complete. This includes synchronizing its data, building indices and running queries. The value of :wait will be true unless overriden. If it is false, then close-triple-store will return immediately but the triple-store will no longer be available to use. Its actual in-memory structures will not be available to the garbage-collector until all of its background activity is complete and it is finally closed.

Create a new triple store with the given name. This is both the name of the triple-store and its location on disk. It can be the full path to a directory or just a directory name. If it is a simple name, then the directory argument is used to convert it to a complete path.

For example, to create a triple-store named 'animals' in the directory 'c:/datafiles/biology', you could use either

(create-triple-store  
 "c:/datafiles/biology/animals") 

or

(create-triple-store "animals"  
 :directory "c:/datafiles/biology/") 

The directory defaults to the directory component of *default-pathname-defaults*. You cannot use a name containing a directory path and the directory argument simultaneously.

Create-triple-store takes numerous keyword arguments:

• :if-exists - controls what to do if the data directory already exists. The default value, :supersede, will cause create-triple-store to delete the old triple store and create a new one; :error causes create-triple-store to signal an error; finally, the value :open will simply open the existing triple store as if you had called open-triple-store.

• :expected-unique-resouces - sets the initial size of the triple-store. It determines the number of unique names (e.g., resources and literals) that the triple store is expected to hold and defaults to the value of default-expected-unique-resources. The triple-store will grow if this number is exceeded but setting the value initially will provide better performance because no resizing will be required.

• :with-indices - adds indices to the newly created triple-store. It is equivalent to calling add-index once for each index in the list of indices. It defaults to the value of the AllegroGraph property standard-indices.

• :include-standard-parts - if true, then AllegroGraph will add the following strings to the triple-store at creation time: rdf:type, owl:sameAs, owl:inverseOf, rdfs:subPropertyOf, rdfs:subClassOf, rdfs:range, rdfs:domain, owl:transitiveProperty. The value defaults to the ag-property(:include-standard-parts).

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

Delete an existing triple store. Returns t if the deletion was successful and nil if it was not. The :db keyword 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 deleted. If it is a name, then the triple store of that name in the directory designated by the :directory keyword argument will be deleted. The directory parameter defaults to the directory component of *default-pathname-defaults*.

The :if-does-not-exist keyword argument specifies what to do if the data directory 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.

The :if-open keyword argument specifies the behavior if the designated triple store is currently open. The default value, :error, causes delete-triple-store to signal an error. The value :close causes delete-triple-store to close the triple store, as if by close-triple-store and then delete it. If AllegroGraph is unable to close the triple store, an error may still be signaled.

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

The directory used can be passed in as an optional parameter. If it is not supplied, then it will get its value from (ag-property temporary-directory).

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

Open an existing triple store (previously created using create-triple-store) with the given name. Name is both the name of the triple-store and its location on disk. It can be the full path to a directory or just a directory name. If it is a simple name, then the directory argument is used to convert it to a complete path.

For example, to open a triple-store named 'animals' in the directory 'c:/datafiles/biology', you could use either

(open-triple-store  
 "c:/datafiles/biology/animals")  
 

or

(open-triple-store "animals"  
 :directory "c:/datafiles/biology/")  
 

The directory defaults to the directory component of *default-pathname-defaults*. You cannot use a name containing a directory path and the directory argument simultaneously.

The :if-does-not-exist keyword argument specifies what to do if the data directory does not exist. The default value, :error, causes open-triple-store to signal an error. The value :create will cause open-triple-store to create the triple store as if by a call to create-triple-store.

You can use the :with-indices parameter to add additional indices to the triple-store. (Adding an index multiple times has no effect). This will not remove any indices that already exist (see drop-index and drop-indices if you need to do that).

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 the same object.

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

The function prepare-reasoning returns no value.

Returns true if the triple-store with the given name exists. Name can be the full path to a directory or just a directory name. If it is a simple name, then the directory argument is used to convert it to a complete path.

For example, to verifty the existance of a triple-store named 'animals' in the directory 'c:/datafiles/biology', you could use either

(triple-store-exists-p  
 "c:/datafiles/biology/animals")  
 

or

(triple-store-exists-p "animals"  
  :directory "c:/datafiles/biology/")  
 

The directory defaults to the directory component of *default-pathname-defaults*. You cannot use a name containing a directory path and the directory argument simultaneously.

Add triples from source to the triple store.

• :db - specifies the triple-store to load into and defaults to the value of db.

• :default-graph defaults to nil, which is interpreted as db's default graph. If supplied, it can be:

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

  • the keyword :source (in which case the source argument will be interned as a URI and the loaded triples added to a graph named by that URI)

• The :verbose argument specifies whether or not progress information is printed to the listener. It defaults to the value of (ag-property :verbose).

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

• source - can be a stream, a pathname to an N-Triples file or a string that can be coerced into a pathname to an N-Triples file.

load-ntriples returns the number of triples added, and the default-graph used, as multiple values.

Add all of the triples from the string to the triple store. The following keyword parameters can be used to control the loading process:

• :db - specifies the triple-store to load into and defaults to the value of db.

• :default-graph defaults to nil, which is interpreted as db's default graph. If supplied, it can be:

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

  • the keyword :source (in which case the source argument will be interned as a URI and the loaded triples added to a graph named by that URI)

• The :verbose argument specifies whether or not progress information is printed to the listener. It defaults to the value of (ag-property :verbose).

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

load-ntriples-from-string returns the number of triples added, and the default-graph used, as multiple values.

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

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

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

• :default-graph defaults to nil, which is interpreted as db's default graph. If supplied, it can be:

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

  • the keyword :source (in which case the source argument will be interned as a URI and the loaded triples added to a graph named by that URI)

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

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

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

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

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

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

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

If error-on-invalid-p is t, the serializer will throw an error if it encounters a type or predicate that it cannot abbreviate for RDF/XML.

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

If from is a cursor, it cannot be traversed multiple times, so prepare-namespaces-p is ignored. If a property is encountered that cannot be abbreviated with the current available prefixes, an error will be signaled, unless error-on-invalid-p is nil. You should be aware of this before using this serializer: serializing the output of a cursor can fail if you do not first prepare namespace mappings, or specify that invalid output is acceptable.

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

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

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

If nestp is t, then (subject to the order of triples in the triple store) some nesting of RDF/XML elements will be applied. nestp of nil will cause a flat tree to be produced, where each resource is its own top-level element.

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.

Please note that the RDF/XML serializer is not guaranteed to work correctly with value-encoded literals.

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.

parse-sparql takes a string and parses it into an s-expression format. A parse error will result in a sparql-parse-error being raised.

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

You do not need an open triple store in order to parse a query.

default-base and default-prefixes allow you to provide BASE and PREFIX arguments to the parser without inserting them textually into the query.

default-base should be nil or a string, and default-prefixes can either be a hash-table (string prefix to string expansion) or a list similar to db.agraph:*standard-namespaces*.

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

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

SELECT and ASK query results will be presented in results-format; the RDF output of DESCRIBE and CONSTRUCT will be serialized according to rdf-format. If the format is programmatic, any results will be returned as the first value, and nothing will be printed on output-stream.

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

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

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

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

• 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 triple store's default graph).

• with-variables should be an alist of symbols and values. Before the query is executed, the variables named after symbols will be bound to the provided values. This allows you to use variables in your query which are externally imposed, or generated by other queries. The format expected by with-variables is the same as that used for each element of the list returned by the :alists results-format.

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

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

Three additional extensions are provided for your use.

• If extendedp is true (or *use-extended-sparql-verbs-p* is true, and the argument omitted) some additional SPARQL verbs become available. SUM, AVERAGE, MEDIAN, STATS, CORRELATION, and COUNT can all be used in place of SELECT. These verbs are still experimental and undocumented.

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

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

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

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

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

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

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

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

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

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

Individual results formats are permitted to return additional values.

Run the provided query, using the results to construct a new graph. The new graph is either returned or serialized onto output-stream as specified by the format argument. construct-pattern must be a list of triple patterns. query-pattern is used as input to run-sparql-select.

See the documentation for run-sparql for more information.

UPI coercion depends on the current value of db!

Run the provided query, using the results to construct a new graph. The new graph is either returned or serialized onto output-stream as specified by the format argument. targets is a list of resources to describe. query is used as input to run-sparql-select to yield further resources to describe.

See the documentation for run-sparql for more information.

Run the provided query, serializing the results as specified by the format argument. :distinct can be t or :distinct, meaning full DISTINCT processing, or :reduced, which optionally discards duplicates.

See the documentation for run-sparql for more information.

Return a list of alists, each of which contains the values for variables in order. If variables is not provided, you can find the variables as the second return value.

Return a list of lists, each of which contains the values for variables in order. If variables is not provided, you can find the variables as the second return value.

Add a new triple to the triple-store with the given subject, predicate and object and graph, specified either as UPIs or strings in N-Triples format. The :db keyword argument specifies the triple store to which the triple will be added and defaults to the value of *db*. Returns the numeric id of the new triple.

Note that duplicate triples can be added to a triple-store but indices will only refer to the same triple once.

Marks the triple whose id is id as deleted.

See also undelete-triple and undeleted-triple-p.

The :db keyword argument specifies the triple store in which the triple should be marked as deleted.

Delete triples matching the given subject, predicate, object, and graph, specified either 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, defaulting to the value of *db*.

Returns a boolean indicated whether the triple whose ID is id is deleted.

The :db keyword argument specifies the triple store in which to check.

Sets and gets the graph UPI of a triple.

In addition to being returned, the optional upi argument will be filled in with the graph's UPI. If not passed in, a new UPI will be created.

Sets and gets the object UPI of a triple.

In addition to being returned, the optional upi argument will be filled in with the object's UPI. If not passed in, a new UPI will be created.

Sets and gets the predicate UPI of a triple.

In addition to being returned, the optional upi argument will be filled in with the predicate's UPI. If not passed in, a new UPI will be created.

Sets and gets the subject UPI of a triple.

In addition to being returned, the optional upi argument will be filled in with the subject's UPI. If not passed in, a new UPI will be created.

Unsets the deleted flag from the triple whose id is id.

The :db keyword argument specifies the triple store in which the triple should be marked as undeleted.

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

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

Decodes UPI and returns the value, the type-code and any extra information as multiple values. These three things can be interpreted as follows:

• value - a string representing the contents of the UPI
• type-code - an integer corresponding to one of the defined UPI types (see supported-types for more information). You can use type-code->type-name to see the English name of the type.
• extra - Some encoded UPIs contain additional information which will be placed in extra if it is there. Examples include the language code or datatype of a literal.

Examples:

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

Create a new future-part with the provided values.

If provide, the language argument should be a valid RDF language tag.

If provided, the datatype can be a string or future-part specifying a resource. 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.

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 

Returns the type encoding for string. String should be XML Schema type designator. For example:

> (datatype-mapping "http://www.w3.org/2001/XMSchema#unsignedByte")  
:unsigned-byte 

see (setf datatype-mapping) for more information.

Returns the type encoding for string. String should be the uriref of a property. For example:

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

See (setf predicate-mapping) for more information.

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.

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. These three things can be interpreted as follows:

• value - a string representing the contents of the UPI
• type-code - an integer corresponding to one of the defined UPI types (see supported-types for more information). You can use type-code->type-name to see the English name of the type.
• extra - Some encoded UPIs contain additional information which will be placed in extra if it is there. Examples include the language code or datatype of a literal.

Examples:

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

Register the predicate predicate for freetext indexing in the triple-store db. Once registered, any triples with this predicate will have the string of their object indexed by AllegroGraph's built-in freetext indexer. Use the db keyword argument to specify the triple-store in which to register the predicate. If left unspecified, the predicate will be registered in triple-store *db*.

 (register-freetext-predicate  
      !<http://www.w3.org/2000/01/rdf-schema#comment>) 

note that you have to register predicates before you add triples with that predicate. Older triples will not get indexed.

Returns a list of ids of the triples whose object contains text matching the expression.

(freetext-get-ids "amsterdam")  
(freetext-get-ids "\"Good girls go to heaven,  
                     bad girls go to Amsterdam\"")  
(freetext-get-ids '(and "amsterdam" "usa"))  
(freetext-get-ids '(and "amst?r* (or "us?" "neth*"))) 

Returns a cursor that iterates over the triples whose objects contain text that matches the expression.

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

Returns all the unique subjects in triples whose objects contain expression. This is a useful function in prolog queries. The following example is included in the tutorial.

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

Adds a new index flavor to a triple-store.

The actual index data structure will be created the next time that AllegroGraph indexes the triple-store (either by a call to index-new-triples or index-all-triples or automatically through the management policy of the triple-store.)

The :db keyword argument specifies the triple-store to which to add the index and will be *db* unless otherwise specified.

The :location keyword argument controls the physical location of the index. It can be left unspecified or set to the location of a directory. If left unspecified, the index will be located in the same directory as the triple-store (see data-directory). If used, it should name an empty directory.

Flavor should be a valid index name (e.g., :posgi). See index-flavors in the reference guide for additional details

Adds several indices to a triple-store at once.

Flavors should be a list of valid index flavors. See add-index for additional details.

Returns the average index-fragment-count for a triple-store. This is the total number of index chunks divided by the number of indices. The higher the chunk count, the more work each query must do to find results.

The keyword argument :db can be used to specify the triple-store to use. It defaults to *db*.

Remove an index from a triple-store.

The flavor argument should be a valid index flavor name that is currently an index of the triple-store.

The keyword argument :db controls the triple-store from which the index will be removed. It will default to *db* unless otherwise specified.

Flavor should be a valid index name (e.g., :posgi). See index-flavors in the reference guide for additional details

Remove several indices from a triple-store at once.

Flavors should be a list of valid index flavors that are indices of the triple-store. See drop-index for more details.

Create a unified index of all the triples in the triple store, including triples previously indexed. The time taken to index all triples includes the time index-new-triples plus the time to merge all index chunks. The first step is proportional to the number of unindexed triples multiplied by the logarithm of the same number (i.e., if N is the number of new triples, then the time is O(N log N)). The merge step is proportional to the total number of triples multiplied by the logarithm of the number of chunks. If you have a very large triple store to which you have added a fairly small number of new triples, you can use index-new-triples to get most of the benefits of indexing at much lower time cost.

Indexing can run as a background task in either the same Lisp process or on mulitple remote Lisp processes (see the clustering documentation for more details). Index-all-triples return the task id of the indexing task that it creates.

The wait keyword argument controls whether index-all-triples returns immediately or waits for all indexing and merging to complete. It defaults to true. If it is false, you can use the id of the task returned to see if indexing has completed.

See the variable maximum-indexing-sort-chunk-size for information on controlling the indexing process.

Index the triples that have been added to the triple store since the last time indices were built. The time taken to index new triples is proportional to the number of unindexed triples multiplied by the logarithm of the same number (i.e., if N is the number of new triples, then the time is O(N log N)).

However, the new indices will not be merged with the older indices which will cause queries to execute more slowly. To maximize query performance you will want to use index-all-triples to build a unified index.

Indexing can run as a background task in either the same Lisp process or on mulitple remote Lisp processes (see the clustering documentation for more details).

The wait keyword argument controls whether index-new-triples returns immediately or waits for all indexing to complete. It defaults to true. If it is false, then index-new-triples return the id of the indexing task that is created.

See the variable maximum-indexing-sort-chunk-size for information on controlling the indexing process.

Returns the status of the current triple-store as regards indexing. This can be one of:

• :scheduled

• :running

• :needed

• :idle

Returns a list of information on the indices of a triple-store.

The :db keyword argument specifies the triple-store on which to report.

The :verbose keyword argument controls how much information to return. If verbose is nil, then only the flavor-names are returned. If it is true, then a list of lists is returned where each sublist starts with an index object and continues with ranges of the unindexed triples.

Returns the next triple from the cursor. The actual triple object returned is always the the same (eql) object. If you want to hold onto a triple for use after you advance the cursor, use the function copy-triple to make a copy of the value returned by next-row

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

Iterate over the triples in cursor while applying the function fn to each one. Use the count keyword to limit the maximum number of triples that map-cursor visits. In each iteration fn is applied to the curent triple and to the list of arguments in args. map-cursor reuses the triple argument as it iterates so make sure to use copy-triple if you are retaining any of the triples that you visit.

The function returns the number of triples visited.

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

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

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

The function get-triples takes the following arguments:

• s, p, o, g - controls the actual query pattern. Use nil as a wildcard.

• s-end, p-end, o-end, g-end - Allows for range queries over encoded triples (triples whose parts are encoded UPIs). Each ?-end parameter may only be used in conjunction with its corresponding starting value parameter.

• The :db keyword argument specifies the triple store to query, defaulting 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.

• include-deleted - if set to true, then triples that are flagged as deleted will not be filtered out by the cursor.

• return-encoded-triples - If true, then get-triples returns triples with encoded parts; i.e., triples that use directly encoded UPIs rather than strings stored in the dictionary. The is set to true unless overridden.

• return-non-encoded-triples - if true, then get-triples will return triples all of whose UPIs are stored as strings. This is set to true unless overridden.

The return value is a cursor object. The functions next-row and next-p operate on this cursor.

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

• db - This keyword argument specifies the triple store to query, defaulting to the value of *db*.

• s, p, o, g - controls the actual query pattern. Use nil as a wildcard.

• s-end, p-end, o-end, g-end - Allows for range queries over encoded triples (triples whose parts are encoded UPIs). Each ?-end parameter may only be used in conjunction with its corresponding starting value parameter.

• cursor - if cursor is supplied then AllegroGraph will use it to return more triples rather than building a new cursor.

• if-fewer - controls the behavior of get-triples-list when fewer than limit triples match the query. Possible values are (defaults to nil):

  • nil - return list of actual results

  • :error - signal error if fewer results than limit
    

  • other -- return other instead of short list

• if-more - controls what happens when more results than limit are available. Possible values are (defaults to :cursor):

  • nil - return list of limit results

  • :error - signal error if more results than limit

  • :cursor - return the list of limit results and a second value of a cursor that will yield the remaining results

  • other - return other instead of truncated list

• limit - This keyword argument can be used to place a cap on the maximum number of triples returned. It defaults to the value of the special variable get-triples-list-limit. If set, then get-triples-list will return no more than :limit triples. If it is nil, then get-triples-list will return all of the triples found by the query. Warning: setting limit to nil can cause get-triples-list to return every triple in the triple-store; this can be a very bad thing over a serial connection.

• return-encoded-triples - If true, then get-triples-list returns triples with encoded parts; i.e., triples that use directly encoded UPIs rather than strings stored in the dictionary. The is set to true unless overridden.

• return-non-encoded-triples - if true, then get-triples-list will return triples all of whose UPIs are stored as strings. This is set to true unless overridden.

• use-reasoner - if true, then the RDFS++ reasoner will be used to return inferred triples. If left unspecified, this will take on the value of *use-reasoner*. Note that most of the arguments to get-triples-list do not make sense when reasoning is turned on. AllegroGraph will signal an error if you try to combine reasoning with other parameters that it cannot use.

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

Start a server that allows client programs to access AllegroGraph triple stores.

• The port argument (default 4567) is the port number where the server listens for connections.

• The jport argument is unused but reserved for situations where two ports are required.

• The users argument specifies the number of simultaneous connections allowed. The default is 50.

• The limit argument specifies the total number of connections allowed over the life of the server. The default is nil to specify unlimited connections.

• The root argument, when non-nil, specifies a default pathname for the entire Lisp image running the server.

• The nanny argument may be nil or a number n of seconds. When non-nil, all connections are scanned every n seconds and triple stores opened by dead connections are closed.

• The ender argument specifies a function of no arguments. This function is called just before the triple store associated with a dead connection is closed.

• The timeout argument specifies a time interval in seconds. If a triple store cannot be accessed within this time interval, an error is signalled.

• The idle-life argument specifies a time interval in minutes. If a triple store is open but idle for this interval, it is closed automatically (and re-opened if needed).

• The indexing argument is currently ignored.

• The verbose and debug arguments may be non-nil to trigger status and progress messages.

The function returns two values: a server port instance that becomes the default server port, and the port number where the server is listening.

Method (agj-server)

Stop the connection identified by the argument.

Method (integer)

Stop the connection identified by integer.

Method (agj-server)

Stop the listening server. If the optional argument is non-nil, stop any running connections as well. The default is t.

Method (null)

Stop the default listening server. If the optional argument is non-nil, stop any running connections as well. The default is t.

This function enables or disables progress messages from client calls. The arguments and results of each call from the client are printed.

The onoff argument may be omitted, nil, :toggle, :close, a string, or any other non-nil value.

Two values are returned, the previous trace state and the new trace state, in that order.

• If the argument is omitted, the function returns the current trace state.

• If the argument is nil, a previous trace state is terminated.

• If the argument is :toggle, the current trace state is reversed.

• If the argument is :close, a previous trace state is terminated.

• If the argument is a string, it should be a pathname to a writable file. The file is opened and supersedes any existing file. Trace output is initiated, and sent to the file.

• Any other non-nil value initiates trace output to standard-output.

This function maps triple store integer ids to the actual triple store instance.

The client code references each triple store by an integer identifier. This integer is printed in the ag-server-trace output.

• If the tsx argument is nil or unspecified, the function retuns an alist of all known triple stores.

• If the tsx argument is an integer, the function returns the specified triple store instance.

• If the setdb argument is non-nil, then the current (global) value of *db* is set to the triple store instance.

When the server argument is an instance of sesame-server, start that Sesame server instance.

When the server argument is nil, start a Sesame server using the default server instance.

When the server argument is an instance of sesame-server, stop that Sesame server instance.

When the server argument is nil, stop the default Sesame server instance.

This function creates a sesame-server instance and optionally starts the HTTP server. The returned value is the server instance. This value also becomes the default server.

• The path argument (default is /sesame) specifies the initial part of the server URL.

• The timeout argument is the default timeout value for all registered triple stores. If a triple store is not available within that number of seconds, a bad request return code is sent back to the client. The default is 15 seconds.

• The idle-life argument is the default idle interval in minutes for an open triple store. If a triple store staus open but idle for this interval, it is closed automatically. The default is 10 minutes.

• The start argument, if non-nil, ensures that the HTTP server is running. If the value is a list, it is passed to the AllegroServe start function. The most common value is (list :port nnn).

• The wserver argument may be an AllegroServe wserver instance.

• The class argument (default sesame-server) allows applications to provide a sub-class.

• If the output-stream argument is specified, it must be a stream. This stream will be bound to standard-output, terminal-io, and debug-io in worker threads running Sesame HTTP requests. Binding this argument to initial-terminal-io may be needed when running under eli.

When the server argument is an instance of sesame-server, make a triple store available as a Sesame 2.0 Remote Repository on that server.

If db is specified, name and directory must be omitted or consistent. If name and directory are specified, db must be omitted or consistent.

The specified database will be opened and closed as required.

Id defaults to name; it is the id by which the database will be known to clients. If id is not unique, an error is signalled.

When the server argument is nil, make a triple store available as a Sesame 2.0 Remote Repository. The default server instance is used for the operation.