DuckDB Solution Reader

The DuckDB solution reader converts a PLEXOS solution ZIP with plexos2duckdb and exposes lazy DuckDB relations for analysis. Import it explicitly to distinguish it from the SQLite-backed solution reader:

from plexosdb.db_solution import PlexosSolution

Wrapper of PLEXOS2duckdb.

class plexosdb.db_solution.PlexosSolution(source_path=None, *, model_name=None, _factory_token=None)

Bases: object

PLEXOS solution wrapper backed by plexos2duckdb.

Passing database to to_duckdb() creates or reuses a file-backed DuckDB database, which is the fastest path for large solutions. Omitting database keeps the result in memory by converting through a temporary DuckDB file and copying it into an in-memory DuckDB connection.

Prevent direct construction; use a named factory instead.

Parameters:

  • source_path (str | Path | None)

  • model_name (str | None)

  • _factory_token (object | None)

classmethod from_zip(path, *, model_name=None)

Create a solution wrapper bound to a PLEXOS solution path.

Parameters:

  • path (str | Path)

  • model_name (str | None)

Return type:

PlexosSolution

to_duckdb(database=None, *, if_exists='reuse', n_threads=None, table_name_pattern=None, in_memory=None)

Convert the solution with plexos2duckdb and open a DuckDB connection.

Parameters:

  • database (str | Path | None) – Output DuckDB path. When omitted, the result is in memory unless in_memory=False is provided.

  • if_exists (Literal['fail', 'reuse', 'replace']) – File-backed overwrite policy: 'fail', 'reuse', or 'replace'. Ignored for in-memory conversion because the intermediate database is temporary.

  • n_threads (int | None) – Optional thread count passed to plexos2duckdb for time-series table writes.

  • table_name_pattern (str | None) – Optional regex passed to plexos2duckdb to restrict generated data tables.

  • in_memory (bool | None) – True forces an in-memory final connection, False forces a file-backed database, and None uses in memory when database is omitted.

Return type:

DuckDBResult

info()

Return metadata about the configured or converted DuckDB solution.

Return type:

DuckDBSolutionInfo

list_tables(*, schema='report')

List tables or views in one DuckDB solution schema.

Parameters:

schema (Literal['raw', 'processed', 'data', 'report'])

Return type:

list[TableInfo]

sql(query_string)

Build a lazy DuckDB relation from a SQL query.

Parameters:

query_string (str)

Return type:

DuckDBPyRelation

query(query_string, params=None)

Execute a read-only query and return all rows.

Parameters:

  • query_string (str)

  • params (tuple[Any, ...] | dict[str, Any] | None)

Return type:

list[Any]

query_dicts(query_string, params=None)

Execute a read-only query and return rows as dictionaries.

Parameters:

  • query_string (str)

  • params (tuple[Any, ...] | dict[str, Any] | None)

Return type:

list[dict[str, Any]]

table(table, *, schema='report')

Build a lazy DuckDB relation for a solution table or view.

Parameters:

  • table (str | ResultTable)

  • schema (Literal['raw', 'processed', 'data', 'report'])

Return type:

DuckDBPyRelation

list_objects_by_class(class_enum, /, *, category=None)

Return solution object names for a PLEXOS class.

Parameters:

  • class_enum (ClassEnum | str)

  • category (str | None)

Return type:

list[str]

list_result_tables(*, schema='report', phase=None, period=None, class_enum=None, collection=None, property_name=None)

List result tables using PLEXOS class, collection, and property filters.

Parameters:
Return type:

list[ResultTable]

result_table(*, schema='report', phase=PhaseEnum.ST, period=PeriodEnum.INTERVAL, class_enum=None, collection=None, property_name)

Return one result table matching PLEXOS dimensions.

Parameters:
Return type:

ResultTable

get_result(table_name, /, *, object_names=None, category=None, sample_names='Mean', bands=None, start=None, end=None, columns=None)

Build a lazy relation for filtered rows from a result table.

Parameters:

  • table_name (ResultTable | str)

  • object_names (str | Iterable[str] | None)

  • category (str | None)

  • sample_names (str | Iterable[str] | None)

  • bands (int | Iterable[int] | None)

  • start (str | None)

  • end (str | None)

  • columns (Sequence[str] | None)

