Crate agdb

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("db4.agdb").unwrap();
db.exec_mut(QueryBuilder::insert().nodes().values([[("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) } ] } ] }

Modules

test_utilities

Structs

DbElement

Database element used in [QueryResult] that represents a node or an edge.

DbError

Universal agdb database error. It represents any error caused by the database processing such as loading a database, writing data etc.

DbF64

Database float is a wrapper around f64 to provide functionality like comparison. The comparison is using total_cmp standard library function. See its docs to understand how it handles NaNs and other edge cases of floating point numbers.

DbId

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 of 0 is logically invalid (there cannot be element with id 0) and a default.

DbImpl

An instance of the agdb database. To create a database:

DbKeyValue

Database key-value pair (aka property) attached to database elements. It can be constructed from a tuple of types that are convertible to DbValue.

FileStorage

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). The StorageData::read() always returns owning buffer.

FileStorageMemoryMapped

The default implementation of the database storage implementing StorageData. It combines the FileStorage and MemoryStorage leveraging the former for the persistence and the latter for performance. The read operations are implemented in terms of the MemoryStorage only and the write operations are implemented in terms of both FileStorage and MemoryStorage.

InsertAliasesQuery

Query to insert or update aliases of existing nodes. All ids must exist. None of the aliases can be empty. If there is an existing alias for any of the elements it will be overwritten with a new one.

InsertEdgesQuery

Query to inserts edges to the database. The from and to ids must exist in the database. There must be enough values for all new edges unless set to Single in which case they will be uniformly applied to all new edges. The each flag is only useful if from 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 insertseach` is assumed.

InsertIndexQuery

Query to create a new index on a given key.

InsertNodesQuery

Query to insert nodes to the database. Only one of count, values or aliases need to be given as the implementation will derive the count from the other parameters. If values is set to Single either count or aliases must be provided however. If values are not set to Single there must be enough value for count/aliases unless they are not se and the count is derived from `values.

InsertValuesQuery

Query to insert or update key-value pairs (properties) to existing elements in the database. All ids must exist in the database. If values is set to Single the properties will be inserted uniformly to all ids otherwise there must be enough values for all ids.

KeyValueComparison

Comparison of a value stored under specific key to a value using the comparison operator.

MemoryStorage

QueryBuilder

The starting point of all queries.

QueryCondition

Query condition. The condition consists of data, logic operator and a modifier.

QueryError

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 a DbError. Typically however it will contain description of a problem with running a query such as “id/alias does not exist”.

QueryResult

Universal database result. Successful execution of a query will always yield this type. The result field is a numerical representation of the result while the elements are the list of DbElements with database ids and properties (key-value pairs).

RemoveAliasesQuery

Query to remove aliases from the database. It is not an error if an alias to be removed already does not exist.

RemoveIndexQuery

Query to create a new index on a given key.

RemoveQuery

Query to remove database elements (nodes & edges). It is not an error if any of the ids do not already exist.

RemoveValuesQuery

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).

SearchQuery

Query to search for ids in the database following the graph.

SelectAliasesQuery

Query to select aliases of given ids. All of the ids must exist in the database and have an alias.

SelectAllAliasesQuery

Query to select all aliases in the database.

SelectEdgeCountQuery

Query to select number of edges of given node ids. All of the ids must exist in the database. If any of the ids is not a node the result will be 0 (not an error).

SelectIndexesQuery

Query to select all indexes in the database.

SelectKeyCountQuery

Query to select number of properties (key count) of given ids. All of the ids must exist in the database.

SelectKeysQuery

Query to select only property keys of given ids. All of the ids must exist in the database.

SelectNodeCountQuery

Query to select number of nodes in the database.

SelectValuesQuery

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.

Transaction

The Transaction is a proxy struct that encapsulates an immutably borrowed DbImpl. It allows running queries via exec().

TransactionMut

The TransactionMut is a proxy struct that encapsulates a mutably borrowed DbImpl. It allows running queries via exec() and exec_mut().

Enums

Comparison

Comparison of database values (DbValue) used by key() condition. Supports the usual set of named comparisons: ==, !=, <, <=, >, => plus contains(). The comparisons are type strict except for the contains comparison which allows vectorized version of the base type. Notably however it does not support the bytes and integral types where the “contains” makes little sense (i.e. does 3 contain 1?).

CountComparison

Comparison of unsigned integers (u64) used by distance() and edge_count*() conditions. Supports the usual set of named comparisons: ==, !=, <, <=, >, =>.

DbKeyOrder

Ordering for search queries

DbValue

Database value is a strongly types value.

QueryConditionData

Query condition data

QueryConditionLogic

Logical operator for query conditions

QueryConditionModifier

Query condition modifier

QueryId

Database id used in queries that lets you refer to a database element as numerical id or a string alias.

QueryIds

List of database ids used in queries. It can either represent a list of QueryIds or a search query. Search query allows query nesting and sourcing the ids dynamically for another query most commonly with the select queries.

QueryValues

Helper type distinguishing uniform (Single) values and multiple (Multi) values in database queries.

SearchQueryAlgorithm

Search algorithm to be used

Traits

AgdbSerialize

DbUserValue

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.

DbUserValueMarker

Marker trait for user values to get around conflicting trait implementations between database and blanket std implementations. Implement it or use the derive macro agdb::UserValueMarker for custom types that are to be used with the database.

Query

Trait for immutable agdb database queries. This trait is unlikely to be implementable for user types.

QueryMut

Trait for mutable agdb database queries. This trait is unlikely to be implementable for user types.

StableHash

StorageData

Minimum set of data operations required by the database to store & retrieve data.

Type Aliases

Db

The default implementation of the database using memory mapped file (full ACID) with write ahead log. If your data set exceeds available (or reasonable amount) of memory consider using DbFile instead. You can load the file created with DbFile and vice versa.

DbFile

The file based implementation of the database (full ACID) with write ahead logging and but minimum memory footprint but slower than the default Db. You can load the file created with Db and vice versa.

DbFileTransaction

A convenience alias for the Transaction type for the default DbFile.

DbFileTransactionMut

A convenience alias for the TransactionMut type for the default DbFile.

DbMemory

The purely in-memory implementation of the database. It has no persistence but offers unmatched performance.

DbMemoryTransaction

A convenience alias for the Transaction type for the default DbMemory.

DbMemoryTransactionMut

A convenience alias for the TransactionMut type for the default DbMemory.

DbTransaction

A convenience alias for the Transaction type for the default Db.

DbTransactionMut

A convenience alias for the TransactionMut type for the default Db.

StorageSlice

Convenience alias for Cow<'a, [u8]>.

Derive Macros

AgdbDeSerialize

The derive macro to add agdb platform agnostic serialization support. This is only needed if you want to serialize custom complex data structures and do not want or cannot use serde. It is primarily used internally to serialize the agdb data structures.

UserValue

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.

UserValueMarker

The helper derive macro to add agdb compatibility to user defined types. This type provides blank implementation of the agdb::DbUserValueMarker trait. This is needed for the vectorized custom values to be compatible with the database as the From trait implementation witohut it conflicts with the blanket implementations.