Implementation:Apache Shardingsphere ShadowColumnDataSourceMappingsRetriever Retrieve

Knowledge Sources	Apache ShardingSphere
Domains	Database_Routing, Shadow_Testing
Last Updated	2026-02-10 00:00 GMT

Overview

Concrete tool for retrieving shadow data source mappings based on column values in DML statements, provided by the ShardingSphere shadow module.

Description

ShadowColumnDataSourceMappingsRetriever is an abstract class implementing ShadowTableDataSourceMappingsRetriever. It is annotated with @HighFrequencyInvocation and @RequiredArgsConstructor, and holds a single field: the ShadowOperationType identifying the current DML operation (INSERT, UPDATE, DELETE, or SELECT).

The retrieve method iterates over each table name in the shadowTables collection. For each table, it asks the ShadowRule for the shadow column names registered for the current operation type. If shadow columns exist, it invokes isMatchAnyColumnShadowAlgorithms to determine whether any of the table's column shadow algorithms match the current statement's column values. Upon finding the first matching table, it returns that table's data source mappings via rule.getShadowDataSourceMappings(tableName). If no table matches, an empty map is returned.

The matching process is a three-level cascade:

1. Column level: For each shadow column name, retrieve the registered ColumnShadowAlgorithm instances for that column and operation type.
2. Condition level: For each column, call the abstract method getShadowColumnConditions(shadowColumnName) to extract the actual column conditions from the SQL statement. This is implemented by concrete subclasses for each DML type (Insert, Delete, Update, Select).
3. Algorithm level: For each condition, evaluate it against each registered algorithm via ColumnShadowAlgorithmDeterminer.isShadow. The determiner constructs a ShadowCondition containing the table name, operation type, and column condition, then delegates to the algorithm.

Concrete subclasses include:

• ShadowInsertStatementDataSourceMappingsRetriever - extracts column values from INSERT values clauses
• ShadowDeleteStatementDataSourceMappingsRetriever - extracts column values from DELETE WHERE clauses
• ShadowUpdateStatementDataSourceMappingsRetriever - extracts column values from UPDATE WHERE clauses
• ShadowSelectStatementDataSourceMappingsRetriever - extracts column values from SELECT WHERE clauses

Usage

This retriever is used internally by the DML shadow routing pipeline as a fallback when hint-based routing does not produce a result. Each DML statement type has its own concrete subclass. 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/column/ShadowColumnDataSourceMappingsRetriever.java
• Lines: 43-52

Signature

@Override
public Map<String, String> retrieve(final ShadowRule rule, final Collection<String> shadowTables)

Abstract Method

protected abstract Collection<ShadowColumnCondition> getShadowColumnConditions(String shadowColumnName);

Import

import org.apache.shardingsphere.shadow.route.retriever.dml.table.column.ShadowColumnDataSourceMappingsRetriever;

I/O Contract

Inputs

Name	Type	Required	Description
rule	ShadowRule	Yes	The shadow rule containing shadow column names, column shadow algorithms, and data source mappings for each shadow table
shadowTables	Collection<String>	Yes	The collection of table names from the current SQL statement that match configured shadow tables

Outputs

Name	Type	Description
return	Map<String, String>	A map of production data source name to shadow data source name for the first shadow table whose column algorithms match the statement's column values, or an empty map if no match is found

Usage Examples

Basic Usage

// Column-based retrieval is invoked by ShadowDMLStatementDataSourceMappingsRetriever
// when hint-based retrieval returns an empty map.

// For an INSERT statement with shadow columns:
// INSERT INTO t_order (id, user_id, shadow_flag) VALUES (1, 100, true)

// The ShadowInsertStatementDataSourceMappingsRetriever (a concrete subclass)
// extracts column conditions: shadow_flag = [true]
// The column shadow algorithm evaluates: true -> shadow match
// Returns: {"ds_prod" -> "ds_shadow"}

// For a SELECT statement with shadow column in WHERE clause:
// SELECT * FROM t_order WHERE shadow_flag = true

// The ShadowSelectStatementDataSourceMappingsRetriever (a concrete subclass)
// extracts column conditions from WHERE: shadow_flag = [true]
// The column shadow algorithm evaluates: true -> shadow match
// Returns: {"ds_prod" -> "ds_shadow"}

Algorithm Matching Flow

// The three-level matching cascade:
// Level 1: Iterate shadow tables
//   -> t_order has shadow columns [shadow_flag] for INSERT operation
// Level 2: Extract column conditions (abstract, subclass-specific)
//   -> ShadowColumnCondition(table="t_order", column="shadow_flag", values=[true])
// Level 3: Evaluate algorithms
//   -> ColumnShadowAlgorithmDeterminer.isShadow(algorithm,
//        new ShadowCondition("t_order", INSERT, columnCondition))
//   -> Returns true if algorithm matches all values in the condition

Related Pages

Implements Principle

• Principle:Apache_Shardingsphere_Column_Based_Routing

Uses Heuristic

• Heuristic:Apache_Shardingsphere_Shadow_Routing_Hint_First_Fallback