FbQuery class

The database query object.

Allows sending SQL statements to the database, as well as fetching data back.

Example:

final db = await FbDb.attach(host: "localhost", database: "employee");
final q = db.query(); // note: no await here
await q.openCursor(sql: "select FIRST_NAME, LAST_NAME from EMPLOYEE");
await for (var row in q.rows()) {
  print("${row['LAST_NAME']}, ${row['FIRST_NAME']}");
};
await q.close(); // close the query
// query object can still be used after close
// e.g. to execute another SQL statement
await db.detach(); // detach from the database
// db cannot be used any more

In order to know, how to pass query parameters correctly and what to expect when fetching query results, one has to know, how the SQL data types in the Firebird database are mapped by FbDb to their corresponding types in Dart.

The type mappings are as follows:

  • SQL textual types (CHAR and VARCHAR) are mapped to String in Dart,
  • SQL integer types (SMALLINT, INTEGER, BIGINT) are mapped to int (64-bit integer) in Dart,
  • SQL integer type INT128 is mapped to double in Dart (there's no 128-bit integer type available),
  • SQL real numbers (DOUBLE PRECISION, NUMERIC(N,M), DECIMAL(N,M)) are mapped to double in Dart,
  • SQL date and time types (DATE, TIME, TIMESTAMP) are mapped to Dart DateTime objects,
  • the same applies to SQL types TIME WITH TIME ZONE and TIMESTAMP WITH TIME ZONE (they are both mapped to DateTime in Dart), which is unfortunate, because currently Dart's DateTime does not support arbitrary time zones (it only supports UTC and the local time zone of the host); this issue will be addressed in the future releases of fbdb,
  • SQL BOOLEAN is mapped to bool in Dart,
  • parameters of the SQL BLOB type can be passed to a query as ByteBuffer objects, any TypedData objects (from which a byte buffer can be obtained), as String objects (in which case they will be encoded as UTF8 and passed byte-by-byte) or as FbBlobId objects (for BLOBs stored beforehand); the returned values are always either ByteBuffer objects or FbBlobId objects (depending on whether BLOB inlining is turned on or off for a particular query).

Constructors

FbQuery.forDb(FbDb? _db)
Creates a query object associated with the specific database connection.

Properties

hashCode → int
The hash code for this object.
no setterinherited
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited

Methods

affectedRows() → Future<int>
Retrieves the number of rows affected by a DML query.
close() → Future<void>
Closes the query (if active).
execute({required String sql, List parameters = const [], bool inlineBlobs = true, FbTransaction? inTransaction}) → Future<FbQuery>
Executes an SQL statement, which does not return a data set and doesn't require a database cursor.
executePrepared({List parameters = const [], bool inlineBlobs = true, FbTransaction? inTransaction}) → Future<FbQuery>
Executes a prepared query without allocating a database cursor.
fetch([int rowCount = 1]) → Future<List<Map<String, dynamic>>>
An alias for FbQuery.fetchAsMaps.
fetchAll({int chunkSize = 10}) → Future<List<Map<String, dynamic>>>
An alias for FbQuery.fetchAllAsMaps.
fetchAllAsLists({int chunkSize = 10}) → Future<List<List>>
Fetches all rows from the data set as lists.
fetchAllAsMaps({int chunkSize = 10}) → Future<List<Map<String, dynamic>>>
Fetches all rows from the data set as maps.
fetchAsLists([int rowCount = 1]) → Future<List<List>>
Fetches the next set of rows from the data set as lists.
fetchAsMaps([int rowCount = 1]) → Future<List<Map<String, dynamic>>>
Fetches the next set of rows from the data set as maps.
fetchOne() → Future<Map<String, dynamic>?>
An alias for FbQuery.fetchOneAsMap.
fetchOneAsList() → Future<List?>
Fetches the next row from the data set as a list.
fetchOneAsMap() → Future<Map<String, dynamic>?>
Fetches the next row from the data set as a map.
fieldDefs() → Future<List<FbFieldDef>?>
Retrieves field / column definitions of the query output.
fieldNames() → Future<List<String>?>
Retrieves field names of the query output.
getOutput() → Future<Map<String, dynamic>>
An alias to FbQuery.getOutputAsMap to shorten the calls.
getOutputAsList() → Future<Map<String, dynamic>?>
Fetches the output data (as a list) of a query without a cursor.
getOutputAsMap() → Future<Map<String, dynamic>>
Fetches the output data (as a map) of a query without a cursor.
isPrepared() → Future<bool>
Informs whether the query contains a prepared SQL statement.
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
open({required String sql, List parameters = const [], bool inlineBlobs = true, FbTransaction? inTransaction}) → Future<FbQuery>
An alias for FbQuery.openCursor.
openCursor({required String sql, List parameters = const [], bool inlineBlobs = true, FbTransaction? inTransaction}) → Future<FbQuery>
Executes an SQL statement, which returns a data set and requires allocation of a database cursor.
openPrepared({List parameters = const [], bool inlineBlobs = true, FbTransaction? inTransaction}) → Future<FbQuery>
Executes a prepared query, allocating a database cursor to fetch records.
prepare({required String sql, FbTransaction? inTransaction}) → Future<FbQuery>
Prepares a statement to be executed later.
rows({int chunkSize = 10}) → Stream<Map<String, dynamic>>
Streams all rows from the data set as maps.
rowValues({int chunkSize = 10}) → Stream<List>
Streams all rows from the data set as lists.
toString() → String
A string representation of this object.
inherited

Operators

operator ==(Object other) → bool
The equality operator.
inherited