use std::collections::HashMap;
use std::sync::Arc;
use parking_lot::{ArcMutexGuard, Mutex, MutexGuard, RawMutex};
use crate::concurrency::database::Database;
use crate::db::collection::Field;
use crate::db::identity::{Entry, IdentityIndex};
use crate::db::loader::Bulk;
use crate::db::partition::Partitioned;
use crate::db::record::{Key, Record};
use crate::db::schema::CodecSpec;
use crate::db::schema_doc;
use crate::db::space::{
CollectionRecord, Metric, SchemaRegistry, VecState, register_codec_for,
register_embedding_space,
};
use crate::error::{Error, Result};
use crate::file::{CommitOutcome, PutFrame, PutVector};
use crate::format::catalog::FrameRole;
use crate::format::{CollectionId, EmbeddingSpaceId, FrameId, TextSpaceId, VectorId};
struct StagedVector {
space_name: String,
collection: CollectionId,
key_bytes: Vec<u8>,
owner_frame: FrameId,
values: Vec<f32>,
}
pub(crate) struct WriterCore {
db: Arc<Database>,
schema: Arc<Mutex<SchemaRegistry>>,
identity: Arc<Mutex<IdentityIndex>>,
staged: Vec<StagedVector>,
}
impl WriterCore {
fn new(
db: Arc<Database>,
schema: Arc<Mutex<SchemaRegistry>>,
identity: Arc<Mutex<IdentityIndex>>,
) -> Self {
Self {
db,
schema,
identity,
staged: Vec::new(),
}
}
fn put(&mut self, coll: &str, key: Key, rec: Record<'_>) -> Result<()> {
let key_bytes = key.encode();
let plan = {
let schema = self.schema.lock();
self.resolve_plan(&schema, coll, &rec)?
};
let (existing, parent_frame) = {
let identity = self.identity.lock();
let existing = identity.get(plan.collection_id, &key_bytes).cloned();
let parent_frame = match &rec.parent {
Some(pk) => {
let pk_bytes = pk.encode();
Some(
identity
.get(plan.collection_id, &pk_bytes)
.map(|e| e.frame_id)
.ok_or_else(|| {
Error::Format(format!(
"put: parent key not found in collection '{coll}'"
))
})?,
)
}
None => None,
};
(existing, parent_frame)
};
if let Some(prev) = &existing
&& !prev.committed
&& !prev.vectors.is_empty()
{
return Err(Error::Unsupported(
"put: cannot update a key whose vectors are not yet committed; commit() first"
.into(),
));
}
let text = rec.text_value();
let payload: &[u8] = text.map(str::as_bytes).unwrap_or(&[]);
let mut ready_vectors: Vec<(EmbeddingSpaceId, VectorId)> =
Vec::with_capacity(plan.ready.len());
let frame_id = {
let mut valise = self.db.inner.write();
let frame_id = valise.put_frame(PutFrame {
collection_id: plan.collection_id,
role: if parent_frame.is_some() {
FrameRole::Chunk
} else {
FrameRole::Document
},
payload,
created_at: rec.created_at,
updated_at: None,
parent_frame_id: parent_frame,
chunk_index: None,
chunk_count: None,
uri: Some(&key_bytes),
})?;
if let (Some(ts_id), Some(_)) = (plan.text_space_id, text) {
valise.index_frame_text(frame_id, ts_id)?;
}
for (space_id, values) in &plan.ready {
let vid = valise.put_vector(PutVector {
owner_frame_id: frame_id,
embedding_space_id: *space_id,
values,
})?;
ready_vectors.push((*space_id, vid));
}
if let Some(prev) = &existing {
if prev.committed {
for (_, vid) in &prev.vectors {
valise.delete_vector(*vid)?;
}
}
valise.delete_frame(prev.frame_id)?;
}
frame_id
};
if let Some(prev) = &existing {
self.staged.retain(|s| s.owner_frame != prev.frame_id);
}
for (space_name, values) in &plan.deferred {
self.staged.push(StagedVector {
space_name: space_name.clone(),
collection: plan.collection_id,
key_bytes: key_bytes.clone(),
owner_frame: frame_id,
values: values.to_vec(),
});
}
{
let mut identity = self.identity.lock();
identity.insert(
plan.collection_id,
key_bytes,
Entry {
frame_id,
vectors: ready_vectors,
committed: false,
},
);
}
Ok(())
}
fn put_auto(&mut self, coll: &str, rec: Record<'_>) -> Result<Key> {
let key = Key::Str(uuid::Uuid::new_v4().to_string());
self.put(coll, key.clone(), rec)?;
Ok(key)
}
fn put_into(&mut self, p: &Partitioned, key: Key, rec: Record<'_>) -> Result<()> {
let name = p.route(&rec, now_secs());
self.ensure_collection_with_shape(&name, p)?;
self.put(&name, key, rec)
}
fn ensure_collection_with_shape(&self, name: &str, p: &Partitioned) -> Result<()> {
let mut schema = self.schema.lock();
if schema
.collections
.get(name)
.is_some_and(|rec| rec.shape.is_some())
{
return Ok(());
}
let doc = schema_doc::SchemaDoc::from_schema(p.base(), p.declared_schema())?;
let plan = {
let valise = self.db.inner.read();
schema_doc::plan_sync(&valise, name, &doc)?
};
let collection_id = crate::db::ensure_collection(&self.db, &mut schema, name)?;
{
let mut valise = self.db.inner.write();
schema_doc::apply_sync(&mut valise, name, &doc, &plan)?;
}
schema.collections.insert(
name.to_owned(),
CollectionRecord {
collection_id,
shape: Some(p.shape().clone()),
doc: Some(doc),
},
);
Ok(())
}
fn delete(&mut self, coll: &str, key: &Key) -> Result<bool> {
let key_bytes = key.encode();
let collection_id = {
let schema = self.schema.lock();
schema
.collections
.get(coll)
.map(|c| c.collection_id)
.ok_or_else(|| Error::Format(format!("delete: unknown collection '{coll}'")))?
};
let entry = {
let identity = self.identity.lock();
identity.get(collection_id, &key_bytes).cloned()
};
let Some(entry) = entry else {
return Ok(false);
};
if !entry.committed && !entry.vectors.is_empty() {
return Err(Error::Unsupported(
"delete: cannot remove a key whose vectors are not yet committed; commit() first"
.into(),
));
}
{
let mut valise = self.db.inner.write();
if entry.committed {
for (_, vid) in &entry.vectors {
valise.delete_vector(*vid)?;
}
}
valise.delete_frame(entry.frame_id)?;
}
self.staged.retain(|s| s.owner_frame != entry.frame_id);
self.identity.lock().remove(collection_id, &key_bytes);
Ok(true)
}
fn commit(&mut self) -> Result<CommitOutcome> {
if !self.staged.is_empty() {
self.flush_deferred()?;
}
let outcome = {
let mut wc = self.db.writer();
wc.commit()?
};
self.identity.lock().mark_all_committed();
Ok(outcome)
}
fn flush_deferred(&mut self) -> Result<()> {
let mut names: Vec<String> = Vec::new();
for s in &self.staged {
if !names.iter().any(|n| n == &s.space_name) {
names.push(s.space_name.clone());
}
}
struct Calib {
dim: u32,
metric: Metric,
sample_target: usize,
codec: CodecSpec,
}
enum Plan {
Ready(EmbeddingSpaceId),
Calib(Calib),
}
let mut plans: HashMap<String, Plan> = HashMap::with_capacity(names.len());
{
let schema = self.schema.lock();
for name in &names {
let entry = schema.vector_spaces.get(name).ok_or_else(|| {
Error::Format(format!("commit: staged vectors for unknown space '{name}'"))
})?;
let plan = match &entry.state {
VecState::Ready { space_id } => Plan::Ready(*space_id),
VecState::Deferred {
sample_target,
codec,
} => Plan::Calib(Calib {
dim: entry.dim,
metric: entry.metric,
sample_target: *sample_target,
codec: codec.clone(),
}),
};
plans.insert(name.clone(), plan);
}
}
let mut resolved: HashMap<String, EmbeddingSpaceId> = HashMap::with_capacity(names.len());
let mut newly_ready: Vec<(String, EmbeddingSpaceId)> = Vec::new();
let mut pushes: Vec<(CollectionId, Vec<u8>, EmbeddingSpaceId, VectorId)> =
Vec::with_capacity(self.staged.len());
{
let mut valise = self.db.inner.write();
for name in &names {
match plans.get(name).expect("BUG: plan present for staged space") {
Plan::Ready(space_id) => {
resolved.insert(name.clone(), *space_id);
}
Plan::Calib(c) => {
let sample: Vec<Vec<f32>> = self
.staged
.iter()
.filter(|s| &s.space_name == name)
.take(c.sample_target)
.map(|s| s.values.clone())
.collect();
if sample.is_empty() {
continue;
}
let codec = register_codec_for(&mut valise, c.dim, &c.codec, &sample)?;
let space_id =
register_embedding_space(&mut valise, name, c.dim, c.metric, codec)?;
resolved.insert(name.clone(), space_id);
newly_ready.push((name.clone(), space_id));
}
}
}
for s in &self.staged {
let Some(&space_id) = resolved.get(&s.space_name) else {
continue;
};
let vid = valise.put_vector(PutVector {
owner_frame_id: s.owner_frame,
embedding_space_id: space_id,
values: &s.values,
})?;
pushes.push((s.collection, s.key_bytes.clone(), space_id, vid));
}
}
if !newly_ready.is_empty() {
let mut schema = self.schema.lock();
for (name, space_id) in newly_ready {
if let Some(e) = schema.vector_spaces.get_mut(&name) {
e.state = VecState::Ready { space_id };
}
}
}
{
let mut identity = self.identity.lock();
for (coll, key_bytes, space_id, vid) in pushes {
identity.push_vector(coll, &key_bytes, space_id, vid);
}
}
self.staged.clear();
Ok(())
}
fn resolve_plan<'a>(
&self,
schema: &SchemaRegistry,
coll: &str,
rec: &Record<'a>,
) -> Result<PutPlan<'a>> {
let record = schema
.collections
.get(coll)
.ok_or_else(|| Error::Format(format!("put: unknown collection '{coll}'")))?;
let shape = record.shape.as_ref().ok_or_else(|| {
Error::Format(format!(
"put: collection '{coll}' has no shape in this process; call store.collection(name, shape) first"
))
})?;
let collection_id = record.collection_id;
for (fname, value) in &rec.fields {
let field = shape.field(fname).ok_or_else(|| {
Error::Format(format!(
"put: field '{fname}' is not in collection '{coll}'"
))
})?;
match (field, value) {
(Field::Text(_), crate::db::record::Value::Text(_)) => {}
(Field::Vector(space), crate::db::record::Value::Vector(v)) => {
if let Some(dim) = space.dim()
&& dim as usize != v.len()
{
return Err(Error::Format(format!(
"put: field '{fname}' expects dim {dim}, got {}",
v.len()
)));
}
if !all_finite(v) {
return Err(Error::Format(format!(
"put: field '{fname}' in collection '{coll}' has non-finite values (NaN/Inf)"
)));
}
}
_ => {
return Err(Error::Format(format!(
"put: field '{fname}' kind does not match the shape"
)));
}
}
}
let text_space_id: Option<TextSpaceId> = match (shape.text_field(), rec.text_value()) {
(Some((_, space)), Some(_)) => {
Some(schema.text_space_id(space.name()).ok_or_else(|| {
Error::Format(format!("put: text space '{}' not registered", space.name()))
})?)
}
_ => None,
};
let mut ready: Vec<(EmbeddingSpaceId, &'a [f32])> = Vec::new();
let mut deferred: Vec<(String, &'a [f32])> = Vec::new();
for (fname, values) in rec.vector_values() {
let Some(Field::Vector(space)) = shape.field(fname) else {
return Err(Error::Format(format!(
"put: field '{fname}' is not a vector field"
)));
};
let name = space.name();
let entry = schema.vector_spaces.get(name).ok_or_else(|| {
Error::Format(format!("put: vector space '{name}' not registered"))
})?;
match entry.state {
VecState::Ready { space_id } => ready.push((space_id, values)),
VecState::Deferred { .. } => deferred.push((name.to_owned(), values)),
}
}
Ok(PutPlan {
collection_id,
text_space_id,
ready,
deferred,
})
}
}
pub struct Writer<'s> {
_guard: MutexGuard<'s, ()>,
core: WriterCore,
}
impl<'s> Writer<'s> {
pub(crate) fn new(
guard: MutexGuard<'s, ()>,
db: Arc<Database>,
schema: Arc<Mutex<SchemaRegistry>>,
identity: Arc<Mutex<IdentityIndex>>,
) -> Self {
Self {
_guard: guard,
core: WriterCore::new(db, schema, identity),
}
}
pub fn put(&mut self, coll: &str, key: impl Into<Key>, rec: Record<'_>) -> Result<()> {
self.core.put(coll, key.into(), rec)
}
pub fn put_auto(&mut self, coll: &str, rec: Record<'_>) -> Result<Key> {
self.core.put_auto(coll, rec)
}
pub fn put_into(
&mut self,
p: &Partitioned,
key: impl Into<Key>,
rec: Record<'_>,
) -> Result<()> {
self.core.put_into(p, key.into(), rec)
}
pub fn delete(&mut self, coll: &str, key: impl Into<Key>) -> Result<bool> {
self.core.delete(coll, &key.into())
}
pub fn commit(&mut self) -> Result<CommitOutcome> {
self.core.commit()
}
pub fn bulk(&mut self) -> Bulk<'_, 's> {
Bulk::new(self, 10_000)
}
}
pub struct OwnedWriter {
_guard: ArcMutexGuard<RawMutex, ()>,
core: WriterCore,
}
impl OwnedWriter {
pub(crate) fn new(
guard: ArcMutexGuard<RawMutex, ()>,
db: Arc<Database>,
schema: Arc<Mutex<SchemaRegistry>>,
identity: Arc<Mutex<IdentityIndex>>,
) -> Self {
Self {
_guard: guard,
core: WriterCore::new(db, schema, identity),
}
}
pub fn put(&mut self, coll: &str, key: impl Into<Key>, rec: Record<'_>) -> Result<()> {
self.core.put(coll, key.into(), rec)
}
pub fn put_auto(&mut self, coll: &str, rec: Record<'_>) -> Result<Key> {
self.core.put_auto(coll, rec)
}
pub fn put_into(
&mut self,
p: &Partitioned,
key: impl Into<Key>,
rec: Record<'_>,
) -> Result<()> {
self.core.put_into(p, key.into(), rec)
}
pub fn delete(&mut self, coll: &str, key: impl Into<Key>) -> Result<bool> {
self.core.delete(coll, &key.into())
}
pub fn commit(&mut self) -> Result<CommitOutcome> {
self.core.commit()
}
}
struct PutPlan<'a> {
collection_id: CollectionId,
text_space_id: Option<TextSpaceId>,
ready: Vec<(EmbeddingSpaceId, &'a [f32])>,
deferred: Vec<(String, &'a [f32])>,
}
#[inline]
fn all_finite(v: &[f32]) -> bool {
v.iter().fold(true, |acc, x| acc & x.is_finite())
}
fn now_secs() -> i64 {
std::time::SystemTime::now()
.duration_since(std::time::UNIX_EPOCH)
.map(|d| d.as_secs() as i64)
.unwrap_or(0)
}