Add optimizer hint query api

[othercorey]

refs #18140

Example mysql index hint:
https://dev.mysql.com/doc/refman/8.4/en/index-hints.html

$query->index('USE', ['my_index1', 'my_index2']);
$query->index('IGNORE', 'my_index3');

select * from table USE INDEX (my_index1, my_index2) IGNORE INDEX (my_index3)

Example mysql optimizer hint (added in 8.4 with plans to warning to deprecate index hint but not done so):
https://dev.mysql.com/doc/refman/8.4/en/optimizer-hints.html

$query->hint('INDEX', 'my_index');

select /*+ INDEX(my_index) */ from table

The postgresql extension has syntax compatible with mysql hint syntax so the api should work for both:
https://github.com/ossc-db/pg_hint_plan/blob/master/docs/hint_details.md

[ADmad]

For the index() method how would one specify the FOR part?

[othercorey]

If we don't mind supporting only mysql 8.4+, we don't need the legacy index hint api and can just use the optimizer hint.

[ADmad]

Optimizer hints can be used for various query types, not just SELECT statements. So are we limiting them to just SelectQuery as we don't foresee usage for other queries?

[othercorey]

Optimizer hints can be used for various query types, not just SELECT statements. So are we limiting them to just SelectQuery as we don't foresee usage for other queries?

No, we can make optimizer hints generic. I used SelectQuery for the RFC because the original index hints were limited. I'm not really sure the syntax for index hints in update statements but I assume it's right after the table name.

[ADmad]

I'm not really sure the syntax for index hints in update statements but I assume it's right after the table name.

From the mysql docs:

The parser recognizes optimizer hint comments after the initial keyword of SELECT, UPDATE, INSERT, REPLACE, and DELETE statements.

[othercorey]

For the optimizer hint, but not for the legacy index hint.

[ADmad]

For the optimizer hint, but not for the legacy index hint.

Right, I was only asking about the hint() method for optimizer hints. Given that legacy index hints are being phased out having them only for SelectQuery (if at all) should be okay I guess.

[ADmad]

Seems SQL Server also has query hints which are specified using the OPTION clause at the end of the query

https://learn.microsoft.com/en-us/sql/t-sql/queries/select-transact-sql?view=sql-server-ver16
https://learn.microsoft.com/en-us/sql/t-sql/queries/hints-transact-sql-query?view=sql-server-ver16#syntax

[ADmad]

Oracle uses the special comment format similar to MySQL and pg_hint_plan.

https://docs.oracle.com/cd/B10500_01/server.920/a96533/hintsref.htm

[othercorey]

Seems SQL Server also has query hints which are specified using the OPTION clause at the end of the query

https://learn.microsoft.com/en-us/sql/t-sql/queries/select-transact-sql?view=sql-server-ver16 https://learn.microsoft.com/en-us/sql/t-sql/queries/hints-transact-sql-query?view=sql-server-ver16#syntax

This syntax varies. I think it simplest way to support it would be to put the entire value into $name.

[othercorey]

For the optimizer hint, but not for the legacy index hint.

Right, I was only asking about the hint() method for optimizer hints. Given that legacy index hints are being phased out having them only for SelectQuery (if at all) should be okay I guess.

Do we think it's worth supporting both? I don't mind, but it could get confusing since index hint is mysql only. Probably not that confusing though.

[ADmad]

I think it simplest way to support it would be to put the entire value into $name.

I am wondering if instead of having $name and $params we should just have a $hint argument, using which you can specify the full hint string as needed. That would simply the implementation for all dbs. This feature is not going to be commonly used.

Do we think it's worth supporting both? I don't mind, but it could get confusing since index hint is mysql only. Probably not that confusing though.

I am wondering the same, since index hints are mysql only and planned to be phased out. It's been over a year since mysql 8.4 is out and wouldn't it be safe to assume that those who need this feature would be able to install the required mysql version?

[ADmad]

Are these constants necessary? We have templates for other clauses (though I see we can't just add a string for this to $_templates due to the way it's used).

[othercorey]

Looks like Oracle uses the same prefix so I'm going to hard-code it for now instead.

[othercorey]

Renamed query api and clause to optimizerHint.

[Copilot]

Pull Request Overview

Adds support for passing engine-specific optimizer hints via a new optimizerHint() API, and integrates hint comments into compiled SQL when the driver supports them.

• Introduces optimizerHint clause in all query types (Select, Insert, Update, Delete)
• Extends QueryCompiler to render hint comments based on a new OPTIMIZER_HINT_COMMENT feature flag
• Adds comprehensive tests for hint behavior and adjusts driver support maps

Reviewed Changes

Copilot reviewed 13 out of 13 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
tests/TestCase/Database/QueryTest.php	Added testOptimizerHintClause() for the new clause
tests/TestCase/Database/QueryCompilerTest.php	Tests for SQL compilation of optimizer hints
src/Database/QueryCompiler.php	Hooked _buildOptimizerHintPart() into SQL builders
src/Database/Query/SelectQuery.php	Added optimizerHint to select query parts
src/Database/Query/InsertQuery.php	Added optimizerHint to insert query parts
src/Database/Query/UpdateQuery.php	Added optimizerHint to update query parts
src/Database/Query/DeleteQuery.php	Added optimizerHint to delete query parts
src/Database/Query.php	Added optimizerHint() API to base Query class
src/Database/DriverFeatureEnum.php	New OPTIMIZER_HINT_COMMENT feature enum
src/Database/Driver/Sqlserver.php	Marked hints unsupported
src/Database/Driver/Sqlite.php	Marked hints unsupported
src/Database/Driver/Postgres.php	Marked hints supported
src/Database/Driver/Mysql.php	Marked hints supported

Comments suppressed due to low confidence (2)

tests/TestCase/Database/QueryCompilerTest.php:225

• [nitpick] The method name has typos and is inconsistent: rename to testUpdateWithOptimizerHint to match other test naming conventions.

public function testUpdateWitOptimizerhHint(): void

tests/TestCase/Database/QueryCompilerTest.php:209

• [nitpick] The test name omits 'Hint'—consider renaming to testUpdateWithOptimizerHint for consistency with the other hint tests.

public function testUpdateWithOptimizer(): void

[Copilot]

Typo in docblock: change 'optmizer' to 'optimizer'.

Suggested change

	* @param list<string> $parts The optmizer hints
	* @param list<string> $parts The optimizer hints