Close the table, flushing all pending writes to disk.

The table handle must not be used after closing.

Delete all entries and keep the table open.

Delete all values for the given key.

Returns Ok(Nil) even if the key does not exist.

Delete a specific key-value pair from the table.

Only the exact matching pair is removed. Other values for the same key are preserved. This is the primary way to remove individual values from a bag without affecting other entries for the same key.

import gleam/dynamic/decode
let assert Ok(table) = bag.open("tags.dets",
  key_decoder: decode.string, value_decoder: decode.string)
let assert Ok(Nil) = bag.insert(table, "color", "red")
let assert Ok(Nil) = bag.insert(table, "color", "blue")
let assert Ok(Nil) = bag.delete_object(table, "color", "red")
let assert Ok(["blue"]) = bag.lookup(table, "color")

Fold over all entries. Order is unspecified.

Returns Error(DecodeErrors(_)) if any entry does not match the expected types. The fold stops at the first decode error. If the callback raises, the exception is re-raised.

Call your callback once for each entry, in an unspecified order.

Pass the decoded entry as Ok(#(key, value)), or its decode errors as Error(decode_errors). The callback returns the next accumulator value. Unlike fold, this function continues after a decode error.

The function returns Ok(accumulator) when it finishes. A table error, such as TableDoesNotExist, makes the function return Error(error). If the callback raises an exception, that exception propagates to the caller.

Examples

Skip entries that fail to decode:

bag.fold_results(table, [], fn(acc, entry) {
  case entry {
    Ok(#(key, value)) -> [#(key, value), ..acc]
    Error(_) -> acc
  }
})

Collect decoded entries and decode errors separately:

bag.fold_results(table, #([], []), fn(acc, entry) {
  case entry {
    Ok(#(key, value)) -> #([#(key, value), ..acc.0], acc.1)
    Error(errors) -> #(acc.0, [errors, ..acc.1])
  }
})

Get the file size in bytes, entry count, and absolute path of an open table.

Returns Error(TableDoesNotExist) if the table is no longer open.

Insert a key-value pair.

If the pair exists, returns Ok(Nil) without adding another copy.

Multiple distinct values for the same key are stored separately.

Insert multiple key-value pairs.

Repeated pairs do not add extra copies.

Insert a key-value pair only if the exact pair does not already exist.

Returns Error(KeyAlreadyPresent) if the exact key-value pair is already in the table. Use insert when you do not need duplicate detection.

Concurrent calls can both return Ok(Nil) for the same pair. The table still stores one copy. To ensure only one caller reports a new insertion, serialize writes through an owner process.

Look up all values for a key, in an unspecified order.

Returns Ok([]) if the key does not exist. This differs from set.lookup, which returns Error(NotFound) for missing keys. Returns Error(DecodeErrors(_)) if any stored value does not match the expected type.

Check if a key exists without returning the values.

Open or create a DETS bag table at the given file path.

The parent directory must exist. This function uses AutoRepair and ReadWrite.

Reads use your decoders to check stored data. Opening a table does not check all its entries.

import gleam/dynamic/decode
let assert Ok(table) = bag.open("data/tags.dets",
  key_decoder: decode.string, value_decoder: decode.string)

Open or create a DETS bag table with a specific repair policy.

The repair policy controls what happens when the table file was not closed cleanly, for example after an abnormal node shutdown:

• AutoRepair: Attempt repair if needed. This is the default for open.
• ForceRepair: Repair even if the file was closed properly.
• NoRepair: Return NeedsRepair if the file requires repair.

Make a backup before you repair a file with data you need to keep. Repair does not guarantee recovery of all data.

import gleam/dynamic/decode
import slate.{ForceRepair}
let assert Ok(table) = bag.open_with(path: "data/tags.dets",
  repair: ForceRepair,
  key_decoder: decode.string, value_decoder: decode.string)

Open a DETS bag table with repair and access mode options.

Use ReadOnly to open a table for reading only. Write operations on a read-only table will return Error(AccessDenied(context)).

import gleam/dynamic/decode
import slate.{AutoRepair, ReadOnly}
let assert Ok(table) = bag.open_with_access(path: "data/tags.dets",
  repair: AutoRepair, access: ReadOnly,
  key_decoder: decode.string, value_decoder: decode.string)
let assert Ok(values) = bag.lookup(table, key: "key")
// bag.insert(table, "key", "val") would return Error(AccessDenied(context))

Return the number of stored entries, not the number of distinct keys.

Each entry is one key-value pair.

Flush pending writes to disk without closing the table.

By default, DETS saves the table after three minutes without table access. Call sync and handle its result when you need to write pending updates to disk before continuing.

Return all entries as a list in an unspecified order.

This loads the entire table into memory. Returns Error(DecodeErrors(_)) if any entry does not match the expected types.

Use a table under exclusive ownership across OS processes.

All clients, including readers, must participate. Ownership covers open, repair, the callback, and clean close. wait limits acquisition only. Keep the handle within the callback; do not reopen or manually close it. Callback errors do not roll back writes. Exceptions are re-raised after cleanup; cleanup failures are logged. Unconfirmed cleanup can retain ownership until VM exit.

Requires the native component and a qualified local filesystem. Symlinks are resolved; hard-linked data and unsafe sidecars are rejected. Data paths and persistent sidecars must remain stable while clients can run sessions.

Use a table within a callback with repair and access mode options.

Select the repair policy and access mode as for open_with_access. The callback must return a Result. ReadOnly requires an existing file, and writes return Error(AccessDenied(context)). NoRepair returns Error(NeedsRepair(context)) if the file was not closed cleanly.

If opening fails, returns the open error without calling the callback. Otherwise, runs the callback and attempts to close the table. If close fails after a successful callback, returns the close error. If both fail, returns the callback error. If the callback raises, attempts close before re-raising the original exception.

Keep the table handle within the callback; do not use it after cleanup. This cannot guarantee cleanup if the process is killed.

import gleam/dynamic/decode
import slate.{NoRepair, ReadOnly}
import slate/bag

use table <- bag.with_table(path: "data/tags.dets",
  repair: NoRepair, access: ReadOnly,
  key_decoder: decode.string, value_decoder: decode.string)
bag.lookup(table, key: "color")