Environment:Apache Shardingsphere Calcite Federation Engine
| Knowledge Sources | |
|---|---|
| Domains | Infrastructure, Query_Federation |
| Last Updated | 2026-02-10 02:00 GMT |
Overview
Apache Calcite 1.40.0 query federation engine for cross-database SQL optimization and execution in ShardingSphere.
Description
This environment provides the SQL federation capability that allows ShardingSphere to execute cross-datasource queries using Apache Calcite's query optimizer and execution framework. Calcite handles SQL parsing, optimization, and execution planning for federated queries that span multiple physical databases. The federation metadata refresh engine maintains Calcite's internal schema representation in sync with the actual database metadata.
Usage
Use this environment when ShardingSphere needs to execute federated queries that cross database or schema boundaries. The federation engine is activated when a SQL statement cannot be fully pushed down to a single data source. It is the prerequisite for the FederationMetaDataRefreshEngine implementation that keeps Calcite metadata synchronized with DDL changes.
System Requirements
| Category | Requirement | Notes |
|---|---|---|
| Java | JDK 8+ | Calcite 1.40.0 requires Java 8+ |
| Memory | Additional heap for query planning | Complex federated queries may require increased heap |
Dependencies
Java Libraries
- `org.apache.calcite:calcite-core` = 1.40.0
Credentials
No additional credentials required. Calcite operates in-process using existing database connections.
Quick Install
# Calcite is included as a transitive dependency of ShardingSphere
# No separate installation required
# Federation is enabled by default in ShardingSphere
# It can be configured via global.yaml:
# sqlFederation:
# sqlFederationEnabled: true
# executionPlanCache:
# initialCapacity: 2000
# maximumSize: 65535
Code Evidence
Calcite version declaration from `pom.xml:77`:
<calcite.version>1.40.0</calcite.version>
Federation metadata refresh engine from `FederationMetaDataRefreshEngine.java:63-70`:
public void refresh(final SQLStatementContext sqlStatementContext,
final Collection<String> logicDataSourceNames) {
findFederationMetaDataRefresher(sqlStatementContext).ifPresent(
optional -> optional.refresh(metaDataPersistFacade.getDatabaseMetaDataFacade(),
database, logicDataSourceNames, sqlStatementContext));
}
Common Errors
| Error Message | Cause | Solution |
|---|---|---|
| `Object not found: schema` | Calcite schema not yet refreshed | DDL changes may not be reflected; check federation refresh pipeline |
| `Cannot apply 'CAST' to arguments` | Type mismatch in federated query | Ensure compatible column types across federated data sources |
Compatibility Notes
- Calcite 1.40.0: Bundled version; upgrading may cause API incompatibilities.
- Federation scope: Only activated for queries that cannot be pushed down to a single data source.
- View support: Federated view metadata is managed by dedicated `FederationMetaDataRefresher` SPI implementations (CREATE VIEW, ALTER VIEW, DROP VIEW).