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("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

• 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.
• 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.
• 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.
• SelectQuery
  Query to select elements with all properties of given ids. All ids must exist 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

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

• 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. If your type contains a field db_id: Option<agdb::DbId> it will be treated specially and will additionally allow shorthand inserts/updates of the elements directly.