WL#17265: Enable hypergraph optimizer in community builds

Affects: Server-9.x   —   Status: Complete

Today, community builds of MySQL do not include support for enabling the hypergraph optimizer, even though the server already exposes the hypergraph_optimizer flag in optimizer_switch. As a result, attempts to enable it (for example via SET optimizer_switch, SET GLOBAL, SET PERSIST, --optimizer-switch, or SET_VAR hints) either fail or are ignored, depending on the mechanism used.

This worklog changes the community build configuration so that the hypergraph optimizer is compiled in by default and made available for use in community releases, unless it is explicitly configured out at build time. The default runtime behavior remains unchanged: the hypergraph optimizer is not enabled by default in sessions.

When the feature is included in the build, users can opt in at runtime by enabling hypergraph_optimizer=on through the existing optimizer_switch mechanisms (session, global, persisted, startup option, or per-statement hinting). When the feature is not included (for example, when WITH_HYPERGRAPH_OPTIMIZER=OFF), attempts to enable it should continue to be rejected or ignored in the same way as before.

Functional Requirements (FR)

FR1 — Default build behavior (availability vs. default use)

  • When MySQL is configured with CMake without specifying WITH_HYPERGRAPH_OPTIMIZER (or specifying it as ON), the hypergraph optimizer is built and available, but is not enabled by default in sessions (i.e., remains controlled by optimizer_switch defaults).

FR2 — Session-level SET optimizer_switch succeeds when available

  • In builds where WITH_HYPERGRAPH_OPTIMIZER=ON (explicitly or by default per FR1):
    • SET optimizer_switch='hypergraph_optimizer=on'; shall succeed (no error).
    • The change shall be observable via SELECT @@optimizer_switch;.

FR3 — Server startup option --optimizer-switch enables it when available

  • In builds where WITH_HYPERGRAPH_OPTIMIZER=ON (explicitly or by default per FR1):
    • Starting mysqld with --optimizer-switch=hypergraph_optimizer=on shall succeed.
    • In a fresh client session, the state shall be observable via:
    • SELECT @@optimizer_switch;
    • SELECT @@global.optimizer_switch;
    • Both shall reflect hypergraph_optimizer=on (subject to usual optimizer_switch semantics).

FR4 — Global SET GLOBAL optimizer_switch succeeds when available

  • In builds where WITH_HYPERGRAPH_OPTIMIZER=ON (explicitly or by default per FR1):
    • SET GLOBAL optimizer_switch='hypergraph_optimizer=on'; shall succeed (no error).
    • The change shall be observable via SELECT @@global.optimizer_switch; in the same session.
    • In a newly created session after the global change, the effective session value shall be observable via SELECT @@session.optimizer_switch; and reflect hypergraph_optimizer=on (subject to usual optimizer_switch semantics).

FR5 — SET PERSIST optimizer_switch succeeds and persists when available

  • In builds where WITH_HYPERGRAPH_OPTIMIZER=ON (explicitly or by default per FR1):
    • SET PERSIST optimizer_switch='hypergraph_optimizer=on'; shall succeed (no error).
    • In the same session, SELECT @@session.optimizer_switch; shall not change solely due to SET PERSIST.
    • In the same session, SELECT @@global.optimizer_switch; shall reflect hypergraph_optimizer=on after the SET PERSIST.
    • In a newly created session after the SET PERSIST, SELECT @@session.optimizer_switch; shall reflect hypergraph_optimizer=on (subject to usual optimizer_switch semantics).
    • After a server restart, SELECT @@global.optimizer_switch; shall reflect hypergraph_optimizer=on, and a newly created session shall reflect hypergraph_optimizer=on in SELECT @@session.optimizer_switch; (subject to usual optimizer_switch semantics).

FR6 — SET_VAR hint can enable and causes hypergraph optimization when available

  • In builds where WITH_HYPERGRAPH_OPTIMIZER=ON (explicitly or by default per FR1):
    • A query using /*+ SET_VAR(optimizer_switch='hypergraph_optimizer=on') */ shall succeed (no error).
    • The hypergraph optimizer shall be used for optimizing that statement.
    • Usage shall be observable using optimizer trace (or equivalent tracing mechanism used by MySQL).

FR7 — ENABLE_HYPERGRAPH_OPTIMIZER forces inclusion

  • If ENABLE_HYPERGRAPH_OPTIMIZER=ON is specified:
    • The resulting configuration shall set WITH_HYPERGRAPH_OPTIMIZER=ON,
    • even if WITH_HYPERGRAPH_OPTIMIZER=OFF is explicitly provided in the same CMake invocation.

