Heuristic:Apache Shardingsphere Shadow Routing Hint First Fallback

Knowledge Sources	Apache ShardingSphere Shadow Routing Implementation
Domains	Shadow_Routing, Optimization
Last Updated	2026-02-10 02:00 GMT

Overview

Shadow routing strategy that evaluates hint-based algorithms first, then falls back to column-based algorithms only when hints produce no results.

Description

When ShardingSphere processes a DML statement through the shadow routing pipeline, it uses a two-phase strategy to determine whether the query should be routed to a shadow data source. The first phase checks SQL comment hints (low-cost string matching). Only if hints yield no routing decision does the system evaluate column-based algorithms (higher-cost value extraction from SQL AST). This ordering minimizes the performance overhead of shadow routing on the critical query path.

Usage

Apply this heuristic when designing or debugging shadow routing behavior. Understanding the hint-first/column-fallback order is essential for:

Performance tuning: Preferring SQL hints over column-based routing for latency-sensitive queries.
Debugging: When a query routes to shadow unexpectedly, check hint annotations first before investigating column conditions.
Configuration: When both hint and column algorithms are configured for the same table, hints always take precedence.

The Insight (Rule of Thumb)

Action: When configuring shadow routing, prefer SQL hint algorithms for performance-critical paths. Column-based algorithms are only evaluated as a fallback.
Value: Hint evaluation is O(1) string matching; column evaluation requires SQL AST traversal and value extraction.
Trade-off: Hint-based routing requires explicit SQL comment annotations (more invasive to application code), while column-based routing is transparent but slower.
Compatibility: The `@HighFrequencyInvocation` annotation on the retriever class marks this as a performance-critical code path.

Reasoning

The `ShadowDMLStatementDataSourceMappingsRetriever.retrieve()` method implements this as a ternary expression: if hint results are non-empty, return them immediately; otherwise delegate to column-based retrieval. This avoids unnecessary SQL AST traversal when hints are sufficient.

The hint retriever (`ShadowTableHintDataSourceMappingsRetriever`) is annotated with `@HighFrequencyInvocation`, indicating the ShardingSphere team has identified this path as performance-critical. The column retriever involves extracting values from WHERE clauses, INSERT value lists, or UPDATE SET clauses — substantially more work than checking a SQL comment.

Code evidence from `ShadowDMLStatementDataSourceMappingsRetriever.java:74-78`:

@Override
public Map<String, String> retrieve(final ShadowRule rule) {
    Collection<String> shadowTables = rule.filterShadowTables(tableNames);
    Map<String, String> result = tableHintDataSourceMappingsRetriever.retrieve(rule, shadowTables);
    return result.isEmpty() && null != shadowColumnDataSourceMappingsRetriever
        ? shadowColumnDataSourceMappingsRetriever.retrieve(rule, shadowTables)
        : result;
}

The null-check on `shadowColumnDataSourceMappingsRetriever` is significant: for non-DML statements (DDL, DCL), the column retriever is null, so only hints are evaluated. This is correct because column-based shadow detection only makes sense for DML statements that contain data values.

Related Pages

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment