RawQuery
public
abstract
@interface
RawQuery
implements
Annotation
androidx.room.RawQuery |
Marks a method in a Dao
annotated class as a raw query method where you can pass the
query as a SupportSQLiteQuery
.
@Dao interface RawDao { @RawQuery Song getSongViaQuery(SupportSQLiteQuery query); } // Usage of RawDao SimpleSQLiteQuery query = new SimpleSQLiteQuery( "SELECT * FROM Song WHERE id = ? LIMIT 1", new Object[]{ songId}); Song song = rawDao.getSongViaQuery(query);
Room will generate the code based on the return type of the function and failure to pass a proper query will result in a runtime failure or an undefined result.
If you know the query at compile time, you should always prefer Query
since it validates
the query at compile time and also generates more efficient code since Room can compute the
query result at compile time (e.g. it does not need to account for possibly missing columns in
the response).
On the other hand, RawQuery
serves as an escape hatch where you can build your own
SQL query at runtime but still use Room to convert it into objects.
RawQuery
methods must return a non-void type. If you want to execute a raw query that
does not return any value, use RoomDatabase#query
methods.
RawQuery methods can only be used for read queries. For write queries, use
RoomDatabase.getOpenHelper().getWritableDatabase()
.
Observable Queries:
RawQuery
methods can return observable types but you need to specify which tables are
accessed in the query using the observedEntities()
field in the annotation.
@Dao interface RawDao { @RawQuery(observedEntities = Song.class) LiveData<List<Song>> getSongs(SupportSQLiteQuery query); } // Usage of RawDao LiveData<List<Song>> liveSongs = rawDao.getSongs( new SimpleSQLiteQuery("SELECT * FROM song ORDER BY name DESC"));Returning POJOs:
RawQueries can also return plain old java objects, similar to Query
methods.
public class NameAndReleaseYear { final String name; @ColumnInfo(name = "release_year") final int year; public NameAndReleaseYear(String name, int year) { this.name = name; this.year = year; } } @Dao interface RawDao { @RawQuery NameAndReleaseYear getNameAndReleaseYear(SupportSQLiteQuery query); } // Usage of RawDao NameAndReleaseYear result = rawDao.getNameAndReleaseYear( new SimpleSQLiteQuery("SELECT * FROM song WHERE id = ?", new Object[]{songId}))
POJOs with Embedded Fields:
RawQuery
methods can return POJOs that include Embedded
fields as well.
public class SongAndArtist { @Embedded public Song song; @Embedded public Artist artist; } @Dao interface RawDao { @RawQuery SongAndArtist getSongAndArtist(SupportSQLiteQuery query); } // Usage of RawDao SongAndArtist result = rawDao.getSongAndArtist( new SimpleSQLiteQuery("SELECT * FROM Song, Artist WHERE Song.artistId = Artist.id LIMIT 1"))Relations:
RawQuery
return types can also be objects with Relations
.
public class AlbumAndSongs { @Embedded public Album album; @Relation(parentColumn = "id", entityColumn = "albumId") public List<Song> pets; } @Dao interface RawDao { @RawQuery List<AlbumAndSongs> getAlbumAndSongs(SupportSQLiteQuery query); } // Usage of RawDao List<AlbumAndSongs> result = rawDao.getAlbumAndSongs( new SimpleSQLiteQuery("SELECT * FROM album"));
Summary
Public methods | |
---|---|
Class[]<?>
|
observedEntities()
Denotes the list of entities which are accessed in the provided query and should be observed for invalidation if the query is observable. |
Inherited methods | |
---|---|
Public methods
observedEntities
public Class[]<?> observedEntities ()
Denotes the list of entities which are accessed in the provided query and should be observed for invalidation if the query is observable.
The listed classes should either be annotated with Entity
or they should reference to
at least 1 Entity (via Embedded
or Relation
).
Providing this field in a non-observable query has no impact.
@Dao interface RawDao { @RawQuery(observedEntities = Song.class) LiveData<List<User>> getUsers(String query); } LiveData<List<Song>> liveSongs = rawDao.getUsers( "SELECT * FROM song ORDER BY name DESC");
Returns | |
---|---|
Class[]<?> |
List of entities that should invalidate the query if changed. |