Basic Object Retrieval¶

Backendless supports multiple data search and retrieval operations. These include finding an object by its objectId, finding first or last object in the collection or retrieving the entire persisted collection. Each method is available in both blocking and non-blocking formats:

Retrieving Data Objects¶

Blocking API¶

Using Java MapCustom Class

Retrieve data objects with the default paging setting from a table:

public List<Map> Backendless.Data.of( "TABLE-NAME" ).find()

Find first data object from a table. The first data object is the first one saved in the data store:

public Map Backendless.Data.of( "TABLE-NAME" ).findFirst()

Find last data object from a table. The last data object is the last one saved in the data store:

public Map Backendless.Data.of( "TABLE-NAME" ).findLast()

Find a data object by its ID:

public Map Backendless.Data.of( "TABLE-NAME" ).findById( String objectId )

Retrieve data objects with the default paging setting from a table. Returned collection will contain objects of type E (the name of the class must match the name of the table):

public List<E> Backendless.Data.of( E ).find()

Find first data object of class E. The first data object is the first one saved in the data store:

public E Backendless.Data.of( E ).findFirst()

Find last data object of type E. The last data object is the last one saved in the data store:

public E Backendless.Data.of( E ).findLast()

Find a data object by its ID:

public E Backendless.Data.of( E ).findById( String objectId )

Non-Blocking API¶

Using Java MapCustom Class

Retrieve data objects with the default paging setting from a table:

public void Backendless.Data.of( "TABLE-NAME" ).find( AsyncCallback<List<Map>> responder )

Find first data object from a table. The first data object is the first one saved in the data store:

public void Backendless.Data.of( "TABLE-NAME" ).findFirst( AsyncCallback<Map> responder )

Find last data object from a table. The last data object is the last one saved in the data store:

public void Backendless.Data.of( "TABLE-NAME" ).findLast( AsyncCallback<Map> responder )

Find a data object by its objectId:

public void Backendless.Data.of( "TABLE-NAME" ).findById( String objectId, 
                                                                 AsyncCallback<Map> responder )

Retrieve data objects with the default paging setting from a table. Returned collection will contain objects of type E (the name of the class must match the name of the table):

public void Backendless.Persistence.of( E ).find( AsyncCallback<List<E>> responder );

Find first data object from a table. The name of the class E must match the name of the table. The first data object is the first one saved in the data store:

public void Backendless.Persistence.of( E ).findFirst( AsyncCallback<E> responder )

Find last data object from a table. The name of the class E must match the name of the table. The last data object is the last one saved in the data store:

public void Backendless.Persistence.of( E ).findLast( AsyncCallback<E> responder )

Find a data object by its ID. The name of the class E must match the name of the table:

public void Backendless.Persistence.of( E ).findById( String objectId, 
                                                      AsyncCallback<E> responder )

where:

Argument	Description
`TABLE-NAME`	Name of the table from where the data is retrieved from.
`E`	Java class identifying the table where from where the data must be loaded from. For example, if the table is "`Person`", the argument should `Person.class`.
`responder`	a responder object which will receive a callback when the method successfully returns a result or an error. Applies to the asynchronous methods only.

Example¶

Using Java Map

The following code demonstrates various search queries:

Load contacts using default paging¶

**Blocking API**
``` java
List<Map> result = Backendless.Data.of( "Contact" ).find();
```

**Non-Blocking API**
``` java
Backendless.Data.of( "Contact" ).find( new AsyncCallback<List<Map>>(){
  @Override
  public void handleResponse( List<Map> foundContacts )
  {
    // every loaded object from the "Contact" table is now an individual java.util.Map
  }
  @Override
  public void handleFault( BackendlessFault fault )
  {
    // an error has occurred, the error code can be retrieved with fault.getCode()
  }
});
```

Find first contact¶

**Blocking API**
``` java
Map firstContact = Backendless.Data.of( "Contact" ).findFirst();
```

**Non-Blocking API**
``` java
Backendless.Data.of( "Contact" ).findFirst( new AsyncCallback<Map>(){
  @Override
  public void handleResponse( Map contact )
  {
    // first contact instance has been found
  }
  @Override
  public void handleFault( BackendlessFault fault )
  {
    // an error has occurred, the error code can be retrieved with fault.getCode()
  }
});
```

