# 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](/dbflow/usage2/usage/modelviews.md)) and `@Index` ([read here](/dbflow/usage2/advanced-usage/indexing.md)) to perform faster retrieval on a set of data constantly queried.

## Synchronous Retrieval

Using the [SQLite query language](/dbflow/usage2/usage/sqlitewrapperlanguage.md) we can retrieve data easily and expressively. To perform it synchronously:

```kotlin
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](/dbflow/usage2/advanced-usage/querymodels.md).

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](/dbflow/usage2/advanced-usage/listbasedqueries.md).

## 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:

```kotlin
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](/dbflow/usage2/usage/storingdata.md). We also provide constructs such as coroutines and RX `Observables` to map to your team's needs.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://dbflow.gitbook.io/dbflow/usage2/usage/retrieval.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.