Skip to content

refactor: move catalog traits to session crate#23703

Draft
timsaucer wants to merge 1 commit into
apache:mainfrom
timsaucer:refactor/catalog-contracts-session
Draft

refactor: move catalog traits to session crate#23703
timsaucer wants to merge 1 commit into
apache:mainfrom
timsaucer:refactor/catalog-contracts-session

Conversation

@timsaucer

Copy link
Copy Markdown
Member

Which issue does this PR close?

Rationale for this change

This will enable users to create table views using table function over an existing table in the catalog via FFI. We are currently unable to access the catalog other than by downcasting a Session to SessionState, which is not effective over FFI.

In order to support this, we need to move many trait definitions out of the datafusion-catalog crate and into the datafusion-session crate. There is more discussion in #23678 about why this is necessary.

What changes are included in this PR?

  • Move a variety of catalog traits into datafusion-session.
  • Add catalog() function to Session.
  • Implement catalog() in ForeignSession for FFI users

Are these changes tested?

New tests are included.

Are there any user-facing changes?

User guide is updated.

Move catalog, schema, table provider, and table function contracts into datafusion-session while preserving datafusion-catalog re-exports. Expose catalog access as a required Session capability, including across ForeignSession and the FFI boundary.

AI Disclosure: This code was written in part by an AI agent.
@timsaucer timsaucer added the api change Changes the API exposed to users of the crate label Jul 19, 2026
@github-actions github-actions Bot added core Core DataFusion crate catalog Related to the catalog crate datasource Changes to the datasource crate ffi Changes to the ffi crate labels Jul 19, 2026
@github-actions

Copy link
Copy Markdown

Thank you for opening this pull request!

Reviewer note: cargo-semver-checks reported the current version number is not SemVer-compatible with the changes in this pull request (compared against the base branch).

Details
     Cloning apache/main
    Building datafusion v54.0.0 (current)
       Built [  97.499s] (current)
     Parsing datafusion v54.0.0 (current)
      Parsed [   0.033s] (current)
    Building datafusion v54.0.0 (baseline)
       Built [  97.176s] (baseline)
     Parsing datafusion v54.0.0 (baseline)
      Parsed [   0.033s] (baseline)
    Checking datafusion v54.0.0 -> v54.0.0 (no change; assume patch)
     Checked [   0.885s] 223 checks: 223 pass, 30 skip
     Summary no semver update required
    Finished [ 198.516s] datafusion
    Building datafusion-catalog v54.0.0 (current)
       Built [  36.194s] (current)
     Parsing datafusion-catalog v54.0.0 (current)
      Parsed [   0.023s] (current)
    Building datafusion-catalog v54.0.0 (baseline)
       Built [  36.227s] (baseline)
     Parsing datafusion-catalog v54.0.0 (baseline)
      Parsed [   0.025s] (baseline)
    Checking datafusion-catalog v54.0.0 -> v54.0.0 (no change; assume patch)
     Checked [   0.168s] 223 checks: 221 pass, 2 fail, 0 warn, 30 skip

--- failure struct_missing: pub struct removed or renamed ---

Description:
A publicly-visible struct cannot be imported by its prior path. A `pub use` may have been removed, or the struct itself may have been renamed or removed entirely.
        ref: https://doc.rust-lang.org/cargo/reference/semver.html#item-remove
       impl: https://github.com/obi1kenobi/cargo-semver-checks/tree/v0.48.0/src/lints/struct_missing.ron