Find last contact¶

**Blocking API**
``` java
Map firstContact = Backendless.Data.of( "Contact" ).findLast();
```

**Non-Blocking API**
``` java
Backendless.Data.of( "Contact" ).findLast( new AsyncCallback<Map>(){
  @Override
  public void handleResponse( Map contact )
  {
    // last contact instance has been found
  }
  @Override
  public void handleFault( BackendlessFault fault )
  {
    // an error has occurred, the error code can be retrieved with fault.getCode()
  }
});
```

Find contact by objectId¶

**Blocking API**
``` java
// Save a contact object first. Once it is saved, we will retrieve it by assigned objectId
HashMap contact = new HashMap();
contact.put( "name", "Jack Daniels" );
contact.put( "age", 147 );
contact.put( "phone", "777-777-777" );
contact.put( "title", "Favorites" );

// save object synchronously
Map savedContact = Backendless.Data.of( "Contact" ).save( contact );

// now retrieve the object using it's objectId
Map lastContact = Backendless.Data.of( "Contact" ).
                                    findById( savedContact.get( "objectId" ) );
```

**Non-Blocking API**
``` java
// Save a contact object first. Once it is saved, we will retrieve it by assigned objectId
HashMap contact = new HashMap();
contact.put( "name", "Jack Daniels" );
contact.put( "age", 147 );
contact.put( "phone", "777-777-777" );
contact.put( "title", "Favorites" );

Backendless.Data.of( "Contact" ).save( contact, new AsyncCallback<Map>()
{
  @Override
  public void handleResponse( Map savedContact )
  {
    // now that the object is saved and has objectId, retrieve it using "findById"
    Backendless.Data.of( Contact.class ).findById( savedContact.get( "objectId" ), 
                                                          new AsyncCallback<Map>() {
      @Override
      public void handleResponse( Map response )
      {
        // an object from the "Contact" table has been found by it's objectId
      }
      @Override
      public void handleFault( BackendlessFault fault )
      {
        // an error has occurred, the error code can be retrieved with fault.getCode()
      }
    } );
  }
  @Override
  public void handleFault( BackendlessFault fault )
  {
    // an error has occurred, the error code can be retrieved with fault.getCode()
  }
} );
```

Custom Class

Consider the following class:

package com.sample;

public class Contact
{
  private String objectId;
  private String name;
  private int age;
  private String phone;
  private String title;

  public String getObjectId() {
    return objectId;
  }

  public void setObjectId( String objectId ) {
    this.objectId = objectId;
  }

  public String getName() {
    return name;
  }

  public void setName( String name ) {
    this.name = name;
  }

  public int getAge() {
    return age;
  }

  public void setAge( int age ) {
    this.age = age;
  }

  public String getPhone() {
    return phone;
  }

  public void setPhone( String phone ) {
    this.phone = phone;
  }

  public String getTitle() {
    return title;
  }

  public void setTitle( String title ) {
    this.title = title;
  }
}

The following code demonstrates various search queries:

Load contacts using default paging¶

**Blocking API**
``` java
List<Contact> result = Backendless.Data.of( Contact.class ).find();
```

**Non-Blocking API**
``` java
Backendless.Data.of( Contact.class).find( new AsyncCallback<List<Contact>>(){
  @Override
  public void handleResponse( List<Contact> foundContacts )
  {
    // all Contact instances have been found
  }
  @Override
  public void handleFault( BackendlessFault fault )
  {
    // an error has occurred, the error code can be retrieved with fault.getCode()
  }
});
```

Find first contact¶

**Blocking API**
``` java
Contact firstContact = Backendless.Data.of( Contact.class ).findFirst();
```

**Non-Blocking API**
``` java
Backendless.Data.of( Contact.class).findFirst( new AsyncCallback<Contact>(){
  @Override
  public void handleResponse( Contact contact )
  {
    // first contact instance has been found
  }
  @Override
  public void handleFault( BackendlessFault fault )
  {
    // an error has occurred, the error code can be retrieved with fault.getCode()
  }
});
```

Find last contact¶

