pub(crate) use std::{
collections::{HashMap, HashSet},
fs::{File, OpenOptions as FsOpenOptions},
path::{Path, PathBuf},
};
pub(crate) use std::sync::Arc;
pub(crate) use arc_swap::ArcSwap;
pub(crate) use parking_lot::{Mutex, RwLock};
pub(crate) use crate::concurrency::snapshot::Snapshot;
pub(crate) mod catalog_io;
pub(crate) mod codec_io;
mod filter_io;
pub(crate) mod query_admission;
pub(crate) mod query_arena;
pub(crate) mod segment_io;
pub(crate) mod text_indexing;
mod time;
mod time_index_io;
mod toc_io;
mod upq_search;
mod vector_search;
pub(in crate::file) use catalog_io::{
dirty_records, read_catalog_snapshot, read_segment_catalog, upsert_collection, upsert_frame,
upsert_vector,
};
pub(in crate::file) use codec_io::build_codec_cache;
pub(in crate::file) use segment_io::{
SegmentRegistry, SegmentRegistryMut, append_registered_segment, append_segment_at_end,
build_segment_map, legacy_offset_segment_ref, read_payload_ref, register_segment,
segment_catalog_entry, segment_ref_at_end, verify_payload_wire_bytes,
};
pub(in crate::file) use time::current_unix_timestamp;
pub(in crate::file) use toc_io::{
FooterCandidate, read_toc_footer, scan_for_footer_candidates, write_toc_footer_at_end,
};
pub(crate) use vector_search::VectorBasePtrs;
pub(in crate::file) use vector_search::build_vector_base_ptrs;
pub(crate) use uuid::Uuid;
pub(crate) use crate::{
codec::VectorCodec,
error::{Error, Result},
format::{
AnalyzerId, CodecId, CollectionId, EmbeddingSpaceId, FieldSchemaId, FrameId,
FusionProfileId, RetrievalProfileId, SegmentId, TextSpaceId, VectorId,
catalog::{
AnalyzerDesc, CatalogSnapshot, CodecDesc, CodecFamily, CollectionDesc,
EmbeddingSpaceDesc, FieldSchemaDesc, FrameDesc, FrameRole, FrameStatus, FrameStub,
FusionProfileDesc, PayloadEncoding, RetrievalProfileDesc, TextSpaceDesc, VectorDesc,
VectorMetric, VectorStatus,
},
catalog_codec::{CatalogTableKind, encode_catalog_delta},
create_contract::CreateContractV1,
dtype::DtypeSet,
header::{Header, HeaderCodec},
payload::PayloadRef,
registry::IdAllocator,
segment::{SEGMENT_HEADER_SIZE, SegmentHeaderCodec, SegmentRef, SegmentType},
toc::{TocFooter, TocFooterBody, TocFooterCodec},
vector::{VectorDataSegmentReader, VectorDataSegmentWriter},
},
io::{Durability, sync_file, sync_parent_dir},
text::analyzer::Analyzer,
};
pub(crate) use text_indexing::{
PendingFrameIndex, TextSpaceState, build_flush_output, rebuild_text_space_state,
text_index_root_mut,
};
pub(in crate::file) use catalog_io::{
upsert_analyzer, upsert_codec, upsert_embedding_space, upsert_field_schema,
upsert_fusion_profile, upsert_retrieval_profile, upsert_text_space,
};
pub(in crate::file) use segment_io::read_segment_payload_typed;
mod api_types;
mod profile;
mod query_profile;
mod query_types;
pub use api_types::{
AutoPromote, CreateOptions, EmbeddingSpaceSpec, OpenMode, PutFrame, PutVector,
ReadVectorResult, Reconstruct, TextMode, VectorContract, VectorFidelity,
};
pub use profile::{CommitOutcome, CommitProfile, IngestProfile, TextIndexBuildProfile};
pub use query_profile::{
QueryProfile, VectorOpenProfile, last_query_profile, last_vector_open_profile,
};
pub(crate) use query_types::DEFAULT_SKETCH_CANDIDATE_BUDGET;
pub use query_types::{
HybridHit, HybridQuery, HybridTextChannel, HybridVectorChannel, QueryAlgorithm,
SketchScanTimings, TextQuery, TimeQuery, VectorHit, VectorSearchQuery, VoteSearchTrace,
};
pub struct ValiseFile {
path: PathBuf,
file: Mutex<File>,
file_mmap: Option<Arc<memmap2::Mmap>>,
published_snapshot: ArcSwap<Snapshot>,
commit_fsync_barrier: RwLock<Option<Arc<crate::concurrency::writer_pipeline::GroupFsync>>>,
mode: OpenMode,
durability: Durability,
header: Header,
footer: TocFooter,
create_contract: CreateContractV1,
catalog: CatalogSnapshot,
frame_locators: HashMap<FrameId, catalog_io::FrameLocator>,
vector_base: RwLock<VectorBasePtrs>,
id_allocator: IdAllocator,
segment_registry: RwLock<SegmentRegistry>,
dirty_segment_ids: HashSet<SegmentId>,
dirty_collection_ids: HashSet<CollectionId>,
dirty_frame_ids: HashSet<FrameId>,
dirty_embedding_space_ids: HashSet<EmbeddingSpaceId>,
dirty_codec_ids: HashSet<CodecId>,
dirty_vector_ids: HashSet<VectorId>,
dirty_text_space_ids: HashSet<TextSpaceId>,
dirty_analyzer_ids: HashSet<AnalyzerId>,
dirty_field_schema_ids: HashSet<FieldSchemaId>,
dirty_retrieval_profile_ids: HashSet<RetrievalProfileId>,
dirty_fusion_profile_ids: HashSet<FusionProfileId>,
codec_cache: HashMap<CodecId, Box<dyn VectorCodec>>,
pending_vector_batches: HashMap<(EmbeddingSpaceId, CodecId), PendingVectorBatch>,
pending_payload_buf: Vec<u8>,
pending_payload_frames: Vec<PendingPayloadFrame>,
pending_payload_by_frame: HashMap<FrameId, usize>,
pending_uri_buf: Vec<u8>,
pending_uris: Vec<PendingUri>,
pub ingest_profile: IngestProfile,
ingest_profile_enabled: bool,
pending_text_indexes: HashMap<TextSpaceId, HashMap<FrameId, PendingFrameIndex>>,
text_space_states: HashMap<TextSpaceId, TextSpaceState>,
tombstoned_frame_count: u64,
analyzer_cache: HashMap<TextSpaceId, Analyzer>,
vector_by_id_cache: HashMap<VectorId, VectorDesc>,
collection_filter_cache: filter_io::CollectionFilterCache,
time_index_cache: time_index_io::TimeIndexCache,
verified_payload_segments: Arc<RwLock<HashSet<SegmentId>>>,
dirty: bool,
}
pub(crate) const PAYLOAD_BATCH_FLUSH_BYTES: usize = 4 * 1024 * 1024;
#[derive(Debug)]
pub(crate) struct PendingPayloadFrame {
frame_id: FrameId,
bytes_offset: u64,
bytes_length: u64,
}
#[derive(Debug)]
pub(crate) struct PendingUri {
frame_id: FrameId,
bytes_offset: u64,
bytes_length: u64,
}
pub(crate) struct PendingVectorBatch {
embedding_space_id: EmbeddingSpaceId,
codec_id: CodecId,
segment_id: SegmentId,
dim: usize,
base_bytes: usize,
vectors: Vec<VectorDesc>,
raw_values: Vec<f32>,
writer: VectorDataSegmentWriter,
}
pub(crate) const VECTOR_CHUNK_SIZE: usize = 4096;
mod accessors;
mod commit;
mod commit_writers;
mod frame_ops;
mod lifecycle;
mod registration;
mod text_ops;
mod vector_ops;
mod internals;
pub(in crate::file) use internals::*;
pub(crate) use internals::{CommitWritePhaseResult, mmap_segment_payload};
#[cfg(test)]
mod tests {
use super::*;
fn sample_text_space_desc() -> TextSpaceDesc {
TextSpaceDesc {
text_space_id: TextSpaceId(3),
name: "default".into(),
analyzer_id: AnalyzerId(5),
field_schema_id: FieldSchemaId(7),
default_profile_id: RetrievalProfileId(11),
flags: 0,
enabled_retrievers: 0,
}
}
fn sample_analyzer_desc() -> AnalyzerDesc {
use crate::format::catalog::{
PunctuationPolicy, Stemming, StopwordsPolicy, Tokenizer, UnicodeNormalization,
};
AnalyzerDesc {
analyzer_id: AnalyzerId(5),
unicode_normalization: UnicodeNormalization::Nfkc,
case_fold: true,
accent_fold: false,
tokenizer: Tokenizer::UnicodeWords,
stemming: Stemming::None,
stopword_set_ref: None,
stopword_query_only: true,
stopwords: StopwordsPolicy::None,
english_possessive_strip: false,
min_token_len: 2,
max_token_len: 64,
shingle_size: 0,
ngram_min: None,
ngram_max: None,
punctuation_policy: PunctuationPolicy::Drop,
}
}
fn sample_field_schema_desc() -> FieldSchemaDesc {
use crate::format::catalog::{FieldDesc, FieldSource};
FieldSchemaDesc {
field_schema_id: FieldSchemaId(7),
fields: vec![FieldDesc {
field_id: 1,
name: "search_text".into(),
source: FieldSource::SearchText,
store_positions: false,
store_term_freq: true,
store_set_membership: false,
weight: 1.0,
}],
}
}
fn sample_retrieval_profile_desc() -> RetrievalProfileDesc {
use crate::format::catalog::{IdfVariant, RetrievalProfileParams, RetrievalProfileType};
RetrievalProfileDesc {
profile_id: RetrievalProfileId(11),
profile_type: RetrievalProfileType::Bm25,
params: RetrievalProfileParams::Bm25 {
k1: 1.2,
b: 0.75,
idf_variant: IdfVariant::RobertsonSparckJones,
},
}
}
#[test]
fn register_text_side_lifecycle_roundtrip() {
use tempfile::tempdir;
let dir = tempdir().unwrap();
let path = dir.path().join("text-catalogs.vls");
let (analyzer_id, field_schema_id, profile_id, text_space_id) = {
let mut valise = ValiseFile::create(&path).unwrap();
let analyzer_id = valise.register_analyzer(sample_analyzer_desc()).unwrap();
let field_schema_id = valise
.register_field_schema(sample_field_schema_desc())
.unwrap();
let profile_id = valise
.register_retrieval_profile(sample_retrieval_profile_desc())
.unwrap();
let mut text_space = sample_text_space_desc();
text_space.analyzer_id = analyzer_id;
text_space.field_schema_id = field_schema_id;
text_space.default_profile_id = profile_id;
let text_space_id = valise.register_text_space(text_space).unwrap();
valise.commit().unwrap();
(analyzer_id, field_schema_id, profile_id, text_space_id)
};
let valise = ValiseFile::open_read_only(&path).unwrap();
assert_eq!(valise.analyzers().len(), 1);
assert_eq!(valise.analyzers()[0].analyzer_id, analyzer_id);
assert_eq!(valise.field_schemas().len(), 1);
assert_eq!(valise.field_schemas()[0].field_schema_id, field_schema_id);
assert_eq!(valise.retrieval_profiles().len(), 1);
assert_eq!(valise.retrieval_profiles()[0].profile_id, profile_id);
assert_eq!(valise.text_spaces().len(), 1);
assert_eq!(valise.text_spaces()[0].text_space_id, text_space_id);
assert_eq!(valise.text_spaces()[0].analyzer_id, analyzer_id);
assert_eq!(valise.text_spaces()[0].field_schema_id, field_schema_id);
assert_eq!(valise.text_spaces()[0].default_profile_id, profile_id);
}
#[test]
fn register_text_space_rejects_unknown_analyzer() {
use tempfile::tempdir;
let dir = tempdir().unwrap();
let path = dir.path().join("bad-analyzer.vls");
let mut valise = ValiseFile::create(&path).unwrap();
let mut text_space = sample_text_space_desc();
text_space.analyzer_id = AnalyzerId(999);
let err = valise
.register_text_space(text_space)
.expect_err("unknown analyzer should be rejected");
assert!(err.to_string().contains("unknown analyzer_id"));
}
#[test]
fn register_text_space_rejects_unknown_field_schema() {
use tempfile::tempdir;
let dir = tempdir().unwrap();
let path = dir.path().join("bad-fs.vls");
let mut valise = ValiseFile::create(&path).unwrap();
let analyzer_id = valise.register_analyzer(sample_analyzer_desc()).unwrap();
let mut text_space = sample_text_space_desc();
text_space.analyzer_id = analyzer_id;
text_space.field_schema_id = FieldSchemaId(999);
let err = valise
.register_text_space(text_space)
.expect_err("unknown field_schema should be rejected");
assert!(err.to_string().contains("unknown field_schema_id"));
}
#[test]
fn register_text_space_rejects_unknown_profile() {
use tempfile::tempdir;
let dir = tempdir().unwrap();
let path = dir.path().join("bad-profile.vls");
let mut valise = ValiseFile::create(&path).unwrap();
let analyzer_id = valise.register_analyzer(sample_analyzer_desc()).unwrap();
let field_schema_id = valise
.register_field_schema(sample_field_schema_desc())
.unwrap();
let mut text_space = sample_text_space_desc();
text_space.analyzer_id = analyzer_id;
text_space.field_schema_id = field_schema_id;
text_space.default_profile_id = RetrievalProfileId(999);
let err = valise
.register_text_space(text_space)
.expect_err("unknown profile should be rejected");
assert!(err.to_string().contains("unknown default_profile_id"));
}
#[test]
fn register_methods_allocate_monotonic_ids() {
use tempfile::tempdir;
let dir = tempdir().unwrap();
let path = dir.path().join("ids.vls");
let mut valise = ValiseFile::create(&path).unwrap();
let a1 = valise.register_analyzer(sample_analyzer_desc()).unwrap();
let a2 = valise.register_analyzer(sample_analyzer_desc()).unwrap();
assert!(a2.0 > a1.0);
let f1 = valise
.register_field_schema(sample_field_schema_desc())
.unwrap();
let f2 = valise
.register_field_schema(sample_field_schema_desc())
.unwrap();
assert!(f2.0 > f1.0);
}
fn sample_fusion_profile_desc() -> FusionProfileDesc {
use crate::format::catalog::FusionNormalization;
FusionProfileDesc {
fusion_profile_id: FusionProfileId(1),
bm25_weight: 0.6,
tfidf_weight: 0.0,
jaccard_weight: 0.0,
vector_weight: 0.4,
normalization: FusionNormalization::ZScore,
}
}
#[test]
fn register_fusion_profiles_persist_across_reopen() {
use tempfile::tempdir;
let dir = tempdir().unwrap();
let path = dir.path().join("fusion.vls");
let fusion_id = {
let mut valise = ValiseFile::create(&path).unwrap();
let fusion_id = valise
.register_fusion_profile(sample_fusion_profile_desc())
.unwrap();
valise.commit().unwrap();
fusion_id
};
let valise = ValiseFile::open_read_only(&path).unwrap();
assert_eq!(valise.fusion_profiles().len(), 1);
assert_eq!(valise.fusion_profiles()[0].fusion_profile_id, fusion_id);
}
#[test]
fn register_fusion_profile_rejects_invalid_weights() {
use crate::format::catalog::FusionNormalization;
use tempfile::tempdir;
let dir = tempdir().unwrap();
let path = dir.path().join("bad-fusion.vls");
let mut valise = ValiseFile::create(&path).unwrap();
let bad = FusionProfileDesc {
fusion_profile_id: FusionProfileId(0),
bm25_weight: 0.0,
tfidf_weight: 0.0,
jaccard_weight: 0.0,
vector_weight: 0.0,
normalization: FusionNormalization::ZScore,
};
let err = valise
.register_fusion_profile(bad)
.expect_err("all-zero weights should be rejected");
assert!(err.to_string().contains("at least one positive"));
}
#[test]
fn fusion_register_methods_allocate_monotonic_ids() {
use tempfile::tempdir;
let dir = tempdir().unwrap();
let path = dir.path().join("monotonic.vls");
let mut valise = ValiseFile::create(&path).unwrap();
let f1 = valise
.register_fusion_profile(sample_fusion_profile_desc())
.unwrap();
let f2 = valise
.register_fusion_profile(sample_fusion_profile_desc())
.unwrap();
assert!(f2.0 > f1.0);
}
}