Struct rocksdb::DBRawIterator

pub struct DBRawIterator<'a> { /* fields omitted */ }

An iterator over a database or column family, with specifiable ranges and direction.

This iterator is different to the standard DBIterator as it aims Into replicate the underlying iterator API within RocksDB itself. This should give access to more performance and flexibility but departs from the widely recognised Rust idioms.

use rocksdb::{DB, Options};

let path = "_path_for_rocksdb_storage4";
{
    let db = DB::open_default(path).unwrap();
    let mut iter = db.raw_iterator();

    // Forwards iteration
    iter.seek_to_first();
    while iter.valid() {
        println!("Saw {:?} {:?}", iter.key(), iter.value());
        iter.next();
    }

    // Reverse iteration
    iter.seek_to_last();
    while iter.valid() {
        println!("Saw {:?} {:?}", iter.key(), iter.value());
        iter.prev();
    }

    // Seeking
    iter.seek(b"my key");
    while iter.valid() {
        println!("Saw {:?} {:?}", iter.key(), iter.value());
        iter.next();
    }

    // Reverse iteration from key
    // Note, use seek_for_prev when reversing because if this key doesn't exist,
    // this will make the iterator start from the previous key rather than the next.
    iter.seek_for_prev(b"my key");
    while iter.valid() {
        println!("Saw {:?} {:?}", iter.key(), iter.value());
        iter.prev();
    }
}
let _ = DB::destroy(&Options::default(), path);

Methods

impl<'a> DBRawIterator<'a>

pub fn valid(&self) -> bool

Returns true if the iterator is valid.

pub fn seek_to_first(&mut self)

Seeks to the first key in the database.

Examples

use rocksdb::{DB, Options};

let path = "_path_for_rocksdb_storage5";
{
    let db = DB::open_default(path).unwrap();
    let mut iter = db.raw_iterator();

    // Iterate all keys from the start in lexicographic order
    iter.seek_to_first();

    while iter.valid() {
        println!("{:?} {:?}", iter.key(), iter.value());
        iter.next();
    }

    // Read just the first key
    iter.seek_to_first();

    if iter.valid() {
        println!("{:?} {:?}", iter.key(), iter.value());
    } else {
        // There are no keys in the database
    }
}
let _ = DB::destroy(&Options::default(), path);

pub fn seek_to_last(&mut self)

Seeks to the last key in the database.

Examples

use rocksdb::{DB, Options};

let path = "_path_for_rocksdb_storage6";
{
    let db = DB::open_default(path).unwrap();
    let mut iter = db.raw_iterator();

    // Iterate all keys from the end in reverse lexicographic order
    iter.seek_to_last();

    while iter.valid() {
        println!("{:?} {:?}", iter.key(), iter.value());
        iter.prev();
    }

    // Read just the last key
    iter.seek_to_last();

    if iter.valid() {
        println!("{:?} {:?}", iter.key(), iter.value());
    } else {
        // There are no keys in the database
    }
}
let _ = DB::destroy(&Options::default(), path);

pub fn seek<K: AsRef<[u8]>>(&mut self, key: K)

Seeks to the specified key or the first key that lexicographically follows it.

This method will attempt to seek to the specified key. If that key does not exist, it will find and seek to the key that lexicographically follows it instead.

Examples

use rocksdb::{DB, Options};

let path = "_path_for_rocksdb_storage7";
{
    let db = DB::open_default(path).unwrap();
    let mut iter = db.raw_iterator();

    // Read the first key that starts with 'a'
    iter.seek(b"a");

    if iter.valid() {
        println!("{:?} {:?}", iter.key(), iter.value());
    } else {
        // There are no keys in the database
    }
}
let _ = DB::destroy(&Options::default(), path);

pub fn seek_for_prev<K: AsRef<[u8]>>(&mut self, key: K)

Seeks to the specified key, or the first key that lexicographically precedes it.

Like .seek() this method will attempt to seek to the specified key. The difference with .seek() is that if the specified key do not exist, this method will seek to key that lexicographically precedes it instead.

Examples

use rocksdb::{DB, Options};

let path = "_path_for_rocksdb_storage8";
{
    let db = DB::open_default(path).unwrap();
    let mut iter = db.raw_iterator();

    // Read the last key that starts with 'a'
    iter.seek_for_prev(b"b");

    if iter.valid() {
        println!("{:?} {:?}", iter.key(), iter.value());
    } else {
        // There are no keys in the database
    }
}
let _ = DB::destroy(&Options::default(), path);

pub fn next(&mut self)

Seeks to the next key.

Returns true if the iterator is valid after this operation.

pub fn prev(&mut self)

Seeks to the previous key.

Returns true if the iterator is valid after this operation.

pub unsafe fn key_inner(&self) -> Option<&[u8]>

Returns a slice to the internal buffer storing the current key.

This may be slightly more performant to use than the standard .key() method as it does not copy the key. However, you must be careful to not use the buffer if the iterator's seek position is ever moved by any of the seek commands or the .next() and .previous() methods as the underlying buffer may be reused for something else or freed entirely.

pub fn key(&self) -> Option<Vec<u8>>

Returns a copy of the current key.

pub unsafe fn value_inner(&self) -> Option<&[u8]>

Returns a slice to the internal buffer storing the current value.

This may be slightly more performant to use than the standard .value() method as it does not copy the value. However, you must be careful to not use the buffer if the iterator's seek position is ever moved by any of the seek commands or the .next() and .previous() methods as the underlying buffer may be reused for something else or freed entirely.

pub fn value(&self) -> Option<Vec<u8>>

Returns a copy of the current value.

Trait Implementations

impl<'a> Drop for DBRawIterator<'a>

fn drop(&mut self)

Executes the destructor for this type.

impl<'a> Into<DBRawIterator<'a>> for DBIterator<'a>

fn into(self) -> DBRawIterator<'a>

Performs the conversion.