Records API

Row containers for file I/O and CRUD inserts.

Records container for file data operations.

This module provides the Records and AsyncRecords classes, which are containers for file data that can be materialized or streaming. Records is designed for file reads and can be used with SQL insert operations.

class moltres.io.records.AsyncLazyRecords(_read_func: Callable[[], Any], _database: 'AsyncDatabase' | None, _schema: Sequence['ColumnDef'] | None = None, _options: dict[str, object] | None = None, _materialized: AsyncRecords | None = None)[source]

Bases: object

Async lazy wrapper for AsyncRecords that materializes on-demand.

AsyncLazyRecords wraps an async read operation and delays materialization until needed. It can be materialized explicitly with await .collect() or automatically when: - Async iteration is used (__aiter__) - insert_into() is called - Used as argument to async DataFrame operations

_read_func

Async callable (coroutine) that returns AsyncRecords when awaited

Type:: Callable[[], Any]

_database

AsyncDatabase reference

Type:: Optional[‘AsyncDatabase’]

_schema

Optional schema information

Type:: Optional[Sequence[‘ColumnDef’]]

_options

Read options

Type:: Optional[dict[str, object]]

_materialized

Cached materialized AsyncRecords (None until materialized)

Type:: Optional[AsyncRecords]

async collect() → AsyncRecords[source]

Explicitly materialize and return AsyncRecords.

Returns:: Materialized AsyncRecords object

async first() → dict[str, object] | None[source]

Return first row or None if empty (auto-materializes).

Returns:: First row dictionary or None if AsyncLazyRecords is empty

async head(n: int = 5) → List[dict[str, object]][source]

Return first n rows as list (auto-materializes).

Parameters:: n – Number of rows to return (default: 5)
Returns:: List of first n row dictionaries

async insert_into(table: str | 'AsyncTableHandle') → int[source]

Insert records into a table (auto-materializes).

Parameters:: table – Table name (str) or AsyncTableHandle
Returns:: Number of rows inserted
Raises:: RuntimeError – If no database is attached

async iter() → AsyncIterator[dict[str, object]][source]

Return an async iterator over rows (auto-materializes).

Returns:: AsyncIterator of row dictionaries

async last() → dict[str, object] | None[source]

Return last row or None if empty (auto-materializes).

Returns:: Last row dictionary or None if AsyncLazyRecords is empty

async rename(columns: Dict[str, str] | str, new_name: str | None = None) → AsyncRecords[source]

Rename columns in records (auto-materializes).

Parameters:

columns – Either a dict mapping old_name -> new_name, or a single column name
new_name – New name for the column (required if columns is a string)

Returns:

New AsyncRecords with renamed columns

Example

>>> async_lazy_records = AsyncLazyRecords(_read_func=lambda: :class:`AsyncRecords`(_data=[{"id": 1}]))
>>> renamed = await async_lazy_records.rename("id", "user_id")
>>> async for row in renamed:
...     print(row)
{"user_id": 1}

async rows() → List[dict[str, object]][source]

Return materialized list of all rows (auto-materializes).

Returns:: List of row dictionaries

property schema: Sequence['ColumnDef'] | None

Get the schema for these records.

Returns:: Schema if available, None otherwise

async select(*columns: str) → AsyncRecords[source]

Select specific columns from records (auto-materializes).

Parameters:: *columns – Column names to select. Must be strings.
Returns:: New AsyncRecords with selected columns

Example

>>> async_lazy_records = AsyncLazyRecords(_read_func=lambda: :class:`AsyncRecords`(_data=[{"id": 1, "name": "Alice"}]))
>>> selected = await async_lazy_records.select("id")
>>> async for row in selected:
...     print(row)
{"id": 1}

async tail(n: int = 5) → List[dict[str, object]][source]

Return last n rows as list (auto-materializes).

Parameters:: n – Number of rows to return (default: 5)
Returns:: List of last n row dictionaries

class moltres.io.records.AsyncRecords(*, data: List[dict[str, object]] | None = None, database: 'AsyncDatabase' | None = None, _data: List[dict[str, object]] | None = None, _generator: Callable[[], AsyncIterator[List[dict[str, object]]]] | None = None, _schema: Sequence['ColumnDef'] | None = None, _database: 'AsyncDatabase' | None = None)[source]

