Skip to content

Dataset Operations

Source: src/memframe/main.py

OpsWrapper is the public dataset-operation interface exposed through MemFrame. It manages uploaded datasets, tracks the active dataset, and reads or records operation history. Each public method has an asynchronous a-prefixed form and a synchronous form. The implementations live on OpsMixin (src/memframe/db_manager/ops.py), which MemFrame inherits, and the connection lifecycle lives on its ConnectorManager.

Public API

Synchronous Asynchronous Purpose
list_tables() await alist_tables() List successful uploads
set_active(data_id) await aset_active(data_id) Set the active dataset (returns a ContextManager)
get_active_table() await aget_active_table() Read the active dataset ID
delete_table(data_id=None, filename=None) await adelete_table(data_id=None, filename=None) Delete an uploaded dataset
list_operations(data_id=None) await alist_operations(data_id=None) List operation history
retrieve_operation(data_id, opidx) await aretrieve_operation(data_id, opidx) Resolve an operation table name

Dataset Management

List Uploaded Datasets

tables = mf.list_tables()

tables = await mf.alist_tables()

The result is ordered from newest to oldest:

[
    {"data_id": "a1b2c3", "filename": "customers.csv"},
    {"data_id": "d4e5f6", "filename": "orders.parquet"},
]

Only registry entries whose upload completed successfully are returned.

Select the Active Dataset

# set_active returns a ContextManager bound to the dataset
ctx = mf.set_active("a1b2c3")
ctx.select_dtypes(include="numeric")   # operate directly on the returned context
active_id = mf.get_active_table()      # still returns the active data_id string

ctx = await mf.aset_active("a1b2c3")

Setting an active dataset first verifies that its upload table exists. set_active/aset_active return a ContextManager you can use for subsequent operations; methods that accept an optional data_id use the active dataset when no ID is given. get_active_table() continues to return the active data_id string.

Delete a Dataset

Delete by data_id:

mf.delete_table(data_id="a1b2c3")

Delete by original filename:

mf.delete_table(filename="customers.csv")

Deletion drops the dataset's generated transient tables, drops its upload table, removes its registry records, and clears the active dataset when necessary.

Warning

Dataset deletion is permanent.

Operation History

List the recorded operations for a dataset:

operations = mf.list_operations("a1b2c3")

Each record contains opidx, operation_type, table_name, and created_at. When no data_id is supplied, list_operations uses the active dataset.

Retrieve the generated table name for one operation:

table_name = mf.retrieve_operation("a1b2c3", opidx=2)

Operation recording is handled internally by memFrame when library operations create generated tables.

Errors

  • Operations that require a database raise RuntimeError when not connected.
  • Selecting an unknown data_id raises DataNotFound.
  • Deletion requires either data_id or filename.
  • Listing operations without a supplied or active dataset raises ValueError.

API Reference

memframe.main.MemFrame

Bases: ContextManager, OpsMixin

alist_tables() async

list_tables()

aset_active(data_id) async

set_active(data_id)

aget_active_table() async

get_active_table()

adelete_table(data_id=..., filename=...) async

delete_table(data_id=..., filename=...)

alist_operations(data_id=...) async

list_operations(data_id=...)

aretrieve_operation(data_id, opidx) async

retrieve_operation(data_id, opidx)