Struct SQLContext 

pub struct SQLContext { /* private fields */ }

A SQL context that supports registering multiple Paimon catalogs and executing SQL.

Example

let mut ctx = SQLContext::new();
ctx.register_catalog("paimon", catalog).await?;
ctx.set_current_catalog("paimon").await?;
let df = ctx.sql("ALTER TABLE paimon.db.t ADD COLUMN age INT").await?;

Implementations

impl SQLContext

pub fn new() -> Self

Creates a new empty SQL context.

pub fn blob_reader_registry(&self) -> BlobReaderRegistry

pub async fn register_catalog( &mut self, catalog_name: impl Into<String>, catalog: Arc<dyn Catalog>, ) -> DFResult<()>

Registers a Paimon catalog under the given name.

The first registered catalog automatically becomes the current catalog for both Paimon-handled SQL and DataFusion-delegated SQL (SELECT, etc.). A “default” database is created if it does not already exist (matching the behavior of Spark/Flink Paimon catalogs).

pub async fn register_catalog_with_default_db( &mut self, catalog_name: impl Into<String>, catalog: Arc<dyn Catalog>, default_db: Option<&str>, ) -> DFResult<()>

Like Self::register_catalog but lets the caller control default-database init.

default_db = Some(name) ensures name exists and sets it as current on the first catalog. default_db = None skips both — required for principals that lack DESCRIBE / CREATEDATABASE on default. Mirrors Java FlinkCatalog’s defaultDatabase / DISABLE_CREATE_TABLE_IN_DEFAULT_DB.

default_db = Some("") is rejected — pass None to opt out instead.

Note on built-in TVFs (vector_search, full_text_search): when default_db = None, bare table names inside these functions still resolve against the literal namespace "default" (the fallback in [register_table_functions]). Callers using None must qualify table names ('db.table' or 'catalog.db.table') in those calls.

pub async fn set_current_catalog( &mut self, catalog_name: impl Into<String>, ) -> DFResult<()>

Sets the current catalog for unqualified table references.

pub async fn set_current_database(&self, database_name: &str) -> DFResult<()>

Sets the current database for unqualified table references.

pub fn ctx(&self) -> &SessionContext

Returns a reference to the inner SessionContext.

pub fn register_temp_table( &self, name: impl Into<TableReference>, table: Arc<dyn TableProvider>, ) -> DFResult<()>

Registers a temporary in-memory table or view.

The name parameter accepts flexible table references, similar to DataFusion:

• "my_table" — uses the current catalog and current database
• "database.my_table" — uses the current catalog with the specified database
• "catalog.database.my_table" — fully qualified

The table exists only for the lifetime of this SQLContext instance.

pub fn deregister_temp_table( &self, name: impl Into<TableReference>, ) -> DFResult<Option<Arc<dyn TableProvider>>>

Deregisters a temporary table or view.

Accepts the same flexible name format as register_temp_table.

pub fn temp_table_exist( &self, name: impl Into<TableReference>, ) -> DFResult<bool>

Returns whether a temporary table or view with the given name already exists.

Accepts the same flexible name format as register_temp_table.

pub async fn sql(&self, sql: &str) -> DFResult<DataFrame>

Execute a SQL statement. ALTER TABLE is handled by Paimon directly; everything else is delegated to DataFusion.

Trait Implementations

impl Default for SQLContext

fn default() -> Self

Returns the “default value” for a type.