FR8 — Session-level SET optimizer_switch fails when not built

  • In builds where WITH_HYPERGRAPH_OPTIMIZER=OFF:
    • SET optimizer_switch='hypergraph_optimizer=on'; shall fail with error ER_HYPERGRAPH_NOT_SUPPORTED_YET (3999).
    • The error message shall indicate lack of support due to WITH_HYPERGRAPH_OPTIMIZER=OFF (e.g., “to enable it, build with CMake option WITH_HYPERGRAPH_OPTIMIZER=ON”).

FR9 — Server startup option --optimizer-switch is accepted but not applied when not built

  • In builds where WITH_HYPERGRAPH_OPTIMIZER=OFF:
    • Starting mysqld with --optimizer-switch=hypergraph_optimizer=on shall succeed (server starts).
    • In a fresh session, both:
    • SELECT @@optimizer_switch;
    • SELECT @@global.optimizer_switch; shall show hypergraph_optimizer=off.
    • Attempting SET optimizer_switch='hypergraph_optimizer=on'; after startup shall fail as specified in FR8.

FR10 — Global SET GLOBAL optimizer_switch fails when not built

  • In builds where WITH_HYPERGRAPH_OPTIMIZER=OFF:
    • SET GLOBAL optimizer_switch='hypergraph_optimizer=on'; shall fail with error ER_HYPERGRAPH_NOT_SUPPORTED_YET (3999).
    • The error message shall indicate lack of support due to WITH_HYPERGRAPH_OPTIMIZER=OFF (e.g., “to enable it, build with CMake option WITH_HYPERGRAPH_OPTIMIZER=ON”).
    • SELECT @@global.optimizer_switch; in the same session shall not show hypergraph_optimizer=on.
    • In a newly created session after the failed global attempt, SELECT @@session.optimizer_switch; shall not show hypergraph_optimizer=on.

FR11 — SET PERSIST optimizer_switch fails when not built

  • In builds where WITH_HYPERGRAPH_OPTIMIZER=OFF:
    • SET PERSIST optimizer_switch='hypergraph_optimizer=on'; shall fail with error ER_HYPERGRAPH_NOT_SUPPORTED_YET (3999).
    • The error message shall indicate lack of support due to WITH_HYPERGRAPH_OPTIMIZER=OFF (e.g., “to enable it, build with CMake option WITH_HYPERGRAPH_OPTIMIZER=ON”).
    • SELECT @@global.optimizer_switch; in the same session shall not show hypergraph_optimizer=on.
    • In a newly created session after the failed attempt, SELECT @@session.optimizer_switch; shall not show hypergraph_optimizer=on.
    • After a server restart, SELECT @@global.optimizer_switch; and a newly created session’s SELECT @@session.optimizer_switch; shall not show hypergraph_optimizer=on.

FR12 — SET_VAR hint is tolerated but does not enable it when not built

  • In builds where WITH_HYPERGRAPH_OPTIMIZER=OFF:
    • A statement using /*+ SET_VAR(optimizer_switch='hypergraph_optimizer=on') */ shall execute successfully.
    • The hypergraph optimizer shall not be used for that statement.
    • The server shall emit warning ER_HYPERGRAPH_NOT_SUPPORTED_YET (3999) for the statement, and the warning text shall indicate WITH_HYPERGRAPH_OPTIMIZER=OFF.

Non-Functional Requirements (NFR)

NFR1 — Default runtime behavior unchanged

  • When WITH_HYPERGRAPH_OPTIMIZER=ON but ENABLE_HYPERGRAPH_OPTIMIZER=OFF (default), server behavior and query planning shall remain unchanged unless a user explicitly enables hypergraph_optimizer=on via optimizer_switch.

NFR2 — No performance regressions in default configuration

  • In the default runtime configuration (hypergraph_optimizer=off), there shall be no measurable performance regressions attributable to this WL (planning latency and execution time unchanged within normal noise).

NFR3 — No new external dependencies

  • Compiling in the hypergraph optimizer by default shall not introduce new external build/runtime dependencies for community builds beyond those already required for the server.

NFR4 — Resource footprint remains acceptable

  • The incremental impact on build artifacts (binary size) and memory usage in the default runtime configuration shall remain within acceptable limits for community builds.

