The CanDB module, containing all methods for initializing and interacting with the CanDB data structure
Auto-Scaling Limit Type
A developer can choose to auto-scale by the count of entities that have been inserted or by the canister heap size
ScalingOptions
autoScalingHook - The auto-scaling shared function in charge of scaling (located on the Index canister) sizeLimit - the auto-scaling limit for the canister: either limit the auto-scaling by the count or the heap size of the canister
Once a canister passes the sizeLimit, it will trigger an inter-canister call from the canister storage partition to the autoScalingHook to spin up a new canister for that partition. Then the scaling status is set to #complete, meaning that further insertions (after messages processed in that same consensus round) are sent to the newly spun up canister. However, updates to existing entity records in a canister storage partition can still happen until the canister hits the 1.75GB limit, held via the HEAP_SIZE_UPDATE LIMIT constant.
CanDB Core
pk - the partition key of the CanDB instance. This also corresponds to the PK of the canister storage partition data - where the data for CanDB is stored count - the size/count of elements in CanDB (can be used for limit) scalingOptions - ScalingOptions
public func init(options : DBInitOptions) : DB
initializes a CanDB data structure
public func skExists(db : DB, sk : E.SK) : Bool
Returns a boolean indicating if an entity with a matching SK is present in CanDB
public func get(db : DB, options : GetOptions) : ?E.Entity
Get an entity if it exists in the DB
public func put(db : DB, options : PutOptions) : async ()
Create an entity or replace an entity if exists in the DB Auto scales by signaling the index canister to create a new canister with this PK if at capacity
public func replace(db : DB, options : ReplaceOptions) : async ?E.Entity
Create an entity or replace an entity if exists in the DB, returning the replaced entity Auto scales by signaling the index canister to create a new canister with this PK if at capacity
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()
public func delete(db : DB, options : DeleteOptions) : ()
Removes an entity from the DB if exists
public func remove(db : DB, options : RemoveOptions) : ?E.Entity
Remove an entity from the DB and return that entity if exists
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)
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