scann-core 0.2.1

Rust bindings for scann-core: ScaNN's approximate nearest-neighbour vector search core as a standalone library (derived from Google's ScaNN; not an official Google product)
Documentation
// Copyright 2026 The Google Research Authors.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.



syntax = "proto2";

package research_scann;

import "scann/proto/distance_measure.proto";
import "scann/proto/exact_reordering.proto";
import "scann/proto/projection.proto";

message PartitioningConfig {
  enum TreeType {
    KMEANS_TREE = 0;

    PCA_TREE = 1;

    RANDOM_PROJECTION_TREE = 2;

    BALL_TREE = 3;

    RANDOM = 4;

    TREE_X_HYBRID = 5;
  }

  optional TreeType tree_type = 31 [default = KMEANS_TREE];

  optional TreeXHybridPartitioningConfig tree_x_hybrid = 46;

  oneof SamplingFractionOrExpectedSize {
    float partitioning_sampling_fraction = 4 [default = 1.0];

    int32 expected_sample_size = 45;
  }

  optional string partitioner_prefix = 8;

  optional int32 clustering_seed = 27 [default = 0];

  optional ProjectionConfig projection = 12;

  optional int32 num_children = 3 [default = 2];

  optional DistanceMeasureConfig partitioning_distance = 10;

  optional DistanceMeasureConfig database_tokenization_distance_override = 24;

  optional DistanceMeasureConfig query_tokenization_distance_override = 25;

  enum TokenizationType {
    FLOAT = 1;

    FIXED_POINT_INT8 = 2;

    ASYMMETRIC = 3;

    reserved 0;
  }

  optional TokenizationType query_tokenization_type = 28 [default = FLOAT];

  optional TokenizationType database_tokenization_type = 29 [default = FLOAT];

  optional int32 max_clustering_iterations = 6 [default = 10];

  optional int32 num_mini_batches = 38 [default = 1];

  optional bool ignore_empty_cluster_errors = 55 [default = false];

  optional float clustering_convergence_tolerance = 7 [default = 1e-5];

  optional float min_cluster_size = 9 [default = 1];

  optional int32 max_cluster_size = 40;

  optional double perturbation = 41;

  enum PartitioningType {
    GENERIC = 0;

    SPHERICAL = 1;
  }

  optional PartitioningType partitioning_type = 23 [default = GENERIC];

  enum BalancingType {
    DEFAULT_UNBALANCED = 0;

    GREEDY_BALANCED = 1;

    UNBALANCED_FLOAT32 = 2;

    SINGLE_PASS_UNBALANCED_FLOAT32 = 3;

    SINGLE_PASS_GREEDY_BALANCED = 4;
  }

  optional BalancingType balancing_type = 35 [default = UNBALANCED_FLOAT32];

  optional int32 balancing_num_nearest_centroids = 56 [default = -1];

  enum SingleMachineCenterInitializationType {
    DEFAULT_KMEANS_PLUS_PLUS = 0;

    RANDOM_INITIALIZATION = 1;
  }

  optional SingleMachineCenterInitializationType
      single_machine_center_initialization = 49
      [default = DEFAULT_KMEANS_PLUS_PLUS];

  optional DatabaseSpillingConfig database_spilling = 20;

  optional QuerySpillingConfig query_spilling = 21;

  optional string resharded_prefix = 14;

  optional int32 num_partitioning_epochs = 1 [default = 1];

  optional string mr_jobname_prefix = 13 [default = "PartitionReshard"];

  optional string cell = 15;

  optional int32 num_cpus = 19 [default = 1];

  optional int32 num_mapper_machines = 30 [default = -1];

  optional int32 ram_gb = 16 [default = 4];

  optional int32 disk_gb = 17 [default = 1];

  enum PartitionerTrainerType {
    DEFAULT_SAMPLING_TRAINER = 0;

    FLUME_KMEANS_TRAINER = 1;

    PCA_KMEANS_TRAINER = 3;

    SAMPLING_PCA_KMEANS_TRAINER = 4;
  }
  optional PartitionerTrainerType trainer_type = 36
      [default = DEFAULT_SAMPLING_TRAINER];

  optional string trainer_stats_prefix = 37;

  optional int32 max_power_of_2_split = 39 [default = 2];

  optional int32 num_top_tokens_for_pca = 42 [default = 20];

  optional float pca_splitting_similarity_threshold = 43 [default = 1e-5];

  optional int32 desired_average_cluster_size = 34 [default = 3000];

  reserved 44;
  reserved "kmeans_flume_config";

  optional float avq = 51 [default = nan];

  optional IncrementalTrainingConfig incremental_training_config = 52;

  optional int32 num_tokenized_branch = 53 [default = 1];

  optional BottomUpTopLevelPartitioner bottom_up_top_level_partitioner = 54;

  optional bool use_float_centers_for_query_tokenization = 26
      [default = false, deprecated = true];

  optional bool partitioning_on_the_fly = 22
      [default = false, deprecated = true];

  optional bool use_flume_kmeans = 32 [default = false, deprecated = true];

  optional int32 max_sample_size = 33 [default = 2147483647, deprecated = true];

  optional int32 max_num_levels = 2 [default = 1, deprecated = true];

  optional int32 max_leaf_size = 11 [default = 1, deprecated = true];

  optional int32 first_n_centroids = 5;

  reserved 47, 48;
}

