query method

QueryRows query(QueryId id, { QueryParameters parameters = const {}, QueryDirection direction = QueryDirection.forward, QueryRowPosition? start, })

Executes a query identified by the given id and returns the result.

See the prepare method for a description of how its columns and order parameters influence the content of every resulting QueryRow.

The optional named arguments of the query method are called query execution parameters in this documentation; they allow providing values for the named parameters of the query's SQL statement, setting the start position of row extraction, and choosing the direction of extraction.

The parameters argument is a map that binds a non-null Object value to a String name of a parameter of the SQL statement. Supported value types include int, double, and String. An SqlP helper class can be used to compose SQL constructs with named parameters:

QueryId qid = sqlite.prepare(
  where: SqlI("distance") >= SqlP("@distance"),
/* ... */
QueryRows rr = sqlite.query(qid, parameters: {"@distance": 43});
/* ... */

A query that can return a large number of rows may benefit from pagination. The pagination this library implements is seek-based. The page size is set by the limit argument to prepare.

• To retrieve the first page, the start position must be null and the direction must be forward.
• To retrieve the last page, the start position must be null and the direction must be reverse.
• To retrieve the next page, the start position must correspond to the last row of the current page and the direction must be forward.
• To retrieve the previous page, the start position must correspond to the first row of the current page and the direction must be reverse.

The queryRowGetPosition helper function returns the position of a row. The row corresponding to the start argument is not included in the result of the query method. The ordering of resulting rows remains the same regardless of the retrieval direction. The following example demonstrates the retrieval of the first, next, last, and previous rows:

QueryId qid = sqlite.prepare(
  limit: 10,
  /* ... */
QueryRows pF = sqlite.query(qid);
/* ... */
QueryRows pN = sqlite.query(qid, start: queryRowGetPosition(pF.last));
/* ... */
QueryRows pL = sqlite.query(qid, direction: QueryDirection.reverse);
/* ... */
QueryRows pP = sqlite.query(
  qid,
  start: queryRowGetPosition(pL.first),
  direction: QueryDirection.reverse,
);
/* ... */

See also: prepare and free.

Implementation

QueryRows query(
  QueryId id, {
  QueryParameters parameters = const {},
  QueryDirection direction = QueryDirection.forward,
  QueryRowPosition? start,
}) {
  checkActive();
  Query query = _queries[id]!;
  ResultSet result = query.run(parameters, direction, start);
  var rows = direction == QueryDirection.forward
      ? result.rows
      : result.rows.reversed;
  return [
    for (var row in rows)
      queryRow(
        FullId(row[0]! as int, row[1]!),
        [
          for (int i = 0; i < query.order.length; ++i) ////
            row[i + 2]!,
        ],
        [
          for (int i = 0; i < query.columns.length; ++i)
            row[i + 2 + query.order.length],
        ],
      ),
  ];
}