**Blocking API**
``` java
Contact lastContact = Backendless.Data.of( Contact.class ).findLast();
```

**Non-Blocking API**
``` java
Backendless.Data.of( Contact.class).findLast( new AsyncCallback<Contact>(){
  @Override
  public void handleResponse( Contact contact )
  {
    // last contact instance has been found
  }
  @Override
  public void handleFault( BackendlessFault fault )
  {
    // an error has occurred, the error code can be retrieved with fault.getCode()
  }
});
```

Find contact by objectId¶

**Blocking API**
``` java
// Save a contact object first. Once it is saved, we will retrieve it by assigned objectId
Contact contact = new Contact();
contact.setName( "Jack Daniels" );
contact.setAge( 147 );
contact.setPhone( "777-777-777" );
contact.setTitle( "Favorites" );

// save object synchronously
Contact savedContact = Backendless.Data.save( contact );

// now retrieve the object using it's objectId
Contact foundContact = Backendless.Data.of( Contact.class ).findById( savedContact.getObjectId() );
```

**Non-Blocking API**
``` java
// Save a contact object first. Once it is saved, we will retrieve it by assigned objectId
Contact contact = new Contact();
contact.setName( "Jack Daniels" );
contact.setAge( 147 );
contact.setPhone( "777-777-777" );
contact.setTitle( "Favorites" );

Backendless.Data.save( contact, new AsyncCallback<Contact>()
{
  @Override
  public void handleResponse( Contact savedContact )
  {
    // now that the object is saved and has objectId, retrieve it using "findById"
    Backendless.Persistence.of( Contact.class ).findById( savedContact.getObjectId(), 
                                                          new AsyncCallback<Contact>() {
      @Override
      public void handleResponse( Contact response )
      {
        // a Contact instance has been found by objectId
      }
      @Override
      public void handleFault( BackendlessFault fault )
      {
        // an error has occurred, the error code can be retrieved with fault.getCode()
      }
    } );
  }
  @Override
  public void handleFault( BackendlessFault fault )
  {
    // an error has occurred, the error code can be retrieved with fault.getCode()
  }
} );
```

Find a data object by object ID with the queryBuilder parameter¶

Signatures Blocking Method¶

public E findById( String id, DataQueryBuilder queryBuilder ) throws BackendlessException

      public E findById( E entity, DataQueryBuilder queryBuilder ) throws BackendlessException

Signatures Non-Blocking Method:¶

public void findById(String id, DataQueryBuilder queryBuilder, AsyncCallback<E> responder)

      public void findById(E entity, DataQueryBuilder queryBuilder, AsyncCallback<E> responder)

Example Blocking Method¶

Using MapCustom Class

DataQueryBuilder queryBuilder = DataQueryBuilder.create();
queryBuilder
    .addRelated( "relationA" )
    .addRelated( "relationB" );

var result = Backendless.Data.of( "tableName" ).findById( "OBJECT_ID", queryBuilder );
//
//Some operations with the result

DataQueryBuilder queryBuilder = DataQueryBuilder.create();
queryBuilder
       .addRelated( "relationA" )
       .addRelated( "relationB" );

var result = Backendless.Data.of( TableName.class ).findById( "OBJECT_ID", queryBuilder );
//
//Some operations with the result

Example Non-Blocking Method¶

Using MapCustom Class

DataQueryBuilder queryBuilder = DataQueryBuilder.create();
queryBuilder
    .addRelated( "relationA" )
    .addRelated( "relationB" );

var result = Backendless.Data.of( "tableName" ).findById( "OBJECT_ID", queryBuilder );
//
//Some operations with the result

DataQueryBuilder queryBuilder = DataQueryBuilder.create();
queryBuilder
       .addRelated( "relationA" )
       .addRelated( "relationB" );

var result = Backendless.Data.of( TableName.class ).findById( "OBJECT_ID", queryBuilder );
//
//Some operations with the result

where:

Argument	Description
`queryBuilder`	Instance of com.backendless.persistence.DataQueryBuilder. When present in the arguments, the object must contain a whereClause query. The query is used by the server to identify a collection of objects.
`tableName`	The name of the existing table within the database.
`objectId`	Object ID of the object to find. For the details about objectId, see the Data Object section of the documentation.
`handleResponse`	Handles successful result of an asynchronous call.
`handleFault`	Handles fault result of an asynchronous call.

