IQSDataTable Interface

IQSDataTable is the core data‑access interface of the Maestro framework. It exposes asynchronous methods to retrieve, insert, update (implicitly), and delete records in a structured, table‑centric way. All operations work against a single underlying table (_TableName, TableInfo) and support two execution modes:

Immediate execution – the command is sent straight to the database.
Batch queuing – the generated SQL is added to a batch queue identified by a BatchId, allowing multiple operations to be committed together later.

Every data‑returning method delivers a DataTable, a scalar value, or a strongly‑typed IQSDataTableRow. Parameters for record identification can be a unique string Id or a decimal Serial, depending on the developer's preference, business logic, or availability. Many methods also accept a comma‑separated or list‑based TargetFields to limit the columns returned.

The interface is initialized using the QSAppContext object using the table name or its unique Guid identifier, for example:

IQSDataTable _targetTable = QSAppContext.Tables["TableName"];

or its unique Guid identifier:

IQSDataTable _targetTable = QSAppContext.Tables[Guid.Parse("some‑table‑guid")];

where "some‑table‑guid" is the unique identifier of the target table within the QSAppContext.

Guid tableId = Guid.Parse("some‑table‑guid");
IQSDataTable _targetTable = QSAppContext.Tables[tableId];

Once initialized, the IQSDataTable instance can be used to perform a wide range of data operations on the specified table.

Data Retrieval by Unique ID

GetByIdAsync

public async Task<DataTable> GetByIdAsync(string Id, string TargetFields = "")

Retrieves a DataTable for a given unique identifier, with optional column selection.

Parameters

Name	Type	Description
`Id`	`string`	The unique record identifier.
`TargetFields`	`string` (optional)	Comma‑separated column list; empty = all columns.

Returns

Task<DataTable> – a table containing the matching row, or an empty table if not found.

Example

DataTable customer = await table.GetByIdAsync("00000000-0000-0000-0000-000000000001");
DataTable limited = await table.GetByIdAsync("00000000-0000-0000-0000-000000000001", "Name,Email");

Data Retrieval by Serial Number

GetBySerialAsync

public async Task<DataTable> GetBySerialAsync(decimal serial, string TargetFields = "")

Retrieves a DataTable for a given decimal serial number, with optional column selection.

Parameters

Name	Type	Description
`serial`	`decimal`	The unique serial number.
`TargetFields`	`string` (optional)	Comma‑separated column list; empty = all columns.

Returns

Task<DataTable> – table with the matching row or empty if not found.

Example

DataTable invoice = await table.GetBySerialAsync(5001);
DataTable limited = await table.GetBySerialAsync(5001, "InvoiceID,Amount");

Scalar Value Retrieval

GetScalarValueByIdAsync

public async Task<object?> GetScalarValueByIdAsync(string Id, string TargetField)

Returns a single column value for the record identified by Id. The result must be cast by the caller.

Parameters

Name	Type	Description
`Id`	`string`	Unique identifier.
`TargetField`	`string`	Column name to return.

Returns

Task<object?> – the column value, or null if no matching record exists.

Example

string? name = (string?)await table.GetScalarValueByIdAsync("00000000-0000-0000-0000-000000000001", "Name");
decimal? sales = (decimal?)await table.GetScalarValueByIdAsync("00000000-0000-0000-0000-000000000001", "TotalSales");

GetScalarValueBySerialAsync

public async Task<object?> GetScalarValueBySerialAsync(decimal Serial, string TargetField)

Returns a single column value for the record identified by Serial.

Parameters

Name	Type	Description
`Serial`	`decimal`	Unique serial number.
`TargetField`	`string`	Column name to return.

Returns

Task<object?> – value or null.

Example

string? product = (string?)await table.GetScalarValueBySerialAsync(1001.50m, "ProductName");

Row Retrieval (Strongly Typed)

GetRowByIdAsync

