GetRowsByWhereStatementAsync
Part of the IQSDataTable interface, this method retrieves multiple rows as strongly‑typed IQSDataTableRow objects. It filters records using a custom SQL‑style WHERE condition and returns each matching row fully initialised with metadata, fields, child grids, and a batch identifier.
the (BatchId) is used to associate the each row retrieved with a logical group of operations, which is useful for tracking the fields modifications and used later when calling SaveBatchAsync(BatchId) or SaveBatchOnlyAsync(BatchId) to determine which fields have been modified and apply the corresponding updates to the data source.
Asynchronously returns a list of IQSDataTableRow (List<IQSDataTableRow>). If no records match the predicate, the list is empty. You can limit the columns fetched by supplying a list of target field names.
Signature
public async Task<List<IQSDataTableRow>> GetRowsByWhereStatementAsync(string predicate, Guid BatchId, List<string> TargetFields = null)Parameters
| Name | Type | Description |
|---|---|---|
predicate | string | The SQL WHERE clause (without the keyword WHERE) used to filter rows. Example: "Status = 'Active' AND Age > 18". |
BatchId | Guid | A batch identifier that groups this operation with others. Every returned IQSDataTableRow is tagged with this BatchId. |
TargetFields | List<string> (optional) | The list of column names to include in each row. When null or omitted, a default set of fields is retrieved (implementation‑specific). |
Returns
A Task<List<IQSDataTableRow>> representing the asynchronous operation. Each IQSDataTableRow in the result is fully built, containing the table’s name and metadata, the underlying DataRow, the given BatchId, and pre‑initialised fields.
Notes
No need to add a WHERE keyword to the predicate string; just provide the condition itself.
No need to add a SELECT clause or specify the table name; the method handles that internally.
No need to add Id field in the TargetFields list, it will be included by default.
If no rows satisfy the predicate, an empty list is returned (never null).
Example Usage
// Define the data table
IQSDataTable ordersTable = QSAppContext.Tables["Orders"];
// Filter criteria and batch context
string wherePredicate = "Status = 'Pending' AND TotalAmount > 1000";
Guid batchId = Guid.NewGuid();
List<string> fields = new List<string> { "OrderId", "CustomerName", "TotalAmount" };
// Retrieve fully initialised rows
List<IQSDataTableRow> pendingOrders = await ordersTable.GetRowsByWhereStatementAsync(wherePredicate, batchId, fields);
foreach (IQSDataTableRow orderRow in pendingOrders)
{
string customer = orderRow["CustomerName"].ToString();
decimal amount = (decimal)orderRow["TotalAmount"];
string orderInfo = $"{customer} – {amount}";
// Modifications to the row's fields will be tracked under the given batchId context
orderRow["Status"] = "Processing";
// Later, when you call SaveBatchAsync(batchId), only the modified fields will be updated in the data source.
await QSAppContext.SaveBatchAsync(batchId);
}