Trait IndexMethodCursor 

pub trait IndexMethodCursor {
    // Required methods
    fn create(
        &mut self,
        connection: &Arc<Connection>,
        database_id: usize,
    ) -> Result<IOResult<()>>;
    fn destroy(
        &mut self,
        connection: &Arc<Connection>,
        database_id: usize,
    ) -> Result<IOResult<()>>;
    fn open_read(
        &mut self,
        connection: &Arc<Connection>,
        database_id: usize,
    ) -> Result<IOResult<()>>;
    fn open_write(
        &mut self,
        connection: &Arc<Connection>,
        database_id: usize,
    ) -> Result<IOResult<()>>;
    fn insert(&mut self, values: &[Register]) -> Result<IOResult<()>>;
    fn delete(&mut self, values: &[Register]) -> Result<IOResult<()>>;
    fn query_start(&mut self, values: &[Register]) -> Result<IOResult<bool>>;
    fn query_next(&mut self) -> Result<IOResult<bool>>;
    fn query_column(&mut self, idx: usize) -> Result<IOResult<Value>>;
    fn query_rowid(&mut self) -> Result<IOResult<Option<i64>>>;

    // Provided methods
    fn pre_commit(&mut self) -> Result<IOResult<()>> { ... }
    fn optimize(
        &mut self,
        _connection: &Arc<Connection>,
        _database_id: usize,
    ) -> Result<IOResult<()>> { ... }
    fn estimate_cost(
        &self,
        pattern_idx: usize,
        base_table_rows: f64,
    ) -> Option<IndexMethodCostEstimate> { ... }
}

cursor opened for index method and capable of executing DML/DDL/DQL queries for the index method over fixed table

Required Methods

fn create( &mut self, connection: &Arc<Connection>, database_id: usize, ) -> Result<IOResult<()>>

create necessary components for index method (usually, this is a bunch of btree-s)

fn destroy( &mut self, connection: &Arc<Connection>, database_id: usize, ) -> Result<IOResult<()>>

destroy components created in the create(…) call for index method

fn open_read( &mut self, connection: &Arc<Connection>, database_id: usize, ) -> Result<IOResult<()>>

open necessary components for reading the index

fn open_write( &mut self, connection: &Arc<Connection>, database_id: usize, ) -> Result<IOResult<()>>

open necessary components for writing the index

fn insert(&mut self, values: &[Register]) -> Result<IOResult<()>>

handle insert action “values” argument contains registers with values for index columns followed by rowid Integer register (e.g. for “CREATE INDEX i ON t USING method (x, z)” insert(…) call will have 3 registers in values: [x, z, rowid])

fn delete(&mut self, values: &[Register]) -> Result<IOResult<()>>

handle delete action “values” argument contains registers with values for index columns followed by rowid Integer register (e.g. for “CREATE INDEX i ON t USING method (x, z)” insert(…) call will have 3 registers in values: [x, z, rowid])

fn query_start(&mut self, values: &[Register]) -> Result<IOResult<bool>>

initialize query to the index method first element of “values” slice is the Integer register which holds index of the chosen IndexMethodDefinition::patterns by query planner next arguments of the “values” slice are values from the original query expression captured by pattern

For example, for 2 patterns [“SELECT * FROM {table} LIMIT ?”, “SELECT * FROM {table} WHERE x = ?”], query_start(…) call can have following arguments:

• [Integer(0), Integer(10)] - pattern “SELECT * FROM {table} LIMIT ?” was chosen with LIMIT parameter equals to 10
• [Integer(1), Text(“turso”)] - pattern “SELECT * FROM {table} WHERE x = ?” was chosen with equality comparison equals to “turso”

Returns false if query will produce no rows (similar to VFilter/Rewind op codes)

fn query_next(&mut self) -> Result<IOResult<bool>>

Moves cursor to the next response row Returns false if query exhausted all rows

fn query_column(&mut self, idx: usize) -> Result<IOResult<Value>>

Return column with given idx (zero-based) from current row

fn query_rowid(&mut self) -> Result<IOResult<Option<i64>>>

Return rowid of the original table row which corresponds to the current cursor row

This method is used by tursodb core in order to “enrich” response from query pattern with additional fields from original table For example, consider pattern like this:

SELECT vector_distance_jaccard(embedding, ?) as d FROM table ORDER BY d LIMIT 10

It can be used in more complex query:

SELECT name, comment, rating, vector_distance_jaccard(embedding, ?) as d FROM table ORDER BY d LIMIT 10

In this case query planner will execute index method query first, and then enrich its result with name, comment, rating columns from original table accessing original row by its rowid returned from query_rowid(…) method

Provided Methods

fn pre_commit(&mut self) -> Result<IOResult<()>>

Called before transaction commit to flush any pending writes. This ensures index method writes are persisted as part of the transaction.

fn optimize( &mut self, _connection: &Arc<Connection>, _database_id: usize, ) -> Result<IOResult<()>>

Optimize the index by merging segments or performing other maintenance.

fn estimate_cost( &self, pattern_idx: usize, base_table_rows: f64, ) -> Option<IndexMethodCostEstimate>

Estimate the cost of executing a query with the given pattern.

This method enables the optimizer to make cost-based decisions when choosing between custom index methods and traditional BTree indexes.

Dyn Compatibility

This trait is dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors

impl IndexMethodCursor for VectorSparseInvertedIndexMethodCursor