Struct SingleFileDiskANN

pub struct SingleFileDiskANN {
    pub dim: usize,
    pub num_vectors: usize,
    pub max_degree: usize,
    pub fraction_top: f64,
    pub fraction_mid: f64,
    pub distance_metric: DistanceMetric,
    /* private fields */
}

Main struct representing a DiskANN index

Fields

dim: usize

Dimensionality of vectors in the index

num_vectors: usize

Number of vectors in the index

max_degree: usize

Maximum number of edges per node

fraction_top: f64

Fraction of vectors in top layer

fraction_mid: f64

Fraction of vectors in middle layer

distance_metric: DistanceMetric

Distance metric used by this index

Implementations

impl SingleFileDiskANN

pub fn build_index_singlefile( num_vectors: usize, dim: usize, max_degree: usize, fraction_top: f64, fraction_mid: f64, distance_metric: DistanceMetric, singlefile_path: &str, ) -> Result<Self, DiskAnnError>

Builds a new single-file index with the specified parameters

Arguments

• num_vectors - Number of vectors to store
• dim - Dimensionality of the vectors
• max_degree - Maximum number of edges per node
• fraction_top - Fraction of vectors in top layer
• fraction_mid - Fraction of vectors in middle layer
• distance_metric - Distance metric to use
• singlefile_path - Path where the index file will be created

Returns

Returns Result<SingleFileDiskANN, DiskAnnError>

Examples found in repository

examples/demo.rs (lines 17-25)

fn main() -> Result<(), DiskAnnError> {
    let singlefile_path = "diskann.db";
    let num_vectors = 100_000;
    let dim = 128;
    let max_degree = 32;
    let fraction_top = 0.01;
    let fraction_mid = 0.1;
    let distance_metric = DistanceMetric::Cosine;

    // Build if missing
    if !std::path::Path::new(singlefile_path).exists() {
        println!("Building single-file diskann at {singlefile_path}...");
        let index = SingleFileDiskANN::build_index_singlefile(
            num_vectors,
            dim,
            max_degree,
            fraction_top,
            fraction_mid,
            distance_metric,
            singlefile_path,
        )?;
        println!("Build done. Index dimension = {}", index.dim);
    } else {
        println!("Index file {singlefile_path} already exists, skipping build.");
    }

    // Open
    let index = Arc::new(SingleFileDiskANN::open_index_singlefile(singlefile_path)?);

    // Query
    let query = vec![0.1, 0.2, 0.3 /* ... up to dim */];
    let k = 10;
    let beam_width = 64;
    let neighbors = index.search(&query, k, beam_width);
    println!("Neighbors for the sample query = {:?}", neighbors);

    Ok(())
}

examples/perf_test.rs (lines 24-32)

fn main() -> Result<(), DiskAnnError> {
    const NUM_VECTORS: usize = 1_000_000;
    const DIM: usize = 1536;
    const MAX_DEGREE: usize = 32;
    const FRACTION_TOP: f64 = 0.01;
    const FRACTION_MID: f64 = 0.1;
    let distance_metric = DistanceMetric::Cosine;

    let singlefile_path = "diskann_parallel.db";

    // Build if missing
    if !std::path::Path::new(singlefile_path).exists() {
        println!(
            "Building single-file index with parallel adjacency + distance={:?}",
            distance_metric
        );
        let start = Instant::now();
        let _index = SingleFileDiskANN::build_index_singlefile(
            NUM_VECTORS,
            DIM,
            MAX_DEGREE,
            FRACTION_TOP,
            FRACTION_MID,
            distance_metric,
            singlefile_path,
        )?;
        let elapsed = start.elapsed().as_secs_f32();
        println!("Done building index in {:.2} s", elapsed);
    } else {
        println!(
            "Index file {} already exists, skipping build.",
            singlefile_path
        );
    }

    // open
    let open_start = Instant::now();
    let index = Arc::new(SingleFileDiskANN::open_index_singlefile(singlefile_path)?);
    let open_time = open_start.elapsed().as_secs_f32();
    println!(
        "Opened index with {} vectors, dim={}, metric={:?} in {:.2} s",
        index.num_vectors, index.dim, index.distance_metric, open_time
    );

    // Create queries
    let queries = 5;
    let k = 10;
    let beam_width = 64;

    // Generate all queries in a batch
    let mut rng = rand::thread_rng();
    let mut query_batch: Vec<Vec<f32>> = Vec::with_capacity(queries);
    for _ in 0..queries {
        let q: Vec<f32> = (0..index.dim).map(|_| rng.gen()).collect();
        query_batch.push(q);
    }

    // Now run queries in parallel
    let search_start = Instant::now();
    query_batch.par_iter().enumerate().for_each(|(i, query)| {
        let neighbors = index.search(query, k, beam_width);
        println!("Query {i} => top-{k} neighbors = {:?}", neighbors);
    });
    let search_time = search_start.elapsed().as_secs_f32();
    println!("Performed {queries} queries in {:.2} s", search_time);

    Ok(())
}

