Core Tables

This page provides detailed documentation for all tables in the Convexity database schema.

Core Tables

network_metadata

Single row per database containing network-level information.

Column	Type	Required	Description
name	TEXT	Yes	Network name
description	TEXT	No	Network description
time_start	DATETIME	Yes	Start time of simulation period
time_end	DATETIME	Yes	End time of simulation period
time_interval	TEXT	Yes	Time resolution (ISO 8601 format, e.g., "PT1H" for hourly)
locked	BOOLEAN	No	Prevents accidental edits when True
created_at	DATETIME	No	Timestamp when network was created
updated_at	DATETIME	No	Timestamp of last update

network_time_periods

Optimized time period storage using start timestamp and interval.

Column	Type	Required	Description
period_count	INTEGER	Yes	Total number of time periods (e.g., 8760 for hourly year)
start_timestamp	INTEGER	Yes	Unix timestamp of first period
interval_seconds	INTEGER	Yes	Seconds between periods (e.g., 3600 for hourly)

Note: Timestamps are computed on-the-fly rather than stored for each period, saving massive space for large datasets.

carriers

Energy carrier types (electricity, gas, heat, hydrogen, etc.).

Column	Type	Required	Description
id	INTEGER	-	Primary key (auto-increment)
name	TEXT	Yes	Carrier name (unique)
co2_emissions	REAL	No	CO2 emissions factor (tonnes/MWh)
color	TEXT	No	Hex color for visualization
nice_name	TEXT	No	Display-friendly name
max_growth	REAL	No	Maximum absolute growth (MW)
max_relative_growth	REAL	No	Maximum relative growth (per unit)
curtailable	BOOLEAN	No	Whether carrier can be curtailed

scenarios

Alternative scenarios for what-if analysis and stochastic optimization.

Column	Type	Required	Description
id	INTEGER	-	Primary key (auto-increment)
name	TEXT	Yes	Scenario name (unique)
description	TEXT	No	Scenario description
probability	REAL	No	Probability for stochastic optimization (0-1, NULL for deterministic)
is_system_scenario	BOOLEAN	No	True for system-reserved scenarios (e.g., "Actual")
system_purpose	TEXT	No	Purpose of system scenario (e.g., "actual")

Sparse override architecture: Scenarios only store attribute values that differ from the base network, making them memory-efficient.

components

Unified table for all network components (BUS, GENERATOR, LOAD, LINE, LINK, STORAGE_UNIT, STORE, etc.).

Column	Type	Required	Description
id	INTEGER	-	Primary key (auto-increment)
component_type	TEXT	Yes	Component type: BUS, GENERATOR, LOAD, LINE, LINK, STORAGE_UNIT, STORE, UNMET_LOAD, CONSTRAINT, TRANSFORMER, SHUNT_IMPEDANCE
name	TEXT	Yes	Component name (unique across all types)
latitude	REAL	No	Geographic latitude for visualization
longitude	REAL	No	Geographic longitude for visualization
geometry	TEXT	No	GeoJSON geometry (Point, LineString, Polygon)
carrier_id	INTEGER	No	Foreign key to carriers table
bus_id	INTEGER	No	Single bus connection (for generators, loads, storage units)
bus0_id	INTEGER	No	Origin bus for lines/links
bus1_id	INTEGER	No	Destination bus for lines/links

Design note: All component types share this table. The component_type field determines which attributes are valid, enforced by the validation system.

component_attributes

Unified table for all component attributes (both static and time series).

Column	Type	Required	Description
id	INTEGER	-	Primary key (auto-increment)
component_id	INTEGER	Yes	Foreign key to components table
attribute_name	TEXT	Yes	Name of the attribute (e.g., "p_nom", "marginal_cost")
scenario_id	INTEGER	No	Scenario ID (NULL = base network)
storage_type	TEXT	Yes	"static" or "timeseries"
static_value	TEXT	No	JSON-encoded value for static attributes
timeseries_data	BLOB	No	Binary f32 array for time series attributes
data_type	TEXT	Yes	Data type: "float", "boolean", "string", "int"
unit	TEXT	No	Physical unit (MW, MWh, EUR/MWh, etc.)
is_input	BOOLEAN	No	True for inputs, False for outputs

Storage strategy:

• Static values stored as JSON strings (handles all data types)
• Time series stored as raw binary f32 arrays (extremely fast, no compression overhead)
• Exactly one of static_value or timeseries_data must be set

attribute_validation_rules

PyPSA attribute definitions with validation constraints (167+ attributes across all component types).

