Expand description
Persistent embedded memory mapped graph database with native object queries.
Readme | Quickstart | Queries | Efficient agdb
§Example
use agdb::{Db, QueryBuilder};
let mut db = Db::new("db.agdb").unwrap();
db.exec_mut(&QueryBuilder::insert().nodes().values(vec![vec![("key", 123).into()]]).query()).unwrap();
let result = db.exec(&QueryBuilder::select().ids(1).query()).unwrap();
println!("{:?}", result);
// QueryResult { result: 1, elements: [ DbElement { id: DbId(1), values: [ DbKeyValue { key: String("key"), value: Int(123) } ] } ] }
Structs§
- Database element used in [
QueryResult
] that represents a node or an edge. - Universal
agdb
database error. It represents any error caused by the database processing such as loading a database, writing data etc. - Database float is a wrapper around
f64
to provide functionality like comparison. The comparison is usingtotal_cmp
standard library function. See its docs to understand how it handles NaNs and other edge cases of floating point numbers. - Database id is a wrapper around
i64
. The id is an identifier of a database element both nodes and edges. The positive ids represent nodes, negative ids represent edges. The value of0
is logically invalid (there cannot be element with id 0) and a default. - An instance of the
agdb
database. To create a database: - Database key-value pair (aka property) attached to database elements. It can be constructed from a tuple of types that are convertible to
DbValue
. - Single file based storage with write ahead log (WAL) for resiliency implementing
StorageData
. It uses the storage name as the file name (.{name}
for WAL). It allows multiple readers from the file by opening additional temporary file handles if the single member file handle is being used (read). TheStorageData::read()
always returns owning buffer. - The default implementation of the database storage implementing
StorageData
. It combines theFileStorage
andMemoryStorage
leveraging the former for the persistence and the latter for performance. The read operations are implemented in terms of theMemoryStorage
only and the write operations are implemented in terms of bothFileStorage
andMemoryStorage
. - Query to insert or update aliases of existing nodes. All
ids
must exist. None of thealiases
can be empty. If there is an existing alias for any of the elements it will be overwritten with a new one. - Query to inserts edges to the database. The
from
andto
ids must exist in the database. There must be enoughvalues
for all new edges unless set toSingle
in which case they will be uniformly applied to all new edges. Theeach
flag is only useful iffrom and
toare symmetric (same length) but you still want to connect every origin to every destination. By default it would connect only the pairs. For asymmetric inserts
each` is assumed. - Query to create a new index on a given key.
- Query to insert nodes to the database. Only one of
count
,values
oraliases
need to be given as the implementation will derive the count from the other parameters. Ifvalues
is set toSingle
eithercount
oraliases
must be provided however. Ifvalues
are not set toSingle
there must be enough value forcount/aliases
unless they are not se and the count is derived from `values. - Query to insert or update key-value pairs (properties) to existing elements in the database. All
ids
must exist in the database. Ifvalues
is set toSingle
the properties will be inserted uniformly to allids
otherwise there must be enoughvalues
for allids
. - The starting point of all queries.
- Query condition. The condition consists of
data
, logic operator and a modifier. - Universal
query
error returned from all query operations. It represents mainly errors from executing queries but the cause of the error may be in exceptional cases aDbError
. Typically however it will contain description of a problem with running a query such as “id/alias does not exist”. - Universal database result. Successful execution of a query will always yield this type. The
result
field is a numerical representation of the result while theelements
are the list ofDbElement
s with database ids and properties (key-value pairs). - Query to remove aliases from the database. It is not an error if an alias to be removed already does not exist.
- Query to create a new index on a given key.
- Query to remove database elements (nodes & edges). It is not an error if any of the
ids
do not already exist. - Query to remove properties from existing elements in the database. All of the specified
ids
must exist in the database however they do not need to have all the listed keys (it is NOT an error if any or all keys do not exist on any of the elements). - Query to search for ids in the database following the graph.
- Query to select aliases of given ids. All of the ids must exist in the database and have an alias.
- Query to select all aliases in the database.
- Query to select all indexes in the database.
- Query to select number of properties (key count) of given ids. All of the ids must exist in the database.
- Query to select only property keys of given ids. All of the ids must exist in the database.
- Query to select elements with all properties of given ids. All ids must exist in the database.
- Query to select elements with only certain properties of given ids. All ids must exist in the database and all of them must have the requested properties.
- The
TransactionMut
is a proxy struct that encapsulates a mutably borrowedDbImpl
. It allows running queries viaexec()
andexec_mut()
.
Enums§
- Comparison of database values (
DbValue
) used bykey()
condition. Supports the usual set of named comparisons:==, !=, <, <=, >, =>
pluscontains()
. The comparisons are type strict except for thecontains
comparison which allows vectorized version of the base type. Notably however it does not support thebytes
and integral types where the “contains” makes little sense (i.e. does 3 contain 1?). - Comparison of unsigned integers (
u64
) used bydistance()
andedge_count*()
conditions. Supports the usual set of named comparisons:==, !=, <, <=, >, =>
. - Ordering for search queries
- Database value is a strongly types value.
- Query condition data
- Logical operator for query conditions
- Query condition modifier
- Database id used in queries that lets you refer to a database element as numerical id or a string alias.
- List of database ids used in queries. It can either represent a list of
QueryId
s or a search query. Search query allows query nesting and sourcing the ids dynamically for another query most commonly with the select queries. - Helper type distinguishing uniform (
Single
) values and multiple (Multi
) values in database queries. - Search algorithm to be used
Traits§
- Trait that allows use of user defined values directly by facilitating translation from/to database primitive types. The names of fields becomes keys of type
String
. Values must be of types that are convertible to/from database primitive types. - Trait for immutable
agdb
database queries. This trait is unlikely to be implementable for user types. - Trait for mutable
agdb
database queries. This trait is unlikely to be implementable for user types. - Minimum set of data operations required by the database to store & retrieve data.
Type Aliases§
- A convenience alias for the
Transaction
type for the defaultDbFile
. - A convenience alias for the
TransactionMut
type for the defaultDbFile
. - The purely in-memory implementation of the database. It has no persistence but offers unmatched performance
- A convenience alias for the
Transaction
type for the defaultDbMemory
. - A convenience alias for the
TransactionMut
type for the defaultDbMemory
. - A convenience alias for the
Transaction
type for the defaultDb
. - A convenience alias for the
TransactionMut
type for the defaultDb
. - Convenience alias for
Cow<'a, [u8]>
.
Derive Macros§
- The derive macro to add
agdb
compatibility to user defined types. It implements [agdb::DbUserValue
] for the type automatically to allow your type to be read and stored from/to the database. If your type contains a fielddb_id: Option<agdb::DbId>
it will be treated specially and will additionally allow shorthand inserts/updates of the elements directly.