GetRecordsByWhereStatementAsync
Part of the IQSDataTable interface, this method fetches multiple records from the data source that satisfy a custom SQL‑style WHERE condition. Each returned record is a dictionary of column‑name/value pairs, giving you a lightweight, flexible result set.
This method is useful for fetching specific records based on complex conditions that cannot be expressed using simple ID or serial number lookups.
Asynchronously returns a list of dictionaries (List<Dictionary<string, object>>), each representing a row. Only the columns listed in TargetFields are included. If no rows match the predicate, an empty list is returned.
Signature
public async Task<List<Dictionary<string, object>>> GetRecordsByWhereStatementAsync(string predicate, List<string> TargetFields = null)Parameters
| Name | Type | Description |
|---|---|---|
predicate | string | The SQL WHERE clause (without the keyword WHERE) used to filter records. Example: "Status = 'Active' AND Age > 18". |
TargetFields | List<string> (optional) | The list of column names to include in each result dictionary. If omitted, a default set of fields is used (implementation‑specific). |
Returns
A Task<List<Dictionary<string, object>>> representing the asynchronous operation. The list contains one dictionary per matching row, where each dictionary maps column names to their values. If no rows match the predicate, the list is empty.
Notes
The dictionary values are of type object. You should cast them to the expected type (e.g. (int)record["Age"]) before use.
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.
Example Usage
// Define the data table
IQSDataTable employeesTable = QSAppContext.Tables["Employees"];
// Filter: active employees in the Sales department
string wherePredicate = "Status = 'Active' AND Department = 'Sales'";
List<string> fields = new List<string> { "Name", "Salary", "Department" };
List<Dictionary<string, object>> salesEmployees = await employeesTable.GetRecordsByWhereStatementAsync(wherePredicate, fields);
foreach (var emp in salesEmployees)
{
string name = emp["Name"].ToString();
decimal salary = Convert.ToDecimal(emp["Salary"]);
string department = emp["Department"].ToString();
string sample = $"{emp["Name"]} earns {emp["Salary"]} and works in the {emp["Department"]} department";
}