From f277db72f7dced98c459941420113baa621e6a76 Mon Sep 17 00:00:00 2001
From: Adam Gutglick <adam@spiraldb.com>
Date: Wed, 24 Jun 2026 13:10:15 +0100
Subject: [PATCH 1/4] Support settings via env

Signed-off-by: Adam Gutglick <adam@spiraldb.com>
---
 vortex-datafusion/src/persistent/format.rs    | 93 ++++++++++++++++++-
 .../bin/sqllogictests-runner.rs               |  1 +
 .../slt/datafusion/pushdown_config.slt        | 48 ++++++++++
 3 files changed, 137 insertions(+), 5 deletions(-)
 create mode 100644 vortex-sqllogictest/slt/datafusion/pushdown_config.slt

diff --git a/vortex-datafusion/src/persistent/format.rs b/vortex-datafusion/src/persistent/format.rs
index a0d49e6105a..a293570520b 100644
--- a/vortex-datafusion/src/persistent/format.rs
+++ b/vortex-datafusion/src/persistent/format.rs
@@ -15,7 +15,11 @@ use datafusion_common::GetExt;
 use datafusion_common::Result as DFResult;
 use datafusion_common::ScalarValue as DFScalarValue;
 use datafusion_common::Statistics;
+use datafusion_common::config::ConfigEntry;
+use datafusion_common::config::ConfigExtension;
 use datafusion_common::config::ConfigField;
+use datafusion_common::config::ExtensionOptions;
+use datafusion_common::config::Visit;
 use datafusion_common::config_namespace;
 use datafusion_common::internal_datafusion_err;
 use datafusion_common::not_impl_err;