message DatabaseSpillingConfig {
  enum SpillingType {
    NO_SPILLING = 0;

    MULTIPLICATIVE = 1;

    ADDITIVE = 2;

    FIXED_NUMBER_OF_CENTERS = 3;

    TWO_CENTER_ORTHOGONALITY_AMPLIFIED = 4;

    SOAR = 4;

    option allow_alias = true;
  }

  optional SpillingType spilling_type = 1 [default = NO_SPILLING];

  optional float replication_factor = 2;

  optional uint32 max_spill_centers = 3 [default = 4294967295];

  optional float orthogonality_amplification_lambda = 4 [default = 1.5];

  optional float overretrieve_factor = 5 [default = 2.0];
}

message QuerySpillingConfig {
  enum SpillingType {
    NO_SPILLING = 0;

    MULTIPLICATIVE = 1;

    ADDITIVE = 2;

    ABSOLUTE_DISTANCE = 3;

    FIXED_NUMBER_OF_CENTERS = 4;
  }

  optional SpillingType spilling_type = 1 [default = NO_SPILLING];

  optional float spilling_threshold = 2;

  optional uint32 max_spill_centers = 3 [default = 2147483647];
}

message IncrementalTrainingConfig {
  oneof reassignment_trigger {
    float fraction = 1 [default = inf];

    uint32 number_of_datapoints = 2 [default = 4294967295];
  }

  optional uint32 cluster_stability_size = 3 [default = 200];

  optional bool autopilot = 4 [default = false];

  optional uint32 max_split = 5 [default = 4294967295];
}

message TreeXHybridPartitioningConfig {
  optional uint32 top_partitioning_children = 1;

  optional float top_partitioner_spilling_ratio = 2 [default = 0.05];

  optional PartitioningConfig.TokenizationType
      top_partitioner_query_tokenization_type = 7 [default = FLOAT];
  optional PartitioningConfig.TokenizationType
      top_partitioner_database_tokenization_type = 8 [default = FLOAT];
  optional PartitioningConfig.TokenizationType
      top_partitioner_training_tokenization_type = 10 [default = FLOAT];

  optional bool top_partitioner_use_flume_trainer = 9 [default = false];

  optional string assets_dir = 3;

  optional ExactReordering query_tokenization_reordering = 6;

  optional ExactReordering training_reordering = 4 [deprecated = true];
  optional ExactReordering database_tokenization_reordering = 5
      [deprecated = true];
}

message TokenList {
  optional uint64 id = 1;
  repeated int64 datapoint_index = 2;
}

message BottomUpTopLevelPartitioner {
  optional bool enabled = 1 [default = false];

  optional int32 num_centroids = 2;

  optional int32 num_centroids_to_search = 3;

  optional float avq = 4 [default = nan];

  message SoarConfig {
    optional bool enabled = 1 [default = false];

    optional float lambda = 2 [default = 1.5];

    optional float overretrieve_factor = 3 [default = 2.0];
  }

  optional SoarConfig soar = 5;

  enum Quantization {
    FLOAT32 = 0;

    BFLOAT16 = 1;

    FIXED8 = 2;
  }

  optional Quantization quantization = 6 [default = FLOAT32];

  optional float noise_shaping_threshold = 7 [default = nan];

  optional BottomUpTopLevelPartitioner next_higher_level = 8;
}