Add triples from source 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. This can be more efficient than iterating over the items yourself since AllegroGraph will only synchronize at the end of the loading.

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

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

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

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

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

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

• :verbose - specifies whether or not progress information is printed as triples are loaded. It defaults to 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).

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

load-ntriples returns the number of triples added, and the 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 into which triples will be loaded. This defaults to the value of *db*.

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

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

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

• :verbose - specifies whether or not progress information is printed as triples are loaded. It defaults to 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).

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

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

Add triples from the named RDF/XML file to the triple-store.

Returns the number of triples added.

The additional arguments are:

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

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

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

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

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

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

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

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

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

Add triples from source 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. This can be more efficient than iterating over the items yourself since AllegroGraph will only synchronize at the end of the loading.

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

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

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

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

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

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

• :verbose - specifies whether or not progress information is printed as triples are loaded. It defaults to 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).

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

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

Add all of the triples from the string 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.

The strings should be in N-Quad format.

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

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

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

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

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

• :verbose - specifies whether or not progress information is printed as triples are loaded. It defaults to 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).

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

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

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

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

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

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

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

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

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

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

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

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

Load a string containing data in TriX format into db

• string - a string containing TriX data

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

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

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

See load-trix for more details.

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.

Create a new future-part with the provided values.

• :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 the string URI, make sure that it is stored in the 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.

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.

• :language - if supplied, then this language will be associated with the literal value. See rfc-3066 for details on language tags.

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

Compute the UPI of value treating it as an typed literal with datatype datatype. Ensure that the literal is in the store's string dictionary and return the UPI.

• value - must be a string

• datatype - a URI, a future-part specifying a URI or a UPI specifying a URI.

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

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.

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.

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

• upi - the UPI to decode

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

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

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

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

Examples:

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

See value->upi for additional information.

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

• upi - a UPI

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

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

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

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

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

• resource - the prefix (if applicable)
• typed-literal - the datatype
• language-literal - 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)
• typed-literal - the literal without the datatype
• language-literal - 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.

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

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

Moves cursor forward to the next triple 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 triple.

Note that cursor-row, cursor-next and cursor-next-p 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 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 cursor-next-row

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

Returns the triple that cursor is currently pointing at.

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

Note that cursor-row, cursor-next and cursor-next-p are lower-level cursor manipulation routines. You may be better served by using collect-cursor, count-cursor, map-cursor and iterate-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 current triple and to the list of arguments in args. map-cursor reuses a single triple as it iterates so make sure to use copy-triple if you retain any of the triples you visit.

The function returns the number of triples visited.

Return the number of triples in db matching the query using only the indices.

Unindexed triples will not be included. An error will be signaled if the triple-store is missing the required index for the query.

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

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

Unindexed triples will not be included. An error will be signaled if the triple-store is missing the required index for the query.

Note that the estimated count includes deleted triples, encoded triples and unencoded triples.

The estimate can be off by as much as twice the triple-store's metaindex-skip-size for each index chunk that must be searched.

Query a triple store for triples matching the given subject, predicate, object, and graph. These can be specified either as UPIs, future-parts, strings in N-Triple format, or the wildcard nil. Returns a cursor object that can be used with cursor-next-p and cursor-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 - specify the query pattern. Use nil as a wildcard. Each of these can be a UPI, a future-part, or a string that can be converted into a part. These can also take on the value :minimum if a corresponding ?-end parameter is specified. If :minimum is used, then the range query will run from the smallest value up to the ending value.

• s-end, p-end, o-end, g-end - Allows for range queries over encoded triples (triples whose parts are encoded UPIs). Each ?-end parameter may only be used in conjunction with its corresponding starting value parameter. Each of these can be a UPI, a future-part, or a string that can be converted into a part. These can also take on the value :maximum if a corresponding starting parameter is specified. If :maximum is used, then the range query will run from the starting value up to the maximum value in the triple-store.

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

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

The return value is a cursor object. The functions cursor-next-row and cursor-next-p can be used to step through the cursor.

If it can be determined that one of the search parameters is not interned in the triple-store, then get-triples will return a null-cursor (i.e., a cursor that has no rows) and a second value of :part-not-found.

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 - Deprecated. If true, then the RDFS++ reasoner will be used to return inferred triples. If left unspecified, this will be true if the db is a reasoning-triple-store and nil otherwise.

Note that most of the arguments to get-triples-list do not make sense when reasoning is turned on. AllegroGraph will signal an error if you try to combine reasoning with other parameters that it cannot use.

If it can be determined that one of the search parameters is not interned in the triple-store, then get-triples-list will return immediately return nil.

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 and (ag-property :default-print-triple-format) 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.

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 and (ag-property :default-print-triple-format) 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.

Gets the size of the spogi cache. Setfable.

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.

Note that

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 positive integer. If you use a positive integer, it has the same effect as turning caching on and setting the spogi-cache-size to that value.

Marks the triple whose id is id as deleted.

Returns t if the triple deletion flag has been changed. Returns nil if the triple was already deleted.

