Link Search Menu Expand Document
Start for Free

Query Hints

This page contains all query hints available in Stardog

Page Contents
  1. General Query Optimization Hints
  2. Query Runtime Hints
  3. Join Control Hints
  4. Reasoning Hints
  5. Virtual Graph Hints
  6. Result Altering Hints
  7. Full-text Search Hints
  8. Federation Hints

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:

- aggressive: every filter will be pushed as deep down as possible

- default: the optimizer will decide how deep to push based on other factors, e.g. estimated cardinality

- off: the optimization is off.

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.
evaluate.limit integer scope Limits the number of results that a pattern evaluated at optimization time is allowed to produce.
query.decomposition default, aggressive, or off scope Specifies query decomposition strategy:

- aggressive: always decompose joins on the subject variable

- default: let the optimizer decide based on other factors, e.g. available indexes

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

- aggressive: always prefer to prevent non-selective joins

- default: let the optimizer decide based on join selectivity

- 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
plan.cache on,off preamble Toggles plan cache for this query.

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

- direct: first by :p (embedded predicate), then by :q (outside predicate)

- inverse: first by :q (outside predicate), then by :p (embedded predicate)
paths.evaluation lazy or eager preamble Specifies how paths should be traversed:

- lazy: search is stopped after each new path is found so it can be returned (not available for PATHS ALL queries)

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

- per_scope: all triple patterns as a group (default)

- 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

- aggressive: always push the one which looks the most selective

- default: the optimizer will decide based on any available criteria

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

- coalesced: returns the fields from each mapping in its own field and null for all other fields.

- 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 service.prefetch.threshold 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.