NFR5 — Backward compatible interfaces

  • No new SQL syntax or new system variables are introduced; existing optimizer_switch semantics and supported scopes (SET, SET GLOBAL, SET PERSIST, --optimizer-switch, SET_VAR) remain backward compatible.

NFR6 — Diagnostics quality

  • When hypergraph optimization cannot be enabled because it is compiled out (WITH_HYPERGRAPH_OPTIMIZER=OFF), the resulting error/warning shall clearly identify the build-time reason so users can self-diagnose misconfiguration.

Observability / Verification Notes

  • Switch observability:

    • Use SELECT @@optimizer_switch; to confirm the effective session value.
    • Use SELECT @@global.optimizer_switch; to confirm the global value.
    • For these requirements, it is sufficient to verify that the returned string contains hypergraph_optimizer=on or hypergraph_optimizer=off as applicable.

  • Startup option verification:

    • When verifying mysqld --optimizer-switch=..., use a fresh connection (new session) after startup.
    • The requirements intentionally distinguish between:
    • “server starts successfully” (option accepted at startup), and
    • “setting takes effect” (visible in @@optimizer_switch / @@global.optimizer_switch).

  • Optimizer usage verification (hypergraph vs. non-hypergraph):

    • When the requirements say “hypergraph optimizer shall be used,” it should be verified via optimizer trace (or an equivalent supported trace facility).
    • The recommended, concrete marker is presence/absence of the string Constructed hypergraph in the optimizer trace output.
    • When hypergraph optimization is required (e.g., FR4 with WITH_HYPERGRAPH_OPTIMIZER=ON), the optimizer trace shall contain Constructed hypergraph.
    • When hypergraph optimization is not expected (e.g., FR8 with WITH_HYPERGRAPH_OPTIMIZER=OFF), the optimizer trace shall not contain Constructed hypergraph.
    • The trace may be queried using the usual optimizer-trace tables/views used by the test suite (for example, selecting TRACE and filtering with LIKE '%Constructed hypergraph%').

  • Error and warning verification:

    • For SET optimizer_switch='hypergraph_optimizer=on' with WITH_HYPERGRAPH_OPTIMIZER=OFF, verify:
    • the statement fails with error code 3999 (ER_HYPERGRAPH_NOT_SUPPORTED_YET), and
    • the message indicates WITH_HYPERGRAPH_OPTIMIZER=OFF.
    • For SET_VAR(optimizer_switch='hypergraph_optimizer=on') with WITH_HYPERGRAPH_OPTIMIZER=OFF, verify:
    • the statement executes,
    • SHOW WARNINGS; returns warning code 3999, and
    • the warning message indicates WITH_HYPERGRAPH_OPTIMIZER=OFF.

Example SQL (optimizer trace marker)

The following sequence illustrates one way to capture and assert the trace marker:

-- Enable optimizer trace collection (scope and options may vary).
SET optimizer_trace = 'enabled=on';
SET optimizer_trace_max_mem_size = 1048576;

-- Run the statement under test.
SELECT /*+ SET_VAR(optimizer_switch='hypergraph_optimizer=on') */ *
FROM t;

-- Verify marker presence/absence.
SELECT TRACE
FROM INFORMATION_SCHEMA.OPTIMIZER_TRACE
WHERE TRACE LIKE '%Constructed hypergraph%';

Build configuration interface

  • Introduce/clarify two separate build-time controls:

    • WITH_HYPERGRAPH_OPTIMIZER (default ON): controls whether the hypergraph optimizer is compiled in and therefore may be enabled at runtime.
    • ENABLE_HYPERGRAPH_OPTIMIZER (default OFF): controls whether the hypergraph optimizer is enabled by default in OPTIMIZER_SWITCH_DEFAULT.

  • Precedence/consistency rule:

    • If ENABLE_HYPERGRAPH_OPTIMIZER=ON is specified, then WITH_HYPERGRAPH_OPTIMIZER shall be treated as ON (ie, enabling by default implies the code must be built).

Runtime interface

  • No new SQL syntax is introduced.
  • The runtime mechanism for enabling/disabling hypergraph optimization remains the existing optimizer_switch system variable, via:
    • session scope: SET optimizer_switch='hypergraph_optimizer=on|off'
    • global scope: SET GLOBAL optimizer_switch='hypergraph_optimizer=on|off'
    • persisted scope: SET PERSIST optimizer_switch='hypergraph_optimizer=on|off'
    • server startup: mysqld --optimizer-switch=...
    • per-statement hint: /*+ SET_VAR(optimizer_switch='hypergraph_optimizer=on|off') */

