mleku
0e9a772462
Added validation to prevent using contradictory filter criteria (e.g., Ids and NotIds together) and reject negation-only queries as they are impractical. Refactored logic for simplicity and added tests to ensure proper handling of invalid filters.
Manifold Database API Documentation
This document provides an overview of the API functions available in the Manifold database package.
Table of Contents
Database Initialization
New
func New() (d *D)
Creates a new database instance with default settings.
Returns:
d *D: A new database instance
Init
func (d *D) Init(path string) (err error)
Initializes the database with the specified path.
Parameters:
path string: The directory path where the database files will be stored
Returns:
err error: Any error that occurred during initialization
Close
func (d *D) Close() (err error)
Closes the database.
Returns:
err error: Any error that occurred during closing
Path
func (d *D) Path() string
Returns the path where the database files are stored.
Returns:
string: The database directory path
Basic Operations
Set
func (d *D) Set(k, v []byte) (err error)
Sets a key-value pair in the database.
Parameters:
k []byte: The keyv []byte: The value (can be nil)
Returns:
err error: Any error that occurred
Get
func (d *D) Get(k []byte) (v []byte, err error)
Gets a value by key from the database.
Parameters:
k []byte: The key
Returns:
v []byte: The valueerr error: Any error that occurred
View
func (d *D) View(fn func(txn *badger.Txn) (err error)) (err error)
Executes a read-only transaction.
Parameters:
fn func(txn *badger.Txn) (err error): The function to execute within the transaction
Returns:
err error: Any error that occurred
Update
func (d *D) Update(fn func(txn *badger.Txn) (err error)) (err error)
Executes a read-write transaction.
Parameters:
fn func(txn *badger.Txn) (err error): The function to execute within the transaction
Returns:
err error: Any error that occurred
Serial
func (d *D) Serial() (ser uint64, err error)
Returns the next monotonic conflict-free unique serial number.
Returns:
ser uint64: The next serial numbererr error: Any error that occurred
Event Operations
StoreEvent
func (d *D) StoreEvent(ev *event.E) (err error)
Stores an event in the database, creating all necessary indexes.
Parameters:
ev *event.E: The event to store
Returns:
err error: Any error that occurred, including "duplicate event" if the event already exists
GetEventIndexes
func (d *D) GetEventIndexes(ev *event.E) (indices [][]byte, ser *number.Uint40, err error)
Generates all the index entries for an event.
Parameters:
ev *event.E: The event to generate indexes for
Returns:
indices [][]byte: The generated index entriesser *number.Uint40: The serial number assigned to the eventerr error: Any error that occurred
FindEventSerialById
func (d *D) FindEventSerialById(evId []byte) (ser *number.Uint40, err error)
Finds the serial number of an event by its ID.
Parameters:
evId []byte: The event ID
Returns:
ser *number.Uint40: The serial number of the eventerr error: Any error that occurred, including "event not found"
GetEventFromSerial
func (d *D) GetEventFromSerial(ser *number.Uint40) (ev *event.E, err error)
Retrieves an event by its serial number.
Parameters:
ser *number.Uint40: The serial number of the event
Returns:
ev *event.E: The retrieved eventerr error: Any error that occurred
GetEventById
func (d *D) GetEventById(evId []byte) (ev *event.E, err error)
Retrieves an event by its ID.
Parameters:
evId []byte: The event ID
Returns:
ev *event.E: The retrieved eventerr error: Any error that occurred
GetIdPubkeyTimestampFromSerial
func (d *D) GetIdPubkeyTimestampFromSerial(ser *number.Uint40) (id, pk []byte, ts int64, err error)
Retrieves the ID, public key, and timestamp of an event by its serial number.
Parameters:
ser *number.Uint40: The serial number of the event
Returns:
id []byte: The event IDpk []byte: The public keyts int64: The timestamperr error: Any error that occurred
Query Operations
QueryEvents
func (d *D) QueryEvents(f filter.F) (eventIds [][]byte, err error)
Queries events based on the provided filter criteria.
Parameters:
f filter.F: The filter criteria, which can include:Ids [][]byte: Specific event IDs to retrieve (if this field is present, any others will be invalid and return an error)Authors [][]byte: Author public keys to filter byTags map[string][][]byte: Tags to filter bySince int64: Minimum timestamp (inclusive)Until int64: Maximum timestamp (inclusive)NotIds [][]byte: Event IDs to excludeNotAuthors [][]byte: Author public keys to excludeNotTags map[string][][]byte: Tags to excludeSort string: Sort order ("asc" or "desc")
Returns:
eventIds [][]byte: The IDs of events matching the filter criteriaerr error: Any error that occurred
Logging
NewLogger
func NewLogger(logLevel int, label string) (l *logger)
Creates a new logger for the database.
Parameters:
logLevel int: The initial log levellabel string: A label for the logger
Returns:
l *logger: The new logger
SetLogLevel
func (l *logger) SetLogLevel(level int)
Sets the log level of the logger.
Parameters:
level int: The new log level
Log Methods
The logger provides the following methods for logging at different levels:
func (l *logger) Errorf(s string, i ...interface{})
func (l *logger) Warningf(s string, i ...interface{})
func (l *logger) Infof(s string, i ...interface{})
func (l *logger) Debugf(s string, i ...interface{})
Each method takes a format string and optional arguments, similar to fmt.Printf.