RawQuery

@Target([AnnotationTarget.FUNCTION, AnnotationTarget.PROPERTY_GETTER, AnnotationTarget.PROPERTY_SETTER]) class RawQuery
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 constructors

<init>(observedEntities: Array<KClass<*>>)

Marks a method in a Dao annotated class as a raw query method where you can pass the query as a SupportSQLiteQuery.

Properties

Array<KClass<*>>

Denotes the list of entities which are accessed in the provided query and should be observed for invalidation if the query is observable.

Public constructors

<init>

RawQuery(observedEntities: Array<KClass<*>>)

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"));
  

Properties

observedEntities

val observedEntities: Array<KClass<*>>

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");
      
Return
Array<KClass<*>>: List of entities that should invalidate the query if changed.