Principle:Apache Shardingsphere Statement Type Classification
| Knowledge Sources | |
|---|---|
| Domains | Database_Routing, Shadow_Testing |
| Last Updated | 2026-02-10 00:00 GMT |
Overview
Classifying SQL statements by type (DML versus non-DML) to select the appropriate shadow routing strategy, ensuring that data manipulation statements receive fine-grained table-level and column-level shadow evaluation while non-DML statements fall back to a simpler hint-only routing path.
Description
Statement Type Classification is the principle of inspecting a parsed SQL statement's category before selecting a shadow routing strategy. In the context of shadow database routing, the statement type determines which retrieval mechanism is used to resolve shadow data source mappings:
- DML statements (INSERT, UPDATE, DELETE, SELECT) contain table references and column values that can be examined for shadow routing conditions. These statements are eligible for both hint-based and column-based shadow algorithms, and the system constructs a retriever that can inspect table-specific shadow rules, column conditions, and hint annotations.
- Non-DML statements (DDL, DCL, utility statements, and any other statement type that does not fall into the four recognized DML categories) cannot be examined at the table or column level for shadow conditions. These statements are routed using only the global hint-based strategy, which checks whether the overall session or statement has been marked for shadow routing.
This classification serves as a strategy selection gateway. It applies the Factory Method pattern to instantiate the correct retriever subclass based on the statement type, encapsulating the decision in a single location and keeping the downstream routing logic unaware of statement categories.
The classification is intentionally conservative: only the four explicitly recognized DML types receive the full DML routing path. Any unrecognized statement type, including database-specific extensions or future SQL additions, defaults to the hint-only path. This ensures that new statement types do not cause routing failures.
Usage
Use Statement Type Classification when:
- You need to determine whether a SQL statement can participate in table-level and column-level shadow algorithm evaluation
- You are designing a strategy selection layer that must dispatch to different routing implementations based on SQL statement category
- You want to ensure that non-DML statements (DDL, DCL) can still be routed to shadow databases via hint-based mechanisms without requiring table or column analysis
- You are implementing a factory method that must produce the correct retriever variant for the current statement context
Theoretical Basis
The classification algorithm uses an instanceof chain against the parsed SQL statement context to determine the operation type:
FUNCTION classifyAndCreateRetriever(queryContext):
statementContext = queryContext.sqlStatementContext
operationType = NONE
IF statementContext IS InsertStatementContext:
operationType = INSERT
ELSE IF statementContext IS DeleteStatementContext:
operationType = DELETE
ELSE IF statementContext IS UpdateStatementContext:
operationType = UPDATE
ELSE IF statementContext IS SelectStatementContext:
operationType = SELECT
IF operationType is present:
RETURN new DMLStatementDataSourceMappingsRetriever(queryContext, operationType)
ELSE:
RETURN new HintDataSourceMappingsRetriever(queryContext.hintValueContext)
The key design properties of this classification are:
- Exhaustive DML coverage: All four standard DML categories are recognized (INSERT, DELETE, UPDATE, SELECT), each mapped to a corresponding ShadowOperationType enum value.
- Safe default: When the statement does not match any DML type, the factory returns a hint-only retriever rather than throwing an exception. This means the shadow feature degrades gracefully for unrecognized statement types.
- Single responsibility: The classification logic is isolated in a factory class with private constructor (utility class pattern), keeping it separate from both the routing logic and the retriever implementations.
- Operation type propagation: The identified operation type is passed forward to the DML retriever, which uses it to look up table-specific shadow algorithms that are registered for that particular operation type.