DataSetBuilder

Utility for building HQ DataSet payloads for BackOffice operations.

Row-state markers:

M = Modified — the new values you want the record to have U = Unchanged — the original values before your edit (for concurrency check) A = Added — a new record (typically uses negative IDs) D = Deleted — a record to remove

For update operations, each modified record requires a pair of rows: a Modified row (new values) and an Unchanged row (original values). HQ compares the Unchanged row against the database to ensure no one else edited the record since you last read it. Without the original values, HQ rejects with error -8.

Use fetch_current() on the endpoint wrapper to GET the current state, then build your Modified row with the changes and the Unchanged row from the original.

For add operations, only an Added row is needed — no prior GET required.

A DataSet payload can contain multiple tables, each with its own columns and rows.

class q2_sdk.hq.models.dataset_builder.RowState(*values)

Bases: Enum

Row-state markers for HQ DataSet rows.

MODIFIED = 'M'

UNCHANGED = 'U'

ADDED = 'A'

DELETED = 'D'

class q2_sdk.hq.models.dataset_builder.DataSetTable(name, columns)

Bases: object

Represents a single table within an HQ DataSet.

Usage:

table = DataSetTable("Q2_User", ["UserID", "FirstName", "LastName"])

# Update: change LastName from "Smith" to "Doe"
table.add_unchanged_row([1, "John", "Smith"])   # original values
table.add_modified_row([1, "John", "Doe"])      # new values

rows: list[dict[str, list]]

add_row(state, values)

Add a row with the given state marker and column values.

Parameters:

• state (RowState) – RowState enum indicating the row’s change state

• values (list[Any]) – List of values corresponding to self.columns (positional)

Return type:

DataSetTable

Returns:

self for chaining

add_modified_row(values)

Shortcut for add_row(RowState.MODIFIED, values).

Return type:

DataSetTable

add_unchanged_row(values)

Shortcut for add_row(RowState.UNCHANGED, values).

Return type:

DataSetTable

add_added_row(values)

Shortcut for add_row(RowState.ADDED, values).

Return type:

DataSetTable

add_deleted_row(values)

Shortcut for add_row(RowState.DELETED, values).

Return type:

DataSetTable

serialize()

Serialize this table to the HQ JSON format.

Return type:

dict

class q2_sdk.hq.models.dataset_builder.DataSetBuilder(dataset_name='NewDataSet')

Bases: BaseParameter

Builds HQ DataSet payloads containing one or more tables.

Passed directly as a parameter value to endpoint ParamsObj instances.

For most update operations, prefer the generated _models.py helpers (e.g., UpdateGroup_models.build_group_edit_dataset()) which handle row construction from typed dataclasses. Use DataSetBuilder directly only when building payloads manually.

Usage:

dataset = DataSetBuilder("DalGroupEdit")
dataset.add_table("Q2_Group", ["GroupID", "GroupDesc"])
dataset.table("Q2_Group").add_unchanged_row([1, "Old Name"])   # original values
dataset.table("Q2_Group").add_modified_row([1, "New Name"])    # new values

params = UpdateGroup.ParamsObj(logger, hq_creds, group_edit=dataset)
await UpdateGroup.execute(params)

add_table(name, columns)

Add a new table to this dataset.

Parameters:

• name (str) – The table name (e.g., “Q2_User”, “Q2_Email”)

• columns (list[str]) – List of column names for this table

Return type:

DataSetTable

Returns:

The created DataSetTable instance

table(name)

Get an existing table by name.

Parameters:

name (str) – The table name

Return type:

DataSetTable

Returns:

The DataSetTable instance

Raises:

KeyError – If the table doesn’t exist

serialize_as_json()

Serialize the entire dataset to HQ’s expected JSON format.

Returns a dict like:

{
    "$type": "DataSet",
    "Q2_User": {"columns": [...], "rows": [...]},
    "Q2_Email": {"columns": [...], "rows": [...]}
}

Return type:

dict

serialize_as_xml()