Skip to main content

quickstart/
quickstart.rs

1// Copyright 2026 Elias Benali (@ebenali) and TheCleaners.
2//
3// Licensed under the Apache License, Version 2.0 (the "License");
4// you may not use this file except in compliance with the License.
5// You may obtain a copy of the License at
6//
7//     http://www.apache.org/licenses/LICENSE-2.0
8//
9// Unless required by applicable law or agreed to in writing, software
10// distributed under the License is distributed on an "AS IS" BASIS,
11// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12// See the License for the specific language governing permissions and
13// limitations under the License.
14
15//! scann-core from Rust: build a tree + asymmetric-hashing index with the
16//! config builder, search it (one query, a batch, from several threads),
17//! add and delete points, and save / reload it.
18//!
19//! Run through CMake (`cmake --build <build> --target scann_core_rust`
20//! builds it), or directly:
21//!   SCANN_CORE_BUILD_ENV=<build>/rust/scann_core_rust_build.env \
22//!     cargo run --release --example quickstart
23
24use scann_core::{
25    AhOptions, ConfigBuilder, DistanceMeasure, ReorderOptions, ScannIndex, SearchOptions,
26    TreeOptions,
27};
28
29const N: usize = 20_000;
30const DIM: usize = 64;
31
32/// Unit-norm points around 50 pseudo-random centers, row-major N x DIM.
33fn make_dataset(n: usize, seed: u64) -> Vec<f32> {
34    let mut s = seed.wrapping_mul(0x9E37_79B9_7F4A_7C15) | 1;
35    let mut uniform = move || {
36        s ^= s << 13;
37        s ^= s >> 7;
38        s ^= s << 17;
39        (s >> 11) as f32 / (1u64 << 53) as f32 * 2.0 - 1.0
40    };
41    let centers: Vec<f32> = (0..50 * DIM).map(|_| uniform()).collect();
42    let mut data = Vec::with_capacity(n * DIM);
43    for i in 0..n {
44        let row: Vec<f32> =
45            centers[(i % 50) * DIM..][..DIM].iter().map(|c| c + 0.3 * uniform()).collect();
46        let norm = row.iter().map(|x| x * x).sum::<f32>().sqrt();
47        data.extend(row.iter().map(|x| x / norm));
48    }
49    data
50}
51
52fn main() -> Result<(), Box<dyn std::error::Error>> {
53    let dataset = make_dataset(N, 1);
54    let queries = make_dataset(5, 2);
55
56    // The same options as the Python
57    //   scann.scann_ops_pybind.builder(db, 5, "dot_product")
58    //       .tree(num_leaves=200, num_leaves_to_search=20, random_init=False)
59    //       .score_ah(2, anisotropic_quantization_threshold=0.2)
60    //       .reorder(100).build()
61    let builder = ConfigBuilder::new(5, DistanceMeasure::DotProduct, DIM)
62        .tree(TreeOptions::new(200, 20).random_init(false)) // k-means++: reproducible
63        .score_ah(AhOptions::new(2).anisotropic_quantization_threshold(0.2))
64        .reorder(ReorderOptions::new(100));
65    println!("config:\n{}", builder.build(N as u64)?);
66    let mut index = builder.build_index(&dataset)?;
67    println!("built {index:?}");
68
69    // One query at a time; SearchOptions overrides the config per query.
70    for (q, query) in queries.chunks(DIM).enumerate() {
71        let nn = index.search(query, SearchOptions::default())?;
72        println!("query {q}: {:?} {:?}", nn.indices, nn.distances);
73    }
74    let wide = index.search(&queries[..DIM], SearchOptions::k(10).leaves_to_search(50))?;
75    println!("query 0, k=10 over 50 leaves: {:?}", wide.indices);
76
77    // A batch, and the same batch split across the index's thread pool.
78    let batched = index.search_batched(&queries, SearchOptions::default())?;
79    index.set_num_threads(4)?;
80    let parallel = index.search_batched_parallel(&queries, SearchOptions::default(), 2)?;
81    assert_eq!(batched[0].indices, parallel[0].indices);
82
83    // ScannIndex is Send + Sync: search it from several threads at once.
84    let index_ref = &index;
85    let from_threads: Vec<Vec<u32>> = std::thread::scope(|s| {
86        let handles: Vec<_> = queries
87            .chunks(DIM)
88            .map(|q| s.spawn(move || index_ref.search(q, SearchOptions::k(1)).unwrap().indices))
89            .collect();
90        handles.into_iter().map(|h| h.join().unwrap()).collect()
91    });
92    println!("top-1 per query, searched concurrently: {from_threads:?}");
93
94    // Mutation: add a point (immediately searchable), then delete it.
95    let added = index.add(&queries[..DIM])?;
96    let nn = index.search(&queries[..DIM], SearchOptions::k(1))?;
97    println!("added point {:?}; query 0's nearest neighbour is now {:?}", added, nn.indices);
98    index.delete(&added)?;
99    println!("deleted it again: {} points", index.len());
100
101    // Save and reload. The directory is also loadable from Python with
102    // scann.scann_ops_pybind.load_searcher(dir).
103    let dir = std::env::temp_dir().join("scann-core-rust-quickstart");
104    std::fs::create_dir_all(&dir)?;
105    index.serialize(&dir, true)?;
106    let reloaded = ScannIndex::load(&dir)?;
107    println!("reloaded {reloaded:?} from {}", dir.display());
108    std::fs::remove_dir_all(&dir)?;
109    Ok(())
110}