12 releases (6 breaking)

new 0.7.0 Mar 25, 2024
0.5.2 Feb 17, 2024
0.5.1 Nov 19, 2023
0.5.0 Aug 9, 2022
0.1.1 Dec 22, 2018

#312 in Data structures

Download history 16/week @ 2023-12-10 90/week @ 2023-12-17 13/week @ 2023-12-24 103/week @ 2023-12-31 218/week @ 2024-01-07 112/week @ 2024-01-14 69/week @ 2024-01-21 107/week @ 2024-01-28 24/week @ 2024-02-04 196/week @ 2024-02-11 353/week @ 2024-02-18 206/week @ 2024-02-25 126/week @ 2024-03-03 141/week @ 2024-03-10 153/week @ 2024-03-17

637 downloads per month
Used in 2 crates (via exocore-chain)

Apache-2.0

66KB
1.5K SLoC

extindex

crates.io

Immutable persisted index (on disk) that can be built in one pass using a sorted iterator, or can use extsort to externally sort the iterator first, and then build the index from it.

The index allows random lookups and sorted scans. An indexed entry consists of a key and a value. The key needs to implement Eq and Ord, and both the key and values need to implement a Serializable trait for serialization to and from disk. It is possible to rely on the serde library to implement this trait for most types.

The index is built using a skip list-like data structure, but lookups start from the end of the index instead of the beginning. This allows building the index in a single pass on a sorted iterator, as starting from the beginning would require knowing checkpoints/nodes ahead in the file.

Example

extern crate extindex;
extern crate serde;

use extindex::{Builder, Entry, Reader, SerdeWrapper};

#[derive(Ord, PartialOrd, Eq, PartialEq, Debug, serde::Serialize, serde::Deserialize)]
struct SomeStruct {
    a: u32,
    b: String,
}

fn main() {
    let index_file = tempfile::NamedTempFile::new().unwrap();

    let builder = Builder::new(index_file.path());
    let entries = vec![Entry::new(
        "my_key".to_string(),
        SerdeWrapper(SomeStruct {
            a: 123,
            b: "my value".to_string(),
        }),
    )];
    builder.build(entries.into_iter()).unwrap();

    let reader = Reader::<String, SerdeWrapper<SomeStruct>>::open(index_file).unwrap();
    assert!(reader.find(&"my_key".to_string()).unwrap().is_some());
    assert!(reader.find(&"notfound".to_string()).unwrap().is_none());
}

Roadmap

  • Possibility to use a Bloom filter to avoid disk access when the index does not contain a key.

Dependencies

~4–15MB
~178K SLoC