Query Hints

This page contains all query hints available in Stardog

<details open markdown="block"> <summary> Page Contents </summary> 1. TOC </details>

General Query Optimization Hints

These hints are suggestions to Stardog’s query optimizer. They can impact the query plan selected by the optimizer but they should not change query results.

Hint Name	Possible Values	Position	Description
`equality.identity`	comma, separated list of variables (e.g. `?o,?o2`)	scope	Enumerates variables for which equality (i.e. ==) should be treated as identity (i.e. `sameTerm` in SPARQL). See Managing Query Performance - equality.identity for more information.
`group.joins`	-	scope	Enables grouping of graph patterns for join order optimization: all patterns in the group will be joined together before joining with other patterns. See Managing Query Performance - group.joins for more information.
`push.filters`	`default`, `aggressive`, or `off`	scope	Specifies how the optimizer tries to push filters down the query plan: <br><br> - aggressive: every filter will be pushed as deep down as possible <br><br> - default: the optimizer will decide how deep to push based on other factors, e.g. estimated cardinality <br><br> - off: the optimization is off. <br><br> See Managing Query Performance - push.filters for more information.
`cardinality`	integer (+ two keywords `low` and `high`).	scope	Suggests the cardinality of the following graph pattern. See Managing Query Performance - cardinality for more information.
`evaluate`	`on`,`off`	scope	Suggests to evaluate the scope at query optimization time. <br><br>See Managing Query Performance - Scope Evaluation Hints for more information.
`evaluate.limit`	integer	scope	Limits the number of results that a pattern evaluated at optimization time is allowed to produce.
`evaluate.limit`	integer	scope	Limits the number of results that a pattern evaluated at optimization time is allowed to produce. <br><br>See Managing Query Performance - Scope Evaluation Hints for more information.
`query.decomposition`	`default`, `aggressive`, or `off`	scope	Specifies query decomposition strategy: <br><br> - aggressive: always decompose joins on the subject variable <br><br> - default: let the optimizer decide based on other factors, e.g. available indexes <br><br> - off: don't decompose group graph patterns.
`query.join.decomposition`	`default`, `aggressive`, or `off`	scope	Enables the optimizer to decompose query patterns in order to prevent non-selective joins before main optimization phase: <br><br> - aggressive: always prefer to prevent non-selective joins <br><br> - default: let the optimizer decide based on join selectivity <br><br> - off: don't decompose group graph patterns along non-selective joins.

Query Runtime Hints

Differently from the optimization hints, these hints may affect the execution of the query beyond the optimization phase. Generally they don’t change results but can have a performance impact.

Hint Name	Possible Values	Position	Description
`executor`	`auto`,`legacy`	preamble	Choses the execution engine used.<br><br> - If `legacy`, the 10.1 query execution engine will be used.
`plan.cache`	`on`,`off`	preamble	Toggles plan cache for this query.<br><br> - If `off`, the query will be optimized without any plan cache lookup
`service.batch`	integer	scope	Specifies how many SPARQL `SERVICE` results will be parsed from the response before processing.
`values.id.lazy`	`on`,`off`	preamble	If `on`, the query engine will try to postpone dictionary encoding for nodes generated during query evaluation until necessary, for example, till a join condition requires it for evaluation.
`edge.properties.lookup`	`direct`,`inverse`	scope	Specifies how edge property patterns like `<<?s :p ?o>> :q ?t` should be evaluated:<br><br>- direct: first by `:p` (embedded predicate), then by `:q` (outside predicate)<br><br>- inverse: first by `:q` (outside predicate), then by `:p` (embedded predicate)
`paths.evaluation`	`lazy` or `eager`	preamble	Specifies how paths should be traversed:<br><br>- lazy: search is stopped after each new path is found so it can be returned (not available for `PATHS ALL` queries)<br><br>- eager: all reachable nodes are reached first

Join Control Hints

These hints are the means to avoid particular join algorithms for a (part of) the query. Their syntactic form is #pragma join.{type} off where {type} specifies the join algorithm, i.e. one of:

hash
directHash
sortMerge
bind
blockBind
service
multiWayService

These hints should be used conservatively and only when it is clear that some particular type of join is the main performance problem in the query. We generally advise to first try group.joins and cardinality hints to help with the optimization process.

Reasoning Hints

These hints control the query rewriting process when reasoning is enabled. Most of them do not change the results, with the notable exception of reasoning.

Hint Name	Possible Values	Position	Description
`reasoning`	`on`, `off`	scope	Specifies whether query rewriting is `on` or `off` for this group graph pattern. Also a result altering hint. See Managing Query Performance - Reasoning for more information.
`reasoning.rewriting`	`per_scope`, `per_pattern`	scope	Specifies how query rewriting should be done: <br><br> - per_scope: all triple patterns as a group (default) <br><br> - per_pattern: each triple pattern individually (results in smaller rewritings in some cases)
`push.reasoning`	`default`, `aggressive`, or `off`	scope	Specifies how the optimizer should try to patterns under reasoning operators like `?s rdf:type ?type` <br><br> - aggressive: always push the one which looks the most selective <br><br> - default: the optimizer will decide based on any available criteria <br><br> - off: the optimization is off

Virtual Graph Hints

These hints control the query rewriting and planning process when querying data in Virtual Graphs.

Hint Name	Possible Values	Position	Description
`cached.dataset.name`	name of dataset, `none`	preamble	Specifies name of the cached dataset to use.
`virtual.transparency`	`on`, `off`	scope	Enables or disables the Virtual Transparency feature. Also a result altering hint.
`vg.union.strategy`	`coalesced`, `embedded`	scope	How to translate to SQL when the fields for the returned solution can come from multiple mappings: <br><br> - coalesced: returns the fields from each mapping in its own field and null for all other fields. <br><br> - embedded: creates two fields for each result, one for the field’s type and one for the field’s value.
`service.prefetch.limit`	integer	preamble	The number of solutions which are prefetched from a Virtual Graph during query planning. Note: This query hint only has an effect if the <a href="../../operating-stardog/database-administration/database-configuration#service"><code>service.prefetch.threshold</code></a> value for the database is a positive integer.
`virtual.distribute.joins`	`default`, `always`, `off`	scope	Determines how joins are distributed over unions of Virtual Graphs. Either whenever possible (always), never (off), or based on the cost of distributing the join (default).

Result Altering Hints

These hints change the semantics of the query and thus the results.

Hint Name	Possible Values	Position	Description
`describe.strategy`	`default`, `bidirectional`, `cbd`, `<custom-strategy>`	preamble	Specifies the strategy to evaluate `DESCRIBE` queries (either built-in or custom). See DESCRIBE Queries for more information.
`reasoning`	`on`, `off`	scope	Specifies whether query rewriting is `on` or `off` for this group graph pattern.
`virtual.transparency`	`on`,`off`	scope	Enables or disables the Virtual Transparency feature

Full-text Search Hints

These hints may affect the query rewriting process when full-text search service is in use. The hints target query performance improvement and query results do not change. The purpose of the hints here is to give priority to more selective patterns, when full-text search query is non-selective. See Performance Hints for full-text search for more information.

Hint Name	Possible Values	Position	Description
`search.push.threshold`	Integer	scope	Cardinality estimation threshold to detect a non-selective full-text search pattern so that more selective parts of the query can be evaluated first.
`search.cardinality.threshold`	Integer	scope	Threshold of maximum cardinality of patterns that can be selected by the optimizer to evaluate before a full-text search pattern.
`search.max.subset.size`	Integer	scope	Maximum number of patterns that can be selected by the optimizer to evaluate before a full-text search pattern.

Federation Hints

These hints control the query planning process when querying federations of SPARQL-based Services. These services include Virtual Graphs, cached Virtual Graphs, other databases, and SPARQL endpoints.

Hint Name	Possible Values	Position	Description
`optimizer.join.order.topk`	Integer	scope	The number of alternative query plans generated during robust query planning. A value of `1` disables robust query planning on a per-scope basis. Higher values may entail longer pre-execution times.