See also undelete-triple and deleted-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.

See also delete-triple and undelete-triple.

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

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

Returns t if the triple deletion flag has been changed. Returns nil if the triple was not deleted before the call.

See also delete-triple and deleted-triple-p.

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

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

The :db keyword argument specifies the triple store to query, defaulting to the value of *db*.

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

Returns the triple printed.

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

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

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

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

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

In other respects this function behaves like print-triples.

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

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

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

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

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

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

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

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

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

xml-base can be t, in which case a generated UUID xml:base attribute is written into the serialized RDF/XML, or a string, UPI, or future-part naming a URI. It can also be a triple-store instance; in this case, a UUID URN associated with the store is used.

For persistent stores this value should remain constant.

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

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

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

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

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

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

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

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

Returns the manifest path and the number of graphs saved.

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

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

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

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

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

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

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

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. If the db being closed is eq to *db*, then *db* is set to nil` after it 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 overridden. 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.

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

• :triple-store-class - the kind of triple-store to create. If left unspecified, then the value of the property :default-triple-store-class will be used. Depending on the class of the triple-store created, other parameters may be possible or required. For example, creating a remote-triple-store requires that you also specify a connection instance.

• :text-index-parameters - a property list describing additional freetext-indexing parameters such as :stop-word-list, :stop-word-file or :minimum-word-size.

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-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 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*. If db-or-name is eq to *db*, the *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 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. Make-tutorial-store takes two keyword parameters:

• :temporary-directory - the directory where the store will be created. If it is not supplied, then it will get its value from (ag-property temporary-directory).

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

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.

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.

WARNING Multiple calls to open-triple-store with the same arguments will each return the same (eq) triple-store. This means that closing a store in one thread will also close the store for all other threads that have opened it. Please contact Franz support staff ([email protected]) for multi-threaded programming strategies

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

The function prepare-reasoning returns no value.

Ensure that all persistent data needed by the triple store is saved to disk.

Called automatically by close-triple-store and the bulk loading operations like load-ntriples. The :db keyword argument defaults to *db*. Returns t.

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

Note that reasoning triple-stores do not report accurate triple-counts (doing so might take an inordinate amount of time!).

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 verify the existence 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.

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

Merge-new-triples combines smaller index chunks into larger ones without trying to merge all of the chunks into one. Suppose, for example, you have loaded a triple-store with 100-million triples and then called index-all-triples. Now suppose you add several batches of a few thousand triples and call index-new-triples after each batch. At this point each index flavor will consist of many chunks: one big one for the initial load and many small ones. A full merge will take significant time and computational resources but having this many chunks makes for inefficient querying. This is when merge-new-triples is a useful half-way measure. It will merge the small chunks into one (which should be quite fast). This will improve query performance without requiring a complete merge.

merge-new-triples determines whether an index chunk is smaller than another one if it is less than (smaller-than-factor (policy-manager *db*)). This value is settable per store and persists when the store is closed. It is normally set to 0.1. As an example, if you have a chunks of sizes 10,000, 2000, 1000, 1000, 1000 and 500, then a call to merge-new-triples will merge the four smallest chunks and leave you with three chunks of sizes 10,000, 3500 and 2000.

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

Note that reasoning triple-stores do not report accurate triple-counts (doing so might take an inordinate amount of time!).

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 sub-list starts with an index object and continues with ranges of the unindexed triples.

Enables the use of the !-reader macros. The values returned are the previous definition of the character in the current readtable.

Note: enable-!-reader modifies readtable specified by the optional readtable argument. 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 exclaimation mark character in other Lisp packages and systems may break. Generally speaking, it is possible to work around these issues. Please contact support for additional help.

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

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

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

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

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

Returns the predicate.

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

Returns true if there are any registered-freetext-predicates that may have triples that need to be added to the freetext-index of db.

• :db - the triple-store to check; defaults to *db*.

Ensure that all freetext-registered-predicates have been applied to every triple in the store.

• :db - the triple-store to check; defaults to *db*.

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

Words smaller than text-index-minimum-word-size will not be indexed.

This is setfable. See also text-index-parameters.

A list of words that will not be indexed.

This is setfable. See also text-index-parameters.

A property list describing additional freetext-indexing parameters.

These include:

• :stop-words - a list of words that will not be indexed
• :minimum-word-size - words smaller than this will not be indexed.

text-index-parameters is also setfable.

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

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

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

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

• upi - the UPI to decode

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

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

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

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

Examples:

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

See value->upi for additional information.

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

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

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

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.

Returns the type encoding for part. Part should be XML Schema type designator. For example:

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

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

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

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

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

The scope of the mapping is the 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 

Create a new federated triple-store named name which federates each of the triple-stores listed in stores. This also sets *db* to the value of the federated store.

A error of type name-in-use-error is signaled if name already names a triple-store (see find-triple-store).

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-args are passed along to the newly created store.

Create an encapsulation that allows only some triples to be seen in the inner 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 with graph-filtered- and add a gensym suffix.
• graphs - A non-empty list of triple part specifiers. Only the triples in the graphs specified by this list are visible in the encapsulated store.
• cached-wrapper-key - If this argument is nil, the call creates a new instance of a filtering wrapper. If the argument is t, a new key is generated from the list of graphs. This key will be equalp to any other key generated from the same set of graphs. If the argument is any other non-nil value, it is used as a key in an equalp hash-table; if a previously created wrapper is found, the previous instance is returned. If no entry is found, a new wrapper is created and saved in the table. The default value is taken from the variable *cached-wrapper-key*. The initial value of this variable is nil.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

FROM FROM

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

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

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

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

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

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

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

Three additional extensions are provided for your use.

• If extendedp is true (or *use-extended-sparql-verbs-p* is true, and the argument omitted) 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, and can only be used with the :allegrograph-2 query engine. extendedp also controls other syntactic extensions in SPARQL queries, such as GEO syntax. Extensions are enabled by default in all versions of AllegroGraph after 3.2.

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

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

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

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

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

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

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

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.

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

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 the requested variables in order.

If variables is not provided, you can find the names of the ones returned in the second return value.

Return a list of lists, each of which contains the values for the requestedvariables in order.

If variables is not provided, you can find the names of the ones returned in the second return value.

The location where UPI maps are kept for this store.

The persistent and settable property helps control where AllegroGraph will search for UPI maps for this triple-store. If nil, the UPI maps are kept in the maps sub-directory of the triple-store's directory. If non-nil, then UPI maps will be kept in the directory this property specifies.

Though this property is necessary to use UPI maps with a read-only triple-store, it also adds several risks to triple-store management. Care must be taken that multiple triple-stores do not place their UPI maps in the same directory -- the results in this situation are undefined. Secondly, UPI maps in an external directory will not be automatically deleted. This issues will be ameliorated in future-releases

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

• db - the triple-store to encapsulate. The defaults to the value of *db*.
• name - the name to give the encapsulated-triple-store. Defaults to the current db-name of the db prefixed with rdfs++- and with a generated suffix .
• has-value-reasoning-enabled - when true, enable OWL hasValue reasoning. The default is nil.
• inferred-graph - This argument specifies the graph component of all inferred triples. The default is to use the default graph of the specified triple store.
• cached-wrapper-key - If this argument is nil, the call creates a new instance of a reasoning wrapper; this instance will cause a new invocation of prepare-reasoning when the first query is issued. If the argument is not nil, it is used as a key in an equalp hash-table; if a previously created wrapper is found, the previous instance is returned. If no entry is found, a new wrapper is created and saved in the table. The default value is taken from the variable *cached-wrapper-key*. The initial value of this variable is nil.
• remote-reasoning - This argument is meaningfull only when the db (or *db*) argument is a remote-triple-store instance. A non-nil value specified that the reasoning wrapper is created on the server side. The value returned by apply-rdfs++-reasoner is a new remote-triple-store instance pointing to the reasoner on the server side.

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

The function prepare-reasoning returns no value.

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

• The idle-life argument specifies a time interval in seconds. If a triple store is open but idle for this interval, it is closed automatically (and re-opened if needed). The default is 24 hours, i.e. (* 24 60 60).

• The indexing argument is currently ignored.

• The worker-stream argument specifies a stream that worker threads can use for random output. The value nil specifies the system default. The value t specifies initial-terminal-io. Any other value must be a suitable stream. When running the server under the Franz Emacs-Lisp interface, the value t may be needed to avoid background-stream errors.

• The error-log argument specifies a stream or file path where error information can be printed. The default is nil. When nil, the error information is sent to the client. When t, print error information on the server console. When :none, error information is not generated at all.

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

• The eval-in-server-file is nil (client eval requests not allowed) or is a filename where each line is a regular expression of a valid Lisp expression. If the contents of the file change while the server is running the server tables are updated. The server checks the file every 10 seconds. The file must exist when the server is started. If the file is deleted while the server is running, the table is cleared, and subsequent client eval requests are disabled until the server is restarted.

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

Stop an AllegroGraph server and optionally any client connections. If the wait argument is non-nil, wait for the server to be fully shut down. A numeric value is a timeout interval in seconds.

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

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 seconds for an open triple store. If a triple store stays open but idle for this interval, it is closed automatically. The default is 24 hours.

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

• The output-stream argument is a synonym for worker-stream retained for compatibility with previous versions of AllegroGraph. If the worker-stream argument is specified, the output-stream argument is ignored.

• If the worker-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, 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.

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

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.

Method (sesame-server)

Return the port number where this server is listening.

Method (null)

Return the port number where the default Sesame HTTP server is listening.

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

name can be:

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

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

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

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

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

Associate the neighbor-matrix matrix with name.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

 A --> B <-- C 

and that these are encoded in AllegroGraph as

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

If we define three generators:

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

then we will find that

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

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

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

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

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

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

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

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

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

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

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

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