Crate agdb

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("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, running queries, 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:
DbKeyOrders
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.
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§

AnyStorage: The enum that can hold any of the other storage types and that implements the StorageData trait by delegating to the inner storage type. When constructed with AnyStorage::new() it will be the memory mapped variant.
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
DbType: 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.
DbTypeMarker: 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::DbTypeMarker 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.
DbAny: A convenience alias for a Db type that can use any implemented storage (mapper, memory or file).
DbAnyTransaction: A convenience alias for the Transaction type for the default DbAny.
DbAnyTransactionMut: A convenience alias for the TransactionMut type for the default DbAny.
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§

DbElement: The same as DbType but additionally implements DbType::db_element_id() allowing more streamlined selection and search of strongly typed elements. This derive adds additional element property to the element representation in the database of type (String, String), i.e. ("db_element_id", <usertypename>.to_string()).
DbSerialize: 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.
DbType: The derive macro to add agdb compatibility to user defined types. It implements [agdb::UserDbType] for the type automatically to allow your type to be read and stored from/to the database.
DbTypeMarker: The helper derive macro to add agdb compatibility to user defined types. This type provides blank implementation of the agdb::DbTypeMarker trait. This is needed for the vectorized custom values to be compatible with the database as the From trait implementation without it conflicts with the blanket implementations.
DbValue: The derive macro to allow automatically serializing user types into DbValue::Bytes. Useful when deriving DbType for a custom type with nested custom types or enums as it avoids the need to manually implement From/TryFrom for such nested types. It does additionally support enums and vectorized types (Vec<T>).

Crate agdb

Crate agdb Copy item path

§Example

Modules§

Structs§

Enums§

Traits§

Type Aliases§

Derive Macros§

Crate agdb