Principle:Apache Shardingsphere Shadow Algorithm Evaluation

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

Overview

Evaluating shadow algorithms to determine whether a given SQL statement should be routed to a shadow database, by constructing algorithm-specific shadow values from the routing context and delegating the decision to pluggable SPI algorithm implementations.

Description

Shadow Algorithm Evaluation is the principle of applying a configured shadow algorithm against a set of contextual inputs (shadow conditions) to produce a boolean decision: should this statement be routed to a shadow database or not? This evaluation is the final decision point in the shadow routing pipeline. All upstream logic (statement classification, hint retrieval, column extraction) converges on this step, where the actual algorithm implementation makes the determination.

There are two distinct categories of shadow algorithm evaluation, corresponding to the two types of shadow algorithms supported by ShardingSphere:

1. Hint Shadow Algorithm Evaluation

Hint algorithms evaluate based on a PreciseHintShadowValue that encapsulates:

• The table name from the shadow condition (empty string for default algorithm evaluation)
• The operation type (e.g., HINT_MATCH for default, or INSERT/UPDATE/DELETE/SELECT for table-specific)
• The isShadow boolean flag from the hint value context

The evaluation delegates to the HintShadowAlgorithm.isShadow method, passing the full set of shadow table names from the rule alongside the shadow value. This allows the algorithm to consider both the current hint state and the broader table configuration when making its decision.

2. Column Shadow Algorithm Evaluation

Column algorithms evaluate based on PreciseColumnShadowValue instances, one per value in the column condition. Each shadow value encapsulates:

• The table name
• The operation type
• The column name
• A single column value

The evaluation applies a conjunctive (AND) logic: the algorithm must return true for every value in the column condition for the overall evaluation to be considered a shadow match. Additionally, the evaluator performs a table name consistency check: if the shadow condition's table name does not match the column condition's table name, the evaluation returns false immediately. This prevents cross-table mismatches when the same column name appears in multiple tables.

The key design insight is that the determiner classes are stateless utility classes that bridge the gap between the routing context model (ShadowCondition, ShadowRule) and the SPI algorithm model (PreciseHintShadowValue, PreciseColumnShadowValue). They translate routing-layer concepts into algorithm-layer inputs.

Usage

Use Shadow Algorithm Evaluation when:

• You need to make the final boolean decision about whether a statement should be routed to a shadow database
• You are implementing the evaluation bridge between shadow routing conditions and SPI shadow algorithm implementations
• You want to understand how hint-based and column-based shadow decisions differ in their evaluation semantics
• You are designing a new shadow algorithm SPI implementation and need to understand what inputs it will receive

Theoretical Basis

Hint Algorithm Evaluation:

FUNCTION evaluateHintAlgorithm(algorithm, condition, shadowRule, isShadow):
    shadowValue = new PreciseHintShadowValue(
        tableName = condition.tableName,       // "" for default, actual name for table-specific
        operationType = condition.operationType, // HINT_MATCH for default, DML type for table-specific
        isShadow = isShadow                     // from HintValueContext
    )
    RETURN algorithm.isShadow(shadowRule.allShadowTableNames, shadowValue)

Column Algorithm Evaluation:

FUNCTION evaluateColumnAlgorithm(algorithm, condition):
    // Table name consistency check
    IF condition.tableName != condition.columnCondition.table:
        RETURN false

    // Conjunctive evaluation over all column values
    FOR EACH value IN condition.columnCondition.values:
        shadowValue = new PreciseColumnShadowValue(
            tableName = condition.tableName,
            operationType = condition.operationType,
            columnName = condition.columnCondition.column,
            value = value
        )
        IF NOT algorithm.isShadow(shadowValue):
            RETURN false

    RETURN true

Key properties of the evaluation model:

• Hint evaluation is single-shot: One shadow value is constructed and evaluated. The algorithm receives the full set of shadow table names for contextual awareness.
• Column evaluation is conjunctive: All values in the column condition must pass the algorithm for the result to be true. This means if a column has multiple values (e.g., in an IN clause), every value must indicate shadow.
• Table consistency guard: Column evaluation includes a defensive check that the shadow condition's table matches the column condition's source table, preventing incorrect evaluations when column conditions are extracted from multi-table statements.
• Stateless determiners: Both HintShadowAlgorithmDeterminer and ColumnShadowAlgorithmDeterminer are utility classes with private constructors and static methods. They maintain no state between evaluations.
• SPI delegation: The actual decision logic resides in the HintShadowAlgorithm and ColumnShadowAlgorithm SPI implementations, making the evaluation framework extensible without modifying the routing code.

Related Pages

Implemented By

• Implementation:Apache_Shardingsphere_ShadowAlgorithmDeterminer_IsShadow