View on GitHub
Install in Dash
FetchRequest Protocol Reference
FetchRequest
public protocol FetchRequest : DatabaseRegionConvertible, SQLRequestProtocolThe protocol for all requests that fetch database rows, and tell how those rows should be interpreted.
struct Player: FetchableRecord { ... }
let request: ... // Some FetchRequest that fetches Player
try request.fetchCursor(db) // Cursor of Player
try request.fetchAll(db) // [Player]
try request.fetchOne(db) // Player?
try request.fetchCount(db) // Int
To build a custom FetchRequest, declare a type with the RowDecoder
associated type, and implement the requestSQL(_:forSingleResult:) method
with the help of SQLLiteral.
For example:
struct PlayerRequest: FetchRequest {
typealias RowDecoder = Player
var id: Int64
func requestSQL(_ context: SQLGenerationContext, forSingleResult singleResult: Bool) throws -> String {
let query: SQLLiteral = "SELECT * FROM player WHERE id = \(id)"
return try query.sql(context)
}
}
let player = try dbQueue.read { db in
try PlayerRequest(id: 42).fetchOne(db)
}
-
The type that tells how fetched database rows should be interpreted.
Declaration
Swift
associatedtype RowDecoder -
makePreparedRequest(_:Default implementationforSingleResult: ) Returns a PreparedRequest that is ready to be executed.
Default Implementation
Returns a PreparedRequest that is ready to be executed.
This default implementation returns a request built from the
requestSQL(_:forSingleResult)method.Declaration
Swift
func makePreparedRequest(_ db: Database, forSingleResult singleResult: Bool) throws -> PreparedRequestParameters
dbA database connection.
singleResultA hint that a single result row will be consumed. Implementations can optionally use it to optimize the prepared statement, for example by adding a
LIMIT 1SQL clause.// Calls makePreparedRequest(db, forSingleResult: true) try request.fetchOne(db)
// Calls makePreparedRequest(db, forSingleResult: false) try request.fetchAll(db)
Return Value
A prepared request.
-
fetchCount(_:Default implementation) Returns the number of rows fetched by the request.
Default Implementation
Returns the number of rows fetched by the request.
The default implementation builds a naive SQL query based on the statement returned by the
requestSQL(_:forSingleResult:)method:SELECT COUNT(*) FROM (...).Declaration
Swift
func fetchCount(_ db: Database) throws -> IntParameters
dbA database connection.
-
databaseRegion(_:Extension method) Returns the database region that the request looks into.
This default implementation returns a region built from the statement returned by the
requestSQL(_:forSingleResult)method.Declaration
Swift
public func databaseRegion(_ db: Database) throws -> DatabaseRegionParameters
dbA database connection.
-
adapted(_:Extension method) Returns an adapted request.
Declaration
Swift
public func adapted(_ adapter: @escaping (Database) throws -> RowAdapter) -> AdaptedFetchRequest<Self>
-
fetchCursor(_:Extension method) A cursor over fetched values.
let request: ... // Some FetchRequest that fetches String let strings = try request.fetchCursor(db) // Cursor of String while let string = try strings.next() { // String ... }If the database is modified during the cursor iteration, the remaining elements are undefined.
The cursor must be iterated in a protected dispath queue.
Throws
A DatabaseError is thrown whenever an SQLite error occurs.Declaration
Swift
public func fetchCursor(_ db: Database) throws -> DatabaseValueCursor<RowDecoder>Parameters
dbA database connection.
Return Value
A cursor over fetched values.
-
fetchAll(_:Extension method) An array of fetched values.
let request: ... // Some FetchRequest that fetches String let strings = try request.fetchAll(db) // [String]Throws
A DatabaseError is thrown whenever an SQLite error occurs.Declaration
Swift
public func fetchAll(_ db: Database) throws -> [RowDecoder]Parameters
dbA database connection.
Return Value
An array of values.
-
fetchOne(_:Extension method) The first fetched value.
The result is nil if the request returns no row, or if no value can be extracted from the first row.
let request: ... // Some FetchRequest that fetches String let string = try request.fetchOne(db) // String?Throws
A DatabaseError is thrown whenever an SQLite error occurs.Declaration
Swift
public func fetchOne(_ db: Database) throws -> RowDecoder?Parameters
dbA database connection.
Return Value
An optional value.
-
fetchCursor(_:Extension method) A cursor over fetched optional values.
let request: ... // Some FetchRequest that fetches Optional<String> let strings = try request.fetchCursor(db) // Cursor of String? while let string = try strings.next() { // String? ... }If the database is modified during the cursor iteration, the remaining elements are undefined.
The cursor must be iterated in a protected dispath queue.
Throws
A DatabaseError is thrown whenever an SQLite error occurs.Declaration
Swift
public func fetchCursor(_ db: Database) throws -> NullableDatabaseValueCursor<RowDecoder.Wrapped>Parameters
dbA database connection.
Return Value
A cursor over fetched values.
-
fetchAll(_:Extension method) An array of fetched optional values.
let request: ... // Some FetchRequest that fetches Optional<String> let strings = try request.fetchAll(db) // [String?]Throws
A DatabaseError is thrown whenever an SQLite error occurs.Declaration
Swift
public func fetchAll(_ db: Database) throws -> [RowDecoder.Wrapped?]Parameters
dbA database connection.
Return Value
An array of values.
-
fetchOne(_:Extension method) The first fetched value.
The result is nil if the request returns no row, or if no value can be extracted from the first row.
let request: ... // Some FetchRequest that fetches String? let string = try request.fetchOne(db) // String?Throws
A DatabaseError is thrown whenever an SQLite error occurs.Declaration
Swift
public func fetchOne(_ db: Database) throws -> RowDecoder.Wrapped?Parameters
dbA database connection.
Return Value
An optional value.
-
fetchCursor(_:Extension method) A cursor over fetched rows.
let request: ... // Some FetchRequest that fetches Row let rows = try request.fetchCursor(db) // RowCursor while let row = try rows.next() { // Row let id: Int64 = row[0] let name: String = row[1] }Fetched rows are reused during the cursor iteration: don’t turn a row cursor into an array with
Array(rows)orrows.filter { ... }since you would not get the distinct rows you expect. UseRow.fetchAll(...)instead.For the same reason, make sure you make a copy whenever you extract a row for later use:
row.copy().If the database is modified during the cursor iteration, the remaining elements are undefined.
The cursor must be iterated in a protected dispath queue.
Throws
A DatabaseError is thrown whenever an SQLite error occurs.Parameters
dbA database connection.
Return Value
A cursor over fetched rows.
-
fetchAll(_:Extension method) An array of fetched rows.
let request: ... // Some FetchRequest that fetches Row let rows = try request.fetchAll(db)Throws
A DatabaseError is thrown whenever an SQLite error occurs.Parameters
dbA database connection.
Return Value
An array of fetched rows.
-
fetchOne(_:Extension method) The first fetched row.
let request: ... // Some FetchRequest that fetches Row let row = try request.fetchOne(db)Throws
A DatabaseError is thrown whenever an SQLite error occurs.Parameters
dbA database connection.
Return Value
An optional row.
-
fetchCursor(_:Extension method) A cursor over fetched values.
let request: ... // Some FetchRequest that fetches String let strings = try request.fetchCursor(db) // Cursor of String while let string = try strings.next() { // String ... }If the database is modified during the cursor iteration, the remaining elements are undefined.
The cursor must be iterated in a protected dispath queue.
Throws
A DatabaseError is thrown whenever an SQLite error occurs.Declaration
Swift
public func fetchCursor(_ db: Database) throws -> FastDatabaseValueCursor<RowDecoder>Parameters
dbA database connection.
Return Value
A cursor over fetched values.
-
fetchAll(_:Extension method) An array of fetched values.
let request: ... // Some FetchRequest that fetches String let strings = try request.fetchAll(db) // [String]Throws
A DatabaseError is thrown whenever an SQLite error occurs.Declaration
Swift
public func fetchAll(_ db: Database) throws -> [RowDecoder]Parameters
dbA database connection.
Return Value
An array of values.
-
fetchOne(_:Extension method) The first fetched value.
The result is nil if the request returns no row, or if no value can be extracted from the first row.
let request: ... // Some FetchRequest that fetches String let string = try request.fetchOne(db) // String?Throws
A DatabaseError is thrown whenever an SQLite error occurs.Declaration
Swift
public func fetchOne(_ db: Database) throws -> RowDecoder?Parameters
dbA database connection.
Return Value
An optional value.
-
fetchCursor(_:Extension method) A cursor over fetched optional values.
let request: ... // Some FetchRequest that fetches Optional<String> let strings = try request.fetchCursor(db) // Cursor of String? while let string = try strings.next() { // String? ... }If the database is modified during the cursor iteration, the remaining elements are undefined.
The cursor must be iterated in a protected dispath queue.
Throws
A DatabaseError is thrown whenever an SQLite error occurs.Declaration
Swift
public func fetchCursor(_ db: Database) throws -> FastNullableDatabaseValueCursor<RowDecoder.Wrapped>Parameters
dbA database connection.
Return Value
A cursor over fetched values.
-
fetchAll(_:Extension method) An array of fetched optional values.
let request: ... // Some FetchRequest that fetches Optional<String> let strings = try request.fetchAll(db) // [String?]Throws
A DatabaseError is thrown whenever an SQLite error occurs.Declaration
Swift
public func fetchAll(_ db: Database) throws -> [RowDecoder.Wrapped?]Parameters
dbA database connection.
Return Value
An array of values.
-
fetchOne(_:Extension method) The first fetched value.
The result is nil if the request returns no row, or if no value can be extracted from the first row.
let request: ... // Some FetchRequest that fetches String? let string = try request.fetchOne(db) // String?Throws
A DatabaseError is thrown whenever an SQLite error occurs.Declaration
Swift
public func fetchOne(_ db: Database) throws -> RowDecoder.Wrapped?Parameters
dbA database connection.
Return Value
An optional value.
-
fetchCursor(_:Extension method) A cursor over fetched records.
let request: ... // Some FetchRequest that fetches Player let players = try request.fetchCursor(db) // Cursor of Player while let player = try players.next() { // Player ... }If the database is modified during the cursor iteration, the remaining elements are undefined.
The cursor must be iterated in a protected dispath queue.
Throws
A DatabaseError is thrown whenever an SQLite error occurs.Declaration
Swift
public func fetchCursor(_ db: Database) throws -> RecordCursor<RowDecoder>Parameters
dbA database connection.
Return Value
A cursor over fetched records.
-
fetchAll(_:Extension method) An array of fetched records.
let request: ... // Some FetchRequest that fetches Player let players = try request.fetchAll(db) // [Player]Throws
A DatabaseError is thrown whenever an SQLite error occurs.Declaration
Swift
public func fetchAll(_ db: Database) throws -> [RowDecoder]Parameters
dbA database connection.
Return Value
An array of records.
-
fetchOne(_:Extension method) The first fetched record.
let request: ... // Some FetchRequest that fetches Player let player = try request.fetchOne(db) // Player?Throws
A DatabaseError is thrown whenever an SQLite error occurs.Declaration
Swift
public func fetchOne(_ db: Database) throws -> RowDecoder?Parameters
dbA database connection.
Return Value
An optional record.