SingleCanisterCanDB

The CanDB module, containing all methods for initializing and interacting with the CanDB data structure

type DB = HT.HashTree

The CanDB data structure - an alias for the HashTree data structure (for more, see the HashTree code/documentation)

public func init() : DB

initializes a CanDB data structure

public func initPreSized(initCapacity : Nat) : DB

initializes a CanDB data structure of specific pk size Note: use this only when you know the starting size of your DB by the number of distinct pks

type GetOptions = { pk : E.PK; sk : E.SK }

public func get(db : DB, options : GetOptions) : ?E.Entity

Get an entity if exists in the DB

type PutOptions = { pk : E.PK; sk : E.SK; attributes : [(E.AttributeKey, E.AttributeValue)] }

public func put(db : DB, options : PutOptions) : ()

Create an entity or replace an entity if exists in the DB

type ReplaceOptions = PutOptions

public func replace(db : DB, options : ReplaceOptions) : ?E.Entity

Create an entity or replace an entity if exists in the DB, returning the replaced entity

type UpdateOptions = { pk : E.PK; sk : E.SK; updateAttributeMapFunction : (?E.AttributeMap) -> E.AttributeMap }

public func update(db : DB, options : UpdateOptions) : ?E.Entity

Similar to replace(), but provides the ability to pass a developer defined update function controlling how specific attributes of the entity are updated on match.

See the create() and update() functions in examples/simpleDB/src/main.mo, and the tests in updateSuite() in test/HashTreeTest for some examples of how to use CanDB.update()

type DeleteOptions = { pk : E.PK; sk : E.SK }

public func delete(db : DB, options : DeleteOptions) : ()

Removes an entity from the DB if exists

type RemoveOptions = DeleteOptions

public func remove(db : DB, options : RemoveOptions) : ?E.Entity

Remove an entity from the DB and return that entity if exists

type ScanOptions = { pk : E.PK; skLowerBound : E.SK; skUpperBound : E.SK; limit : Nat; ascending : ?Bool }

Options passed to scan

pk - type Text: The Partition Key skLowerBound - The Sort Key lower bound to scan from (inclusive) skUpperBound - The Sort Key upper bound to scan from (inclusive) limit - The limit of entries to scan within the sk bounds at a given time ascending - Determines the order of results and where scanning will start from, defaults to ascending (starting from the skLowerBound and ending at the skUpperBound)

type ScanResult = { entities : [E.Entity]; nextKey : ?E.SK }

Return type of scan()

entities - array of entities that match the scan nextKey - next key to be evaluated when the scan limit is hit, is ideal for pagination (i.e. if the limit was hit and the user desires to scan/view more matching results)

public func scan(db : DB, options : ScanOptions) : ScanResult

Scans the DB by partition key, a lower/upper bounded sort key range, and a desired result limit Returns 0 or more items from the db matching the conditions of the ScanOptions passed