Error/warning surface

  • When WITH_HYPERGRAPH_OPTIMIZER=OFF, the server shall continue to reject attempts to enable the hypergraph optimizer using SET optimizer_switch/SET GLOBAL/SET PERSIST with error ER_HYPERGRAPH_NOT_SUPPORTED_YET (3999), and shall continue to ignore SET_VAR enabling attempts while raising warning ER_HYPERGRAPH_NOT_SUPPORTED_YET (3999).

  • The error/warning text shall indicate the build-time reason (eg, to enable it, build with CMake option WITH_HYPERGRAPH_OPTIMIZER=ON).

Observability interface

  • The effective configuration is observable via the existing system variable interfaces:

    • SELECT @@session.optimizer_switch;
    • SELECT @@global.optimizer_switch;

  • When hypergraph optimization is used for a statement, this is observable via optimizer trace output (eg, by the presence of Constructed hypergraph in INFORMATION_SCHEMA.OPTIMIZER_TRACE.TRACE).

Overview

WL#17265 is implemented purely as a build-configuration change plus a small adjustment to the user-facing error text. No new runtime knobs are introduced; instead, the existing optimizer_switch entry hypergraph_optimizer becomes usable in community builds by compiling in the hypergraph optimizer code by default.

CMake changes

1) Default compilation of hypergraph optimizer

  • Set WITH_HYPERGRAPH_OPTIMIZER to be a normal CMake option with default ON.
  • Remove/avoid build-type dependent defaults (eg, “ON only for Debug builds”).
  • Rationale: community builds should include the code unless explicitly configured out.

2) Separate “compiled in” vs “enabled by default”

  • Keep ENABLE_HYPERGRAPH_OPTIMIZER as the build-time switch that controls whether hypergraph_optimizer=on is present in OPTIMIZER_SWITCH_DEFAULT.
  • Maintain the invariant:
    • if ENABLE_HYPERGRAPH_OPTIMIZER=ON then WITH_HYPERGRAPH_OPTIMIZER must evaluate to ON.
    • This prevents a contradictory configuration where the default attempts to enable a feature that was compiled out.

3) Internal option overrides

  • Preserve existing internal override logic (eg, if an internal feature set such as WITH_RAPID requires it) by defining the option early in internal/cmake/mysql_internal_options.cmake, so later defaults do not override it.

Server behavior (unchanged, except where noted)

1) Default runtime behavior

  • Even when the hypergraph optimizer is compiled in, it remains disabled by default at runtime.
  • Users opt in by setting optimizer_switch (session/global/persist), passing --optimizer-switch, or using SET_VAR hints.

2) Behavior when compiled out

  • If WITH_HYPERGRAPH_OPTIMIZER=OFF, attempts to enable the hypergraph optimizer are rejected/ignored as before:
    • SET optimizer_switch='hypergraph_optimizer=on' fails with error 3999.
    • SET GLOBAL ... / SET PERSIST ... fails with error 3999.
    • --optimizer-switch=hypergraph_optimizer=on is accepted for startup but does not result in hypergraph_optimizer=on at runtime.
    • SET_VAR(optimizer_switch='hypergraph_optimizer=on') is tolerated but does not enable hypergraph optimization and raises warning 3999.

3) Error message wording (change)

  • Update the message for ER_HYPERGRAPH_NOT_SUPPORTED_YET (3999) emitted by the optimizer-switch validation logic to reference the explicit build-time reason:
    • ERROR 42000: The hypergraph optimizer does not yet support 'this build configuration; to enable it, build with CMake option WITH_HYPERGRAPH_OPTIMIZER=ON'
  • Rationale: after this WL, “non-debug builds” is no longer the defining condition; the controlling factor is the compile-time option.

Validation/observability

  • Confirm compiled-in behavior by enabling hypergraph_optimizer=on and verifying:

    • @@optimizer_switch / @@global.optimizer_switch changes as expected for the chosen scope.
    • optimizer trace contains the marker Constructed hypergraph for statements optimized using hypergraph.

  • Confirm compiled-out behavior by verifying error/warning code 3999 and that optimizer trace does not contain Constructed hypergraph when attempting to enable via SET_VAR.



Copyright (c) 2000, 2026, Oracle Corporation and/or its affiliates. All rights reserved.