Skip to content

Retrieving objects

This operation retrieves data objects from a database table. The retrieval is performed according to the provided options, which allow you to:

  • Retrieve objects with a query
  • Using paging
  • Using sorting
  • With related objects
unitOfWorkInstance.find( String tableName, DataQueryBuilder queryBuilder )

The tableName argument specified the table where the objects are retrieved from. The queryBuilder argument contains the data retrieval options. For more information about available options see the Advanced Object Retrieval API section of this guide.


You can retrieve a single object by setting the pageSize option to 1. However, remember the method still returns a collection of objects, therefore if you need to get only one object, you need to use the OpResult API to resolve it to a OpResultValueReference.

Return Value

The operation returns an OpResult object which represents the result of this operation - a collection of retrieved objects. The OpResult object can be used as an argument in other operations in the same transaction (same UnitOfWork instance). There are two ways to reference a result from a previous operation - using the OpResult class or using the OpResultValueReference. You can learn about these classes in detail from the Operation Result chapter of this guide, but in short the OpResult objects represent the entire result of a transaction operation, while the OpResultValueReference objects represent a specific object.


The example below demonstrates retrieval of an object and updating its property in a transaction:

UnitOfWork unitOfWork = new UnitOfWork();

// Create a query builder
DataQueryBuilder queryBuilder = DataQueryBuilder.create();
// set the where clause
queryBuilder.setWhereClause( "name = 'India'" );
// we're asking the server to return only one object
queryBuilder.setPageSize( 1 );
// run the query in the transaction
OpResult findCountryResult = unitOfWork.find( "Country", queryBuilder );

// The entire findCountryResult is a collection, so we need to 
// get the first object from the response of the previous operation
OpResultValueReference india = findCountryResult.resolveTo( 0 );

// update the object and set a value for the "population" property
unitOfWork.update( india, "population", 1339000000 );

// now run the transaction
unitOfWork.execute( new AsyncCallback<UnitOfWorkResult>()
    public void handleResponse( UnitOfWorkResult uowResult )
      // transaction is complete. Use uowResult to check the result

    public void handleFault( BackendlessFault fault )
       // server reported an error
       Log.e( "MYAPP", "Server reported an error " + fault );