Skip to content

Java query hints #1942

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 2 commits into
base: main
Choose a base branch
from
Open

Java query hints #1942

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
968753c
Update Java Query Hints
MattSchur Jun 30, 2025
dfa4a76
Update link
MattSchur Jun 30, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion java/cqn-services/persistence-services.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -147,7 +147,7 @@ By default, the SAP HANA adapter in CAP Java generates SQL that is optimized for
cds.sql.hana.optimizationMode: legacy
```

Use the [hints](../working-with-cql/query-execution#hana-hints) `hdb.USE_HEX_PLAN` and `hdb.NO_USE_HEX_PLAN` to overrule the configured optimization mode per statement.
Use the [hints](../working-with-cql/query-execution#query-hints) `hdb.USE_HEX_PLAN` and `hdb.NO_USE_HEX_PLAN` to overrule the configured optimization mode per statement.

::: warning Rare error in `HEX` mode
In some corner cases, particularly when using [native HANA views](../../advanced/hana#create-native-sap-hana-objects), queries in `HEX` optimization mode may fail with a "hex enforced but cannot be selected" error. This is the case if the statement execution requires the combination of HEX only features with other features that are not yet supported by the HEX engine. If CAP detects this error it will, as a fallback, execute the query in _legacy_ mode.
Expand Down
10 changes: 5 additions & 5 deletions java/working-with-cql/query-execution.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -117,15 +117,15 @@ var params = Map.of("minStock", 100);
Result result = service.run(query, params);
```

#### Adding Query Hints for SAP HANA { #hana-hints}
### Query Hints { #query-hints}

To add a hint clause to a statement, use the `hints` method and prefix the [SAP HANA hints](https://help.sap.com/docs/HANA_CLOUD_DATABASE/c1d3f60099654ecfb3fe36ac93c121bb/4ba9edce1f2347a0b9fcda99879c17a1.htmlS) with `hdb.`:
Use the `hints` method to add specific hints to a CDS QL statement. [SAP HANA hints](https://help.sap.com/docs/HANA_CLOUD_DATABASE/c1d3f60099654ecfb3fe36ac93c121bb/4ba9edce1f2347a0b9fcda99879c17a1.htmlS) need to be prefix with `hdb.`
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Use the `hints` method to add specific hints to a CDS QL statement. [SAP HANA hints](https://help.sap.com/docs/HANA_CLOUD_DATABASE/c1d3f60099654ecfb3fe36ac93c121bb/4ba9edce1f2347a0b9fcda99879c17a1.htmlS) need to be prefix with `hdb.`
Use the `hints` method to add specific hints to a CDS QL statement that override the default behavior of the CAP Java runtime or influence the query execution on the database. Supported runtime hints are documented together with the runtime behavior.
[SAP HANA hints](https://help.sap.com/docs/HANA_CLOUD_DATABASE/c1d3f60099654ecfb3fe36ac93c121bb/4ba9edce1f2347a0b9fcda99879c17a1.htmlS) need to be prefix with `hdb.`

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

prefix with hdb.

maybe we should support hana. as a synonym

Supported runtime hints are documented together with the runtime behavior.

maybe we should summarize the supported runtime hints in a table


```java
CqnSelect query = Select.from(BOOKS).hints("hdb.USE_HEX_PLAN", "hdb.ESTIMATION_SAMPLES(0)");
Select.from(BOOKS).hints("hdb.USE_HEX_PLAN", "hdb.HEX_INDEX_JOIN");
```
::: warning
Hints prefixed with `hdb.` are directly rendered into SQL for SAP HANA and therefore **must not** contain external input!
::: danger
Hints prefixed with `hdb.` are directly rendered into SQL for SAP HANA and **must not** contain untrusted input!
:::

### Data Manipulation
Expand Down