feat: expose scanner execution tuning options

include/lance/lance.h

@@ -934,6 +934,74 @@ LanceScanner* lance_scanner_new(
 int32_t lance_scanner_set_limit(LanceScanner* scanner, int64_t limit);
 int32_t lance_scanner_set_offset(LanceScanner* scanner, int64_t offset);
 int32_t lance_scanner_set_batch_size(LanceScanner* scanner, int64_t batch_size);
+
+/**
+ * Set the target output batch size in bytes.
+ *
+ * When set, this takes precedence over the row-based batch size. The value
+ * must be greater than zero and must be set before scanning starts.
+ */
+int32_t lance_scanner_set_batch_size_bytes(
+    LanceScanner* scanner,
+    uint64_t batch_size_bytes
+);
+
+/**
+ * Set the scanner I/O buffer size in bytes.
+ *
+ * The value must be between 1 and INT64_MAX, inclusive, and must be set before
+ * scanning starts. This bounds buffered I/O received from storage, but is not
+ * a hard limit on all memory used by the scanner.
+ *
+ * @param scanner               Scanner handle. Must not be NULL.
+ * @param io_buffer_size_bytes  I/O buffer size in bytes, in the range [1, INT64_MAX].
+ * @return 0 on success, -1 on error.
+ */
+int32_t lance_scanner_set_io_buffer_size(
+    LanceScanner* scanner,
+    uint64_t io_buffer_size_bytes
+);
+
+/**
+ * Set the maximum number of batches decoded concurrently.
+ *
+ * @param batch_readahead  Number of in-flight batch decode tasks. Must be greater than zero.
+ */
+int32_t lance_scanner_set_batch_readahead(
+    LanceScanner* scanner,
+    size_t batch_readahead
+);
+
+/**
+ * Set fragment readahead for unordered scans.
+ *
+ * This setting is only used when scan-in-order is disabled. The value must be
+ * greater than zero.
+ */
+int32_t lance_scanner_set_fragment_readahead(
+    LanceScanner* scanner,
+    size_t fragment_readahead
+);
+
+/**
+ * Set the target number of physical execution partitions.
+ *
+ * This controls the partition count used by the physical optimizer and can be
+ * used to bound scan CPU parallelism. The value must be greater than zero and
+ * must be set before scanning starts.
+ */
+int32_t lance_scanner_set_target_parallelism(
+    LanceScanner* scanner,
+    size_t target_parallelism
+);
+
+/**
+ * Configure whether batches are returned in storage order (default: true).
+ *
+ * Disabling ordering can improve throughput by returning batches as soon as
+ * they are ready.
+ */
+int32_t lance_scanner_set_scan_in_order(LanceScanner* scanner, bool scan_in_order);
 int32_t lance_scanner_with_row_id(LanceScanner* scanner, bool enable);
 
 /**
@@ -1656,6 +1724,19 @@ int32_t lance_scanner_nearest(
 );
 
 int32_t lance_scanner_set_nprobes(LanceScanner* scanner, uint32_t n);
+
+/**
+ * Set vector index partition-search concurrency for each query.
+ *
+ * A value of -1 uses the CPU pool size, 0 selects Lance's automatic policy,
+ * 1 uses the sequential path, and values greater than 1 request parallel
+ * partition search. The effective value is capped by available parallelism.
+ * Values below -1 are rejected. Must be set before scanning starts.
+ */
+int32_t lance_scanner_set_query_parallelism(
+    LanceScanner* scanner,
+    int32_t query_parallelism
+);
 int32_t lance_scanner_set_refine_factor(LanceScanner* scanner, uint32_t f);
 int32_t lance_scanner_set_ef(LanceScanner* scanner, uint32_t e);
 int32_t lance_scanner_set_metric(LanceScanner* scanner, LanceMetricType metric);

include/lance/lance.hpp

@@ -1196,6 +1196,48 @@ class Scanner {
         return *this;
     }
 
+    /// Set the target output batch size in bytes.
+    Scanner& batch_size_bytes(uint64_t bytes) {
+        if (lance_scanner_set_batch_size_bytes(handle_.get(), bytes) != 0)
+            check_error();
+        return *this;
+    }
+
+    /// Set the scanner I/O buffer size in bytes, in the range [1, INT64_MAX].
+    Scanner& io_buffer_size(uint64_t bytes) {
+        if (lance_scanner_set_io_buffer_size(handle_.get(), bytes) != 0)
+            check_error();
+        return *this;
+    }
+
+    /// Set the number of batches decoded concurrently.
+    Scanner& batch_readahead(size_t batches) {
+        if (lance_scanner_set_batch_readahead(handle_.get(), batches) != 0)
+            check_error();
+        return *this;
+    }
+
+    /// Set fragment readahead for unordered scans.
+    Scanner& fragment_readahead(size_t fragments) {
+        if (lance_scanner_set_fragment_readahead(handle_.get(), fragments) != 0)
+            check_error();
+        return *this;
+    }
+
+    /// Set the target number of physical execution partitions.
+    Scanner& target_parallelism(size_t partitions) {
+        if (lance_scanner_set_target_parallelism(handle_.get(), partitions) != 0)
+            check_error();
+        return *this;
+    }
+
+    /// Configure whether batches are returned in storage order.
+    Scanner& scan_in_order(bool ordered = true) {
+        if (lance_scanner_set_scan_in_order(handle_.get(), ordered) != 0)
+            check_error();
+        return *this;
+    }
+
     /// Enable/disable row ID in output.
     Scanner& with_row_id(bool enable = true) {
         if (lance_scanner_with_row_id(handle_.get(), enable) != 0)
@@ -1313,6 +1355,11 @@ class Scanner {
         if (lance_scanner_set_nprobes(handle_.get(), n) != 0) check_error();
         return *this;
     }
+    Scanner& query_parallelism(int32_t parallelism) {
+        if (lance_scanner_set_query_parallelism(handle_.get(), parallelism) != 0)
+            check_error();
+        return *this;
+    }
     Scanner& refine_factor(uint32_t f) {
         if (lance_scanner_set_refine_factor(handle_.get(), f) != 0) check_error();
         return *this;