SPARQL API reference

If true, then warnings found during query parsing, planning and execution will cause a query to fail immediately rather than continuing.

Warnings include things like unknown variables in a ORDER BY clause or FILTER expression, constants in the query that cannot be in the store and so on.The possible values are:

• yes - turn the option on
• no - turn the option off

Example of specifying the query option value via a PREFIX:

PREFIX franzOption_cancelQueryOnWarnings: <franz:no> 

The default value is: no

Controls whether to use Chunk at a Time (CaaT) processing.

It can be:

• possibly - use CaaT for unordered queries with small limits and use the single-set approach otherwise. Note that this works best when solutions are found in the first several chunks processed which means that the query can finish quickly. If a large portion of the search space must be scanned, then the single-set approach can be faster.

• yes - always use CaaT when possible (some query clauses like EXISTS filters and SPIN magic properties do not yet support CaaT).

• no - always use the single set approach and never use CaaT.

The default value is possibly which means that AllegroGraph is optimizing for speed rather than space. The no option is focused on speed at the possible cost of higher memory use whereas the yes option is more constrained in memory use at the cost of slower queries.

Example of specifying the query option value via a PREFIX:

PREFIX franzOption_chunkProcessingAllowed: <franz:possibly> 

Specifies the maximum amount of memory used by a single chunk.

Controls the size (in bytes) of the chunks used by the CaaT executor. This option takes precedence over the deprecated chunkProcessingSize option.

The minimium allowed value is 200M.

See the chunkProcessingAllowed option for additional query control.

Example of specifying the query option value via a PREFIX:

PREFIX franzOption_chunkProcessingMemory: <franz:4294967296> 

The default value is: 4,294,967,296

(Deprecated) Specifies the chunk processing size in rows

Deprecated in favor of the chunkProcessingMemory option.

Control the size (in rows of answers) of the chunks used by the CaaT executor. The higher the number, the larger the chunks processed will be which is both more efficient and more memory intensive. A typical value is 400000 or 1000000.

See the chunkProcessingAllowed option for additional control.

Example of specifying the query option value via a PREFIX:

PREFIX franzOption_chunkProcessingSize: <franz:400000> 

The default value is: 400,000

The strategy used to reorder triple patterns in a query.

This option controls how the triple patterns in a single Basic Graph Pattern (BGP) are reordered.

The available strategies will depend on the query engine being used but will always include identity which tells the query planner to not reorder the triple patterns of the BGPs. Another common choice is statistical which uses the statistics of the triple-store to try to reorder clauses most efficiently.

Note that other query planning algebraic manipulations may cause BGPs in your query to be merged and that reordering does not extend to larger query structures (like UNION or OPTIONAL).

Example of specifying the query option value via a PREFIX:

PREFIX franzOption_clauseReorderer: <franz:statistical> 

The clause reorderer defaults to statistical

Specify the default attributes to assign to any triple created by a SPARQL update command.

The attributes must be specified in URL encoded JSON format. So the example below is using the URL encoded form of which is the URL encoded form of {"rank": "High" }.

Example of specifying the query option value via a PREFIX:

PREFIX franzOption_defaultAttributes: <franz:%7B%22rank%22%3A%20%22High%22%20%7D> 

No attributes

In a SPARQL query the FROM clause specifies the default graph of the dataset, and the FROM NAMED clause specifies the named graphs of the dataset (see Specifying RDF Datasets in the SPARQL 1.1 standard).

If a SPARQL query does not specifiy FROM or FROM NAMED then it is up to the implementation to choose a behaviour. AllegroGraph offers three possibilities. The table below indicates which triples are present in which part of the dataset for each possible behaviour:

                                        +--------------------------+  
             default dataset behaviour: |   all  |   rdf  | default|  
                                        + - - - -| - - - -| - - - -|  
dataset's default graph / named graphs: | DG  NG | DG  NG | DG  NG |  
                                        |        |        |        |  
       triple (s,p,o) in default graph: |  x     |  x     |  x     |  
       triple (s,p,o,g) in named graph: |  x  x  |     x  |        |   "x" means present  
                                        +--------+--------+--------+ 

The possible values are:

• all - All triples are present in the dataset's default graph. Triples in a named graph are present in the dataset in that named graph. Triples in a named graph thus occur twice in the dataset: once in the default graph, and once in the named graph.
• rdf - Triples in the default graph are present in the dataset's default graph. Triples in a named graph are present in the dataset in that named graph.
• default - Triples in the default graph are present in the dataset's default graph. The dataset has no named graphs.

