Principle:Apache Shardingsphere Federation Metadata Refresh

Knowledge Sources	Apache ShardingSphere ShardingSphere Docs
Domains	Metadata_Management, DDL_Processing
Last Updated	2026-02-10 00:00 GMT

Overview

View-related DDL operations require a separate metadata refresh path to keep the federated query engine (Apache Calcite) synchronized with the current view definitions.

Description

ShardingSphere uses Apache Calcite as its federated query engine for executing cross-database queries. Calcite maintains its own internal metadata catalog that must accurately reflect the current state of views in the database. When view-related DDL statements (CREATE VIEW, ALTER VIEW, DROP VIEW) are executed, the standard push-down metadata refresh updates the core ShardingSphere metadata, but the Calcite federation layer also needs to be notified so it can update its own schema representation.

The Federation Metadata Refresh principle introduces a parallel refresh path specifically for view DDL operations. It follows the same architectural patterns as the push-down refresh:

• A supported types set containing only view-related DDL classes (CreateViewStatement, AlterViewStatement, DropViewStatement).
• An isNeedRefresh() guard method that checks membership in this set.
• An SPI-based refresher lookup using FederationMetaDataRefresher<T extends SQLStatement> to load type-specific handlers.
• A superclass fallback strategy for vendor-specific view statement subclasses.

The federation refresh engine is intentionally separate from the push-down refresh engine because:

1. Different scope: Push-down refresh handles all DDL types; federation refresh handles only view DDL.
2. Different target: Push-down refresh updates the ShardingSphere metadata model; federation refresh updates the Calcite catalog.
3. Different interface: The FederationMetaDataRefresher has a simpler parameter set since it does not need route units, configuration properties, or logic data source names.

Usage

Use this principle when:

• Understanding the dual refresh path for view DDL operations (push-down + federation).
• Implementing support for new view-related DDL operations in the federation layer.
• Troubleshooting Calcite query plan issues after view DDL changes.
• Extending the federation metadata refresh to cover additional DDL types that affect federated queries.

Theoretical Basis

The federation refresh operates as a parallel pipeline to the push-down refresh:

FEDERATION_SUPPORTED_TYPES = {CreateView, AlterView, DropView}

function federationIsNeedRefresh(sqlStatementContext):
    statementClass = sqlStatementContext.getSqlStatement().getClass()
    return statementClass IN FEDERATION_SUPPORTED_TYPES

function federationRefresh(sqlStatementContext, persistService, database):
    refresher = findFederationRefresher(sqlStatementContext)
    if refresher is absent:
        return

    schemaName = resolveSchemaName(database, sqlStatementContext)
    databaseType = sqlStatementContext.getSqlStatement().getDatabaseType()
    refresher.refresh(persistService, databaseType, database, schemaName, sqlStatement)

function findFederationRefresher(sqlStatementContext):
    statementClass = sqlStatementContext.getSqlStatement().getClass()
    refresher = TypedSPILoader.findService(FederationMetaDataRefresher, statementClass)
    if refresher is present:
        return refresher
    // Fallback to superclass
    return TypedSPILoader.findService(FederationMetaDataRefresher, statementClass.getSuperclass())

The dual refresh flow for a CREATE VIEW statement:

DDL Execution: CREATE VIEW my_view AS SELECT ...
    |
    +-- Push-Down Refresh Path (PushDownMetaDataRefreshEngine)
    |     |
    |     +-- PushDownMetaDataRefresher<CreateViewStatement>
    |           +-- Reload view metadata from database
    |           +-- Persist to repository (triggers cluster events)
    |
    +-- Federation Refresh Path (FederationMetaDataRefreshEngine)
          |
          +-- FederationMetaDataRefresher<CreateViewStatement>
                +-- Update Calcite catalog with new view definition
                +-- Persist federation metadata changes

Key design decisions:

• Separation of concerns: Federation refresh is isolated from push-down refresh, allowing each to evolve independently.
• Consistent architecture: Both engines use the same SPI-based discovery and superclass fallback patterns.
• Minimal scope: Federation refresh is limited to view DDL, reflecting that only views affect federated query plans.

Related Pages

Implemented By

• Implementation:Apache_Shardingsphere_FederationMetaDataRefreshEngine_Refresh