Return type:

DuckDBPyRelation

property connection: DuckDBPyConnection

The active DuckDB connection.

close()

Close the active DuckDB connection.

Return type:

None

Result Types

Data models and public type aliases for DuckDB-backed PLEXOS solutions.

class plexosdb.db_solution_models.DuckDBResult(database, tables=<factory>)

Bases: object

Result returned by plexosdb.db_solution.PlexosSolution.to_duckdb().

Parameters:

  • database (Annotated[Path | None, 'Filesystem path of the DuckDB file, or None for an in-memory database.'])

  • tables (Annotated[list[str], 'Names of tables present in the raw DuckDB schema after conversion.'])

database: Annotated[Path | None, 'Filesystem path of the DuckDB file, or None for an in-memory database.']
tables: Annotated[list[str], 'Names of tables present in the raw DuckDB schema after conversion.']
property is_in_memory: bool

Return True when the database lives in memory only.

class plexosdb.db_solution_models.DuckDBSolutionInfo(database, source, model_name=None, converter_version=None)

Bases: object

Metadata about a DuckDB-backed PLEXOS solution.

Parameters:

  • database (Annotated[Path | None, 'Filesystem path of the DuckDB file, or None for an in-memory database.'])

  • source (Annotated[Path | None, 'Path to the original PLEXOS solution source, when known.'])

  • model_name (Annotated[str | None, 'PLEXOS model name recorded by plexos2duckdb.'])

  • converter_version (Annotated[str | None, 'plexos2duckdb converter version.'])

database: Annotated[Path | None, 'Filesystem path of the DuckDB file, or None for an in-memory database.']
source: Annotated[Path | None, 'Path to the original PLEXOS solution source, when known.']
model_name: Annotated[str | None, 'PLEXOS model name recorded by plexos2duckdb.'] = None
converter_version: Annotated[str | None, 'plexos2duckdb converter version.'] = None
class plexosdb.db_solution_models.TableInfo(name, schema, table_type)

Bases: object

Metadata about one table or view in a DuckDB solution schema.

Parameters:

  • name (Annotated[str, 'DuckDB table or view name.'])

  • schema (Annotated[str, 'DuckDB schema containing the table or view.'])

  • table_type (Annotated[str, 'DuckDB information_schema table type.'])

name: Annotated[str, 'DuckDB table or view name.']
schema: Annotated[str, 'DuckDB schema containing the table or view.']
table_type: Annotated[str, 'DuckDB information_schema table type.']
class plexosdb.db_solution_models.ResultTable(name, schema, phase, period, class_enum, collection, property_name, table_type, value_column)

Bases: object

Metadata for one PLEXOS solution result table or view.

Parameters:

  • name (Annotated[str, 'DuckDB table or view name.'])

  • schema (Annotated[Literal['data', 'report'], 'DuckDB schema containing the result.'])

  • phase (Annotated[PhaseEnum, 'PLEXOS solve phase.'])

  • period (Annotated[PeriodEnum, 'PLEXOS result period.'])

  • class_enum (Annotated[ClassEnum | None, 'Object class associated with the result collection.'])

  • collection (Annotated[CollectionEnum, 'PLEXOS collection represented by the result.'])

  • property_name (Annotated[str, 'PLEXOS property represented by the result.'])

  • table_type (Annotated[TableTypeEnum, 'DuckDB information_schema table type.'])

  • value_column (Annotated[str, 'Column containing the result values.'])

name: Annotated[str, 'DuckDB table or view name.']
schema: Annotated[Literal['data', 'report'], 'DuckDB schema containing the result.']
phase: Annotated[PhaseEnum, 'PLEXOS solve phase.']
period: Annotated[PeriodEnum, 'PLEXOS result period.']
class_enum: Annotated[ClassEnum | None, 'Object class associated with the result collection.']
collection: Annotated[CollectionEnum, 'PLEXOS collection represented by the result.']
property_name: Annotated[str, 'PLEXOS property represented by the result.']
table_type: Annotated[TableTypeEnum, 'DuckDB information_schema table type.']
value_column: Annotated[str, 'Column containing the result values.']

See Reading a PLEXOS Solution for a complete ZIP-to-DuckDB workflow.