Editing databases
Most of what VoLCA reads is background data: Agribalyse, ecoinvent, BAFU. Those are shared by everything running on the engine, so nothing writes to them. What you author goes into a database of your own – one you uploaded, or a copy you made – and references the background through the usual cross-database links.
Where writing is allowed
Section titled “Where writing is allowed”| Database | Writing, editing an inventory | Deleting activities | Saved |
|---|---|---|---|
| Configured in the engine’s TOML | refused | in memory only | – |
| Uploaded, whatever its format | yes | yes | to a journal beside its files |
| A copy of either | yes | yes | to a journal of its own |
“Copy it first” is therefore about the background data the engine is configured with, which every caller shares. A database you uploaded is already yours: it takes an edit directly, and keeps it. If you want a draft rather than a change, copy it because you want a draft – nothing refuses the edit otherwise.
An edit never rewrites the files you uploaded. It is recorded in a journal beside them, and loading the database replays the journal over what the files say. That is what makes every format editable on the same terms: EcoSpold 1, SimaPro CSV, ILCD and Excel derive each process identity from names, categories and the position of a dataset in its file, so rewriting them would have moved every identity at the next read. A file that is never rewritten parses to the same identifiers forever.
A copy shares the source’s value without duplicating its files: it keeps its own identity and its own journal, and reads the files of the database it was copied from. For that reason the source cannot be deleted while a copy of it exists.
Exporting is unaffected: an export is a snapshot that leaves the original in place, and every writer accepts every database.
On a hosted instance
Section titled “On a hosted instance”An instance can be configured read-only, and then it answers every question and changes nothing: writing an activity comes back as a 403, as loading, uploading and deleting already do. That is what a shared instance is – one engine several accounts read at once, where any one caller writing would write for all of them. The free tier is exactly that, so authoring starts on a tier with an instance of its own.
A copy is a database of your own, so it spends the same budget an upload does: one slot of what the plan can store, and one of what it can hold in memory. If a copy is refused, the message says which of the two ran out.
The licence a database is published under
Section titled “The licence a database is published under”A database states the licence it is published under, one of three things:
- a standard licence, such as CC BY or the French Licence Ouverte. What it allows follows from its text, and nobody adjusts it: a CC BY-NC that also refused downloads would no longer be CC BY-NC;
- an own licence: its publisher’s text, what it refuses, whether results must name the publisher, and whether readers accept the text before opening the database;
- no licence stated: nothing is refused, and nothing is claimed either.
A licence settles six permissions: reading the inventory, seeing detailed scores, downloading the export and files, publishing results, reselling the data itself, and using it in a paid application. The Setup page lists what a licence refuses and who holds each refusal. VoLCA holds back three of them, for every reader, the database’s owner included:
- downloading: the export and the files of its literature answer with a 403;
- reading the inventory: the inventory, the supply chain, the consumers, the tree, the graph, the inputs and outputs, the path to a supplier, the aggregation and the comparisons are refused, and an activity names its exchanges, suppliers and compartments without their amounts;
- seeing detailed scores: the contributing flows and activities and the sensitivity are refused, and a score keeps its total and its categories.
Each of these rebuilds the one before it: the files hold the inventory, and the inventory gives back the contributions. So a licence that refuses the detailed scores refuses the inventory and the download too, and one that refuses the inventory refuses the download; the Setup page ticks them together. The other refusals are shown as your commitment, since VoLCA cannot see what happens to a result once it leaves.
On an engine of your own, the owner sets the licence of each uploaded database,
from its Setup page or with PUT /api/v1/db/{name}/licence (set_licence in
Python). GET /api/v1/licences lists the standard ones:
curl -X PUT -H "Authorization: Bearer $VOLCA_TOKEN" \ -H 'Content-Type: application/json' \ -d '{"kind": "own", "text": "Members of the project only", "refused": ["download", "resell"], "attribution": true}' \ https://app.volca.run/@you/private/api/v1/db/my-db/licenceA standard licence is sent as {"kind": "standard", "id": "CC-BY-4.0"}, and
no licence as {"kind": "unstated"}.
A member invited to the engine reads under the licence but cannot change it. A
copy, or a parent or child derived from it, is served under the
licence of the database whose files it reads, so copying a database is no way
round a refusal. A database named in the engine’s configuration file states its
licence there: licence = "CC-BY-4.0" for a standard one, or licence_text,
refuses, attribution and accept for an own one. A downloads key, the
single switch these keys replaced, stops the engine at startup with the line to
write instead: an own licence with refuses = ["download"].
Terms readers accept first
Section titled “Terms readers accept first”An own licence can ask its readers to accept its text before they open the
database: accept = true in the configuration file, "accept": true in the
licence sent to the engine, or the box “Readers accept these terms first” on
the Setup page. A standard licence never asks: its readers are bound by it
without ticking anything.
Until a reader accepts, every request reading the database, or a database
built on it, is refused with a 403 that carries the terms. The web interface
shows them in place of the page, with a checkbox; accepting is remembered by
the browser, in a volca_terms cookie. From Python, read the terms and accept
them for the client:
for terms in c.terms_to_accept("my-db"): print(terms["text"])if input("Do you accept these terms? [y/N] ") == "y": c.accept_terms("my-db")An assistant connected over MCP is handed the terms by the refused tool. It
shows them to you, and calls accept_terms only once you agree. When the text
of the licence changes, readers are asked again.
The name a database is shown under
Section titled “The name a database is shown under”An uploaded database can be renamed from its Setup page: Change, next to its
name, then Save. Only the name it is shown under changes. The identifier in its
address stays, so links to it, the databases built on it and its copies keep
working. With PUT /api/v1/db/{name}/display-name, the body is the new name as
a JSON string; the spaces around it are dropped, and a blank one is refused:
curl -X PUT -H "Authorization: Bearer $VOLCA_TOKEN" \ -H 'Content-Type: application/json' \ -d '"Cheeses"' \ https://app.volca.run/@you/private/api/v1/db/my-db/display-nameFrom Python, c.set_display_name("Cheeses", "my-db"). A database named in the
engine’s configuration file takes its name from displayName there.
Its description, shown on its card, changes the same way: Add or Change next to
it, or PUT /api/v1/db/{name}/description with the text as a JSON string.
Emptying the field, or sending null, removes it. From Python,
c.set_description("Pressed cheeses", "my-db"), None to remove it. A
configured database takes it from description in the configuration file.
The release a database is
Section titled “The release a database is”A database can declare the published release it is: a name, a version and, when it has one, a system model, such as ecoinvent 3.12, Allocation, cut-off by classification. It is what lets a model built on that database be computed on another engine holding the same release. Only the system model is read from the files, and the Setup page proposes it; the name and the version are always declared by the owner, since the files do not carry them.
The owner declares it from the Setup page, or with
PUT /api/v1/db/{name}/release; null removes it:
curl -X PUT -H "Authorization: Bearer $VOLCA_TOKEN" \ -H 'Content-Type: application/json' \ -d '{"name": "ecoinvent", "version": "3.12", "systemModel": "Allocation, cut-off by classification"}' \ https://app.volca.run/@you/private/api/v1/db/my-db/releaseA database named in the engine’s configuration file declares it there:
release = { name = "ecoinvent", version = "3.12", system_model = "..." }. A
copy starts with no release, since it is made to be changed.
Giving a model to another engine
Section titled “Giving a model to another engine”A model built on a database you may not hand over, such as a product that buys
ecoinvent 3.12 electricity, travels as a package: on its Export page, tick
“Package it for another engine”, or send "package": "ro-crate" with
POST /api/v1/db/{name}/export. The result is a .ro-crate.zip holding the
exported file unchanged, beside an RO-Crate description of the licence it is
published under and of the release of every database it links to. Every one of
those databases must have declared its release, or the export is refused and
names the one to declare.
Uploaded to another engine, the package keeps its licence and links only to a database of each release it requires; the others are neither linked nor offered. Its Setup page shows each required release under “Built on”:
- held here: the database of that release is named, and linked;
- not held, but a database of the same name in another version is: a “Use … instead” button accepts it in the release’s place. Scores computed on it will not be the ones the model’s author computed, so the choice is the reader’s, recorded, and shown from then on;
- not held at all: upload that release and declare it, and the package links to it.
The same choice through the API:
curl -X POST -H "Authorization: Bearer $VOLCA_TOKEN" \ -H 'Content-Type: application/json' \ -d '{"release": {"name": "ecoinvent", "version": "3.12", "systemModel": "Allocation, cut-off by classification"}, "database": "ecoinvent-3.11"}' \ https://app.volca.run/@you/private/api/v1/db/my-model/accept-substitutionThe engine checks the package’s fingerprint and refuses one whose file was changed. It does not check that you hold the right to the releases it requires: that is between you and their publisher.
What changed, and why
Section titled “What changed, and why”Some licences let you change their data only if you say what you changed and why, ship that record with the changed data, and label it as changed. VoLCA keeps that record for you, for every database.
Every change can carry a reason. In the web interface, edit mode and the texts
form have a Why this change? field, and so does the confirmation of a
deletion; the reason typed goes with each change saved until you rewrite it.
Through the API it is a note beside the change:
POST /api/v1/db/my-copy/activity/{process_id}/exchanges{"setAmounts": [{"select": {"kind": "biosphere", "flow": "{flow-id}"}, "amount": 3.0}], "note": "Measured on site, March 2026"}In Python it is note= on every write (client.edit_exchanges(pid, set_amounts=[...], note="Measured on site, March 2026")), and an assistant
passes note to edit_exchanges and edit_database_parameters. A reason is
optional: a change saved without one is listed as such.
The database’s page then has a History tab, and the engine answers
GET /api/v1/db/{name}/history (client.database_history(), the
get_database_history tool): each change in words, its date, its reason, and
each line it touched with the value it replaced:
2026-10-20 09:14 UTC Edited "bread" (FR) Reason: Measured on site, March 2026 - Flow "Carbon dioxide": amount from 1.2 set to 3.0A database holding any change, or divided otherwise than its
files declare, is modified data: its card and its pages say so, and it is
exported only as a package. Its .ro-crate.zip carries, beside the data,
CHANGES.md, which names the original it was made from, says that the
publisher of the original did not make these changes, and lists every change
with its reason, and LICENCE.txt, the licence it is served under in plain
words. A plain export of it is refused with a sentence saying so; the web
interface and pyvolca ask for the package themselves.
Dividing a database by price or by mass
Section titled “Dividing a database by price or by mass”A process with several products is divided between them. Most databases are
read under declared, the shares the source file states (the allocation key
described in Configuration). To see what price,
dry mass or wet mass would have said instead, you derive the database in two
steps, both from the same Duplicate form that copies a database.
First a parent: the source’s files read again with every process of several products kept whole, each declared share turned into a price. That is a full load, and it takes minutes on a large database.
Then a child of that parent, divided by a system model: a small TOML file naming the property every process of several products is divided by, and the exceptions, each with its own property, the reason for it, and the processes it takes.
name = "Agribalyse, economic"version = "1.0.0"
[allocation]default = "price"
[[allocation.exceptions]]key = "wet mass"reason = "Dairies weigh their milk, not its price."classification = { system = "Category", value = "Agricultural\\Food\\Cheese production" }The child is divided from the parent as it stands, its edits included: a price changed on the parent reaches the child the next time it is loaded. The model is kept beside the child as written, and the child’s page gives it back with the processes each exception takes. A model naming a key the engine does not read, an exception without a reason, one that takes no process or divides none of those it takes, and a process two exceptions take are each refused with what is wrong. On a read-only instance nothing can be held at all, so this is not available on the free tier, for the same reason writing is not.
A model can also leave a coproduct out of the division and substitute it: count what it displaces instead of giving it a share. The swine slurry digester of Agribalyse 4.0 makes 978.4 kg of digestate and 18 m³ of biogas; at 65 % methane, a m³ of biogas displaces 23.3 MJ of natural gas.
[[substitutions]]coproduct = "<digester>_<biogas>"replaces = "<natural gas furnace>_<its heat>"ratio = 23.3reason = "Biogas at 65 % methane displaces natural gas of the same heating value."Both are written activity_product, and the process replaced must be in the
parent. In the child the biogas row becomes an avoided product of
18 × 23.3 = 419.4 MJ of natural gas, credited against the furnace, and the
digestate carries the rest of the digester. A process that bought the biogas
buys natural gas instead, at the same ratio. A substitution that names a
product the parent does not make, leaves a block with no product, or would
credit a block the model leaves whole is refused with what is wrong.
A model can also set a method parameter: an input parameter of the parent’s
processes taken at another value. Agribalyse 4.0 writes the European recycling
formula into its packaging processes as parameters of each process. R1, R2
and R3 are data: how much recycled material goes in, how much is recycled or
burned at end of life. A and B are choices of method: how the benefit of
recycling and of energy recovery is shared. The corrugated cardboard end of life
has A = 0.2 and R2 = 0.689, and avoids (1 - A) * R2 * Qsout_Qp / cardboard_waste
= 0.434 kg of virgin linerboard.
[[method_parameters]]name = "A"value = 1reason = "Cut-off: recycled material is credited neither on input nor at end of life."In the child, every process of the parent that declares A as an input
parameter takes it at 1, and its amounts are computed again: the cardboard’s
avoided linerboard and its recycling line fall to 0, its landfill and
incineration lines are unchanged. The child’s model page lists the processes
each parameter moves. Agribalyse also multiplies its incineration lines by
(1 - B), so B = 1 removes the incineration of the waste along with its
energy credit. A name no process declares, a process that computes it by a
formula, or one that reads it from the database’s parameters without declaring
it is refused with what is wrong.
A child’s package is its delivery sheet. Beside the export and CHANGES.md, it
holds system-model.toml, the model as written, and allocation.csv, one row
per process the model changed, cut from a block of the parent or moved by a
method parameter, with the parent’s process it comes from, its share and the
rule that gave it:
process_id,parent_process_id,activity,product,share_percent,rule<dairy>_<whey>,<dairy>_<cheese>,Cheese dairy,Whey,75,"wet mass, exception: Dairies weigh their milk, not its price."<digester>_<digestate>,<digester>_<digestate>,Digester,Digestate,100,"substitution: Biogas at 65 % methane displaces natural gas of the same heating value."<mill>_<bran>,<mill>_<flour>,Mill,Wheat bran,7.1,"price, default key"<cardboard EoL>_<waste>,<cardboard EoL>_<waste>,Cardboard end of life,Cardboard waste,100,"as the parent has it; parameter A = 1 ""Cut-off: recycled material is credited neither on input nor at end of life."""A process not listed is the parent’s as it stands, untouched by the model. The same row is on the process’s page, under its information tab, with a link to the parent’s process. The package also names the parent by the SHA-256 digests of its source files, of the patches applied to them and of its journal of changes, and the division as an action of the engine, with its version, on that parent and that model. The parent’s own package carries the same digests, so the two can be matched. For a parent read from a directory, the digest of its files is what this prints in that directory:
find . -type f -printf '%P\n' | LC_ALL=C sort | xargs -d '\n' sha256sum | sha256sumA parent exports with its blocks whole. In EcoSpold 2 the other products of a
block are written as coproducts, each with its dry mass and its price. In an
openLCA package each block carries one economic allocation factor per product,
its share under price, so openLCA divides it as the child divided by price
does. Where the prices cannot weigh a block, as when an expert’s price in euros
stands beside prices deduced from shares, the factors are the shares its
products declare, and the export names those blocks with the reason.
From Python, each step is one call:
client.derive_database("agribalyse-32-parent", parent=True, db_name="agribalyse-32")client.derive_database("agribalyse-32-economic", system_model="economic.toml", db_name="agribalyse-32-parent")Identity is minted, not chosen
Section titled “Identity is minted, not chosen”You never supply a process_id. The engine derives it from four things you do
supply – activity name, location, product name, product unit – so writing the
same description twice addresses the same row.
That is what makes correcting an activity a correction rather than a duplicate. It also means changing any of those four describes a different activity: to rename one you wrote, write the new one and delete the old. An activity you imported is renamed in place instead (below).
Changing an activity you imported
Section titled “Changing an activity you imported”An activity that came out of a file cannot be re-described. Its identity was minted by the parser that read it, from that file’s names and categories, so a description written by hand addresses a different row – and a description carries less than the file did anyway: classification, synonyms, parameters, pedigree, allocation and coproducts have nowhere to go in it.
So an imported activity is changed by naming only what moves, lines or texts:
POST /api/v1/db/my-copy/activity/{process_id}/exchanges{"remove": [{"kind": "biosphere", "flow": "{flow-id}"}], "setAmounts": [{"select": {"kind": "input", "provider": "{process-id}"}, "amount": 2.5}], "addInputs": [{"provider": "{process-id}", "amount": 1.2}], "setLocation": "CH", "setDescription": ["Corrected from the 2024 farm survey."]}Everything the request does not name stays exactly as it was. setName,
setLocation and setDescription (one string per paragraph, an empty list
clears it) restate the activity’s texts under the process id it already has,
on every product of the activity. Of the exchanges, only the inventory side is
addressable – an input by its supplier, a waste output by its
treatment, a flow of nature by its flow – because the reference product and the
coproducts are what the activity is, not what it exchanges.
A line that names no supplier of its own, such as a line the engine linked to
a supplier in another database, is addressed by its flow and the location it
states instead: {"kind": "input", "flow": "{flow-id}", "location": "FR"}.
There is no need to work out which form a line takes: each exchange that
get_activity returns carries its selector, ready to send back. Two lines
naming no supplier, of one flow and one location, share a selector, and an edit
changes both.
A selector that matches nothing is refused rather than quietly doing nothing,
and one that matches several lines changes all of them and says how many. The
answer counts what happened per selector: {"removed": [2], "amountsSet": [1], "added": 1, "textsSet": ["location", "description"], "transient": false, "warnings": []}.
The same edit is a call in Python (client.edit_exchanges(...)), a command
(volca database edit-exchanges), a tool an assistant can use
(edit_exchanges), and, in the web interface, the Edit exchanges button on
each of an activity’s four exchange tabs. In edit mode each amount and each
formula is underlined: a click opens a field under its row, and each row gains a
bin to remove it. The tab’s own add button opens a picker for the kind of line
that tab lists. The Edit name, location and description button on its
documentation tab opens its texts.
Parameters and formulas
Section titled “Parameters and formulas”A line can carry a formula instead of a bare number, and an activity can carry
parameters its formulas read. Take a bakery: a parameter yield = 0.8, and the
flour line with the formula 1 / yield, so 1.25 kg of flour. Formulas are
written in VoLCA’s own formula language,
whatever format the database came from.
The same edit request sets them:
POST /api/v1/db/my-copy/activity/{process_id}/exchanges{"setParameters": [{"name": "yield", "value": 0.5}], "setFormulas": [{"select": {"kind": "input", "provider": "{flour-id}"}, "formula": "1 / yield + 0.1"}]}A parameter states a value (with an uncertainty if it varies) or a
formula whose value the engine computes, never both, and it is replaced
whole: a unit or a description left out is dropped. removeParameters takes
names, and is refused while a formula still reads the name, naming that
formula. A formula of null drops the line’s formula and keeps its amount.
After the edit, every line whose formula no longer gives its amount takes the
formula’s value, and the answer lists those lines under restated with the
amount they moved from and to. Here the flour line moves from 1.25 to 2.1.
A database has parameters of its own as well, read by every process that has
no parameter of the same name. GET /api/v1/db/{db}/parameters lists them, and
POST /api/v1/db/{db}/parameters with setParameters and removeParameters
edits them; every process that reads an edited one is restated the same way,
and the answer names those processes.
To score at other values without changing the database, send them with the
scoring request instead: parameters: [{"name": "yield", "value": 0.5}], with
a process for a process’s own parameter.
In the web interface, the field a line’s amount or formula opens takes either.
Typing 2 on the flour line sets 2 kg and drops 1 / yield, which would
otherwise give 1.25 back; typing 2 / yield writes a formula, checked by the
engine as you type. On a line that other formulas read by its name, a number
becomes the line’s formula, so the name they read stays. The
Edit parameters button on the Parameters tab makes each value and formula
clickable the same way, for the process’s own parameters and the database
parameters it reads. On the Impacts page, values typed under Parameter
values score the activity at those values without changing it.
Scenarios
Section titled “Scenarios”A scenario is a set of parameter values saved under a name on the database,
such as “high salt” for salt_kg at 0.02:
PUT /api/v1/db/my-copy/scenarios/high%20salt{"parameters": [{"name": "salt_kg", "value": 0.02}]}Saving under a name already taken replaces what it held.
GET /api/v1/db/{db}/scenarios lists them and DELETE drops one. Saving one
changes nothing in the database: to score a scenario, send its values as the
parameters of a scoring request. Values a scoring request would refuse are
refused when saved, and a scenario that a later edit has made unusable (a
parameter removed) is listed with the problem. Scenarios are kept on a database
you uploaded or copied, and a copy takes them along; a database the engine
reads from its configuration refuses them, since they would be lost at the next
restart.
An openLCA package brings its own scenarios: each parameter set of a product
system is listed as one, named after the system (“PV system: Long life”), and
marked shipped, on any database, the configured ones included. It applies
like a saved one, but it cannot be dropped, since it comes back at every load,
and saving under its name is refused: choose another name.
On the Impacts page, the typed parameter values are saved under a name with Save as scenario, and each scenario of the database is listed with Apply and Drop; one the database ships is tagged “from the database” and its Drop is disabled.
In Python: edit_exchanges(..., set_parameters=[SetParameter(...)], set_formulas=[SetFormula(...)], remove_parameters=[...]),
database_parameters(), edit_database_parameters(...), scenarios(),
save_scenario(name, [ParameterValue(...)]) and drop_scenario(name). An
assistant has edit_exchanges, get_database_parameters,
edit_database_parameters, list_scenarios, save_scenario, drop_scenario,
and check_formula to try a formula before writing it.
Exporting parameters and formulas
Section titled “Exporting parameters and formulas”An export writes the database’s parameters and formulas, not only the amounts they give, so the file read back elsewhere still moves when a parameter does. What each format keeps:
- SimaPro CSV: database and process parameters, and each line’s formula.
- openLCA JSON-LD: global and process parameters, and each line’s formula. The product systems the package was read with are written back, carrying their parameter sets and every saved scenario that still applies (one a later edit made unusable is left out and named). A saved scenario named after a system (“PV system: Hot climate”) goes on that system as the set “Hot climate”; any other goes on the first system, by name, that has no set of that name and shares its name with no other system. A database read from another format has no product system, so its saved scenarios are left out, and the export says so. No other format keeps scenarios.
- EcoSpold 2: each dataset carries its own parameters and formulas, and a line keeps the name other formulas read it by. The format has no database-wide parameter, so each dataset also carries a copy of the database parameters it reads; one that no dataset reads is not written, and the export says so.
- Brightway Excel: database and activity parameters, and a
formulacolumn on the exchanges, written in Brightway’s Python. Brightway recomputes a line’s formula only in an activity with parameters of its own; the export names the activities that have formulas and none. - EcoSpold 1 and ILCD: the amounts only.
A formula a format cannot express is written as the value it gives, and the
export’s warnings name it (the first ten, then how many more): one using a
function the format lacks, or reading a parameter named like one of the
format’s reserved words (sum in Brightway), which is left out. The warnings come with every export, in the
X-Volca-Export-Warnings header of POST /api/v1/db/{db}/export and on the
Export page.
Writing is strict
Section titled “Writing is strict”Importing a 20 000-dataset file is tolerant on purpose: a row whose supplier does not resolve is warned about and dropped, because refusing the whole file over one line helps nobody. Authoring is the opposite situation – you are here, the batch is small, and every defect is fixable on the spot. So:
- a supplier that does not resolve is an error, not a dropped line;
- an amount that is not a finite non-zero number is an error;
- a unit that cannot be converted into the supplier’s is an error;
- a biosphere exchange must be stated in its flow’s own unit, because the biosphere matrix carries amounts through unconverted.
Everything wrong with a batch comes back at once, each complaint naming the activity and the exchange it belongs to, and nothing is written until it all passes.
A biosphere line names its flow in words – name, compartment, unit – or by identifier. Words reach the flow the database already declares under them, so an emission written the way an inventory shows it lands on the curated flow rather than on a copy of it. The compartment is the whole compartment: a flow recorded in “water, river” is reached by that sub-compartment, not by “water” alone, and a line that drops the sub-compartment describes a different flow.
What words cannot decide, they refuse. A name several flows answer to comes back with their identifiers, so you can name the one you mean; the exception is two flows of one name in two units, an energy carrier in kg and in MJ, which the unit the line already states tells apart. A unit the flow does not use comes back too, rather than being converted.
A name nothing answers to introduces a flow, and that comes back as a warning rather than an error: no characterization factor matches a brand-new flow by identity, so it scores as zero in every method until one is mapped to it. Its unit still has to be one the database knows, because the unit is half of what makes the new flow that flow.
Deriving from an activity that exists
Section titled “Deriving from an activity that exists”Starting from a row the database already holds is the common case, and a read hands back what a write takes. An input hands back the process that supplies it, which is exactly what a written input names; a biosphere exchange hands back its flow’s name, compartment and unit, which is exactly what a written one names, and its identifier for the lines words cannot address, a name two flows answer to or a flow whose source recorded no compartment. So an inventory can be restated line for line.
Compare like with like when you do: a derivative missing the source’s emissions scores lower for that reason alone, so the honest baseline is the same inventory written the same way, without the substitution.
From Python
Section titled “From Python”from volca import ActivityInput, BioExchange, Client, TechInput
client = Client(db="my-database")client.copy_database("my-database-draft")
written = client.create_activities( ActivityInput( name="yogurt, at dairy", location="FR", product_name="yogurt", product_amount=1.0, product_unit="kg", inputs=[TechInput(provider="5b0f…_c16c…", amount=1.2)], biosphere=[BioExchange.from_name("Carbon dioxide", "air", "emission", 0.8, "kg")], ), db_name="my-database-draft",)print(written["written"]) # the process ids you can now ask aboutreplace_activity(process_id, activity) rewrites one that is already there.
Both return {"written", "transient", "warnings"}; transient is true when
the edit lives in memory only.
From the command line
Section titled “From the command line”The same JSON document works over either transport:
volca database create-activities my-database-draft --from activities.jsonvolca database replace-activity my-database-draft --process-id 5b0f…_c16c… --from one.jsonA worked example
Section titled “A worked example”The derived-activity example copies a database, writes an existing activity into the copy twice, first with its technosphere inputs alone and then with a single supplier substituted, scores the two, and prints the per-category change.