Implementation:Apache Shardingsphere FederationMetaDataRefreshEngine Refresh

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

Overview

Concrete tool for refreshing Apache Calcite federation metadata after view-related DDL operations, provided by the ShardingSphere mode-core module.

Description

FederationMetaDataRefreshEngine manages the metadata refresh pipeline for the federation (Apache Calcite) query engine. It is structurally parallel to PushDownMetaDataRefreshEngine but with a narrower scope: it only handles view-related DDL statements (CreateViewStatement, AlterViewStatement, DropViewStatement).

The class maintains a static SUPPORTED_REFRESH_TYPES set containing the three view DDL statement classes. It exposes:

• isNeedRefresh(): Checks if the SQL statement class is a view DDL operation by performing a HashSet membership test.
• refresh(): Looks up a FederationMetaDataRefresher via TypedSPILoader, resolves the schema name, and delegates to the refresher to update the Calcite metadata catalog.

Unlike PushDownMetaDataRefreshEngine which uses @RequiredArgsConstructor, this class has an explicit constructor that takes an SQLStatementContext. The refresh() method has a simpler parameter list, requiring only the persist service and database (no route units or configuration properties).

The SPI lookup uses the same superclass fallback strategy as the push-down engine: if no refresher is registered for the exact statement class, it tries the superclass.

Usage

Use this engine after DDL execution when the statement is a view operation. Call isNeedRefresh() first; if true, call refresh() with the metadata manager persist service and the database.

Code Reference

Source Location

• Repository: Apache ShardingSphere
• File: mode/core/src/main/java/org/apache/shardingsphere/mode/metadata/refresher/federation/FederationMetaDataRefreshEngine.java
• Lines: 37-77

Signature

public final class FederationMetaDataRefreshEngine {

    public FederationMetaDataRefreshEngine(final SQLStatementContext sqlStatementContext)

    public boolean isNeedRefresh()

    public void refresh(final MetaDataManagerPersistService metaDataManagerPersistService,
                        final ShardingSphereDatabase database)
}

FederationMetaDataRefresher SPI Interface

@SingletonSPI
public interface FederationMetaDataRefresher<T extends SQLStatement> extends TypedSPI {

    void refresh(MetaDataManagerPersistService metaDataManagerPersistService,
                 DatabaseType databaseType,
                 ShardingSphereDatabase database,
                 String schemaName,
                 T sqlStatement);

    @Override
    Class<T> getType();
}

Import

import org.apache.shardingsphere.mode.metadata.refresher.federation.FederationMetaDataRefreshEngine;
import org.apache.shardingsphere.mode.metadata.refresher.federation.FederationMetaDataRefresher;

I/O Contract

Inputs (Constructor)

Name	Type	Required	Description
sqlStatementContext	SQLStatementContext	Yes	The context wrapping the parsed SQL statement to evaluate for federation refresh

Inputs (isNeedRefresh)

Name	Type	Required	Description
(none)			Uses the sqlStatementContext provided at construction time

Outputs (isNeedRefresh)

Name	Type	Description
return	boolean	True if the statement is a view DDL (CreateView, AlterView, DropView); false otherwise

Inputs (refresh)

Name	Type	Required	Description
metaDataManagerPersistService	MetaDataManagerPersistService	Yes	Service for persisting federation metadata changes
database	ShardingSphereDatabase	Yes	The database whose federation metadata needs updating

Outputs (refresh)

Name	Type	Description
return	void	No return value; federation metadata is refreshed as a side effect

Usage Examples

// After view DDL execution, refresh federation metadata
FederationMetaDataRefreshEngine federationEngine =
    new FederationMetaDataRefreshEngine(sqlStatementContext);

if (federationEngine.isNeedRefresh()) {
    federationEngine.refresh(metaDataManagerPersistService, database);
}

// Typically used alongside the push-down refresh:
PushDownMetaDataRefreshEngine pushDownEngine =
    new PushDownMetaDataRefreshEngine(sqlStatementContext);
if (pushDownEngine.isNeedRefresh()) {
    pushDownEngine.refresh(metaDataManagerPersistService, database, props, routeUnits);
}
// Federation refresh handles the Calcite-specific metadata update
if (federationEngine.isNeedRefresh()) {
    federationEngine.refresh(metaDataManagerPersistService, database);
}

Related Pages

Implements Principle

• Principle:Apache_Shardingsphere_Federation_Metadata_Refresh

Requires Environment

• Environment:Apache_Shardingsphere_Calcite_Federation_Engine