pub fn open_index_singlefile(path: &str) -> Result<Self, DiskAnnError>

Opens an existing index file

Arguments

• path - Path to the index file

Returns

Returns Result<SingleFileDiskANN, DiskAnnError>

Examples found in repository

examples/demo.rs (line 32)

fn main() -> Result<(), DiskAnnError> {
    let singlefile_path = "diskann.db";
    let num_vectors = 100_000;
    let dim = 128;
    let max_degree = 32;
    let fraction_top = 0.01;
    let fraction_mid = 0.1;
    let distance_metric = DistanceMetric::Cosine;

    // Build if missing
    if !std::path::Path::new(singlefile_path).exists() {
        println!("Building single-file diskann at {singlefile_path}...");
        let index = SingleFileDiskANN::build_index_singlefile(
            num_vectors,
            dim,
            max_degree,
            fraction_top,
            fraction_mid,
            distance_metric,
            singlefile_path,
        )?;
        println!("Build done. Index dimension = {}", index.dim);
    } else {
        println!("Index file {singlefile_path} already exists, skipping build.");
    }

    // Open
    let index = Arc::new(SingleFileDiskANN::open_index_singlefile(singlefile_path)?);

    // Query
    let query = vec![0.1, 0.2, 0.3 /* ... up to dim */];
    let k = 10;
    let beam_width = 64;
    let neighbors = index.search(&query, k, beam_width);
    println!("Neighbors for the sample query = {:?}", neighbors);

    Ok(())
}

examples/perf_test.rs (line 44)

fn main() -> Result<(), DiskAnnError> {
    const NUM_VECTORS: usize = 1_000_000;
    const DIM: usize = 1536;
    const MAX_DEGREE: usize = 32;
    const FRACTION_TOP: f64 = 0.01;
    const FRACTION_MID: f64 = 0.1;
    let distance_metric = DistanceMetric::Cosine;

    let singlefile_path = "diskann_parallel.db";

    // Build if missing
    if !std::path::Path::new(singlefile_path).exists() {
        println!(
            "Building single-file index with parallel adjacency + distance={:?}",
            distance_metric
        );
        let start = Instant::now();
        let _index = SingleFileDiskANN::build_index_singlefile(
            NUM_VECTORS,
            DIM,
            MAX_DEGREE,
            FRACTION_TOP,
            FRACTION_MID,
            distance_metric,
            singlefile_path,
        )?;
        let elapsed = start.elapsed().as_secs_f32();
        println!("Done building index in {:.2} s", elapsed);
    } else {
        println!(
            "Index file {} already exists, skipping build.",
            singlefile_path
        );
    }

    // open
    let open_start = Instant::now();
    let index = Arc::new(SingleFileDiskANN::open_index_singlefile(singlefile_path)?);
    let open_time = open_start.elapsed().as_secs_f32();
    println!(
        "Opened index with {} vectors, dim={}, metric={:?} in {:.2} s",
        index.num_vectors, index.dim, index.distance_metric, open_time
    );

    // Create queries
    let queries = 5;
    let k = 10;
    let beam_width = 64;

    // Generate all queries in a batch
    let mut rng = rand::thread_rng();
    let mut query_batch: Vec<Vec<f32>> = Vec::with_capacity(queries);
    for _ in 0..queries {
        let q: Vec<f32> = (0..index.dim).map(|_| rng.gen()).collect();
        query_batch.push(q);
    }

    // Now run queries in parallel
    let search_start = Instant::now();
    query_batch.par_iter().enumerate().for_each(|(i, query)| {
        let neighbors = index.search(query, k, beam_width);
        println!("Query {i} => top-{k} neighbors = {:?}", neighbors);
    });
    let search_time = search_start.elapsed().as_secs_f32();
    println!("Performed {queries} queries in {:.2} s", search_time);

    Ok(())
}