Example of specifying the query option value via a PREFIX:

PREFIX franzOption_defaultDatasetBehavior: <franz:all> 

The default value is: all

Specifies the number of solutions to keep in memory before writing temporary files.

This should be a number like 500000 or 100m. The larger the value, the more memory AllegroGraph will use during query processing. Smaller values can be more memory efficient but also can perform more slowly because the will be more I/O activity.

Note that this setting controls the memory used to hold completed solutions not the memory used to hold intermediate solutions. See the chunkProcessingMemory option for more details.

Example of specifying the query option value via a PREFIX:

PREFIX franzOption_diskChunkRowCount: <franz:500000> 

The default value is: 500,000

The query engine to use.The possible values are:

• mjqe - New merge-join based query engine for supported queries ~ (e.g. select); fallback to :sbqe for other queries.
• sbqe - Old set-based query engine (with or without Chunk-at-a-Time) ~ for all queries

Example of specifying the query option value via a PREFIX:

PREFIX franzOption_engine: <franz:sbqe> 

The default value is: sbqe

Controls the length of query log lines.

The logLineLength query option limits the maximum length of each line of the query log. This can make the log easier to read at the cost of removing some information. Use zero print the entirety of every log message.

See the logQuery option for more details.

Example of specifying the query option value via a PREFIX:

PREFIX franzOption_logLineLength: <franz:512> 

The default value is: 512

Controls whether or not query execution details are logged.

logQuery can be 'no', 'yes', or 'onFailure'.

The length of the log lines can be limited by using the logLineLength query log option.

If logging is on, the query engine prints additional information to the AllegroGraph log file as it plans and executes a query. If logging is onFailure, then query log information is gathered but not emitted unless there is a query failure.

Logging on failure has a small cost especially when the amount of data logged is high (e.g., when chunkProcessingAllowed is turned on). We recommend setting the value to onFailure during development and then turning it to no for production.

Example of specifying the query option value via a PREFIX:

PREFIX franzOption_logQuery: <franz:no> 

The default value is: no

Specifies an upper limit on the number of solutions that are allowed during query processing before a warning is logged.

Queries run best when the solution space is kept small. This warning is in an indication that a query is generating many intermediate results. This is a normal part of query processing but can indicate that a query should be optimized

Example of specifying the query option value via a PREFIX:

PREFIX franzOption_maximumSolutionsSize: <franz:100k> 

The default is to warn when the intermediate solution space is larger than 100,000,000 solutions

This option limits the number of VALUES that AllegroGraph will send to a SPARQL endpoint when executing a SERVICE clause. Sending partial results to the endpoint can help it answer the query more quickly but if the number of partial results is very large, the cost of data transfer can offset the help of supplying the data.

If the number of VALUES exceeds the limit, the the query will be sent to the endpoint with no VALUES supplied.

Example of specifying the query option value via a PREFIX:

PREFIX franzOption_maximumValuesCountForService: <franz:1048576> 

no limit

Specify how much system memory must be free for a query to continue.

If the query process is using more than this setting's percentage of total physical memory, then the query will be canceled. The default value is 90%.

Example of specifying the query option value via a PREFIX:

PREFIX franzOption_memoryExhaustionWarningPercentage: <franz:90.0> 

The default value is: 90.0

Specifies the memory limit per query.

If a query tries to use more than this, it will be canceled.

Example of specifying the query option value via a PREFIX:

PREFIX franzOption_memoryLimit: <franz:8G> 

The default value will be 85% of the physical memory on the server

The timezone in which xsd:dateTimes and xsd:times are serialized.

For example, if presentationTimeZone is "-02:00", then "2013-10-01T15:21:23+03:00" is serialized as "2013-10-01T10:21:23-02:00". Zoneless xsd:datetimes and xsd:times are always presented without a timezone. This option has no effect on what is stored in the database. The allowed values are strings representing the timezone. The format of these strings is the same as in xsd:dateTimes. The special value "none" means that no conversion will take place.

Example of specifying the query option value via a PREFIX:

PREFIX franzOption_presentationTimeZone: <franz:-5:00> 

The default is set to none.

Specifies a query timeout value in seconds.

Note that the timeout is not an interrupt; AllegroGraph checks for query timeout relatively infrequently so that a query can run for many seconds longer than the specified timeout. This is especially true for operations involving reasoning or non-triple-pattern based queries like free-text indexing or SNA path planning operators.

Setting the timeout to zero is the same as having no timeout.

