Models

CentauroModel

Base class for all stored objects. Extends Pydantic BaseModel.

from centaurodb import CentauroModel

class Sensor(CentauroModel):
    __centauro_name__ = "Sensor"   # required ClassVar[str]
    unit: str = ""                 # all fields need defaults

Class variables

Instance attributes

Default config

CentauroModel sets validate_assignment=True by default — field values are validated on every attribute assignment. See Model Rules for the full constraints, and the Performance Guide for when to opt out.

It also sets populate_by_name=True, which is what allows renamed_from() to read JSON under both the old alias and the current field name.

To disable per-assignment validation:

from pydantic import ConfigDict

class MySensor(CentauroModel):
    __centauro_name__ = "MySensor"
    model_config = ConfigDict(validate_assignment=False, populate_by_name=True)
    value: float = 0.0

CentauroModelSeries

Extends CentauroModel with time-series values. Each instance represents exactly one series of (time, value) pairs.

from centaurodb import CentauroModelSeries

class WeatherStation(CentauroModelSeries):
    __centauro_name__ = "WeatherStation"
    city: str = ""

Additional attributes

CentauroValues

A single time-series data point.

from centaurodb import CentauroValues

val = CentauroValues(time="2025-06-01T08:00:00", value=22.5)

RowFields

Database metadata attached to persisted objects.

parent_ref()

Field helper for declaring one-to-many relationships. Creates a nullable int field that stores the parent object's row.id.

from centaurodb import CentauroModel, parent_ref

class Portfolio(CentauroModel):
    __centauro_name__ = "Portfolio"
    strategy: str = ""

class Trade(CentauroModel):
    __centauro_name__ = "Trade"
    portfolio: int | None = parent_ref(Portfolio)
    symbol: str = ""

Raises — TypeError if parent_model is not a CentauroModel subclass.

The field defaults to None to satisfy the zero-migration rule. CentauroDB enforces non-null at write and update time — an object with an unset parent_ref raises UnlinkedParentError.

You can pass a persisted parent object directly — it auto-resolves to row.id:

coll.write_object(portfolio)
trade = Trade(symbol="AAPL", portfolio=portfolio)  # resolves to portfolio.row.id
trade.portfolio = other_portfolio                   # also works on assignment

Passing an unpersisted parent object raises an exception at construction time. Assigning an unpersisted parent via attribute assignment raises ValueError. Integer ids are still accepted.

The relationship metadata is registered on the child class as __centauro_refs__, which collection helpers (write_child, children_of) use to auto-discover foreign-key fields. Subclasses inherit parent_ref fields from their parent class.

renamed_from()

Field helper for safe renames. Uses Pydantic AliasChoices under the hood.

from centaurodb import renamed_from

class Sensor(CentauroModel):
    __centauro_name__ = "Sensor"
    temperature: float = renamed_from("temp", default=0.0)
    # reads from "temp" or "temperature" in JSON

Field

A query-building class exported from centaurodb. Useful for constructing conditions dynamically when you don't have a reference to the model class at the call site.

from centaurodb import Field

condition = Field("unit") == "Celsius"
results = coll.read_objects(condition)

Operators: ==, !=, >, >=, <, <=, .like(pattern), .is_in(values)

In most cases, prefer the type-safe Model.fields accessor (e.g. Sensor.fields.unit == "Celsius"), which validates field names against the model at construction time. Field is an escape hatch for generic code.

OrGroup

Combine multiple conditions with OR logic. Built by chaining | on conditions:

from centaurodb import OrGroup

group = (Sensor.fields.unit == "Celsius") | (Sensor.fields.unit == "Kelvin")
results = coll.read_objects(group, Sensor.fields.threshold > 50)

OrGroup is also exported for type annotations and isinstance checks. See read_objects for the full query reference.