revector 0.4.0

Declarative, versioned schema & config migrations for Qdrant — Alembic for vector collections.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195

//! Declarative spec types — the on-disk vocabulary for describing Qdrant
//! schema and config.
//!
//! These types are deliberately decoupled from `qdrant-client`: they are the
//! stable, serde-friendly surface that users author in YAML. The executor
//! ([`crate::ops`]) translates them into client calls. Keeping the file format
//! independent of the client crate means a `qdrant-client` upgrade can't
//! silently change the meaning of a committed migration.

use indexmap::IndexMap;
use serde::{Deserialize, Serialize};

/// Distance metric for a vector field.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "PascalCase")]
pub enum Distance {
    Cosine,
    Euclid,
    Dot,
    Manhattan,
}

/// Storage datatype for vector elements.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum Datatype {
    Float32,
    Uint8,
    Float16,
}

/// Configuration for a single (dense) named vector.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct VectorSpec {
    /// Dimensionality. Immutable once created — changing it requires the
    /// add-vector → re-embed → drop-old dance.
    pub size: u64,
    /// Distance metric. Also immutable in place.
    pub distance: Distance,
    /// Store vectors on disk rather than in RAM.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub on_disk: Option<bool>,
    /// Per-vector HNSW overrides.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub hnsw_config: Option<HnswConfigSpec>,
    /// Per-vector quantization overrides.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub quantization_config: Option<QuantizationSpec>,
    /// Element storage type.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub datatype: Option<Datatype>,
}

/// How sparse vector indexes are stored.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct SparseVectorSpec {
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub on_disk: Option<bool>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub full_scan_threshold: Option<u64>,
}

/// HNSW index parameters. All fields optional — only the ones set are sent.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct HnswConfigSpec {
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub m: Option<u64>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub ef_construct: Option<u64>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub full_scan_threshold: Option<u64>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub max_indexing_threads: Option<u64>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub on_disk: Option<bool>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub payload_m: Option<u64>,
}

/// Quantization configuration. Exactly one variant should be set.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum QuantizationSpec {
    Scalar(ScalarQuantizationSpec),
    Product(ProductQuantizationSpec),
    Binary(BinaryQuantizationSpec),
    Turboquant(TurboquantQuantizationSpec),
    /// Explicitly disable quantization (used by `update_collection`).
    Disabled,
}

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct ScalarQuantizationSpec {
    /// Quantization type. Only `int8` exists today.
    #[serde(default = "default_int8")]
    pub r#type: String,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub quantile: Option<f32>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub always_ram: Option<bool>,
}

fn default_int8() -> String {
    "int8".to_string()
}

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct ProductQuantizationSpec {
    /// Compression ratio: `x4`, `x8`, `x16`, `x32`, `x64`.
    pub compression: String,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub always_ram: Option<bool>,
}

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct BinaryQuantizationSpec {
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub always_ram: Option<bool>,
}

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct TurboquantQuantizationSpec {
    /// Bits per component: `1`, `1.5`, `2`, or `4`. Omitted → server default.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub bits: Option<String>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub always_ram: Option<bool>,
}

/// Optimizer thresholds and behaviour.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct OptimizersConfigSpec {
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub deleted_threshold: Option<f64>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub vacuum_min_vector_number: Option<u64>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub default_segment_number: Option<u64>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub max_segment_size: Option<u64>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub memmap_threshold: Option<u64>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub indexing_threshold: Option<u64>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub flush_interval_sec: Option<u64>,
}

/// Field types for payload indexes.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum PayloadSchemaType {
    Keyword,
    Integer,
    Float,
    Geo,
    Text,
    Bool,
    Datetime,
    Uuid,
}

/// A full collection specification, used both for `create_collection` ops and
/// as the declared desired state for `diff`.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct CollectionSpec {
    /// Named dense vectors. A single-vector collection uses one entry, by
    /// convention keyed `""` or any chosen name.
    #[serde(default)]
    pub vectors: IndexMap<String, VectorSpec>,
    /// Named sparse vectors.
    #[serde(default, skip_serializing_if = "IndexMap::is_empty")]
    pub sparse_vectors: IndexMap<String, SparseVectorSpec>,
    /// Collection-level HNSW defaults.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub hnsw_config: Option<HnswConfigSpec>,
    /// Collection-level quantization defaults.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub quantization_config: Option<QuantizationSpec>,
    /// Optimizer configuration.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub optimizers_config: Option<OptimizersConfigSpec>,
    /// Number of shards (immutable after create on single-node).
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub shard_number: Option<u32>,
    /// Replication factor.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub replication_factor: Option<u32>,
    /// Write consistency factor.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub write_consistency_factor: Option<u32>,
    /// Store the whole collection on disk.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub on_disk_payload: Option<bool>,
}