retrieval.md

Retrieval

DBFlow provides a few ways to retrieve information from the database. Through the Model classes we can map this information to easy-to-use objects.

DBFlow provides a few different ways to retrieve information from the database. We can retrieve synchronously or asynchronous (preferred).

We can also use ModelView (read here) and @Index (read here) to perform faster retrieval on a set of data constantly queried.

Synchronous Retrieval

Using the SQLite query language we can retrieve data easily and expressively. To perform it synchronously:

databaseForTable<Employee> { db ->
    // list
    val employees = (select from Employee::class).queryList(db)

    // single result, we apply a limit(1) automatically to get the result even faster.
    val employee: Employee? = (select from Employee::class
                            where Employee_Table.name.eq("Andrew Grosner")).querySingle(db)

    // can require result to get non-null if you know it exists
    // throws a SQLiteException if missing
    val employee: Employee? = (select from Employee::class
                            where Employee_Table.name.eq("Andrew Grosner")).requireSingle(db)

    // get a custom list
    val employees: List<AnotherTable> = (select from Employee::class)
                    .queryCustomList(database)

    // custom object
    val anotherObject: AnotherTable? = (select from Employee::class
                            where(Employee_Table.name.eq("Andrew Grosner")))
                            .queryCustomSingle()

    // require custom object
    val anotherObject: AnotherTable = (select from Employee::class
                            where(Employee_Table.name.eq("Andrew Grosner")))
                            .requireCustomSingle()
}

To query custom objects or lists, see how to do so in QueryModel.

Also you can query a FlowCursorList/FlowTableList from a query easily via queryCursorList() and the queryTableList() methods. To see more on these, go to Flow Lists.

Asynchronous Retrieval

DBFlow provides the very-handy Transaction system that allows you to place all calls to the DB in a background queue. Using this system, we recommend placing retrieval queries on this queue to help prevent locking and threading issues when using a database.

We wrap our queries in a beginTransactionAsync block, executing and providing call backs to the method as follows:

database.beginTransactionAsync { db ->
  // body of transaction. Return the value you wish to pass into the Success callback.
  (select from TestModel1::class
    where TestModel1_Table.name.is("Async")).querySingle(db)
  }
    .execute(
     ready = { transaction -> }, // called when transaction is ready to be executed.
     success = { transaction, r ->   }, // if successful
     error  = { transaction, throwable ->  }, // any exception thrown is put here
     completion = { transaction -> }) // always called success or failure
     
// or inverse is supported
(select from TestModel1::class
    where TestModel1_Table.name.is("Async")).async { d -> querySingle(d) }
    .execute { _, model: TestModel1? ->
      
    }

A ITransaction<R> simply returns a result, R , which could be a query, or a result from multiple queries combined into one result.

By default the library uses an ordered queue that executes FIFO (first-in-first-out) and blocks itself until new Transaction are added. Each subsequent call to the database.beginTransactionAsync places a new transaction on this queue.

If you wish to customize and provide a different queue (or map it to an existing system), read up on Transactions. We also provide constructs such as coroutines and RX Observables to map to your team's needs.