Example of specifying the query option value via a PREFIX:

PREFIX franzOption_queryTimeout: <franz:30> 

The default is to have no query timeout. I.e., queries will run until complete.

The number of seconds to wait before a remote query times out.

This will also have an effect on SPARQL Federated query (i.e., using the SERVICE clause).

Example of specifying the query option value via a PREFIX:

PREFIX franzOption_serviceTimeout: <franz:120> 

The default value is: 120

Specifies query duration threshold in milliseconds that triggers slow query logging.

If a query's runtime exceeds the threshold, it will be logged either to the file specified by the slowQueryLogFile configuration setting or to agraph.log.

Example of specifying the query option value via a PREFIX:

PREFIX franzOption_slowQueryLogThreshold: <franz:1000> 

The default is to not log slow queries.

Specifies the maximum number of results to return from a given SOLR query.

Example of specifying the query option value via a PREFIX:

PREFIX franzOption_solrQueryLimit: <franz:100> 

The default value is: 100

Specifies the maximum amount of temporary file space that may be used by a query.

If a query tries to use more file space than this, it will be canceled.

Queries write intermediate results to the filesystem when they will not fit in memory. With a huge query it is possible for such temporary files to fill the filesystem. In order to prevent this, the temporaryFilesystemSpaceLimit query option may be set.

The minimum allowable value for this setting is 2-gigabytes.

Example of specifying the query option value via a PREFIX:

PREFIX franzOption_temporaryFilesystemSpaceLimit: <franz:672061440> 

The default value is to use the minimum of 8-gigabytes and one quarter of the available filesystem space at the time the query begins.

If yes, then range queries will not scan typed literal triples.

This means that only encoded triples will be considered. The only reason to set this option to no is if your triple-store contains typed literals that are not encoded (i.e., that are in the string-table) which could happen if you disabled AllegroGraph's datatype mapping.The possible values are:

• yes - turn the option on
• no - turn the option off

Example of specifying the query option value via a PREFIX:

PREFIX franzOption_trustEncodedDatatypesForRangeQueries: <franz:yes> 

The default value is: yes

If yes, then predicate type mappings will be used for range queries.

This means that any triples whose encoded data-type does not match their predicate mapping will be ignored. This could happen only if a predicate mapping was added or changed after triples had been added.The possible values are:

• yes - turn the option on
• no - turn the option off

Example of specifying the query option value via a PREFIX:

PREFIX franzOption_trustPredicateTypeMappingsForRangeQueries: <franz:yes> 

The default value is: yes

Use subject and object UPI type-codes to improve constraint inference

If yes, then the query engine will gather information about the subjects and objects associated with particular predicates. This can be used in constraint analysis and query transformations. As an example, suppose we have a query like:

?one ex:date ?date1 .  
?two ex:date ?date2 .  
filter( ?date1 > ?date2 ) 

If there is no predicate type-mapping, then the query engine can not make any assumptions about the range comparison. If there is a predicate type-mapping and trustPredicateTypeMappingsForRangeQueries is true, then the engine can know that the filter can be treated as a date comparison. If usePredicateConstrainedUpiTypeInformation is yes, then the query engine will check the triple-store to determine which UPI type-codes the subjects and objects associated with ex:date can take on. If the objects of ex:date only have, e.g., UPI type-code +rdf-date+, then the filter will be handled more efficiently.

The type-code information is cached but if the store is changing rapidly, then the cache will often be invalid and this computation will slightly add to the cost of queries.The possible values are:

• yes - turn the option on
• no - turn the option off

Example of specifying the query option value via a PREFIX:

PREFIX franzOption_usePredicateConstrainedUpiTypeInformation: <franz:yes> 

The default value is: yes

Use typed-literal XSD types to improve constraint inference.

Similar to usePredicateConstrainedUpiTypeInformation but involves a scan of all typed-literals (which can be expensive). This is currently not cached!The possible values are:

• yes - turn the option on
• no - turn the option off

Example of specifying the query option value via a PREFIX:

PREFIX franzOption_usePredicateConstrainedXsdTypeInformation: <franz:no> 

The default value is: no

Specify the user attributes to use while evaluating the query.

The attributes must be specified in URL encoded JSON format. So the example below is using the URL encoded form of {"access-level": "medium", "department": "hr"}.

Example of specifying the query option value via a PREFIX:

PREFIX franzOption_userAttributes: <franz:%7B%22access-level%22%3A%20%22medium%22%2C%20%22department%22%3A%20%22hr%22%7D> 

empty