public async Task<IQSDataTableRow> GetRowByIdAsync(string Id, Guid BatchId, string TargetFields = "")

Returns a fully initialised IQSDataTableRow for the given Id and batch context. The row contains table metadata, data, and pre‑built fields/grids.

Parameters

Name	Type	Description
`Id`	`string`	Unique record identifier.
`BatchId`	`Guid`	Batch identifier for the operation.
`TargetFields`	`string` (optional)	Comma‑separated columns; empty = all.

Returns

Task<IQSDataTableRow> – the built row, or null if the ID wasn't found.

Example

Guid batchId = Guid.NewGuid();
IQSDataTableRow row = await table.GetRowByIdAsync("00000000-0000-0000-0000-000000000001", batchId);
if (row != null) { string name = row["Name"].ToString(); }

GetRowBySerialAsync

public async Task<IQSDataTableRow> GetRowBySerialAsync(decimal serial, Guid BatchId, string TargetFields = "")

Returns a fully initialised IQSDataTableRow for the given serial number.

Parameters

Name	Type	Description
`serial`	`decimal`	Unique serial number.
`BatchId`	`Guid`	Batch identifier.
`TargetFields`	`string` (optional)	Comma‑separated columns.

Returns

Task<IQSDataTableRow> or null.

Example

IQSDataTableRow row = await table.GetRowBySerialAsync(5001, batchId);

Filtered Retrieval (WHERE Clause)

GetRecordsByWhereStatementAsync

public async Task<List<Dictionary<string, object>>> GetRecordsByWhereStatementAsync(string predicate, List<string> TargetFields = null)

Retrieves multiple records as a list of dictionaries. Only the specified TargetFields are included in each dictionary.

Parameters

Name	Type	Description
`predicate`	`string`	SQL `WHERE` clause (without the keyword).
`TargetFields`	`List<string>` (optional)	List of column names to return.

Returns

Task<List<Dictionary<string, object>>> – an empty list if no match.

Example

var active = await table.GetRecordsByWhereStatementAsync(
    "Status = 'Active'", new List<string> { "Id", "Name" });

GetRowsByWhereStatementAsync

public async Task<List<IQSDataTableRow>> GetRowsByWhereStatementAsync(string predicate, Guid BatchId, List<string> TargetFields = null)

Retrieves multiple fully built IQSDataTableRow objects that satisfy the predicate.

Parameters

Name	Type	Description
`predicate`	`string`	SQL `WHERE` clause.
`BatchId`	`Guid`	Batch identifier for each row.
`TargetFields`	`List<string>` (optional)	Columns to include.

Returns

Task<List<IQSDataTableRow>> – empty list if none.

Example

var pending = await table.GetRowsByWhereStatementAsync(
    "Status = 'Pending'", batchId, new List<string> { "OrderId", "Amount" });

Aggregate Operations

GetAggregateValueByWhereStatementAsync

public async Task<object> GetAggregateValueByWhereStatementAsync(string predicate, string aggregateFunction, string targetField)

Computes an SQL aggregate (SUM, AVG, COUNT, MAX, MIN) on a filtered set of records.

Parameters

Name	Type	Description
`predicate`	`string`	Filter expression.
`aggregateFunction`	`string`	Aggregate function name.
`targetField`	`string`	Column to aggregate; use `"*"` for `COUNT`.

Returns

Task<object> – the computed value (boxed), or null if no rows match.

Example

decimal? total = (decimal?)await table.GetAggregateValueByWhereStatementAsync(
    "Status = 'Active'", "SUM", "Amount");

Adding Records

AddRecordByDictionaryAsync

public async Task<int> AddRecordByDictionaryAsync(Dictionary<string, object?> record, Guid BatchId, bool ImmediateAction = false)

Inserts a new record using a dictionary of column‑value pairs. If ImmediateAction is true, the insert is executed straight away; otherwise it is queued.

Parameters