Bases: object

Async container for file data that can be materialized or streaming.

AsyncRecords is NOT an AsyncDataFrame - it does not support SQL operations. It is designed for file reads and can be used with SQL insert operations.

Prefer from_list() or the data / database keyword arguments.

async first() → dict[str, object] | None[source]

Return first row or None if empty.

Returns:: First row dictionary or None if AsyncRecords is empty

classmethod from_dataframe(df: Any, database: 'AsyncDatabase' | None = None) → AsyncRecords[source]: Create AsyncRecords from pandas/polars data (materialized).

classmethod from_dicts(*dicts: dict[str, object], database: 'AsyncDatabase' | None = None) → AsyncRecords[source]: Create AsyncRecords from individual row dictionaries.

classmethod from_list(data: List[dict[str, object]], database: 'AsyncDatabase' | None = None) → AsyncRecords[source]: Create AsyncRecords from a list of dictionaries.

async head(n: int = 5) → List[dict[str, object]][source]

Return first n rows as list.

Parameters:: n – Number of rows to return (default: 5)
Returns:: List of first n row dictionaries
Raises:: ValueError – If n is negative

async insert_into(table: str | 'AsyncTableHandle') → int[source]

Insert records into a table.

Parameters:: table – Table name (str) or AsyncTableHandle
Returns:: Number of rows inserted
Raises:: RuntimeError – If no database is attached

Note

For DataFrame-based operations, consider creating a DataFrame from the data and using df.write.insertInto() instead.

async iter() → AsyncIterator[dict[str, object]][source]

Return an async iterator over rows.

Returns:: AsyncIterator of row dictionaries

async last() → dict[str, object] | None[source]

Return last row or None if empty.

Returns:: Last row dictionary or None if AsyncRecords is empty

async rename(columns: Dict[str, str] | str, new_name: str | None = None) → AsyncRecords[source]

Rename columns in records (in-memory operation).

Parameters:

columns – Either a dict mapping old_name -> new_name, or a single column name (if new_name provided)
new_name – New name for the column (required if columns is a string)

Returns:

New AsyncRecords instance with renamed columns

Raises:

ValueError – If column doesn’t exist or new name conflicts with existing column
RuntimeError – If AsyncRecords is empty

Example

>>> records = :class:`AsyncRecords`(_data=[{"id": 1, "name": "Alice"}], _database=db)
>>> renamed = await records.rename({"id": "user_id", "name": "user_name"})
>>> async for row in renamed:
...     print(row)
{"user_id": 1, "user_name": "Alice"}

async rows() → List[dict[str, object]][source]

Return materialized list of all rows.

Returns:: List of row dictionaries

property schema: Sequence['ColumnDef'] | None: Get the schema for these records.

async select(*columns: str) → AsyncRecords[source]

Select specific columns from records (in-memory operation).

Parameters:

*columns – Column names to select. Must be strings.

Returns:

New AsyncRecords instance with only the selected columns

Raises:

ValueError – If no columns provided or column doesn’t exist
RuntimeError – If AsyncRecords is empty

Example

>>> records = :class:`AsyncRecords`(_data=[{"id": 1, "name": "Alice", "age": 30}], _database=db)
>>> selected = await records.select("id", "name")
>>> async for row in selected:
...     print(row)
{"id": 1, "name": "Alice"}

async tail(n: int = 5) → List[dict[str, object]][source]

Return last n rows as list.

Parameters:: n – Number of rows to return (default: 5)
Returns:: List of last n row dictionaries
Raises:: ValueError – If n is negative

class moltres.io.records.LazyRecords(_read_func: Callable[[], Records], _database: 'Database' | None, _schema: Sequence['ColumnDef'] | None = None, _options: dict[str, object] | None = None, _materialized: Records | None = None)[source]

Bases: Sequence[Mapping[str, object]]

Lazy wrapper for Records that materializes on-demand.

