Documents

Documents are JSON text, which the engine parses as it writes them. Collection::docs parses what it reads through JsonTape: get hands out a jsontape::Json parsed out of the one-off arena it read through, get_json hands out the text itself as a String, and set writes a jsontape::Json. With the serde feature, get_as deserializes a document into any DeserializeOwned type. ustore::Json names JSON text in the batch verbs below, so JsonTape’s types are always spelled with their jsontape:: prefix.

let mut movies = database.collection("movies")?;
movies.docs().set(avatar, &jsontape::parse(br#"{"title":"Avatar","year":2009}"#)?)?;
let title = movies.docs().get(avatar)?.and_then(|movie| movie["title"].as_str().map(str::to_owned));
let text: Option<String> = movies.docs().get_json(avatar)?;
let fields: Option<BTreeMap<String, jsontape::Json>> = movies.docs().get_as(avatar)?;

The batch verbs carry documents as text both ways and parse nothing on the Rust side. A field is a top-level key or an RFC 6901 pointer, which crosses as the bytes of a &str, so a "/user/name" literal crosses as it stands, and an empty field addresses the whole document. docs_write writes whole documents or fields inside them, and docs_read reads either, as ustore_docs_write and ustore_docs_read do.

use ustore::{Column, Document, DocumentEntry, FieldAddress, FieldEntry, Json, KeyedBy, Modification, Text};

let documents = [DocumentEntry::<Json>::new(ada, r#"{"name":"Ada","born":1815}"#)];
database.head().docs_write(people, &documents, Modification::Upsert, Durability::Buffered)?;

let born = [DocumentEntry::<i64>::new(Key::from(5u64), &1815)];
database.head().docs_write(people, &born, Modification::Upsert, Durability::Buffered)?;

let keyed = [Document::new(r#"{"_id":2,"name":"Grace"}"#)];
database.head().docs_write(people, KeyedBy("_id", &keyed), Modification::Insert, Durability::Buffered)?;

let died = [FieldEntry::<i64>::new(ada, "died", &1852)];
database.head().docs_write(people, &died, Modification::Upsert, Durability::Buffered)?;
let family = [FieldEntry::<Json>::new(ada, "/family", r#"{"father":"Byron"}"#)];
database.head().docs_write(people, &family, Modification::Upsert, Durability::Buffered)?;
let unborn = [DocumentEntry::<Json>::new(ada, r#"{"born":null}"#)];
database.head().docs_write(people, &unborn, Modification::Merge, Durability::Buffered)?;

let whole = database.head().docs_read(people, [ada, grace], Json, &mut arena)?;
let names = database.head().docs_read(people, &[FieldAddress::new(ada, "name")], Text, &mut arena)?;

A write carries one format for the whole batch, named by the type of its entries: a scalar from f64 down to u8 or bool, Text for a JSON string, or Json for any JSON value. The same formats write a whole document, which is then one number, one boolean or one string rather than an object. KeyedBy writes documents that carry their keys under a field of their own: a non-negative integer, spelled as Key::from spells it, or a UUID in canonical text. Mixing two formats in one batch does not compile, and every entry carries a value: On::remove removes whole documents, and a merge carrying a JSON null removes a field. Modification chooses between an upsert, an update, an insert, an RFC 6902 patch and an RFC 7386 merge. Reads hand back the same Values a binary read does, of keys for whole documents or of FieldAddress values for fields, exported in the format named before the arena, Json or printed Text, with a missing document or field reported as None.

Every document verb also takes owned inputs, which a deferred view needs. Whole documents go as keys beside a stringtape::CharsTape of JSON texts, or as the tape alone inside a KeyedBy, and field writes as keys and a CharsTape of paths beside a tape of JSON values. A field read takes keys beside a CharsTape of paths, and a gather a Vec<Column<'static>>, whose Column::new takes a &str or a String.

use ustore::stringtape::CharsTape;

let deferred = database.head().deferred(&executor);
let texts: CharsTape<u64> = [r#"{"name":"Ada"}"#, r#"{"name":"Grace"}"#].into_iter().collect();
deferred.docs_write(people, (vec![ada, grace], texts), Modification::Upsert, Durability::Buffered)?.wait()?;

let paths: CharsTape<u32> = ["name", "name"].into_iter().collect();
let names = deferred.docs_read(people, (vec![ada, grace], paths), Text, &mut arena)?.await?;
assert_eq!(names.get(1), Some(b"Grace".as_slice()));

A gist lists the unique paths to the leaves of a batch of documents as &str pointers, and a gather converts fields into typed columns, a row per key:

let paths = database.head().docs_gist(people, [ada, grace], &mut arena)?;

let columns = [Column::new::<u64>("born"), Column::new::<Text>("name")];
let gathered = database.head().docs_gather(people, &[ada, grace], &columns, &mut other_arena)?;
let born: &[u64] = gathered.scalars::<u64>(0)?;
let valid = gathered.validities(0)?.unwrap().get(1);
let name = gathered.strings(1)?.get(0);

Columns borrow their arena and hold the columns they were asked for, borrowed or owned, and hand out scalar columns as slices straight out of the arena, and string columns as a StringColumn each, whose Text strings come without the null terminator the arena keeps after them. Beside the scalars a gather converts into, Half is a column of IEEE 754 binary16 bit patterns the caller reinterprets and UUID a column of sixteen bytes parsed from canonical text; neither is a format a write carries, and a value that will not fit either leaves its cell zero and sets the collision bit of its row. Every column carries three bitmaps: validity for a value found and converted, conversions for a value whose meaning changed on the way, such as text parsed into a number, and collisions for a value of a type that would not convert. Asking for a column in a type other than the one it was gathered in is refused with Status::InvalidArgument. Paths from one arena address the fields a gather reads through another.