Skip to content

Most visited

Recently visited

navigation
added in version 1.0.0
belongs to Maven artifact android.arch.persistence.room:common:1.0.0

Query

public abstract @interface Query
implements Annotation

android.arch.persistence.room.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 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.

     @Query("SELECT * FROM user WHERE user_name LIKE :name AND last_name LIKE :last")
     public abstract List<User> findUsersByNameAndLastName(String name, String last);
 

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.

     @Query("SELECT * FROM user WHERE uid IN(:userIds)")
     public abstract List findByIds(int[] userIds);
 
For the example above, if the userIds is an array of 3 elements, Room will run the query as: SELECT * FROM user WHERE uid IN(?, ?, ?) and bind each item in the userIds array into the statement.

There are 3 types of queries supported in Query methods: SELECT, 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 java object. For queries that return multiple values, you can use List or Array. In addition to these, any query may return Cursor or any query result can be wrapped in a LiveData.

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 Entity row that does not exist). You can return Flowable<T[]> or Flowable<List<T>> 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 EmptyResultSetException.

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.

You can return arbitrary POJOs from your query methods as long as the fields of the POJO match the column names in the query result. For example, if you have class:

 class UserName {
     public String name;
     @ColumnInfo(name = "last_name")
     public String lastName;
 }
 
You can write a query like this:
     @Query("SELECT last_name, name FROM user WHERE uid = :userId LIMIT 1")
     public abstract UserName findOneUserName(int userId);
 
And Room will create the correct implementation to convert the query result into a UserName object. If there is a mismatch between the query result and the fields of the POJO, as long as there is at least 1 field match, Room prints a CURSOR_MISMATCH warning and sets as many fields as it can.

Summary

Public methods

String value()

The SQLite query to be run.

Inherited methods

From interface java.lang.annotation.Annotation

Public methods

value

String value ()

The SQLite query to be run.

Returns
String The query to be run.

This site uses cookies to store your preferences for site-specific language and display options.

Get the latest Android developer news and tips that will help you find success on Google Play.

* Required Fields

Hooray!

Follow Google Developers on WeChat

Browse this site in ?

You requested a page in , but your language preference for this site is .

Would you like to change your language preference and browse this site in ? If you want to change your language preference later, use the language menu at the bottom of each page.

This class requires API level or higher

This doc is hidden because your selected API level for the documentation is . You can change the documentation API level with the selector above the left navigation.

For more information about specifying the API level your app requires, read Supporting Different Platform Versions.

Take a short survey?
Help us improve the Android developer experience.
(Sep 2017 survey)