Query Hints
This page contains all query hints available in Stardog
Page Contents
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. 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. See Managing Query Performance - Scope Evaluation Hints for more information. |
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 |
|---|---|---|---|
executor | auto,legacy | preamble | Choses the execution engine used. - If legacy, the 10.1 query execution engine will be used. |
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:
hashdirectHashsortMergebindblockBindservicemultiWayService
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. |