[codex] docs(sqlite): add JSON metadata ergonomics (0xPlaygrounds#1798)

* docs(sqlite): add JSON metadata ergonomics

* docs(sqlite): document JSON metadata dependencies

Author: gold-silver-copper

crates/rig-sqlite/README.md

@@ -26,9 +26,13 @@ Add the companion crate to your `Cargo.toml`, along with the rig-core crate:
 [dependencies]
 rig-sqlite = "0.2.6"
 rig-core = "0.37.0"
+serde = { version = "1", features = ["derive"] }
+serde_json = "1"
 ```
 
-You can also run `cargo add rig-sqlite rig-core` to add the most recent versions of the dependencies to your project.
+You can also run `cargo add rig-sqlite rig-core serde_json` and
+`cargo add serde --features derive` to add the most recent versions of the
+dependencies to your project.
 
 See the [`/examples`](./examples) folder for usage examples.
 
@@ -45,6 +49,52 @@ unsafe {
 }
 ```
 
+## Storing JSON Metadata
+
+Declare JSON metadata columns with `Column::new("metadata", "JSON")` and store
+the value as `serde_json::Value`. Rig writes the value as JSON text and parses
+it back as structured JSON when documents are returned from vector searches.
+
+```rust
+use rig_core::Embed;
+use rig_sqlite::{Column, ColumnValue, SqliteVectorStoreTable};
+use serde::{Deserialize, Serialize};
+
+#[derive(Clone, Debug, Deserialize, Embed, Serialize)]
+struct Document {
+    id: String,
+    #[embed]
+    text: String,
+    metadata: serde_json::Value,
+}
+
+impl SqliteVectorStoreTable for Document {
+    fn name() -> &'static str {
+        "documents"
+    }
+
+    fn schema() -> Vec<Column> {
+        vec![
+            Column::new("id", "TEXT PRIMARY KEY"),
+            Column::new("text", "TEXT"),
+            Column::new("metadata", "JSON"),
+        ]
+    }
+
+    fn id(&self) -> String {
+        self.id.clone()
+    }
+
+    fn column_values(&self) -> Vec<(&'static str, Box<dyn ColumnValue>)> {
+        vec![
+            ("id", Box::new(self.id.clone())),
+            ("text", Box::new(self.text.clone())),
+            ("metadata", Box::new(self.metadata.clone())),
+        ]
+    }
+}
+```
+
 ## Filtering JSON Metadata
 
 SQLite filters can target document-table columns that store JSON text. Use

crates/rig-sqlite/src/lib.rs

@@ -30,6 +30,8 @@ pub enum SqliteError {
 }
 
 /// Value that can be stored in a SQLite vector store document column.
+///
+/// Use [`serde_json::Value`] for columns declared as `JSON`.
 pub trait ColumnValue: Send + Sync {
     /// Converts this value to a typed SQLite value.
     fn to_sql_value(&self) -> Value;
@@ -2274,6 +2276,16 @@ impl ColumnValue for bool {
     }
 }
 
+impl ColumnValue for serde_json::Value {
+    fn to_sql_value(&self) -> Value {
+        Value::Text(self.to_string())
+    }
+
+    fn column_type(&self) -> &'static str {
+        "JSON"
+    }
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;
@@ -2371,6 +2383,35 @@ mod tests {
         Ok(())
     }
 
+    #[test]
+    fn serde_json_value_column_value_round_trips_json_column() -> anyhow::Result<()> {
+        let value = serde_json::json!({
+            "knowledge_doc_id": 361,
+            "knowledge_id": 1,
+            "user_id": 1
+        });
+        anyhow::ensure!(
+            value.column_type() == "JSON",
+            "serde_json::Value should declare JSON column type"
+        );
+
+        let text = match value.to_sql_value() {
+            Value::Text(text) => text,
+            value => {
+                anyhow::bail!("serde_json::Value should serialize as JSON text, got {value:?}")
+            }
+        };
+
+        let column = Column::new("metadata", "JSON");
+        let round_trip = sqlite_column_value_to_json(0, &column, ValueRef::Text(text.as_bytes()))?;
+        anyhow::ensure!(
+            round_trip == value,
+            "serde_json::Value should round-trip through a JSON column, got {round_trip:?}"
+        );
+
+        Ok(())
+    }
+
     fn filter_error<T: std::fmt::Debug>(
         result: Result<T, FilterError>,
         context: &str,
@@ -4890,7 +4931,11 @@ mod tests {
                 ("id", Box::new(self.id.clone())),
                 (
                     "metadata",
-                    Box::new(serde_json::to_string(&self.metadata).unwrap_or_default()),
+                    Box::new(serde_json::json!({
+                        "user_id": self.metadata.user_id,
+                        "knowledge_id": self.metadata.knowledge_id,
+                        "knowledge_doc_id": self.metadata.knowledge_doc_id,
+                    })),
                 ),
                 ("title", Box::new(self.title.clone())),
             ]