# Gremlin query hints
You can use query hints to specify optimization and evaluation strategies for a particular Gremlin query in Amazon Neptune.
Query hints are specified by adding a `withSideEffect` step to the query with the following syntax.
```
g.withSideEffect(hint, value)
```
+ *hint* – Identifies the type of the hint to apply.
+ *value* – Determines the behavior of the system aspect under consideration.
For example, the following shows how to include a `repeatMode` hint in a Gremlin traversal.
**Note**
All Gremlin query hints side effects are prefixed with `Neptune#`.
```
g.withSideEffect('Neptune#repeatMode', 'DFS').V("3").repeat(out()).times(10).limit(1).path()
```
The preceding query instructs the Neptune engine to traverse the graph *Depth First* (`DFS`) rather than the default Neptune, *Breadth First* (`BFS`).
The following sections provide more information about the available query hints and their usage.
**Topics**
+ [Gremlin repeatMode query hint](gremlin-query-hints-repeatMode.md)
+ [Gremlin noReordering query hint](gremlin-query-hints-noReordering.md)
+ [Gremlin typePromotion query hint](gremlin-query-hints-typePromotion.md)
+ [Gremlin useDFE query hint](gremlin-query-hints-useDFE.md)
+ [Gremlin query hints for using the results cache](gremlin-query-hints-results-cache.md)
# Gremlin repeatMode query hint
The Neptune `repeatMode` query hint specifies how the Neptune engine evaluates the `repeat()` step in a Gremlin traversal: breadth first, depth first, or chunked depth first.
The evaluation mode of the `repeat()` step is important when it is used to find or follow a path, rather than simply repeating a step a limited number of times.
## Syntax
The `repeatMode` query hint is specified by adding a `withSideEffect` step to the query.
```
g.withSideEffect('Neptune#repeatMode', 'mode').gremlin-traversal
```
**Note**
All Gremlin query hints side effects are prefixed with `Neptune#`.
**Available Modes**
+ `BFS`
Breadth-First Search
Default execution mode for the `repeat()` step. This gets all sibling nodes before going deeper along the path.
This version is memory-intensive and frontiers can get very large. There is a higher risk that the query will run out of memory and be cancelled by the Neptune engine. This most closely matches other Gremlin implementations.
+ `DFS`
Depth-First Search
Follows each path to the maximum depth before moving on to the next solution.
This uses less memory. It may provide better performance in situations like finding a single path from a starting point out multiple hops.
+ `CHUNKED_DFS`
Chunked Depth-First Search
A hybrid approach that explores the graph depth-first in chunks of 1,000 nodes, rather than 1 node (`DFS`) or all nodes (`BFS)`.
The Neptune engine will get up to 1,000 nodes at each level before following the path deeper.
This is a balanced approach between speed and memory usage.
It is also useful if you want to use `BFS`, but the query is using too much memory.
## Example
The following section describes the effect of the repeat mode on a Gremlin traversal.
In Neptune the default mode for the `repeat()` step is to perform a breadth-first (`BFS`) execution strategy for all traversals.
In most cases, the TinkerGraph implementation uses the same execution strategy, but in some cases it alters the execution of a traversal.
For example, the TinkerGraph implementation modifies the following query.
```
g.V("3").repeat(out()).times(10).limit(1).path()
```
The `repeat()` step in this traversal is "unrolled" into the following traversal, which results in a depth-first (`DFS`) strategy.
```
g.V().out().out().out().out().out().out().out().out().out().out().limit(1).path()
```
**Important**
The Neptune query engine does not do this automatically.
Breadth-first (`BFS`) is the default execution strategy, and is similar to TinkerGraph in most cases. However, there are certain cases where depth-first (`DFS`) strategies are preferable.
**BFS (Default)**
Breadth-first (BFS) is the default execution strategy for the `repeat()` operator.
```
g.V("3").repeat(out()).times(10).limit(1).path()
```
The Neptune engine fully explores the first nine-hop frontiers before finding a solution ten hops out. This is effective in many cases, such as a shortest-path query.
However, for the preceding example, the traversal would be much faster using the depth-first (`DFS`) mode for the `repeat()` operator.
**DFS**
The following query uses the depth-first (`DFS`) mode for the `repeat()` operator.
```
g.withSideEffect("Neptune#repeatMode", "DFS").V("3").repeat(out()).times(10).limit(1)
```
This follows each individual solution out to the maximum depth before exploring the next solution.
# Gremlin noReordering query hint
When you submit a Gremlin traversal, the Neptune query engine investigates the structure of the traversal and reorders parts of the query, trying to minimize the amount of work required for evaluation and query response time. For example, a traversal with multiple constraints, such as multiple `has()` steps, is typically not evaluated in the given order. Instead it is reordered after the query is checked with static analysis.
The Neptune query engine tries to identify which constraint is more selective and runs that one first. This often results in better performance, but the order in which Neptune chooses to evaluate the query might not always be optimal.
If you know the exact characteristics of the data and want to manually dictate the order of the query execution, you can use the Neptune `noReordering` query hint to specify that the traversal be evaluated in the order given.
## Syntax
The `noReordering` query hint is specified by adding a `withSideEffect` step to the query.
```
g.withSideEffect('Neptune#noReordering', true or false).gremlin-traversal
```
**Note**
All Gremlin query hints side effects are prefixed with `Neptune#`.
**Available Values**
+ `true`
+ `false`
# Gremlin typePromotion query hint
When you submit a Gremlin traversal that filters on a numerical value or range, the Neptune query engine must normally use type promotion when it executes the query. This means that it has to examine values of every type that could hold the value you are filtering on.
For example, if you are filtering for values equal to 55, the engine must look for integers equal to 55, long integers equal to 55L, floats equal to 55.0, and so forth. Each type promotion requires an additional lookup on storage, which can cause an apparently simple query to take an unexpectedly long time to complete.
Let's say you are searching for all vertexes with a customer-age property greater than 5:
```
g.V().has('customerAge', gt(5))
```
To execute that traversal thoroughly, Neptune must expand the query to examine every numeric type that the value you are querying for could be promoted to. In this case, the `gt` filter has to be applied for any integer over 5, any long over 5L, any float over 5.0, and any double over 5.0. Because each of these type promotions requires an additional lookup on storage, you will see multiple filters per numeric filter when you run the [Gremlin `profile` API](gremlin-profile-api.md) for this query, and it will take significantly longer to complete than you might expect.
Often type promotion is unnecessary because you know in advance that you only need to find values of one specific type. When this is the case, you can speed up your queries dramatically by using the `typePromotion` query hint to turn off type promotion.
## Syntax
The `typePromotion` query hint is specified by adding a `withSideEffect` step to the query.
```
g.withSideEffect('Neptune#typePromotion', true or false).gremlin-traversal
```
**Note**
All Gremlin query hints side effects are prefixed with `Neptune#`.
**Available Values**
+ `true`
+ `false`
To turn off type promotion for the query above, you would use:
```
g.withSideEffect('Neptune#typePromotion', false).V().has('customerAge', gt(5))
```
# Gremlin useDFE query hint
Use this query hint to enable use of the DFE for executing the query. By default Neptune does not use the DFE without this query hint being set to `true`, because the [neptune\$1dfe\$1query\$1engine](parameters.md#parameters-instance-parameters-neptune_dfe_query_engine) instance parameter defaults to `viaQueryHint`. If you set that instance parameter to `enabled`, the DFE engine is used for all queries except those having the `useDFE` query hint set to `false`.
Example of enabling the DFE for a query:
```
g.withSideEffect('Neptune#useDFE', true).V().out()
```
# Gremlin query hints for using the results cache
The following query hints can be used when the [query results cache](gremlin-results-cache.md) is enabled.
## Gremlin `enableResultCache` query hint
The `enableResultCache` query hint with a value of `true` causes query results to be returned from the cache if they have already been cached. If not, it returns new results and caches them until such time as they are cleared from the cache. For example:
```
g.with('Neptune#enableResultCache', true)
.V().has('genre','drama').in('likes')
```
Later, you can access the cached results by issuing exactly the same query again.
If the value of this query hint is `false`, or if it isn't present, query results are not cached. However, setting it to `false` does not clear existing cached results. To clear cached results, use the `invalidateResultCache` or `invalidateResultCachekey` hint.
## Gremlin `enableResultCacheWithTTL` query hint
The `enableResultCacheWithTTL` query hint also returns cached results if there are any, without affecting the TTL of results already in the cache. If there are currently no cached results, the query returns new results and caches them for the time to live (TTL) specified by the `enableResultCacheWithTTL` query hint. That time to live is specified in seconds. For example, the following query specifies a time to live of sixty seconds:
```
g.with('Neptune#enableResultCacheWithTTL', 60)
.V().has('genre','drama').in('likes')
```
Before the 60-second time-to-live is over, you can use the same query (here, `g.V().has('genre','drama').in('likes')`) with either the `enableResultCache` or the `enableResultCacheWithTTL` query hint to access the cached results.
**Note**
The time to live specified with `enableResultCacheWithTTL` does not affect results that have already been cached.
If results were previously cached using `enableResultCache`, the cache must first be explicitly cleared before `enableResultCacheWithTTL` generates new results and caches them for the TTL that it specifies.
If results were previously cached using `enableResultCachewithTTL`, that previous TTL must first expire before `enableResultCacheWithTTL` generates new results and caches them for the TTL that it specifies.
After the time to live has passed, the cached results for the query are cleared, and a subsequent instance of the same query then returns new results. If `enableResultCacheWithTTL` is attached to that subsequent query, the new results are cached with the TTL that it specifies.
## Gremlin `invalidateResultCacheKey` query hint
The `invalidateResultCacheKey` query hint can take a `true` or `false` value. A `true` value causes cached results for the the query to which `invalidateResultCacheKey` is attached to be cleared. For example, the following example causes results cached for the query key `g.V().has('genre','drama').in('likes')` to be cleared:
```
g.with('Neptune#invalidateResultCacheKey', true)
.V().has('genre','drama').in('likes')
```
The example query above does not cause its new results to be cached. You can include `enableResultCache` (or `enableResultCacheWithTTL`) in the same query if you want to cache the new results after clearing the existing cached ones:
```
g.with('Neptune#enableResultCache', true)
.with('Neptune#invalidateResultCacheKey', true)
.V().has('genre','drama').in('likes')
```
## Gremlin `invalidateResultCache` query hint
The `invalidateResultCache` query hint can take a `true` or `false` value. A `true` value causes all results in the results cache to be cleared. For example:
```
g.with('Neptune#invalidateResultCache', true)
.V().has('genre','drama').in('likes')
```
The example query above does not cause its results to be cached. You can include `enableResultCache` (or `enableResultCacheWithTTL`) in the same query if you want to cache new results after completely clearing the existing cache:
```
g.with('Neptune#enableResultCache', true)
.with('Neptune#invalidateResultCache', true)
.V().has('genre','drama').in('likes')
```
## Gremlin `numResultsCached` query hint
The `numResultsCached` query hint can only be used with queries that contain `iterate()`, and it specifies the maximum number of results to cache for the query to which it is attached. Note that the results cached when `numResultsCached` is present are not returned, only cached.
For example, the following query specifies that up to 100 of its results should be cached, but none of those cached results returned:
```
g.with('Neptune#enableResultCache', true)
.with('Neptune#numResultsCached', 100)
.V().has('genre','drama').in('likes').iterate()
```
You can then use a query like the following to retrieve a range of the cached results (here, the first ten):
```
g.with('Neptune#enableResultCache', true)
.with('Neptune#numResultsCached', 100)
.V().has('genre','drama').in('likes').range(0, 10)
```
## Gremlin `noCacheExceptions` query hint
The `noCacheExceptions` query hint can take a `true` or `false` value. A `true` value causes any exceptions related to the results cache to be suppressed. For example:
```
g.with('Neptune#enableResultCache', true)
.with('Neptune#noCacheExceptions', true)
.V().has('genre','drama').in('likes')
```
In particular, this suppresses the `QueryLimitExceededException`, which is raised if the results of a query are too large to fit in the results cache.