# Query

Artifact: [androidx.room:room-common](https://developer.android.com/jetpack/androidx/releases/room) [View Source](https://cs.android.com/search?q=file:androidx/room/Query.kt+class:androidx.room.Query) Added in [2.0.0](https://developer.android.com/jetpack/androidx/releases/room#2.0.0)

*** ** * ** ***

Common/AllAndroid/JVMNative/C/iOSJavaScript
- Cmn

  ```
  @Target(allowedTargets = [AnnotationTarget.FUNCTION, AnnotationTarget.PROPERTY_GETTER])
  @Retention(value = AnnotationRetention.BINARY)
  annotation Query
  ```

*** ** * ** ***

Marks a method in a `Dao` annotated class as a query method.

The value of the annotation includes the query that will be run when this method is called. This query is **verified at compile time** by Room to ensure that it compiles fine against the database.

The arguments of the method will be bound to the bind arguments in the SQL statement. See [SQLite's binding documentation](https://www.sqlite.org/c3ref/bind_blob.html) for details of bind arguments in SQLite.

Room only supports named bind parameter `:name` to avoid any confusion between the method parameters and the query bind parameters.

Room will automatically bind the parameters of the method into the bind arguments. This is done by matching the name of the parameters to the name of the bind arguments.

```kotlin
@Query("SELECT * FROM song WHERE release_year = :year")
public abstract fun findSongsByReleaseYear(year: Int): List<Song>
```

As an extension over SQLite bind arguments, Room supports binding a list of parameters to the query. At runtime, Room will build the correct query to have matching number of bind arguments depending on the number of items in the method parameter.

```kotlin
@Query("SELECT * FROM song WHERE id IN(:songIds)")
public abstract fun findByIds(songIds: Array<Long>): List<Song>
```

For the example above, if the `songIds` is an array of 3 elements, Room will run the query as: `SELECT * FROM song WHERE id IN(?, ?, ?)` and bind each item in the `songIds` array into the statement. One caveat of this type of binding is that only 999 items can be bound to the query, this is a limitation of SQLite [see Section 9 of SQLite Limits](https://www.sqlite.org/limits.html)

There are 4 type of statements supported in `Query` methods: SELECT, INSERT, UPDATE, and DELETE.

For SELECT queries, Room will infer the result contents from the method's return type and generate the code that will automatically convert the query result into the method's return type. For single result queries, the return type can be any data object (also known as data classes). For queries that return multiple values, you can use java.util.List or `Array`. In addition to these, any query may return android.database.Cursor or any query result can be wrapped in a androidx.lifecycle.LiveData.

INSERT queries can return `void` or `Long`. If it is a `Long`, the value is the SQLite rowid of the row inserted by this query. Note that queries which insert multiple rows cannot return more than one rowid, so avoid such statements if returning `Long`.

UPDATE or DELETE queries can return `void` or `Int`. If it is an `Int`, the value is the number of rows affected by this query.

**Flow**

If you are using Kotlin, you can also return `Flow<T>` from query methods. This creates a `Flow<T>` object that emits the results of the query and re-dispatches the query every time the data in the queried table changes.

Note that querying a table with a return type of `Flow<T>` always returns the first row in the result set, rather than emitting all of the rows in sequence. To observe changes over multiple rows in a table, use a return type of `Flow<List<T>>` instead.

Keep nullability in mind when choosing a return type, as it affects how the query method handles empty tables:

- When the return type is `Flow<T>`, querying an empty table throws a null pointer exception.

- When the return type is `Flow<T?>`, querying an empty table emits a null value.

- When the return type is `Flow<List<T>>`, querying an empty table emits an empty list.

**RxJava2**

If you are using RxJava2, you can also return `Flowable<T>` or `Publisher<T>` from query methods. Since Reactive Streams does not allow `null`, if the query returns a nullable type, it will not dispatch anything if the value is `null` (like fetching an `https://developer.android.com/reference/kotlin/androidx/room/Entity` row that does not exist). You can return \[Flowable\] or Flowable\> to workaround this limitation.

Both `Flowable<T>` and `Publisher<T>` will observe the database for changes and re-dispatch if data changes. If you want to query the database without observing changes, you can use `Maybe<T>` or `Single<T>`. If a `Single<T>` query returns `null`, Room will throw androidx.room.EmptyResultSetException.

Additionally if the statement is an INSERT, UPDATE or DELETE then the return types, `Single<T>`, `Maybe<T>` and `Completable` are supported.

You can return arbitrary data classes from your query methods as long as the properties of the data class match the column names in the query result.

For example, if you have class:

```kotlin
data class SongDuration (
  val name: String,
  @ColumnInfo(name = "duration")
  val length: String
)
```

You can write a query like this:

```kotlin
@Query("SELECT name, duration FROM song WHERE id = :songId LIMIT 1")
public abstract fun findSongDuration(songId: Int): SongDuration
```

And Room will create the correct implementation to convert the query result into a `SongDuration` object. If there is a mismatch between the query result and the properties of the data class, and as long as there is at least 1 field match, Room prints a `https://developer.android.com/reference/kotlin/androidx/room/RoomWarnings#QUERY_MISMATCH()` warning and sets as many properties as it can.

## Summary

| ### Public constructors |
|---|---|
| `https://developer.android.com/reference/kotlin/androidx/room/Query#Query(kotlin.String)(value: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html)` | Cmn |

| ### Public properties |
|---|---|---|
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html` | `https://developer.android.com/reference/kotlin/androidx/room/Query#value()` The SQLite query to be run. | Cmn |

## Public constructors

### Query

Cmn Added in [2.8.5](https://developer.android.com/jetpack/androidx/releases/room#2.8.5)

```
Query(value: String)
```

## Public properties

### value

Cmn

```
val value: String
```

The SQLite query to be run.

| Returns |
|---|---|
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html` | The query to be run. |