Name	Type	Description
`record`	`Dictionary<string, object?>`	Column name → value mapping.
`BatchId`	`Guid`	Batch identifier.
`ImmediateAction`	`bool` (default `false`)	If `true`, execute immediately.

Returns

Task<int> – immediate: rows affected (usually 1); queued: 1 for success.

Example

var dict = new Dictionary<string, object?> { {"Id", "CUST-005"}, {"Name", "Jane Doe"} };
int result = await table.AddRecordByDictionaryAsync(dict, batchId, true);

AddRecordByNameValueAsync

public async Task<int> AddRecordByNameValueAsync(NameValueCollection record, Guid BatchId, bool ImmediateAction = false)

Inserts a new record using a NameValueCollection. Internally converted to a dictionary and forwarded to AddRecordByDictionaryAsync.

Parameters

Name	Type	Description
`record`	`NameValueCollection`	String key–value pairs.
`BatchId`	`Guid`	Batch identifier.
`ImmediateAction`	`bool` (default `false`)	Execution mode.

Returns

Task<int> – rows affected (immediate) or 1 (queued).

Example

var nvc = new NameValueCollection();
nvc.Add("Id", "PROD-101"); nvc.Add("Price", "29.99");
int res = await table.AddRecordByNameValueAsync(nvc, batchId);

Deleting Records

DeleteRecordByIdAsync

public async Task<int> DeleteRecordByIdAsync(string RecordId, Guid BatchId, bool ImmediateAction = false)

Deletes the record with the given RecordId. Supports immediate execution or batch queuing.

Parameters

Name	Type	Description
`RecordId`	`string`	Unique identifier of the record to delete.
`BatchId`	`Guid`	Batch identifier.
`ImmediateAction`	`bool` (default `false`)	If `true`, delete immediately.

Returns

Task<int> – deleted rows (immediate) or 1 (queued).

Example

await table.DeleteRecordByIdAsync("CUST-006", batchId, true);

DeleteRecordBySerialAsync

public async Task<int> DeleteRecordBySerialAsync(decimal Serial, Guid BatchId, bool ImmediateAction = false)

Deletes the record with the given Serial number.

Parameters

Name	Type	Description
`Serial`	`decimal`	Unique serial number.
`BatchId`	`Guid`	Batch identifier.
`ImmediateAction`	`bool` (default `false`)	If `true`, execute immediately.

Returns

Task<int> – deleted rows (immediate) or 1 (queued).

Example

await table.DeleteRecordBySerialAsync(5001, batchId);

DeleteRecordAsync

public async Task<int> DeleteRecordAsync(IQSDataTableRow record, Guid BatchId, bool ImmediateAction = false)

Deletes a record represented by an IQSDataTableRow object. The row’s Id field is used to generate the delete statement.

Parameters

Name	Type	Description
`record`	`IQSDataTableRow`	The row to delete (Id is extracted automatically).
`BatchId`	`Guid`	Batch identifier.
`ImmediateAction`	`bool` (default `false`)	If `true`, delete immediately.

Returns

Task<int> – deleted rows (immediate) or 1 (queued).

Example

IQSDataTableRow row = await table.GetRowByIdAsync("CUST-006", batchId);
int result = await table.DeleteRecordAsync(row, batchId, true);

DeleteRecordsByWhereStatementAsync

public async Task<int> DeleteRecordsByWhereStatementAsync(string predicate, Guid BatchId, bool ImmediateAction = false)

Deletes all records that match a WHERE predicate. The generated SQL is DELETE FROM [QS].[table] WHERE predicate;.

Parameters

Name	Type	Description
`predicate`	`string`	SQL `WHERE` condition.
`BatchId`	`Guid`	Batch identifier.
`ImmediateAction`	`bool` (default `false`)	If `true`, execute immediately.

Returns

Task<int> – rows affected (immediate) or 1 (queued).

Example

int deleted = await table.DeleteRecordsByWhereStatementAsync(
    "Status = 'Cancelled'", batchId, true);