LazyRecords wraps a read operation and delays materialization until needed. It can be materialized explicitly with .collect() or automatically when: - Sequence operations are used (__len__, __getitem__, __iter__) - insert_into() is called - Used as argument to DataFrame operations

_read_func

Callable that returns Records when called (the read operation)

Type:: Callable[[], Records]

_database

Database reference

Type:: Optional[‘Database’]

_schema

Optional schema information

Type:: Optional[Sequence[‘ColumnDef’]]

_options

Read options

Type:: Optional[dict[str, object]]

_materialized

Cached materialized Records (None until materialized)

Type:: Optional[Records]

collect() → Records[source]

Explicitly materialize and return Records.

Returns:: Materialized Records object

first() → dict[str, object] | None[source]

Return first row or None if empty (auto-materializes).

Returns:: First row dictionary or None if LazyRecords is empty

head(n: int = 5) → List[dict[str, object]][source]

Return first n rows as list (auto-materializes).

Parameters:: n – Number of rows to return (default: 5)
Returns:: List of first n row dictionaries

insert_into(table: str | 'TableHandle') → int[source]

Insert records into a table (auto-materializes).

Parameters:: table – Table name (str) or TableHandle
Returns:: Number of rows inserted
Raises:: RuntimeError – If no database is attached

iter() → Iterator[dict[str, object]][source]

Return an iterator over rows (auto-materializes).

Returns:: Iterator of row dictionaries

last() → dict[str, object] | None[source]

Return last row or None if empty (auto-materializes).

Returns:: Last row dictionary or None if LazyRecords is empty

rename(columns: Dict[str, str] | str, new_name: str | None = None) → Records[source]

Rename columns in records (auto-materializes).

Parameters:

columns – Either a dict mapping old_name -> new_name, or a single column name
new_name – New name for the column (required if columns is a string)

Returns:

New Records with renamed columns (materialized)

Example

>>> lazy_records = LazyRecords(_read_func=lambda: :class:`Records`(_data=[{"id": 1}]))
>>> renamed = lazy_records.rename("id", "user_id")
>>> list(renamed)
[{"user_id": 1}]

rows() → List[dict[str, object]][source]

Return materialized list of all rows (auto-materializes).

Returns:: List of row dictionaries

property schema: Sequence['ColumnDef'] | None

Get the schema for these records.

Returns:: Schema if available, None otherwise

select(*columns: str) → Records[source]

Select specific columns from records (auto-materializes).

Parameters:: *columns – Column names to select. Must be strings.
Returns:: New Records with selected columns (materialized)

Example

>>> lazy_records = LazyRecords(_read_func=lambda: :class:`Records`(_data=[{"id": 1, "name": "Alice"}]))
>>> selected = lazy_records.select("id")
>>> list(selected)
[{"id": 1}]

tail(n: int = 5) → List[dict[str, object]][source]

Return last n rows as list (auto-materializes).

Parameters:: n – Number of rows to return (default: 5)
Returns:: List of last n row dictionaries

class moltres.io.records.Records(*, data: List[dict[str, object]] | None = None, database: 'Database' | None = None, _data: List[dict[str, object]] | None = None, _generator: Callable[[], Iterator[List[dict[str, object]]]] | None = None, _dataframe: Any | None = None, _schema: Sequence['ColumnDef'] | None = None, _database: 'Database' | None = None)[source]

Bases: Sequence[Mapping[str, object]]

Container for file data that can be materialized or streaming.

Records is NOT a DataFrame - it does not support SQL operations. It is designed for file reads and can be used with SQL insert operations.

Prefer from_list() or the data / database keyword arguments. Underscore-prefixed fields (_data, _database) are deprecated and will be removed in 2.0.

first() → dict[str, object] | None[source]

Return first row or None if empty.

Delegates to RecordsAccessor.

Returns:: First row dictionary or None if Records is empty

classmethod from_dataframe(df: Any, database: 'Database' | None = None) → Records[source]

Create Records from pandas/polars DataFrame or polars LazyFrame.

Parameters:

df – pandas DataFrame, polars DataFrame, or polars LazyFrame
database – Optional database reference for insert operations

Returns:

Records object with lazy DataFrame conversion

Example

>>> import pandas as pd
>>> df = pd.:class:`DataFrame`([{"id": 1, "name": "Alice"}])
>>> records = :class:`Records`.from_dataframe(df, database=db)
>>> records.insert_into("users")

classmethod from_dicts(*dicts: dict[str, object], database: 'Database' | None = None) → Records[source]

Create Records from multiple dictionary arguments.

Convenience method for creating Records from individual row dictionaries.

Parameters:

*dicts – Individual row dictionaries
database – Optional database reference for insert operations

Returns:

Records object

Example

>>> records = :class:`Records`.from_dicts(
...     {"id": 1, "name": "Alice"},
...     {"id": 2, "name": "Bob"},
...     database=db
... )
>>> records.insert_into("users")

classmethod from_list(data: List[dict[str, object]], database: 'Database' | None = None) → Records[source]

Create Records from a list of dictionaries.

This is the recommended way to create Records from Python data.

Parameters:

data – List of row dictionaries
database – Optional database reference for insert operations

Returns:

Records object

Example

>>> records = :class:`Records`.from_list(
...     [{"id": 1, "name": "Alice"}, {"id": 2, "name": "Bob"}],
...     database=db
... )
>>> records.insert_into("users")

head(n: int = 5) → List[dict[str, object]][source]

Return first n rows as list.

Delegates to RecordsAccessor.

Parameters:: n – Number of rows to return (default: 5)
Returns:: List of first n row dictionaries
Raises:: ValueError – If n is negative

insert_into(table: str | 'TableHandle') → int[source]

Insert records into a table.

Delegates to RecordsWriter.

Parameters:: table – Table name (str) or TableHandle
Returns:: Number of rows inserted
Raises:: RuntimeError – If no database is attached

Note

For DataFrame-based operations, consider creating a DataFrame from the data and using df.write.insertInto() instead.

iter() → Iterator[dict[str, object]][source]

Return an iterator over rows.

Delegates to RecordsAccessor.

Returns:: Iterator of row dictionaries

last() → dict[str, object] | None[source]

Return last row or None if empty.

Delegates to RecordsAccessor.

Returns:: Last row dictionary or None if Records is empty

rename(columns: Dict[str, str] | str, new_name: str | None = None) → Records[source]

Rename columns in records (in-memory operation).

Delegates to RecordsSchema.

Parameters:

columns – Either a dict mapping old_name -> new_name, or a single column name (if new_name provided)
new_name – New name for the column (required if columns is a string)

Returns:

New Records instance with renamed columns

Raises:

ValueError – If column doesn’t exist or new name conflicts with existing column
RuntimeError – If Records is empty

Example

>>> records = Records(_data=[{"id": 1, "name": "Alice"}], _database=db)
>>> renamed = records.rename({"id": "user_id", "name": "user_name"})
>>> list(renamed)
[{"user_id": 1, "user_name": "Alice"}]

>>> renamed = records.rename("id", "user_id")
>>> list(renamed)
[{"user_id": 1, "name": "Alice"}]

rows() → List[dict[str, object]][source]

Return materialized list of all rows.

Delegates to RecordsAccessor.

Returns:: List of row dictionaries

property schema: Sequence['ColumnDef'] | None

Get the schema for these records.

Delegates to RecordsSchema.

select(*columns: str) → Records[source]

Select specific columns from records (in-memory operation).

Delegates to RecordsSchema.

Parameters:

*columns – Column names to select. Must be strings.

Returns:

New Records instance with only the selected columns

Raises:

ValueError – If no columns provided or column doesn’t exist
RuntimeError – If Records is empty

Example

>>> records = Records(_data=[{"id": 1, "name": "Alice", "age": 30}], _database=db)
>>> selected = records.select("id", "name")
>>> list(selected)
[{"id": 1, "name": "Alice"}]

tail(n: int = 5) → List[dict[str, object]][source]

Return last n rows as list.

Delegates to RecordsAccessor.

Parameters:: n – Number of rows to return (default: 5)
Returns:: List of last n row dictionaries
Raises:: ValueError – If n is negative