Data retuned by SQL queries.
Class Recordset
The recordset class abstracts a set of data returned by SQL queries.
Data can be fetched row by row into Falcon arrays or dictionaries by the Recordset.fetch method. In the first case, the value extracted from each column is returned in the corresponding position of the returned array (the first column value at array position [0], the second column value in the array [1] and so on).
When fetching a dictionary, it will be filled with column names and values respectively as the key corresponding value entries.
The Recordset.fetch method can also be used to retrieve all the recordset contents (or part of it) into a Falcon Table.
Returned values can be of various falcon item types or classes; see the dbi_value_types section for further details.
Other than fetching data, the Recordset class can be used to retrieve general informations about the recordset (as the returned column size and names).
Note: Closing the database handle while the recordset is still open and in use may lead to various kind of errors. It's a thing that should be generally avoided.
| Methods | |
| discard | Discards one or more records in the recordset. |
| do | Calls back a function for each row in the recordset. |
| fetch | Fetches a record and advances to the next. |
| next | Gets the next recordset in queries returning multiple recordsets. |
Discards one or more records in the recordset.
Recordset.discard( count )
| count | The number of records to be skipped. |
| Return | true if successful, false if the recordset is over. |
This skips the next count records.
Calls back a function for each row in the recordset.
Recordset.do( cb, [item] )
| cb | The callback function that must be called for each row. | ||
| item | A fetchable item that will be filled and then passed to cb. | ||
| Raise |
|
This method calls back a given cb callable item fetching one row at a time from the recordset, and then passing the data to cb either as parameters or as a single item.
If item is not given, all the field values in the recordset are passed directly as parameters of the given cb function. If it is given, then that item is filled along the rules of Recordset.fetch and then it is passed to the cb item.
The item may be:
The cb method may return an oob(0) value to interrupt the processing of the recordset.
The recordset is not rewinded before starting to call cb. Any previously fetched data won't be passed to cb.
Fetches a record and advances to the next.
Recordset.fetch( [item],[count] )
| item | Where to store the fetched record. | ||
| count | Number of rows fetched when item is a Table. | ||
| Return | The item passed as a paramter filled with fetched data or nil when the recordset is terminated. | ||
| Raise |
|
If item is not given, a newly created array is filled with the fetched data and then returned, otherwise, the given item is filled with the data from the fetch.
The item may be:
Gets the next recordset in queries returning multiple recordsets.
Recordset.next()
| Return | Another recordset on success, nil if this query didn't generate any more recordset. | ||
| Raise |
|
Some engines may cause multiple recordsets to be generated after a single query. In that case, this method may be used to retrieve the secondary recordest after the first one has been completed.
When there aren't any more recordset to be fetched, this method returns nil.
The rules to access sub-recorsets may vary depending on the final engine, but usually this can be considered safe:
rs = dbi.query( "..." )
// process the query result as usual
data = [=>]
while rs.fetch(data)
// do things
end
// process the sub-queries.
while (sub_rs = rs.next() )
data = [=>]
while sub_rs.fetch(data)
// do more things things
end
end
rs.close()