@@ -165,12 +169,18 @@ config_namespace! {
         /// When enabled, projection expressions may be partially evaluated during
         /// the scan. When disabled, Vortex reads only the referenced columns and
         /// all expressions are evaluated after the scan.
-        pub projection_pushdown: bool, default = false
+        ///
+        /// Enabled by default. Override per session with
+        /// `SET vortex.projection_pushdown = false`.
+        pub projection_pushdown: bool, default = true
         /// Whether to enable predicate pushdown into the underlying Vortex scan.
         ///
         /// When enabled, supported filters are evaluated during the scan. When
         /// disabled, DataFusion evaluates filters after the scan, while
         /// `VortexSource` can still use the full predicate for file pruning.
+        ///
+        /// Enabled by default. Override per session with
+        /// `SET vortex.predicate_pushdown = false`.
         pub predicate_pushdown: bool, default = true
         /// The intra-partition scan concurrency, controlling the number of row splits to process
         /// concurrently per-thread within each file.
@@ -183,6 +193,66 @@ config_namespace! {
 
 impl Eq for VortexTableOptions {}
 
+/// Exposes [`VortexTableOptions`] as a DataFusion session config extension under
+/// the `vortex` prefix, so options can be set with e.g.
+/// `SET vortex.projection_pushdown = false` and reset with
+/// `SET vortex.projection_pushdown = true`.
+///
+/// [`VortexFormat`] reads these from the session unless the table provides its
+/// own `OPTIONS(...)` or the [`VortexFormatFactory`] was given explicit options.
+impl ExtensionOptions for VortexTableOptions {
+    fn as_any(&self) -> &dyn std::any::Any {
+        self
+    }
+
+    fn as_any_mut(&mut self) -> &mut dyn std::any::Any {
+        self
+    }
+
+    fn cloned(&self) -> Box<dyn ExtensionOptions> {
+        Box::new(self.clone())
+    }
+
+    fn set(&mut self, key: &str, value: &str) -> DFResult<()> {
+        ConfigField::set(self, key, value)
+    }
+
+    fn entries(&self) -> Vec<ConfigEntry> {
+        struct Visitor(Vec<ConfigEntry>);
+
+        impl Visit for Visitor {
+            fn some<V: std::fmt::Display>(
+                &mut self,
+                key: &str,
+                value: V,
+                description: &'static str,
+            ) {
+                self.0.push(ConfigEntry {
+                    key: key.to_string(),
+                    value: Some(value.to_string()),
+                    description,
+                });
+            }
+
+            fn none(&mut self, key: &str, description: &'static str) {
+                self.0.push(ConfigEntry {
+                    key: key.to_string(),
+                    value: None,
+                    description,
+                });
+            }
+        }
+
+        let mut v = Visitor(vec![]);
+        ConfigField::visit(self, &mut v, "", "");
+        v.0
+    }
+}
+
+impl ConfigExtension for VortexTableOptions {
+    const PREFIX: &'static str = "vortex";
+}
+
 /// Registration entry point for the file-backed Vortex integration.
 ///
 /// `VortexFormatFactory` is the type most applications use. Register it with a
@@ -286,13 +356,26 @@ impl FileFormatFactory for VortexFormatFactory {
     #[expect(clippy::disallowed_types, reason = "required by trait signature")]
     fn create(
         &self,
-        _state: &dyn Session,
+        state: &dyn Session,
         format_options: &std::collections::HashMap<String, String>,
     ) -> DFResult<Arc<dyn FileFormat>> {
-        let mut opts = self.options.clone().unwrap_or_default();
+        // Precedence: explicit factory options, else the session's `vortex` config
+        // extension (allowing `SET vortex.* = ...`), else the built-in defaults.
+        // Table-level `OPTIONS(...)` are then layered on top.
+        let mut opts = self
+            .options
+            .clone()
+            .or_else(|| {
+                state
+                    .config_options()
+                    .extensions
+                    .get::<VortexTableOptions>()
+                    .cloned()
+            })
+            .unwrap_or_default();
         for (key, value) in format_options {
             if let Some(key) = key.strip_prefix("format.") {
-                opts.set(key, value)?;
+                ConfigField::set(&mut opts, key, value)?;
             } else {
                 tracing::trace!("Ignoring option '{key}'");
             }
@@ -698,7 +781,7 @@ mod tests {
     #[test]
     fn format_plumbs_footer_initial_read_size() {
         let mut opts = VortexTableOptions::default();
-        opts.set("footer_initial_read_size_bytes", "12345").unwrap();
+        ConfigField::set(&mut opts, "footer_initial_read_size_bytes", "12345").unwrap();
 
         let format = VortexFormat::new_with_options(VortexSession::default(), opts);
         assert_eq!(format.options().footer_initial_read_size_bytes, 12345);
diff --git a/vortex-sqllogictest/bin/sqllogictests-runner.rs b/vortex-sqllogictest/bin/sqllogictests-runner.rs
index 3ff6febe227..45e5091e5ad 100644
--- a/vortex-sqllogictest/bin/sqllogictests-runner.rs
+++ b/vortex-sqllogictest/bin/sqllogictests-runner.rs
@@ -10,6 +10,7 @@ use std::sync::LazyLock;
 use datafusion::common::GetExt;
 use datafusion::datasource::provider::DefaultTableFactory;
 use datafusion::execution::SessionStateBuilder;
+use datafusion::prelude::SessionConfig;
 use datafusion::prelude::SessionContext;
 use datafusion_sqllogictest::DataFusion;
 use datafusion_sqllogictest::df_value_validator;
diff --git a/vortex-sqllogictest/slt/datafusion/pushdown_config.slt b/vortex-sqllogictest/slt/datafusion/pushdown_config.slt
new file mode 100644
index 00000000000..639871653d5
--- /dev/null
+++ b/vortex-sqllogictest/slt/datafusion/pushdown_config.slt
@@ -0,0 +1,48 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright the Vortex contributors
+
+# Projection and predicate pushdown are enabled by default for Vortex scans and
+# can be toggled per session via `SET vortex.<flag> = ...`, then reset. Results
+# must be identical regardless of the setting.
+
+include ../setup.slt.no
+
+query I
+COPY (SELECT * FROM (VALUES (1, 10), (2, 20), (3, 30)) AS t(a, b)) TO '${WORK_DIR}/pushdown.vortex';
+----
+3
+
+# Disable projection pushdown; a projection expression still computes correctly.
+statement ok
+SET vortex.projection_pushdown = false;
+
+query I
+SELECT a + b AS s FROM '${WORK_DIR}/pushdown.vortex' ORDER BY s;
+----
+11
+22
+33
+
+# Reset projection pushdown.
+statement ok
+SET vortex.projection_pushdown = true;
+
+# Disable predicate pushdown; a filter still computes correctly.
+statement ok
+SET vortex.predicate_pushdown = false;
+
+query I
+SELECT b FROM '${WORK_DIR}/pushdown.vortex' WHERE a > 1 ORDER BY b;
+----
+20
+30
+
+# Reset predicate pushdown.
+statement ok
+SET vortex.predicate_pushdown = true;
+
+query I
+SELECT b FROM '${WORK_DIR}/pushdown.vortex' WHERE a > 1 ORDER BY b;
+----
+20
+30

From df36fd4c8b9ee222be840108a7dcdd101f0cccc1 Mon Sep 17 00:00:00 2001
From: Adam Gutglick <adam@spiraldb.com>
Date: Wed, 24 Jun 2026 15:45:30 +0100
Subject: [PATCH 2/4] .

Signed-off-by: Adam Gutglick <adam@spiraldb.com>
---
 vortex-datafusion/src/persistent/format.rs    | 71 ++-----------------
 .../bin/sqllogictests-runner.rs               |  3 +
 2 files changed, 10 insertions(+), 64 deletions(-)

diff --git a/vortex-datafusion/src/persistent/format.rs b/vortex-datafusion/src/persistent/format.rs
index a293570520b..daf7c652eb3 100644
--- a/vortex-datafusion/src/persistent/format.rs
+++ b/vortex-datafusion/src/persistent/format.rs
@@ -15,12 +15,9 @@ use datafusion_common::GetExt;
 use datafusion_common::Result as DFResult;
 use datafusion_common::ScalarValue as DFScalarValue;
 use datafusion_common::Statistics;
-use datafusion_common::config::ConfigEntry;
 use datafusion_common::config::ConfigExtension;
 use datafusion_common::config::ConfigField;
-use datafusion_common::config::ExtensionOptions;
-use datafusion_common::config::Visit;
-use datafusion_common::config_namespace;
+use datafusion_common::extensions_options;
 use datafusion_common::internal_datafusion_err;
 use datafusion_common::not_impl_err;
 use datafusion_common::parsers::CompressionTypeVariant;
@@ -136,7 +133,11 @@ impl Debug for VortexFormat {
     }
 }
 
-config_namespace! {
+// Exposes [`VortexTableOptions`] as a DataFusion session config extension under
+// the `vortex` prefix, so options can be set with e.g.
+// `SET vortex.projection_pushdown = false` and reset with
+// `SET vortex.projection_pushdown = true`.
+extensions_options! {
     /// Options to configure [`VortexFormat`] and [`VortexSource`].
     ///
     /// These options are usually set on a [`VortexFormatFactory`] and inherited
@@ -191,64 +192,6 @@ config_namespace! {
     }
 }
 
-impl Eq for VortexTableOptions {}
-
-/// Exposes [`VortexTableOptions`] as a DataFusion session config extension under
-/// the `vortex` prefix, so options can be set with e.g.
-/// `SET vortex.projection_pushdown = false` and reset with
-/// `SET vortex.projection_pushdown = true`.
-///
-/// [`VortexFormat`] reads these from the session unless the table provides its
-/// own `OPTIONS(...)` or the [`VortexFormatFactory`] was given explicit options.
-impl ExtensionOptions for VortexTableOptions {
-    fn as_any(&self) -> &dyn std::any::Any {
-        self
-    }
-
-    fn as_any_mut(&mut self) -> &mut dyn std::any::Any {
-        self
-    }
-
-    fn cloned(&self) -> Box<dyn ExtensionOptions> {
-        Box::new(self.clone())
-    }
-
-    fn set(&mut self, key: &str, value: &str) -> DFResult<()> {
-        ConfigField::set(self, key, value)
-    }
-
-    fn entries(&self) -> Vec<ConfigEntry> {
-        struct Visitor(Vec<ConfigEntry>);
-
-        impl Visit for Visitor {
-            fn some<V: std::fmt::Display>(
-                &mut self,
-                key: &str,
-                value: V,
-                description: &'static str,
-            ) {
-                self.0.push(ConfigEntry {
-                    key: key.to_string(),
-                    value: Some(value.to_string()),
-                    description,
-                });
-            }
-
-            fn none(&mut self, key: &str, description: &'static str) {
-                self.0.push(ConfigEntry {
-                    key: key.to_string(),
-                    value: None,
-                    description,
-                });
-            }
-        }
-
-        let mut v = Visitor(vec![]);
-        ConfigField::visit(self, &mut v, "", "");
-        v.0
-    }
-}
-
 impl ConfigExtension for VortexTableOptions {
     const PREFIX: &'static str = "vortex";
 }
@@ -803,7 +746,7 @@ mod tests {
             .downcast_ref::<VortexSource>()
             .ok_or_else(|| anyhow::anyhow!("expected VortexSource"))?;
 
-        assert_eq!(source.options(), &opts);
+        // assert_eq!(source.options(), &opts);
         Ok(())
     }
 }
diff --git a/vortex-sqllogictest/bin/sqllogictests-runner.rs b/vortex-sqllogictest/bin/sqllogictests-runner.rs
index 45e5091e5ad..8f99ff4ec49 100644
--- a/vortex-sqllogictest/bin/sqllogictests-runner.rs
+++ b/vortex-sqllogictest/bin/sqllogictests-runner.rs
@@ -22,6 +22,7 @@ use sqllogictest::harness::Failed;
 use sqllogictest::harness::Trial;
 use sqllogictest::strict_column_validator;
 use vortex_datafusion::VortexFormatFactory;
+use vortex_datafusion::VortexTableOptions;
 use vortex_sqllogictest::duckdb::DuckDB;
 use vortex_sqllogictest::duckdb::duckdb_validator;
 use vortex_sqllogictest::normalize::PathNormalizing;
@@ -62,8 +63,10 @@ fn drive_datafusion(path: &Path, work_dir: &Path, mode: Mode) -> anyhow::Result<
 
     let rt = build_runtime()?;
     rt.block_on(async {
+        let config = SessionConfig::default().with_option_extension(VortexTableOptions::default());
         let factory = Arc::new(VortexFormatFactory::new());
         let session_state_builder = SessionStateBuilder::new()
+            .with_config(config)
             .with_default_features()
             .with_table_factory(
                 factory.get_ext().to_uppercase(),

From 05fa753c6a56b91171b0085f5b2313eead0fe7cb Mon Sep 17 00:00:00 2001
From: Adam Gutglick <adam@spiraldb.com>
Date: Wed, 24 Jun 2026 16:04:43 +0100
Subject: [PATCH 3/4] fix

Signed-off-by: Adam Gutglick <adam@spiraldb.com>
---
 vortex-datafusion/src/persistent/format.rs    | 134 ++++++++++++------
 .../slt/datafusion/pushdown_config.slt        |  48 -------
 .../slt/datafusion/table_options.slt          |  76 ++++++++++
 3 files changed, 168 insertions(+), 90 deletions(-)
 delete mode 100644 vortex-sqllogictest/slt/datafusion/pushdown_config.slt
 create mode 100644 vortex-sqllogictest/slt/datafusion/table_options.slt

diff --git a/vortex-datafusion/src/persistent/format.rs b/vortex-datafusion/src/persistent/format.rs
index daf7c652eb3..252751ab2e1 100644
--- a/vortex-datafusion/src/persistent/format.rs
+++ b/vortex-datafusion/src/persistent/format.rs
@@ -133,32 +133,62 @@ impl Debug for VortexFormat {
     }
 }
 
-// Exposes [`VortexTableOptions`] as a DataFusion session config extension under
-// the `vortex` prefix, so options can be set with e.g.
-// `SET vortex.projection_pushdown = false` and reset with
-// `SET vortex.projection_pushdown = true`.
 extensions_options! {
     /// Options to configure [`VortexFormat`] and [`VortexSource`].
     ///
-    /// These options are usually set on a [`VortexFormatFactory`] and inherited
-    /// by the `VortexFormat` / `VortexSource` instances created for individual
-    /// tables.
+    /// The API follows DataFusion's built-in Parquet and JSON format factories:
+    /// a format factory may carry customized defaults, the session may carry
+    /// format defaults, and `CREATE EXTERNAL TABLE ... OPTIONS(...)` can
+    /// override individual fields for one table.
+    ///
+    /// [`FileFormatFactory::create`] builds the `VortexTableOptions` copied into
+    /// each [`VortexFormat`] as follows:
+    ///
+    /// 1. If the factory has explicit options from
+    ///    [`VortexFormatFactory::with_options`] or
+    ///    [`VortexFormatFactory::new_with_options`], start from that complete
+    ///    `VortexTableOptions` value. This matches
+    ///    [`ParquetFormatFactory::new_with_options`] and
+    ///    [`JsonFormatFactory::new_with_options`]: factory options replace
+    ///    session defaults; they are not merged with them field-by-field.
+    /// 2. If the factory does not have explicit options, read the session's
+    ///    `vortex` extension at the time `create` is called. This is the value
+    ///    changed by `SET vortex.<option> = ...`.
+    /// 3. If the session has no `vortex` extension, start from
+    ///    `VortexTableOptions::default()`.
+    /// 4. Apply table `OPTIONS(...)` last. Each option overwrites only its
+    ///    matching field, so per-table settings can override either the factory
+    ///    options or the session/default value.
+    ///
+    /// In SQL, session settings use the `vortex.` prefix. Table options use the
+    /// field names directly, the same style as Parquet or JSON table options:
+    ///
+    /// ```text
+    /// SET vortex.predicate_pushdown = false;
+    ///
+    /// CREATE EXTERNAL TABLE t (x BIGINT)
+    /// STORED AS vortex
+    /// LOCATION 's3://bucket/path/'
+    /// OPTIONS(predicate_pushdown 'true');
+    /// ```
     ///
     /// # Example
     ///
     /// ```rust
     /// use vortex_datafusion::{VortexFormatFactory, VortexTableOptions};
     ///
-    /// let factory = VortexFormatFactory::new().with_options(VortexTableOptions {
-    ///     projection_pushdown: true,
-    ///     predicate_pushdown: true,
-    ///     scan_concurrency: Some(8),
-    ///     ..Default::default()
-    /// });
+    /// let mut options = VortexTableOptions::default();
+    /// options.predicate_pushdown = true;
+    /// options.projection_pushdown = true;
+    /// options.scan_concurrency = Some(8);
+    ///
+    /// let factory = VortexFormatFactory::new().with_options(options);
     /// # let _ = factory;
     /// ```
     ///
     /// [`SessionConfig`]: https://docs.rs/datafusion/latest/datafusion/prelude/struct.SessionConfig.html
+    /// [`ParquetFormatFactory::new_with_options`]: https://docs.rs/datafusion/latest/datafusion/datasource/file_format/parquet/struct.ParquetFormatFactory.html#method.new_with_options
+    /// [`JsonFormatFactory::new_with_options`]: https://docs.rs/datafusion/latest/datafusion/datasource/file_format/json/struct.JsonFormatFactory.html#method.new_with_options
     pub struct VortexTableOptions {
         /// The number of bytes to read when parsing a file footer.
         ///
@@ -171,23 +201,25 @@ extensions_options! {
         /// the scan. When disabled, Vortex reads only the referenced columns and
         /// all expressions are evaluated after the scan.
         ///
-        /// Enabled by default. Override per session with
-        /// `SET vortex.projection_pushdown = false`.
-        pub projection_pushdown: bool, default = true
+        /// Disabled by default.
+        pub projection_pushdown: bool, default = false
         /// Whether to enable predicate pushdown into the underlying Vortex scan.
         ///
         /// When enabled, supported filters are evaluated during the scan. When
         /// disabled, DataFusion evaluates filters after the scan, while
         /// `VortexSource` can still use the full predicate for file pruning.
         ///
-        /// Enabled by default. Override per session with
-        /// `SET vortex.predicate_pushdown = false`.
+        /// Enabled by default.
         pub predicate_pushdown: bool, default = true
         /// The intra-partition scan concurrency, controlling the number of row splits to process
         /// concurrently per-thread within each file.
         ///
         /// This does not affect the overall parallelism
         /// across partitions, which is controlled by DataFusion's execution configuration.
+        ///
+        /// Leave as `None` to use Vortex's scan default. Override per session
+        /// with `SET vortex.scan_concurrency = <n>`, or per table with
+        /// `OPTIONS(scan_concurrency '<n>')`.
         pub scan_concurrency: Option<usize>, default = None
     }
 }
@@ -202,9 +234,12 @@ impl ConfigExtension for VortexTableOptions {
 /// DataFusion session, and DataFusion will create [`VortexFormat`] values for
 /// `CREATE EXTERNAL TABLE`, [`ListingTable`], and URL-table scans.
 ///
-/// The factory stores a [`VortexSession`] and default [`VortexTableOptions`].
-/// Those defaults are copied into the formats and sources created for each
-/// table.
+/// The factory stores a [`VortexSession`] and optional factory-level
+/// [`VortexTableOptions`]. When options are set on the factory they act like
+/// customized format defaults, matching DataFusion's Parquet and JSON factory
+/// APIs. Otherwise, `VortexFormatFactory::create` uses the session's `vortex`
+/// options. In both cases, table `OPTIONS(...)` are applied last for the table
+/// being created.
 ///
 /// # Example
 ///
@@ -216,11 +251,11 @@ impl ConfigExtension for VortexTableOptions {
 /// use datafusion_common::GetExt;
 /// use vortex_datafusion::{VortexFormatFactory, VortexTableOptions};
 ///
-/// let factory = Arc::new(VortexFormatFactory::new().with_options(VortexTableOptions {
-///     projection_pushdown: true,
-///     predicate_pushdown: true,
-///     ..Default::default()
-/// }));
+/// let mut options = VortexTableOptions::default();
+/// options.predicate_pushdown = true;
+/// options.projection_pushdown = true;
+///
+/// let factory = Arc::new(VortexFormatFactory::new().with_options(options));
 ///
 /// let mut state_builder = SessionStateBuilder::new()
 ///     .with_default_features()
@@ -248,7 +283,12 @@ impl GetExt for VortexFormatFactory {
 }
 
 impl VortexFormatFactory {
-    /// Creates a factory with a default [`VortexSession`] and default options.
+    /// Creates a factory with a default [`VortexSession`] and no factory-level
+    /// options.
+    ///
+    /// Formats created by this factory start from the session's `vortex`
+    /// options, or from [`VortexTableOptions::default`] if the session does not
+    /// contain them. Table-level `OPTIONS(...)` are still applied last.
     #[expect(
         clippy::new_without_default,
         reason = "FormatFactory defines `default` method, so having `Default` implementation is confusing"
@@ -260,11 +300,13 @@ impl VortexFormatFactory {
         }
     }
 
-    /// Creates a factory with an explicit session and default options.
+    /// Creates a factory with an explicit session and factory-level options.
     ///
-    /// The supplied options become the baseline for every [`VortexFormat`]
-    /// created by this factory. DataFusion may still override them with
-    /// table-level options passed into [`FileFormatFactory::create`].
+    /// The supplied options become the complete starting value for every
+    /// [`VortexFormat`] created by this factory. Session `SET vortex.*` values
+    /// are ignored for these formats, matching DataFusion's built-in
+    /// `new_with_options` factories. Table-level `OPTIONS(...)` are still
+    /// applied last.
     pub fn new_with_options(session: VortexSession, options: VortexTableOptions) -> Self {
         Self {
             session,
@@ -272,21 +314,23 @@ impl VortexFormatFactory {
         }
     }
 
-    /// Overrides the default options for this factory.
+    /// Sets factory-level options.
     ///
-    /// This is the usual way to turn on features such as projection pushdown for
-    /// every table created through the factory.
+    /// This is the usual way to customize Vortex defaults for every table
+    /// created through the factory. These options replace, rather than merge
+    /// with, session `SET vortex.*` values. Table-level `OPTIONS(...)` are still
+    /// applied last.
     ///
     /// # Example
     ///
     /// ```rust
     /// use vortex_datafusion::{VortexFormatFactory, VortexTableOptions};
     ///
-    /// let factory = VortexFormatFactory::new().with_options(VortexTableOptions {
-    ///     projection_pushdown: true,
-    ///     predicate_pushdown: true,
-    ///     ..Default::default()
-    /// });
+    /// let mut options = VortexTableOptions::default();
+    /// options.predicate_pushdown = true;
+    /// options.projection_pushdown = true;
+    ///
+    /// let factory = VortexFormatFactory::new().with_options(options);
     /// # let _ = factory;
     /// ```
     pub fn with_options(mut self, options: VortexTableOptions) -> Self {
@@ -302,9 +346,15 @@ impl FileFormatFactory for VortexFormatFactory {
         state: &dyn Session,
         format_options: &std::collections::HashMap<String, String>,
     ) -> DFResult<Arc<dyn FileFormat>> {
-        // Precedence: explicit factory options, else the session's `vortex` config
-        // extension (allowing `SET vortex.* = ...`), else the built-in defaults.
-        // Table-level `OPTIONS(...)` are then layered on top.
+        // This mirrors DataFusion's Parquet/JSON file-format factories:
+        //
+        // 1. Factory options are a complete customized default when present.
+        // 2. Without factory options, use the session's `vortex` extension
+        //    (`SET vortex.* = ...`), falling back to built-in defaults.
+        // 3. Table-level `CREATE EXTERNAL TABLE ... OPTIONS(...)` values apply
+        //    last. DataFusion prefixes file-format options with `format.`
+        //    before passing them to this factory; SQL users write the field
+        //    name directly, e.g. `OPTIONS(predicate_pushdown 'false')`.
         let mut opts = self
             .options
             .clone()
diff --git a/vortex-sqllogictest/slt/datafusion/pushdown_config.slt b/vortex-sqllogictest/slt/datafusion/pushdown_config.slt
deleted file mode 100644
index 639871653d5..00000000000
--- a/vortex-sqllogictest/slt/datafusion/pushdown_config.slt
+++ /dev/null
@@ -1,48 +0,0 @@
-# SPDX-License-Identifier: Apache-2.0
-# SPDX-FileCopyrightText: Copyright the Vortex contributors
-
-# Projection and predicate pushdown are enabled by default for Vortex scans and
-# can be toggled per session via `SET vortex.<flag> = ...`, then reset. Results
-# must be identical regardless of the setting.
-
-include ../setup.slt.no
-
-query I
-COPY (SELECT * FROM (VALUES (1, 10), (2, 20), (3, 30)) AS t(a, b)) TO '${WORK_DIR}/pushdown.vortex';
-----
-3
-
-# Disable projection pushdown; a projection expression still computes correctly.
-statement ok
-SET vortex.projection_pushdown = false;
-
-query I
-SELECT a + b AS s FROM '${WORK_DIR}/pushdown.vortex' ORDER BY s;
-----
-11
-22
-33
-
-# Reset projection pushdown.
-statement ok
-SET vortex.projection_pushdown = true;
-
-# Disable predicate pushdown; a filter still computes correctly.
-statement ok
-SET vortex.predicate_pushdown = false;
-
-query I
-SELECT b FROM '${WORK_DIR}/pushdown.vortex' WHERE a > 1 ORDER BY b;
-----
-20
-30
-
-# Reset predicate pushdown.
-statement ok
-SET vortex.predicate_pushdown = true;
-
-query I
-SELECT b FROM '${WORK_DIR}/pushdown.vortex' WHERE a > 1 ORDER BY b;
-----
-20
-30
diff --git a/vortex-sqllogictest/slt/datafusion/table_options.slt b/vortex-sqllogictest/slt/datafusion/table_options.slt
new file mode 100644
index 00000000000..b2a60ff3ea7
--- /dev/null
+++ b/vortex-sqllogictest/slt/datafusion/table_options.slt
@@ -0,0 +1,76 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright the Vortex contributors
+
+# Example-style coverage for DataFusion Vortex table options.
+#
+# Session settings provide the baseline for tables created through
+# VortexFormatFactory::create. Per-table OPTIONS override that baseline for the
+# table being created.
+
+include ../setup.slt.no
+
+statement ok
+SET vortex.predicate_pushdown = false;
+
+statement ok
+CREATE EXTERNAL TABLE session_disabled_pushdown (
+    x BIGINT NOT NULL,
+    y BIGINT NOT NULL
+)
+STORED AS vortex
+LOCATION '${WORK_DIR}/session_disabled_pushdown/';
+
+statement ok
+INSERT INTO session_disabled_pushdown VALUES
+    (1, 10),
+    (2, 20),
+    (3, 30);
+
+query TT
+EXPLAIN SELECT y FROM session_disabled_pushdown WHERE x > 1 ORDER BY y;
+----
+logical_plan
+01)Sort: session_disabled_pushdown.y ASC NULLS LAST
+02)--Projection: session_disabled_pushdown.y
+03)----Filter: session_disabled_pushdown.x > Int64(1)
+04)------TableScan: session_disabled_pushdown projection=[x, y], partial_filters=[session_disabled_pushdown.x > Int64(1)]
+physical_plan
+01)SortExec: expr=[y@0 ASC NULLS LAST], preserve_partitioning=[false]
+02)--FilterExec: x@0 > 1, projection=[y@1]
+03)----DataSourceExec: file_groups={<slt:ignore>}, projection=[x, y], file_type=vortex
+
+statement ok
+CREATE EXTERNAL TABLE table_enabled_pushdown (
+    x BIGINT NOT NULL,
+    y BIGINT NOT NULL
+)
+STORED AS vortex
+LOCATION '${WORK_DIR}/table_enabled_pushdown/'
+OPTIONS(predicate_pushdown 'true');
+
+statement ok
+INSERT INTO table_enabled_pushdown VALUES
+    (1, 10),
+    (2, 20),
+    (3, 30);
+
+query TT
+EXPLAIN SELECT y FROM table_enabled_pushdown WHERE x > 1 ORDER BY y;
+----
+logical_plan
+01)Sort: table_enabled_pushdown.y ASC NULLS LAST
+02)--Projection: table_enabled_pushdown.y
+03)----Filter: table_enabled_pushdown.x > Int64(1)
+04)------TableScan: table_enabled_pushdown projection=[x, y], partial_filters=[table_enabled_pushdown.x > Int64(1)]
+physical_plan
+01)SortExec: expr=[y@0 ASC NULLS LAST], preserve_partitioning=[false]
+02)--DataSourceExec: file_groups={<slt:ignore>}, projection=[y], file_type=vortex, predicate: x@0 > 1
+
+query I
+SELECT y FROM table_enabled_pushdown WHERE x > 1 ORDER BY y;
+----
+20
+30
+
+statement ok
+SET vortex.predicate_pushdown = true;

From 2ab0b5739a097b9cf04d945121a3e47cad98ca1c Mon Sep 17 00:00:00 2001
From: Adam Gutglick <adam@spiraldb.com>
Date: Wed, 24 Jun 2026 16:29:07 +0100
Subject: [PATCH 4/4] clippy fix

Signed-off-by: Adam Gutglick <adam@spiraldb.com>
---
 benchmarks/datafusion-bench/src/lib.rs     | 11 ++++++-----
 vortex-datafusion/src/persistent/format.rs |  7 ++++++-
 2 files changed, 12 insertions(+), 6 deletions(-)

diff --git a/benchmarks/datafusion-bench/src/lib.rs b/benchmarks/datafusion-bench/src/lib.rs
index fdda58188e7..1100d38d24e 100644
--- a/benchmarks/datafusion-bench/src/lib.rs
+++ b/benchmarks/datafusion-bench/src/lib.rs
@@ -122,9 +122,10 @@ pub fn format_to_df_format(format: Format) -> Arc<dyn FileFormat> {
 }
 
 fn vortex_table_options() -> VortexTableOptions {
-    VortexTableOptions {
-        projection_pushdown: true,
-        predicate_pushdown: true,
-        ..Default::default()
-    }
+    let mut opts = VortexTableOptions::default();
+
+    opts.predicate_pushdown = true;
+    opts.predicate_pushdown = true;
+
+    opts
 }
diff --git a/vortex-datafusion/src/persistent/format.rs b/vortex-datafusion/src/persistent/format.rs
index 252751ab2e1..c139fe2767f 100644
--- a/vortex-datafusion/src/persistent/format.rs
+++ b/vortex-datafusion/src/persistent/format.rs
@@ -796,7 +796,12 @@ mod tests {
             .downcast_ref::<VortexSource>()
             .ok_or_else(|| anyhow::anyhow!("expected VortexSource"))?;
 
-        // assert_eq!(source.options(), &opts);
+        assert_eq!(
+            source.options().projection_pushdown,
+            opts.projection_pushdown
+        );
+        assert_eq!(source.options().predicate_pushdown, opts.predicate_pushdown);
+        assert_eq!(source.options().scan_concurrency, opts.scan_concurrency);
         Ok(())
     }
 }