query#
Run a SQL SELECT statement and return the result set with rows mapped to Rust structs (R2O, relation-to-object mapping).
Rust API#
// sync_api
pub fn mudu_query<R: Entity>(
oid: OID,
sql: &dyn SQLStmt,
params: &dyn SQLParams,
) -> RS<EntitySet<R>> {
/* ... */
}
// async_api
pub async fn mudu_query<R: Entity>(
oid: OID,
sql: &dyn SQLStmt,
params: &dyn SQLParams,
) -> RS<EntitySet<R>> {
/* ... */
}
Conceptual signature#
query<R: Entity>(sql: string, params?: [Value]) -> EntitySet<R>
Parameters#
oid— the current system session identifier passed into the procedure.sql— a singleSELECTstatement using?as parameter placeholders.params— the values bound to the placeholders.
Behavior#
Executes the
SELECTin the current session and automatically maps each result row to the entity typeR(R2O mapping);Rmust implement theEntitytrait (see Mudu Procedure).Row visibility follows the current transaction’s isolation rules, as with any other read.
Return value#
RS<EntitySet<R>>— the mapped result set. Callnext_record()to iterate: it returnsRS<Option<R>>, yieldingOk(Some(row))for each row andOk(None)at the end of the result set.
Errors#
Parse: the SQL text cannot be parsed.EntityNotFound: theoiddoes not identify a live session.Database: the storage engine failed to execute the statement.
Transaction semantics#
The query participates in the current session transaction.
A procedure invocation runs as one transaction that commits on
Okand rolls back onErr; see Mudu Procedure.
Example#
use sys_interface::sync_api::mudu_query;
let wallets = mudu_query::<Wallets>(
oid,
sql_stmt!(&Wallets::SQL_GET_BY_PK),
sql_params!(&(user_id,)),
)?;
if let Some(wallet) = wallets.next_record()? {
// wallet is a Wallets struct mapped from the selected row
}
Notes#
Use
queryonly forSELECT. ForINSERT/UPDATE/DELETEusecommand; for multiple statements in one call usebatch.Entity modules are normally generated with
mgen entity, which also emits theSQL_GET_BY_PK/SQL_INSERT/SQL_DELETE_BY_PKtext constants used above.