Principle:Apache Shardingsphere Hint Based Routing
| Knowledge Sources | |
|---|---|
| Domains | Database_Routing, Shadow_Testing |
| Last Updated | 2026-02-10 00:00 GMT |
Overview
Using SQL hint annotations or session-level hint flags to determine whether a SQL statement should be routed to shadow databases, independent of the actual SQL content or column values.
Description
Hint Based Routing is a shadow routing strategy in which the decision to redirect a SQL statement to a shadow database is driven by external metadata (hints) rather than by inspecting the SQL statement's columns or values. Hints are out-of-band signals that accompany a SQL statement, typically set through ShardingSphere's HintManager API or SQL comment annotations. The hint mechanism tells the routing layer: "this statement is shadow traffic" or "this statement is production traffic," without requiring the SQL itself to contain any distinguishing data.
This principle addresses several important scenarios:
- Non-DML statements: DDL, DCL, and utility statements do not have column values to inspect. Hint-based routing is the only mechanism available for routing these statements to shadow databases.
- Cross-cutting shadow flags: When an entire session or request is designated as shadow traffic (e.g., from a load testing tool), a single hint flag can redirect all statements regardless of their content.
- DML statements with table-level hints: Even for DML statements, hint-based routing is attempted first before falling back to column-based routing. This provides a fast-path for table-level shadow decisions.
The hint routing evaluation follows a two-tier approach:
- Default algorithm check: If no shadow tables match the statement's table names, the system checks whether a default shadow algorithm is configured and whether it accepts the current hint state. If it matches, all data source mappings are returned.
- Table-specific algorithm check: If shadow tables are found, the system iterates through each table's registered hint shadow algorithms. The first table whose hint algorithms match the current hint condition triggers the return of that table's specific data source mappings.
This two-tier approach ensures that both global (default) and table-specific hint rules are honored, with the default algorithm serving as a catch-all for statements that reference no configured shadow tables.
Usage
Use Hint Based Routing when:
- You need to route non-DML statements (DDL, DCL) to shadow databases
- You want to designate an entire session or request as shadow traffic using a single flag
- You prefer explicit, external control over shadow routing rather than implicit column-value detection
- You are implementing a shadow routing retriever that must evaluate hint shadow algorithms at the table level within the DML routing pipeline
Theoretical Basis
The hint-based routing algorithm for DML table-level retrieval operates as follows:
FUNCTION retrieveByHint(shadowRule, shadowTables, operationType, isShadowHint):
IF shadowTables is empty:
// No matching shadow tables - check default algorithm
defaultAlgorithm = shadowRule.getDefaultShadowAlgorithm()
IF defaultAlgorithm is present:
condition = new ShadowCondition() // empty condition for default
IF HintShadowAlgorithmDeterminer.isShadow(defaultAlgorithm, condition, shadowRule, isShadowHint):
RETURN shadowRule.getAllShadowDataSourceMappings()
RETURN empty map
ELSE:
// Check table-specific hint algorithms
FOR EACH tableName IN shadowTables:
condition = new ShadowCondition(tableName, operationType)
FOR EACH hintAlgorithm IN shadowRule.getHintShadowAlgorithms(tableName):
IF HintShadowAlgorithmDeterminer.isShadow(hintAlgorithm, condition, shadowRule, isShadowHint):
RETURN shadowRule.getShadowDataSourceMappings(tableName)
RETURN empty map
Key properties of this algorithm:
- First-match semantics: When multiple shadow tables are configured, the first table whose hint algorithm matches determines the returned data source mappings. Subsequent tables are not evaluated.
- Default fallback scope: The default algorithm applies globally to all data sources, not to a specific table. It is only consulted when no shadow tables match the statement.
- Shadow condition construction: For table-specific checks, the condition includes the table name and operation type. For the default algorithm check, an empty condition (no table, HINT_MATCH operation type) is used.
- Hint state propagation: The isShadow boolean from the HintValueContext is propagated through to the algorithm, allowing the algorithm to make its determination based on the session-level shadow flag.