Codeless Reference¶

The data table employees presented below is used throughout all Codeless examples as the main reference:

data_service_example_data_table_basic_object_retrieval

Find First Object¶

The example below retrieves the first object stored in the "employees" data table.

data_service_get_first_object_from_table

where:

Argument	Description
`table name`	Name of the data table from where the required object is retrieved.
`relations`	Name of the related property to load. For example, if table employees has a relation column `homeAddress` pointing to an object in the `Address` table, the value of the parameter would be `homeAddress`. The syntax allows to add relations of relations. For example, if the same `Address` table has a relation country pointing to the `Country` table, then `homeAddress`.country would instruct the backend to load the related `Country` object.
`relations depth`	Depth of the relations to include into the response.
`properties`	Names of the properties/columns for which to load the corresponding values.
`exclude properties`	Names of the properties/columns that should not be included in the response.

The operation has returned the following result:

data_service_example_get_first_object_from_table

Find Last Object¶

The example below retrieves the last object stored in the "employees" data table.

data_service_get_last_object_from_table

The operation has returned the following result:

data_service_example_get_last_object_from_table

Find Object By ID¶

Consider the following scenario where you want to retrieve an object associated with both the object id: "2B6392CA-B720-4930-8E1C-14C7B06E4397" and the name "Alex Lincoln". In the example provided below, the operation searches for an object by its object id and returns it as part of the response:

data_service_get_object_by_objectId

where:

Argument	Description
`table name`	Name of the data table from where the required object is retrieved.
`object id`	Unique identifier of the object to retrieve.
`relations`	Name of the related property to load. For example, if table employees has a relation column `homeAddress` pointing to an object in the `Address` table, the value of the parameter would be `homeAddress`. The syntax allows to add relations of relations. For example, if the same `Address` table has a relation country pointing to the `Country` table, then `homeAddress`.country would instruct the backend to load the related `Country` object.
`relations depth`	Depth of the relations to include into the response.
`properties`	Names of the properties/columns for which to load the corresponding values.
`exclude properties`	Names of the properties/columns that should not be included in the response.

The result of this operation will look as shown below after the Codeless logic runs.

data_service_example_find_object_by_id

Load All Objects From Data Table¶

The example below loads all objects from the employees data table.

data_service_load_objects

where:

Argument	Description
`table name`	Name of the data table from where the objects are retrieved.
`where clause`	A search query used by the server it to determine objects matching the condition. Refer to the Search With The Where Clause topic for more information.
`having clause`	Sets a condition on a aggregate function to filter groups.
`relations`	Name of the related property to load. For example, if table employees has a relation column homeAddress pointing to an object in the Address table, the value of the parameter would be `homeAddress`. The syntax allows to add relations of relations. For example, if the same `Address` table has a relation country pointing to the `Country` table, then `homeAddress`.country would instruct the backend to load the related `Country` object.
`properties`	Names of the properties/columns for which to load the corresponding values.
`exclude properties`	Names of the properties/columns that should not be included in the response.
`relations depth`	Depth of the relations to include into the response.
`relations page size`	Sets the number of related objects returned in the response.
`sort by`	Lists properties by which the returned collection should be sorted by.
`group by`	Sets the name of the columns to group the results by.
`page size`	Sets the page size which is the number of objects to be returned in the response.
`page offset`	Zero-based index of the object in the persistent store from which to run the search. This parameter should be used when implementing paged access to data. Suppose the first request returned 20 objects (if `pageSize` is set to 20) and there are 100 objects total. The subsequent request can set offset to 20, so the next batch of objects is loaded sequentially.
`distinct`	Used to return only unique values from a column.
`file reference prefix`	This property allows replacing the default URL file prefix. For instance, when the operation returns a path to a file stored on the server (`"https://yourdomain.backendless.app/my-file.jpg"`), then you can reconstruct it by passing the new file name that must start with a slash - `"/wonderful_forest.jpg"`. It is useful when you want the client application to open a specific file locally.

The result of this operation will look as shown below after the Codeless logic runs.

data_service_example_load_objects_2