CanDB

type ScalingLimitType = {#count : Nat; #heapSize : Nat}

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

type ScalingOptions = { autoScalingHook : AutoScalingCanisterSharedFunctionHook; sizeLimit : ScalingLimitType }

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.

type DB = { pk : E.PK; var data : RT.RangeTree; var count : Nat; var scalingOptions : ScalingOptions; var scalingStatus : {#not_started; #started; #complete} }

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

type DBInitOptions = { pk : E.PK; scalingOptions : ScalingOptions }

public func init(options : DBInitOptions) : DB

initializes a CanDB data structure

type GetOptions = { sk : E.SK }

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

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

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

type ReplaceOptions = PutOptions

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

type UpdateOptions = { 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 = { 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 = { 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