Skip to content
47 changes: 47 additions & 0 deletions docs/source/howtos/add_properties.md
Original file line number Diff line number Diff line change
Expand Up @@ -81,6 +81,53 @@ db.add_property(
)
```

## Updating Properties

Use `update_property` to change the value of an existing property without
removing its scenario, band, date, or text metadata:

```python
db.update_property(
"Generator1",
"Max Capacity",
125.0,
object_class=ClassEnum.Generator,
)
```

When a property has multiple bands, pass `band` to update only the matching
band. Pass `scenario` to update a scenario-specific value. If `scenario` is
omitted, only the base, non-scenario property is updated.

```python
db.update_property(
"Generator1",
"Heat Rate",
9.8,
object_class=ClassEnum.Generator,
band=2,
scenario="High Demand",
)
```

The `collection` and `parent_class` arguments can be supplied when the property
belongs to a non-default collection or membership:

```python
db.update_property(
"Generator1",
"Max Capacity",
130.0,
object_class=ClassEnum.Generator,
collection=CollectionEnum.Generators,
parent_class=ClassEnum.System,
)
```

The method raises `NotFoundError` when the object or matching property row does
not exist, and `NameError` when the property is invalid for the selected
collection.

## Bulk Adding Properties

For efficiency when adding many properties at once (use the flat format; the
Expand Down
34 changes: 34 additions & 0 deletions docs/source/howtos/bulk_operations.md
Original file line number Diff line number Diff line change
Expand Up @@ -70,6 +70,40 @@ Key performance features:
- Direct SQL execution with prepared statements
- Automatic property enablement (sets `is_dynamic` and `is_enabled` flags)

## Bulk Updating Properties

Use `update_properties` to update several existing property values in one
transaction. Each update record uses the same selectors as `update_property`:
`object_name`, `property_name`, `new_value`, and `object_class`. The optional
`scenario`, `band`, `collection`, and `parent_class` fields narrow the matching
property row.

```python
updates = [
{
"object_name": "Generator1",
"property_name": "Max Capacity",
"new_value": 125.0,
"object_class": ClassEnum.Generator,
},
{
"object_name": "Generator2",
"property_name": "Heat Rate",
"new_value": 9.8,
"object_class": ClassEnum.Generator,
"band": 2,
"scenario": "High Demand",
},
]

db.update_properties(updates)
```

All updates are committed together. If an update cannot find its object,
property, scenario, or requested band, the transaction fails and earlier updates
in the batch are rolled back. When `scenario` is omitted, the update targets the
base property rather than a scenario-tagged row.

### Handling Different Object Classes

You can process different types of objects separately:
Expand Down
Loading