Failed in:
  struct datafusion_catalog::TableFunction, previously in file /home/runner/work/datafusion/datafusion/target/semver-checks/git-apache_main/69ad9c0d9a1eaf0d1e99353644bc42465f437ce8/datafusion/catalog/src/table.rs:600
  struct datafusion_catalog::ScanArgs, previously in file /home/runner/work/datafusion/datafusion/target/semver-checks/git-apache_main/69ad9c0d9a1eaf0d1e99353644bc42465f437ce8/datafusion/catalog/src/table.rs:406
  struct datafusion_catalog::TableFunctionArgs, previously in file /home/runner/work/datafusion/datafusion/target/semver-checks/git-apache_main/69ad9c0d9a1eaf0d1e99353644bc42465f437ce8/datafusion/catalog/src/table.rs:554
  struct datafusion_catalog::ScanResult, previously in file /home/runner/work/datafusion/datafusion/target/semver-checks/git-apache_main/69ad9c0d9a1eaf0d1e99353644bc42465f437ce8/datafusion/catalog/src/table.rs:502

--- failure trait_missing: pub trait removed or renamed ---

Description:
A publicly-visible trait cannot be imported by its prior path. A `pub use` may have been removed, or the trait itself may have been renamed or removed entirely.
        ref: https://doc.rust-lang.org/cargo/reference/semver.html#item-remove
       impl: https://github.com/obi1kenobi/cargo-semver-checks/tree/v0.48.0/src/lints/trait_missing.ron

Failed in:
  trait datafusion_catalog::CatalogProviderList, previously in file /home/runner/work/datafusion/datafusion/target/semver-checks/git-apache_main/69ad9c0d9a1eaf0d1e99353644bc42465f437ce8/datafusion/catalog/src/catalog.rs:175
  trait datafusion_catalog::TableProvider, previously in file /home/runner/work/datafusion/datafusion/target/semver-checks/git-apache_main/69ad9c0d9a1eaf0d1e99353644bc42465f437ce8/datafusion/catalog/src/table.rs:52
  trait datafusion_catalog::SchemaProvider, previously in file /home/runner/work/datafusion/datafusion/target/semver-checks/git-apache_main/69ad9c0d9a1eaf0d1e99353644bc42465f437ce8/datafusion/catalog/src/schema.rs:37
  trait datafusion_catalog::CatalogProvider, previously in file /home/runner/work/datafusion/datafusion/target/semver-checks/git-apache_main/69ad9c0d9a1eaf0d1e99353644bc42465f437ce8/datafusion/catalog/src/catalog.rs:108
  trait datafusion_catalog::TableFunctionImpl, previously in file /home/runner/work/datafusion/datafusion/target/semver-checks/git-apache_main/69ad9c0d9a1eaf0d1e99353644bc42465f437ce8/datafusion/catalog/src/table.rs:579
  trait datafusion_catalog::TableProviderFactory, previously in file /home/runner/work/datafusion/datafusion/target/semver-checks/git-apache_main/69ad9c0d9a1eaf0d1e99353644bc42465f437ce8/datafusion/catalog/src/table.rs:544

     Summary semver requires new major version: 2 major and 0 minor checks failed
    Finished [  74.060s] datafusion-catalog
    Building datafusion-datasource v54.0.0 (current)
       Built [  35.531s] (current)
     Parsing datafusion-datasource v54.0.0 (current)
      Parsed [   0.029s] (current)
    Building datafusion-datasource v54.0.0 (baseline)
       Built [  35.238s] (baseline)
     Parsing datafusion-datasource v54.0.0 (baseline)
      Parsed [   0.031s] (baseline)
    Checking datafusion-datasource v54.0.0 -> v54.0.0 (no change; assume patch)
     Checked [   0.336s] 223 checks: 223 pass, 30 skip
     Summary no semver update required
    Finished [  72.641s] datafusion-datasource
    Building datafusion-datasource-arrow v54.0.0 (current)
       Built [  36.143s] (current)
     Parsing datafusion-datasource-arrow v54.0.0 (current)
      Parsed [   0.011s] (current)
    Building datafusion-datasource-arrow v54.0.0 (baseline)
       Built [  35.264s] (baseline)
     Parsing datafusion-datasource-arrow v54.0.0 (baseline)
      Parsed [   0.012s] (baseline)
    Checking datafusion-datasource-arrow v54.0.0 -> v54.0.0 (no change; assume patch)
     Checked [   0.091s] 223 checks: 223 pass, 30 skip
     Summary no semver update required
    Finished [  72.878s] datafusion-datasource-arrow
    Building datafusion-ffi v54.0.0 (current)
       Built [  55.313s] (current)
     Parsing datafusion-ffi v54.0.0 (current)
      Parsed [   0.057s] (current)
    Building datafusion-ffi v54.0.0 (baseline)
       Built [  54.221s] (baseline)
     Parsing datafusion-ffi v54.0.0 (baseline)
      Parsed [   0.057s] (baseline)
    Checking datafusion-ffi v54.0.0 -> v54.0.0 (no change; assume patch)
     Checked [   0.331s] 223 checks: 223 pass, 30 skip
     Summary no semver update required
    Finished [ 112.040s] datafusion-ffi
    Building datafusion-session v54.0.0 (current)
       Built [  33.646s] (current)
     Parsing datafusion-session v54.0.0 (current)
      Parsed [   0.011s] (current)
    Building datafusion-session v54.0.0 (baseline)
       Built [  33.000s] (baseline)
     Parsing datafusion-session v54.0.0 (baseline)
      Parsed [   0.009s] (baseline)
    Checking datafusion-session v54.0.0 -> v54.0.0 (no change; assume patch)
     Checked [   0.118s] 223 checks: 222 pass, 1 fail, 0 warn, 30 skip

