com.squareup.sqlbrite3

Class SqlBrite.Query

java.lang.Object

com.squareup.sqlbrite3.SqlBrite.Query

Enclosing class:

SqlBrite

public abstract static class SqlBrite.Query
extends java.lang.Object

An executable query.

Constructor Summary

Constructors

Constructor and Description
Query()

Method Summary

Modifier and Type	Method and Description
<T> <any>	asRows(<any> mapper) Execute the query on the underlying database and return an Observable of each row mapped to T by mapper.
static <T> <any>	mapToList(<any> mapper) Creates an operator which transforms a query to a List<T> using mapper.
static <T> <any>	mapToOne(<any> mapper) Creates an operator which transforms a query returning a single row to a T using mapper.
static <T> <any>	mapToOneOrDefault(<any> mapper, T defaultValue) Creates an operator which transforms a query returning a single row to a T using mapper.
static <T> <any>	mapToOptional(<any> mapper) Creates an operator which transforms a query returning a single row to a Optional<T> using mapper.
abstract android.database.Cursor	run() Execute the query on the underlying database and return the resulting cursor.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Query

public Query()

Method Detail

mapToOne

public static <T> <any> mapToOne(<any> mapper)

Creates an operator which transforms a query returning a single row to a T using mapper. Use with Observable#lift.

It is an error for a query to pass through this operator with more than 1 row in its result set. Use LIMIT 1 on the underlying SQL query to prevent this. Result sets with 0 rows do not emit an item.

This operator ignores null cursors returned from run().

Parameters:

mapper - Maps the current Cursor row to T. May not return null.

mapToOneOrDefault

public static <T> <any> mapToOneOrDefault(<any> mapper,
                                          T defaultValue)

Creates an operator which transforms a query returning a single row to a T using mapper. Use with Observable#lift.

It is an error for a query to pass through this operator with more than 1 row in its result set. Use LIMIT 1 on the underlying SQL query to prevent this. Result sets with 0 rows emit defaultValue.

This operator emits defaultValue if null is returned from run().

Parameters:

mapper - Maps the current Cursor row to T. May not return null.

defaultValue - Value returned if result set is empty

mapToOptional

public static <T> <any> mapToOptional(<any> mapper)

Creates an operator which transforms a query returning a single row to a Optional<T> using mapper. Use with Observable#lift.

It is an error for a query to pass through this operator with more than 1 row in its result set. Use LIMIT 1 on the underlying SQL query to prevent this. Result sets with 0 rows emit Optional.empty().

This operator ignores null cursors returned from run().

Parameters:

mapper - Maps the current Cursor row to T. May not return null.

mapToList

public static <T> <any> mapToList(<any> mapper)

Creates an operator which transforms a query to a List<T> using mapper. Use with Observable#lift.

Be careful using this operator as it will always consume the entire cursor and create objects for each row, every time this observable emits a new query. On tables whose queries update frequently or very large result sets this can result in the creation of many objects.

This operator ignores null cursors returned from run().

Parameters:

mapper - Maps the current Cursor row to T. May not return null.

run

public abstract android.database.Cursor run()

Execute the query on the underlying database and return the resulting cursor.

Returns:

A Cursor with query results, or null when the query could not be executed due to a problem with the underlying store. Unfortunately it is not well documented when null is returned. It usually involves a problem in communicating with the underlying store and should either be treated as failure or ignored for retry at a later time.

asRows

public final <T> <any> asRows(<any> mapper)

Execute the query on the underlying database and return an Observable of each row mapped to T by mapper.

Standard usage of this operation is in flatMap:

 flatMap(q -> q.asRows(Item.MAPPER).toList())
 

However, the above is a more-verbose but identical operation as QueryObservable.mapToList(<any>). This asRows method should be used when you need to limit or filter the items separate from the actual query.

 flatMap(q -> q.asRows(Item.MAPPER).take(5).toList())
 // or...
 flatMap(q -> q.asRows(Item.MAPPER).filter(i -> i.isActive).toList())
 

Note: Limiting results or filtering will almost always be faster in the database as part of a query and should be preferred, where possible.

The resulting observable will be empty if null is returned from run().