pub fn search(&self, query: &[f32], k: usize, beam_width: usize) -> Vec<u32>

Searches the index for nearest neighbors

Arguments

• query - Query vector
• k - Number of nearest neighbors to return
• beam_width - Beam width for the search

Returns

Returns a vector of node IDs representing the nearest neighbors

Examples found in repository

examples/demo.rs (line 38)

fn main() -> Result<(), DiskAnnError> {
    let singlefile_path = "diskann.db";
    let num_vectors = 100_000;
    let dim = 128;
    let max_degree = 32;
    let fraction_top = 0.01;
    let fraction_mid = 0.1;
    let distance_metric = DistanceMetric::Cosine;

    // Build if missing
    if !std::path::Path::new(singlefile_path).exists() {
        println!("Building single-file diskann at {singlefile_path}...");
        let index = SingleFileDiskANN::build_index_singlefile(
            num_vectors,
            dim,
            max_degree,
            fraction_top,
            fraction_mid,
            distance_metric,
            singlefile_path,
        )?;
        println!("Build done. Index dimension = {}", index.dim);
    } else {
        println!("Index file {singlefile_path} already exists, skipping build.");
    }

    // Open
    let index = Arc::new(SingleFileDiskANN::open_index_singlefile(singlefile_path)?);

    // Query
    let query = vec![0.1, 0.2, 0.3 /* ... up to dim */];
    let k = 10;
    let beam_width = 64;
    let neighbors = index.search(&query, k, beam_width);
    println!("Neighbors for the sample query = {:?}", neighbors);

    Ok(())
}

examples/perf_test.rs (line 67)

fn main() -> Result<(), DiskAnnError> {
    const NUM_VECTORS: usize = 1_000_000;
    const DIM: usize = 1536;
    const MAX_DEGREE: usize = 32;
    const FRACTION_TOP: f64 = 0.01;
    const FRACTION_MID: f64 = 0.1;
    let distance_metric = DistanceMetric::Cosine;

    let singlefile_path = "diskann_parallel.db";

    // Build if missing
    if !std::path::Path::new(singlefile_path).exists() {
        println!(
            "Building single-file index with parallel adjacency + distance={:?}",
            distance_metric
        );
        let start = Instant::now();
        let _index = SingleFileDiskANN::build_index_singlefile(
            NUM_VECTORS,
            DIM,
            MAX_DEGREE,
            FRACTION_TOP,
            FRACTION_MID,
            distance_metric,
            singlefile_path,
        )?;
        let elapsed = start.elapsed().as_secs_f32();
        println!("Done building index in {:.2} s", elapsed);
    } else {
        println!(
            "Index file {} already exists, skipping build.",
            singlefile_path
        );
    }

    // open
    let open_start = Instant::now();
    let index = Arc::new(SingleFileDiskANN::open_index_singlefile(singlefile_path)?);
    let open_time = open_start.elapsed().as_secs_f32();
    println!(
        "Opened index with {} vectors, dim={}, metric={:?} in {:.2} s",
        index.num_vectors, index.dim, index.distance_metric, open_time
    );

    // Create queries
    let queries = 5;
    let k = 10;
    let beam_width = 64;

    // Generate all queries in a batch
    let mut rng = rand::thread_rng();
    let mut query_batch: Vec<Vec<f32>> = Vec::with_capacity(queries);
    for _ in 0..queries {
        let q: Vec<f32> = (0..index.dim).map(|_| rng.gen()).collect();
        query_batch.push(q);
    }

    // Now run queries in parallel
    let search_start = Instant::now();
    query_batch.par_iter().enumerate().for_each(|(i, query)| {
        let neighbors = index.search(query, k, beam_width);
        println!("Query {i} => top-{k} neighbors = {:?}", neighbors);
    });
    let search_time = search_start.elapsed().as_secs_f32();
    println!("Performed {queries} queries in {:.2} s", search_time);

    Ok(())
}