Implementation:Apache Shardingsphere ShadowTableHintDataSourceMappingsRetriever Retrieve
| Knowledge Sources | |
|---|---|
| Domains | Database_Routing, Shadow_Testing |
| Last Updated | 2026-02-10 00:00 GMT |
Overview
Concrete tool for retrieving shadow data source mappings based on SQL hint annotations at the table level, provided by the ShardingSphere shadow module.
Description
ShadowTableHintDataSourceMappingsRetriever is a final class implementing ShadowTableDataSourceMappingsRetriever. It is annotated with @HighFrequencyInvocation and @RequiredArgsConstructor, and holds two fields: the ShadowOperationType and a boolean isShadow flag indicating the hint value context's shadow state.
The retrieve method implements a two-branch decision:
- Empty shadow tables branch: When the shadowTables collection is empty (the statement's tables do not match any configured shadow tables), the method calls isMatchDefaultAlgorithm. This checks whether a default shadow algorithm is configured on the rule and whether it accepts the current hint state via HintShadowAlgorithmDeterminer.isShadow. If it matches, rule.getAllShadowDataSourceMappings() is returned (all production-to-shadow mappings). Otherwise, execution falls through to the table-specific branch.
- Table-specific branch: The findShadowDataSourceMappingsBySQLHints method iterates over each shadow table. For each table, it retrieves the table's registered HintShadowAlgorithm instances from the rule and evaluates them via HintShadowAlgorithmDeterminer.isShadow. The first table with a matching algorithm triggers a return of that table's specific data source mappings via rule.getShadowDataSourceMappings(tableName). If no table matches, an empty map is returned.
This class is instantiated by ShadowDMLStatementDataSourceMappingsRetriever and is always evaluated before any column-based retriever. The hint-based check acts as a fast-path that can short-circuit the more expensive column-based evaluation.
Usage
This retriever is used internally by the DML shadow routing pipeline. It is instantiated when a DML statement is being processed and the system needs to check hint-based shadow conditions before falling back to column-based conditions. It is not intended for direct use by application code.
Code Reference
Source Location
- Repository: Apache ShardingSphere
- File: features/shadow/core/src/main/java/org/apache/shardingsphere/shadow/route/retriever/dml/table/hint/ShadowTableHintDataSourceMappingsRetriever.java
- Lines: 44-47
Signature
@Override
public Map<String, String> retrieve(final ShadowRule rule, final Collection<String> shadowTables)
Import
import org.apache.shardingsphere.shadow.route.retriever.dml.table.hint.ShadowTableHintDataSourceMappingsRetriever;
I/O Contract
Inputs
| Name | Type | Required | Description |
|---|---|---|---|
| rule | ShadowRule | Yes | The shadow rule containing default shadow algorithm, table-specific hint shadow algorithms, and data source mappings |
| shadowTables | Collection<String> | Yes | The collection of table names from the current SQL statement that match configured shadow tables; may be empty |
Outputs
| Name | Type | Description |
|---|---|---|
| return | Map<String, String> | A map of production data source name to shadow data source name. Returns all shadow mappings if the default algorithm matches on empty shadow tables, table-specific mappings if a table's hint algorithm matches, or an empty map if no hint algorithms match |
Usage Examples
Basic Usage
// Instantiated internally by ShadowDMLStatementDataSourceMappingsRetriever:
ShadowTableHintDataSourceMappingsRetriever hintRetriever =
new ShadowTableHintDataSourceMappingsRetriever(ShadowOperationType.INSERT, true);
// When shadow tables are found for the statement:
Collection<String> shadowTables = Arrays.asList("t_order");
Map<String, String> mappings = hintRetriever.retrieve(shadowRule, shadowTables);
// If t_order has a hint shadow algorithm that matches: {"ds_prod" -> "ds_shadow"}
// If no hint algorithm matches: {}
// When no shadow tables are found (e.g., table not in shadow config):
Collection<String> emptyTables = Collections.emptyList();
Map<String, String> defaultMappings = hintRetriever.retrieve(shadowRule, emptyTables);
// If default algorithm matches: all configured shadow data source mappings
// If no default algorithm or it does not match: {}