Collections

A database holds no collection until one is created, and every call names the collections it addresses, refusing a collections view with NULL data with ustore_status_invalid_argument_k. A collection is created with an optional name and the ustore_modality_t it holds, and addressed afterwards by the identifier the call answers, a UUIDv7 its create mints once and never reuses:

char const name[] = "movies";
ustore_collection_id_t movies = {0};
ustore_collection_create(&(ustore_collection_create_t){
    .database = database,
    .outcome = &outcome,
    .name = {(uint8_t const*)name, sizeof(name) - 1},
    .modality = ustore_modality_docs_k,
    .collection = &movies,
});

ustore_collection_id_t values = {0};
ustore_collection_create(&(ustore_collection_create_t){
    .database = database,
    .outcome = &outcome,
    .modality = ustore_modality_blobs_k,
    .collection = &values,
});

The examples below write binary values into values and documents into movies.

Each engine records names in the _names system collection and every collection’s modality and name in _collections, which no identifier reaches and no listing shows, so a name starting with _ is refused, and a name resolves in two phases: once through ustore_collection_find, which answers the identifier and the modality of every name of a batch at the head or at a snapshot, and by identifier from then on, as no other call carries one. Collections are created and dropped only at the head, so their names are never read inside a transaction, and resolving one never joins the conflicts of the work that follows it. A create records the name in the same step as the collection, refusing a name another collection carries even under a concurrent creator. A name no collection carries resolves to the nil UUID with its presence bit cleared, and ustore_collection_drop with ustore_drop_collection_k forgets a collection’s name before the collection goes. ustore_collection_list exports the identifier of every collection and, where asked, its modality and its name, as a tape where a collection created without one has an empty name. A listing describes the database rather than a transaction, so it reads the head or a snapshot.

§ Describing, Clearing and Compacting

ustore_database_describe reports the engine of an open database, what it supports and how much it holds, while ustore_database_clear and ustore_database_compact work on every collection at once:

ustore_database_description_t description = {0};
ustore_database_describe(&(ustore_database_describe_t){
    .database = database,
    .outcome = &outcome,
    .description = &description,
});
printf("%s holds %llu keys in %llu bytes on disk\n", ustore_engine_name(description.engine),
       (unsigned long long)description.keys, (unsigned long long)description.disk_bytes);

ustore_database_clear(&(ustore_database_clear_t){.database = database, .outcome = &outcome, .mode = ustore_drop_pairs_k});
ustore_database_compact(&(ustore_database_compact_t){.database = database, .outcome = &outcome});

A description’s capabilities say whether the engine supports transactions, collections and snapshots, engine names the engine, and isolation says how its transactions see each other: as the ram engine was opened, and ustore_isolation_snapshot_k elsewhere. keys, memory_bytes and disk_bytes are the engine’s estimates of the keys across every collection and of the bytes the data takes, and zero where it keeps none, as LevelDB keeps no count of its keys. pin_refused_bytes and crossing_requests report where the NVMe engine went unpinned: the arena bytes the locked-memory cap refused to pin, and the requests that crossed a gibibyte of a pinned arena. ustore_database_clear empties every collection as its mode names:

• ustore_drop_pairs_k removes every pair, keeping the collections and their names;
• ustore_drop_collection_k drops every collection but the main one with its name, and empties the main one;
• ustore_drop_values_k empties every value, keeping the keys.

The ram and RocksDB engines refuse to drop the collections while a snapshot is open, with ustore_status_invalid_argument_k, since the snapshot belongs to its holder. ustore_database_compact reclaims the space overwritten and removed data still takes, one collection at a time: RocksDB and LevelDB flush and compact their trees, and the ram engine frees the versions no reader needs and rewrites its image.