Column	Type	Required	Description
id	INTEGER	-	Primary key
component_type	TEXT	Yes	Component type this rule applies to
attribute_name	TEXT	Yes	Attribute name (unique per component type)
display_name	TEXT	No	User-friendly display name
data_type	TEXT	Yes	Data type: "float", "boolean", "string", "int"
unit	TEXT	No	Physical unit
default_value	TEXT	No	Default value if not set
allowed_storage_types	TEXT	Yes	"static", "timeseries", or "static_or_timeseries"
is_required	BOOLEAN	No	Whether attribute must be set
is_input	BOOLEAN	No	True for input attributes, False for outputs
min_value	REAL	No	Minimum allowed value for numeric types
max_value	REAL	No	Maximum allowed value for numeric types
allowed_values	TEXT	No	JSON array of allowed values for string types
group_name	TEXT	No	Grouping for UI organization

Data Storage Tables

network_data_store

Generic key-value storage for arbitrary network-level data (configuration, scripts, custom data).

Column	Type	Required	Description
id	INTEGER	-	Primary key
category	TEXT	Yes	Data category (config, results, statistics, scripts)
name	TEXT	Yes	Data item name (unique within category)
data_format	TEXT	No	Format: json, csv, binary, text, yaml, toml
data	BLOB	Yes	Actual data content
metadata	TEXT	No	JSON metadata about the data
checksum	TEXT	No	Data integrity checksum

network_solve_results

Optimization solver results per scenario.

Column	Type	Required	Description
id	INTEGER	-	Primary key
scenario_id	INTEGER	No	Scenario ID (NULL = base network)
solved_at	DATETIME	No	When optimization completed
solver_name	TEXT	Yes	Solver used (highs, gurobi, etc.)
solve_type	TEXT	Yes	Type of optimization (lopf, pf, etc.)
solve_status	TEXT	Yes	Solver status (optimal, infeasible, etc.)
objective_value	REAL	No	Objective function value
solve_time_seconds	REAL	No	Computation time
results_json	TEXT	Yes	Full results as JSON
metadata_json	TEXT	No	Additional solver metadata

network_solve_results_by_year

Year-specific results for capacity expansion models.

Column	Type	Required	Description
id	INTEGER	-	Primary key
scenario_id	INTEGER	No	Scenario ID (NULL = base network)
year	INTEGER	Yes	Investment period year
results_json	TEXT	Yes	Results for this year as JSON
metadata_json	TEXT	No	Additional metadata

Documentation Tables

network_notes

Network-level documentation, todos, and warnings.

Column	Type	Required	Description
id	INTEGER	-	Primary key
title	TEXT	Yes	Note title
content	TEXT	No	Note content (markdown supported)
tags	TEXT	No	JSON array of tags
note_type	TEXT	No	Type: note, todo, warning, info, doc
priority	INTEGER	No	Priority level (for sorting)

component_notes

Component-specific documentation.

Column	Type	Required	Description
id	INTEGER	-	Primary key
component_id	INTEGER	Yes	Foreign key to components table
title	TEXT	Yes	Note title
content	TEXT	No	Note content (markdown supported)
tags	TEXT	No	JSON array of tags
note_type	TEXT	No	Type: note, todo, warning, info, doc
priority	INTEGER	No	Priority level

System Tables

system_metadata

System-level configuration and version tracking.

Column	Type	Required	Description
id	INTEGER	-	Primary key
key	TEXT	Yes	Configuration key (unique)
value	TEXT	Yes	Configuration value
description	TEXT	No	Description of this setting

Standard keys:

• schema_version: Database schema version
• validation_rules_version: Validation rules version
• validation_rules_count: Total number of validation rules

network_config

Network-level configuration parameters with scenario support.

Column	Type	Required	Description
id	INTEGER	-	Primary key
scenario_id	INTEGER	No	Scenario ID (NULL = network defaults)
param_name	TEXT	Yes	Parameter name
param_type	TEXT	Yes	Type: boolean, real, integer, string, json
param_value	TEXT	Yes	Parameter value
param_description	TEXT	No	Parameter description

attribute_scenario_cache

Performance optimization table for quick scenario counting.

Column	Type	Required	Description
component_id	INTEGER	Yes	Component ID (part of composite PK)
attribute_name	TEXT	Yes	Attribute name (part of composite PK)
scenario_count	INTEGER	Yes	Number of scenarios with values
has_base_value	BOOLEAN	Yes	True if base network has value
has_scenario_values	BOOLEAN	Yes	True if any scenarios have values
scenario_details	TEXT	No	JSON array of scenario details

Purpose: Maintained by application code for instant UI updates without querying all scenarios.