--- failure trait_method_added: pub trait method added ---

Description:
A non-sealed public trait added a new method without a default implementation, which breaks downstream implementations of the trait
        ref: https://doc.rust-lang.org/cargo/reference/semver.html#trait-new-item-no-default
       impl: https://github.com/obi1kenobi/cargo-semver-checks/tree/v0.48.0/src/lints/trait_method_added.ron

Failed in:
  trait method datafusion_session::session::Session::catalog_list in file /home/runner/work/datafusion/datafusion/datafusion/session/src/session.rs:85
  trait method datafusion_session::Session::catalog_list in file /home/runner/work/datafusion/datafusion/datafusion/session/src/session.rs:85

     Summary semver requires new major version: 1 major and 0 minor checks failed
    Finished [  68.326s] datafusion-session

@github-actions github-actions Bot added the auto detected api change Auto detected API change label Jul 19, 2026
@codecov-commenter

Copy link
Copy Markdown

Codecov Report

❌ Patch coverage is 73.66071% with 59 lines in your changes missing coverage. Please review.
✅ Project coverage is 80.67%. Comparing base (67947b6) to head (968fbc4).

Files with missing lines Patch % Lines
datafusion/session/src/catalog.rs 56.52% 20 Missing ⚠️
datafusion/session/src/table.rs 85.47% 17 Missing ⚠️
datafusion/session/src/schema.rs 40.90% 13 Missing ⚠️
...usion/core/src/datasource/listing_table_factory.rs 0.00% 3 Missing ⚠️
datafusion/datasource-arrow/src/file_format.rs 0.00% 3 Missing ⚠️
datafusion/datasource/src/url.rs 0.00% 3 Missing ⚠️
Additional details and impacted files
@@            Coverage Diff             @@
##             main   #23703      +/-   ##
==========================================
- Coverage   80.67%   80.67%   -0.01%     
==========================================
  Files        1088     1088              
  Lines      367591   367648      +57     
  Branches   367591   367648      +57     
==========================================
+ Hits       296563   296592      +29     
- Misses      53374    53397      +23     
- Partials    17654    17659       +5     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

Comment on lines +84 to +85
/// Return the catalogs registered with this session.
fn catalog_list(&self) -> Arc<dyn CatalogProviderList>;

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This new function on the Session trait is the main point of this PR. The other code is moved around to support the dependency requirements.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

api change Changes the API exposed to users of the crate auto detected api change Auto detected API change catalog Related to the catalog crate core Core DataFusion crate datasource Changes to the datasource crate ffi Changes to the ffi crate

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants