velesdb_core/collection/metadata_collection.rs
1//! `MetadataCollection`: payload-only storage without vectors.
2//!
3//! Ideal for reference tables, catalogs, and structured metadata.
4//! Supports CRUD and VelesQL queries on payload — NOT vector search.
5//!
6//! # Design
7//!
8//! `MetadataCollection` is a pure newtype over `Collection` — all operations
9//! delegate to the single `inner` instance, matching the `VectorCollection` pattern
10//! and eliminating any dual-storage desync risk (C-02).
11
12use std::collections::HashMap;
13use std::path::PathBuf;
14
15use crate::collection::types::Collection;
16use crate::error::{Error, Result};
17use crate::point::{Point, SearchResult};
18
19/// A metadata-only collection storing structured payloads without vector indexes.
20///
21/// # Examples
22///
23/// ```rust,no_run
24/// use velesdb_core::{MetadataCollection, Point};
25/// use serde_json::json;
26///
27/// let coll = MetadataCollection::create("./data/products".into(), "products")?;
28///
29/// coll.upsert(vec![
30/// Point::metadata_only(1, json!({"name": "Widget", "price": 9.99})),
31/// ])?;
32/// # Ok::<(), velesdb_core::Error>(())
33/// ```
34#[derive(Clone)]
35pub struct MetadataCollection {
36 /// Single source of truth — all operations delegate here (C-02 pure newtype).
37 pub(crate) inner: Collection,
38}
39
40impl MetadataCollection {
41 // -------------------------------------------------------------------------
42 // Lifecycle
43 // -------------------------------------------------------------------------
44
45 /// Creates a new `MetadataCollection`.
46 ///
47 /// # Errors
48 ///
49 /// Returns an error if the directory cannot be created or storage fails.
50 pub fn create(path: PathBuf, name: &str) -> Result<Self> {
51 Ok(Self {
52 inner: Collection::create_metadata_only(path, name)?,
53 })
54 }
55
56 /// Opens an existing `MetadataCollection` from disk.
57 ///
58 /// # Errors
59 ///
60 /// Returns an error if config or storage cannot be opened.
61 pub fn open(path: PathBuf) -> Result<Self> {
62 Ok(Self {
63 inner: Collection::open(path)?,
64 })
65 }
66
67 /// Flushes to disk.
68 ///
69 /// Issue #423: This fast-path flush skips `vectors.idx` serialization.
70 /// The WAL provides crash recovery for the vector index.
71 ///
72 /// # Errors
73 ///
74 /// Returns an error if the flush fails.
75 pub fn flush(&self) -> Result<()> {
76 self.inner.flush()
77 }
78
79 /// Full durability flush including `vectors.idx` serialization.
80 ///
81 /// Issue #423: Use on graceful shutdown to avoid a full WAL replay
82 /// on the next startup.
83 ///
84 /// # Errors
85 ///
86 /// Returns an error if the flush fails.
87 pub fn flush_full(&self) -> Result<()> {
88 self.inner.flush_full()
89 }
90
91 // -------------------------------------------------------------------------
92 // Metadata
93 // -------------------------------------------------------------------------
94
95 /// Returns the collection name.
96 #[must_use]
97 pub fn name(&self) -> String {
98 self.inner.config().name
99 }
100
101 /// Returns the number of items in the collection.
102 #[must_use]
103 pub fn len(&self) -> usize {
104 self.inner.len()
105 }
106
107 /// Returns `true` if the collection is empty.
108 #[must_use]
109 pub fn is_empty(&self) -> bool {
110 self.inner.is_empty()
111 }
112
113 /// Returns all stored IDs.
114 #[must_use]
115 pub fn all_ids(&self) -> Vec<u64> {
116 self.inner.all_ids()
117 }
118
119 // -------------------------------------------------------------------------
120 // CRUD
121 // -------------------------------------------------------------------------
122
123 /// Inserts or updates metadata points (must have no vector).
124 ///
125 /// # Errors
126 ///
127 /// Returns an error if a point carries a non-empty vector,
128 /// or if storage operations fail.
129 pub fn upsert(&self, points: impl IntoIterator<Item = Point>) -> Result<()> {
130 let points: Vec<Point> = points.into_iter().collect();
131 let name = self.inner.config().name;
132
133 for point in &points {
134 if !point.vector.is_empty() {
135 return Err(Error::VectorNotAllowed(name.clone()));
136 }
137 }
138
139 self.inner.upsert_metadata(points)
140 }
141
142 /// Retrieves items by IDs.
143 #[must_use]
144 pub fn get(&self, ids: &[u64]) -> Vec<Option<Point>> {
145 self.inner.get(ids)
146 }
147
148 /// Deletes items by IDs.
149 ///
150 /// # Errors
151 ///
152 /// Returns an error if storage operations fail.
153 pub fn delete(&self, ids: &[u64]) -> Result<()> {
154 self.inner.delete(ids)
155 }
156
157 // -------------------------------------------------------------------------
158 // Text search
159 // -------------------------------------------------------------------------
160
161 /// Performs BM25 full-text search over payloads.
162 ///
163 /// # Errors
164 ///
165 /// Returns an error if storage retrieval fails.
166 pub fn text_search(&self, query: &str, k: usize) -> Result<Vec<SearchResult>> {
167 self.inner.text_search(query, k)
168 }
169
170 // -------------------------------------------------------------------------
171 // VelesQL
172 // -------------------------------------------------------------------------
173
174 /// Executes a `VelesQL` query.
175 ///
176 /// # Errors
177 ///
178 /// Returns an error if the query is invalid or execution fails.
179 pub fn execute_query(
180 &self,
181 query: &crate::velesql::Query,
182 params: &HashMap<String, serde_json::Value>,
183 ) -> Result<Vec<SearchResult>> {
184 self.inner.execute_query(query, params)
185 }
186
187 /// Executes a raw VelesQL string.
188 ///
189 /// # Errors
190 ///
191 /// Returns an error if parsing or execution fails.
192 pub fn execute_query_str(
193 &self,
194 sql: &str,
195 params: &HashMap<String, serde_json::Value>,
196 ) -> Result<Vec<SearchResult>> {
197 self.inner.execute_query_str(sql, params)
198 }
199}