Structured Writers and Transactions
Scientific Python in GX-TXT · Module 4 · Lesson 24
The publication of structured data may take multiple steps: declare dimensions and variables, write values and conclude the operation. In this lesson we use the public writer of GX-TXT to create a Synthetic Dataset with two variables and observe the cancellation of a second incomplete publication.
Objectives: to include begin, schema statement, write_variable, finalize and abort; to distinguish a complete Dataset from an undone attempt; to reread the published values.
Prerequisites: Dataset and variables of lessons 19–23, exceptions and Python functions.
A multi-step publication
A writer is the managed object used to prepare and write a Dataset. With DATASET_PUBLICATION_API_v2 the example path is:
begin: prepares the writer for a definition of Dataset.declare_dimension: declares a size and its length.declare_variable: associates with each variable type, rank, size and unit.write_variable: writes the values of declared variables.finalize: concludes the publication.abort: undoes a writer that should not be concluded.
These operations work through the public provider: the script does not directly change the Session log. A transaction is used to prevent an incomplete sequence being presented as a complete publication. Exact guarantees and error conditions depend on the contract and the transaction documented.
Example Data and Scheme
We create corso_python_writer_sintetico with three samples. The time_values variable contains [0.0, 0.5, 1.0] s; signal contains [1.2, 1.5, 1.3] mV. Both are float64, rank 1, associated with the sample size of length 3. The data are synthetic, not experimental measures and have no uncertainty assigned.
The coordinate role signals the time variable; data signals the signal content. Type, form, unity and role must be consistent with values and scientific meaning. The form passed to the writing is [3] for each variable.
Managing the Writer
The try block contains statements, scripts and finalize. If one of these operations raises an exception, the manager asks abort and then uses raise to propagate the error. It doesn’t turn a failure into a successful message. In real applications it is also necessary to consider the case when cleaning itself fails, keeping the message of the original error.
After full publication, we open a second writer for corso_python_writer_annullato, we declare a dimension and call intentionally abort without writing or finalizing. Then we ask for the catalogue: in the execution shown the unsubscribed ID is not present. This is a controlled example of cancellation, not proof of all possible faults or interruptions.
The replace_owned=True option on the full definition allows replacement only when authorized by the provider rules for the manufacturer. Do not replace Dataset of different properties: use a dedicated session and free ID if necessary.
Full code
import numpy as np
from gxtxt import gxtxt_api_call, gxtxt_api_require
gxtxt_api_require("CANONICAL_DATASET_API_v2@2")
gxtxt_api_require("DATASET_PUBLICATION_API_v2@2")
api = "DATASET_PUBLICATION_API_v2"
dataset = "corso_python_writer_sintetico"
definition = {"dataset_id": dataset, "contract": "table.generic", "storage": "hdf5", "replace_owned": True, "provenance": "Teaching Synthetic Data"}
writer = gxtxt_api_call(api, "begin", [definition])
try:
gxtxt_api_call(api, "declare_dimension", [writer, "campione", 3, {"extendible": 0}])
schema_t = {"dtype": "float64", "rank": 1, "dimension_ids": "campione", "unit": "s", "coordinate_role": "coordinate"}
schema_y = {"dtype": "float64", "rank": 1, "dimension_ids": "campione", "unit": "mV", "coordinate_role": "data"}
gxtxt_api_call(api, "declare_variable", [writer, "tempo", schema_t])
gxtxt_api_call(api, "declare_variable", [writer, "segnale", schema_y])
gxtxt_api_call(api, "write_variable", [writer, "tempo", np.array([0.0, 0.5, 1.0]), [3]])
gxtxt_api_call(api, "write_variable", [writer, "segnale", np.array([1.2, 1.5, 1.3]), [3]])
result = gxtxt_api_call(api, "finalize", [writer])
except Exception:
gxtxt_api_call(api, "abort", [writer])
raise
print("Full dataset:", result.get("dataset_id"))
trial_value = "corso_python_writer_annullato"
temporary = gxtxt_api_call(api, "begin", [{"dataset_id": trial_value, "contract": "table.generic", "storage": "hdf5"}])
gxtxt_api_call(api, "declare_dimension", [temporary, "campione", 3, {"extendible": 0}])
gxtxt_api_call(api, "abort", [temporary])
catalog = gxtxt_api_call("CANONICAL_DATASET_API_v2", "list", [])
print("Dateset cancelled present:", trial_value in catalog)
read_result_value = gxtxt_api_call("CANONICAL_DATASET_API_v2", "read_range", [dataset, ["tempo", "segnale"], 0, 3])
print("Tempo (s):", read_result_value["tempo"]["values"].reshape(-1))
print("Segnale (mV):", read_result_value["segnale"]["values"].reshape(-1))
The rereading uses CANONICAL_DATASET_API_v2/read_range: so we compare the published values with the written ones. The reshape(-1) transformation is appropriate for these two single-dimensional variables read as columns; do not apply it without verifying the meaning of the shape in a multi-dimensional Dataset.

The writer declares scheme and values before the publication is completed.
Execution and control
- Open a dedicated session and the Viewer Python Scripts.
- Import
structured_writer.py, assigns name and Script ID into thesessionbroom, then saves. - Open the Runner and press Run Job.
- Check that the output indicates the full Dataset,
Dataset annullato present: Falseand the two sets of three expected values.

The complete Dataset is readable; the canceled attempt does not appear in the catalog shown.
Common error
Declaring a dimension of three elements and writing a different number is not a simple label difference: the scheme and the data would be inconsistent. Check form, type and unit before writing and do not declare publication completed when one of the necessary operations has failed.
Exercise
To publish four samples instead of three, what parts of the example should they change? What control would you use after publication?
Worked solution
It is necessary to declare the sample size with length 4, to provide four consistent values for each variable and to indicate the [4] shape to the scripts. After finalize, reread four rows with the canonical API and compare values, units and schemas with those provided. The data must be clearly identified as synthetic if invented.
In the next module we will use numerical APIs for transformations and models.