Documentation

17. API Reference

Every public function, class, signature, return type, and usage note in one place.

Core imports

from relpy import RelPy, AutoNumber, col, AND, OR, NOT
from relpy import count, sum_, avg, min_, max_
from relpy import (
    RelPyError, SchemaError, TableNotFoundError, ColumnNotFoundError,
    ConstraintError, QueryError, QueryTypeError, ViewError,
    NoRowsFoundError, MultipleRowsFoundError, EncryptionError,
)

Schema

Function	Signature	Returns
`create_table`	`create_table(table_name: str) → self`	Creates an empty table.
`add_column`	`add_column(table, name, type, *, is_primary_key, nullable, default, references, on_delete, is_pii, is_encrypted) → self`	Adds a typed column with optional constraints.
`set_primary_key`	`set_primary_key(table: str, columns: list[str]) → self`	Defines a composite primary key.
`describe_table`	`describe_table(table: str) → dict`	Column metadata for one table.
`describe_schema`	`describe_schema() → dict`	Full schema metadata for all tables.

Data operations

Function	Signature	Returns
`insert`	`insert(table: str, values: dict) → dict`	Inserts one row; returns the stored row (plaintext).
`insert_many`	`insert_many(table: str, rows: list[dict]) → list[dict]`	Batch insert with optimised index rebuild.
`update`	`update(table, values, where=None, allow_all=False) → int`	Updates matching rows. Returns count updated.
`delete`	`delete(table, where=None, allow_all=False) → int`	Deletes matching rows. Returns count deleted.

Query builder (chainable)

All methods below are called on the object returned by db.query(table).

Method	Description
`.where(condition)`	Filter rows. Accepts `col()` conditions, `AND()`, `OR()`, `NOT()`.
`.select(*columns)`	Project specific columns by name.
`.order_by(col, descending=False)`	Sort by one or more columns. Alias: `.orderby()`.
`.limit(n)`	Return at most n rows.
`.offset(n)`	Skip the first n rows.
`.distinct()`	Remove duplicate rows from projected result.
`.join(table, on=None, left_on=None, right_on=None, method="inner")`	Join another table. FK inferred automatically if `on` not given.
`.inner_join(table)`	Shortcut for `method="inner"`.
`.left_join(table)`	Shortcut for `method="left"`.
`.right_join(table)`	Shortcut for `method="right"`.
`.full_join(table)`	Shortcut for `method="full"`.
`.cross_join(table)`	Cartesian product.
`.natural_join(table)`	Join on columns with matching names.
`.group_by(*columns)`	Switch query to grouped mode.
`.aggregate(**kwargs)`	Define aggregate expressions. Each kwarg becomes a result column.
`.having(condition)`	Filter on aggregated values. Must follow `.aggregate()`.

Terminal methods

Method	Returns	Notes
`.to_list()`	`list[dict]`	Execute query, return all rows.
`.first()`	`dict \| None`	First row or `None`.
`.one()`	`dict`	Exactly one row; raises on 0 or 2+.
`.exists()`	`bool`	True if at least one row matches.
`.pluck(column)`	`list`	Flat list of values for one column.
`.count()`	`int`	Row count.
`.sum(column)`	`number`	Sum of column.
`.avg(column)` / `.average()`	`float`	Mean of column.
`.min(column)`	value	Minimum value.
`.max(column)`	value	Maximum value.

`col()` expressions

col("x") == v       col("x") != v
col("x") > v        col("x") >= v
col("x") < v        col("x") <= v
col("x").like("%pattern%")
col("x").in_(["a", "b", "c"])
col("x").between(lo, hi)
col("x").is_null()
col("x").is_not_null()

# logical
(cond_a) & (cond_b)    # AND
(cond_a) | (cond_b)    # OR
~cond_a                # NOT

AND(cond_a, cond_b, ...)
OR(cond_a, cond_b, ...)
NOT(cond_a)

Aggregate functions (for use in `.aggregate()`)

count()             # COUNT(*)
count("column")     # COUNT(column) — skips None
sum_("column")      # SUM(column)
avg("column")       # AVG(column)
min_("column")      # MIN(column)
max_("column")      # MAX(column)

Views

Function	Signature	Returns
`create_view`	`create_view(name: str, callable) → self`	Register a named query.
`view`	`view(name: str) → Query`	Execute the view callable and return its `Query`.
`drop_view`	`drop_view(name: str) → self`	Remove a view.
`list_views`	`list_views() → list[str]`	All registered view names.
`describe_view`	`describe_view(name: str) → dict`	Metadata for one view.
`describe_views`	`describe_views() → list[dict]`	Metadata for all views.

Indexes

Function	Signature	Notes
`create_index`	`create_index(table, column, unique=False) → self`	Accepts a single column name or a list for composite indexes.
`drop_index`	`drop_index(index_name: str) → self`
`list_indexes`	`list_indexes() → list[str]`
`describe_index`	`describe_index(name: str) → dict`
`describe_indexes`	`describe_indexes() → list[dict]`

Exports

Function	Returns	Notes
`to_list(table, column_name=None, where_key=None, decrypt=False)`	`list[dict] \| list`	Python dicts. Pass `decrypt=True` to reveal encrypted values.
`to_json(table, column_name=None, where_key=None, decrypt=False)`	`str`	JSON string.
`to_pandas(table, column_name=None, where_key=None, decrypt=False)`	`DataFrame`	Requires pandas installed.
`to_numpy(table, column_name=None, where_key=None, decrypt=False)`	`ndarray`	Requires NumPy installed.
`to_sql(table, where_key=None, decrypt=False)`	`str`	SQL `INSERT` statements.
`to_ddl()`	`str`	SQL `CREATE TABLE` statements for the full schema.
`print_table(table, limit=None, decrypt=False)`	prints	Pretty-prints a table to stdout.

Persistence

Function	Signature	Notes
`save`	`save(path: str) → None`	Serialises schema, data, and index definitions to JSON. Views are not saved.
`load`	`RelPy.load(path, encryption_key=None) → RelPy`	Class method. Restores full state including AutoNumber sequences.

Encryption

Function / flag	Notes
`RelPy.generate_encryption_key()`	Returns a new Fernet key as bytes. Store this securely — it is never saved to the JSON file.
`RelPy(encryption_key=key)`	Pass key at construction time.
`db.set_encryption_key(key)`	Set key after construction.
`is_encrypted=True` in `add_column`	Encrypts stored values; exports show `[ENCRYPTED]` by default.
`decrypt=True` in export functions	Reveals plaintext. Requires a key to be loaded.

← 16. Errors 18. Examples →

17. API Reference

Core imports

Schema

Data operations

Query builder (chainable)

Terminal methods

col() expressions

Aggregate functions (for use in .aggregate())

Views

Indexes

Exports

Persistence

Encryption

`col()` expressions

Aggregate functions (for use in `.aggregate()`)