Reference/Databases

Databases

CES

Persist entries, named attributes, directed relationships, and indexed numeric queries.

C++23 mc/CES.h
#include <mc/CES.h>

ID zero denotes absence. Relationship and attribute names can be reused: creating an existing name returns its existing ID.

Replace existing relations or attribute values by deleting and recreating them. Integer and floating-point attributes support range queries; arbitrary cvar attributes support equality.

Jump to a declaration · 38
CES CES::addAttribute CES::addEntry CES::addRelation CES::addRelationship CES::CES CES::compact CES::deleteAttribute CES::deleteEntry CES::deleteRelation CES::deleteRelationship CES::deleteValueFloat CES::deleteValueInt CES::deleteValueVar CES::getAttribute CES::getAttributes CES::getEntriesByAttributeEQ CES::getEntriesByAttributeGE CES::getEntriesByAttributeLE CES::getEntryAttributes CES::getEntryRelationsFrom CES::getEntryRelationsTo CES::getRelationsFrom CES::getRelationship CES::getRelationships CES::getRelationsTo CES::getValueFloat CES::getValueInt CES::getValueVar CES::hasRelation CES::Id CES::Id4 CES::Ids CES::operator= CES::setValue CES::shutdown CES::StringSet CES::~CES

CES

class CES

Types, constants & data

using Id = uint64_t;
using Id4 = uint32_t;
using Ids = CVector<Id>;
using StringSet = CHashSet<cstr>;

Methods

CES

CES(const cstr& path, bool create);
CES(const CES&) = delete;

Creates a new entry-store database or opens an existing one. Stored counters preserve entry, attribute, and relationship identities across reopen.

shutdown

void shutdown();

Persists committed data and closes the store. Later data operations are rejected; repeated shutdown is harmless.

compact

void compact();

Reclaims storage after deletions; this is a relatively expensive maintenance operation.

addEntry

Id addEntry();

Allocates and persists a new nonzero entry ID. An entry with no values or relations is represented by its ID alone.

deleteEntry

void deleteEntry(Id entryId);

Removes the entry and its associated relations and attribute values.

addRelationship

Id addRelationship(const cstr& name);

Returns the existing ID for a relationship name or creates and commits a new named relationship.

deleteRelationship

void deleteRelationship(Id4 relationshipId);

Removes the relationship and all relations using it.

addAttribute

Id addAttribute(const cstr& name);

Returns the existing ID for an attribute name or creates and commits a new named attribute.

deleteAttribute

void deleteAttribute(Id4 attributeId);

Removes the attribute and all values using it.

addRelation

void addRelation(Id4 relationshipId, Id fromEntryId, Id toEntryId, double value = CNan<double>);

Adds a directed relation with an optional ordering weight and commits it. The default NaN weight is stored as zero; delete an existing relation explicitly when replacing it.

deleteRelation

void deleteRelation(Id4 relationshipId, Id fromEntryId, Id toEntryId);

Removes relations matching the relationship and both endpoint IDs, then commits the change.

setValue

void setValue(Id4 attributeId, Id entryId, double value);
void setValue(Id4 attributeId, Id entryId, int64_t value);
void setValue(Id4 attributeId, Id entryId, const cvar& value);

Inserts and commits an attribute value in the integer, floating-point, or dynamic-value store selected by the overload. This is not a general overwrite operation; delete previous values before replacement.

getValueInt

int64_t getValueInt(Id4 attributeId, Id entryId) const;

Returns an integer attribute value for an entry. A missing value raises CError; it does not search the other attribute-type stores.

getValueFloat

double getValueFloat(Id4 attributeId, Id entryId) const;

Returns a floating-point attribute value for an entry. A missing value raises CError; it does not convert an integer-store value.

getValueVar

cvar getValueVar(Id4 attributeId, Id entryId) const;

Returns an owned dynamic attribute value. A missing value raises CError.

deleteValueInt

void deleteValueInt(Id4 attributeId, Id entryId);

Removes integer values for the attribute/entry pair and commits the deletion. Floating-point and dynamic values are unaffected.

deleteValueFloat

void deleteValueFloat(Id4 attributeId, Id entryId);

Removes floating-point values for the attribute/entry pair and commits the deletion. Other value-type stores are unaffected.

deleteValueVar

void deleteValueVar(Id4 attributeId, Id entryId);

Removes a dynamic value for the attribute/entry pair if present and commits the deletion.

getRelationsFrom

Ids getRelationsFrom(Id4 relationshipId, Id fromEntryId) const;

Returns destination entry IDs for outgoing relations of the specified kind, traversed in ascending relation-weight order.

getRelationsTo

Ids getRelationsTo(Id4 relationshipId, Id toEntryId) const;

Returns source entry IDs for incoming relations of the specified kind, traversed in ascending relation-weight order.

hasRelation

bool hasRelation(Id4 relationshipId, Id fromEntryId, Id toEntryId) const;

Tests for a directed relation matching the relationship kind and both endpoint IDs.

getRelationship

Id getRelationship(const cstr& relationship) const;

Returns the named relationship ID, or zero when absent.

getAttribute

Id getAttribute(const cstr& attribute) const;

Returns the named attribute ID, or zero when absent.

getRelationships

StringSet getRelationships() const;

Returns a set of registered relationship names.

getAttributes

StringSet getAttributes() const;

Returns a set of registered attribute names.

getEntriesByAttributeEQ

Ids getEntriesByAttributeEQ(Id4 attributeId, double value) const;
Ids getEntriesByAttributeEQ(Id4 attributeId, int64_t value) const;
Ids getEntriesByAttributeEQ(Id4 attributeId, const cvar& value) const;

Returns entry IDs whose attribute equals the supplied value. The overload selects integer, floating-point, or dynamic-value comparison.

getEntriesByAttributeLE

Ids getEntriesByAttributeLE(Id4 attributeId, double value) const;
Ids getEntriesByAttributeLE(Id4 attributeId, int64_t value) const;

Returns entry IDs whose numeric attribute is at most the supplied bound, including equality. The overload selects the numeric store.

getEntriesByAttributeGE

Ids getEntriesByAttributeGE(Id4 attributeId, double value) const;
Ids getEntriesByAttributeGE(Id4 attributeId, int64_t value) const;

Returns entry IDs whose numeric attribute is at least the supplied bound, including equality. The overload selects the numeric store.

getEntryAttributes

cvar getEntryAttributes(Id entryId) const;

Returns attribute names mapped to this entry’s stored values. An entry with no values currently returns Null; repeated names across value-type stores overwrite earlier results.

getEntryRelationsFrom

cvar getEntryRelationsFrom(Id entryId) const;

Returns a map from relationship names to vectors of destination entry IDs.

getEntryRelationsTo

cvar getEntryRelationsTo(Id entryId) const;

Returns a map from relationship names to vectors of source entry IDs.