Retrieval with Relation Depth

The Data Service API supports a mechanism for loading related objects without identifying each by its name. Instead, the API includes a parameter which specifies the "depth" of the relations to include into the response. Consider the following diagram:

The diagram shows a hierarchy for class structure - the Order class has two relations: with OrderItem and Customer classes. Each in turn has a relation to the Manufacturer and Address classes. When an instance or a collection of Order objects is retrieved from Backendless, the API may include a parameter specifying the depth of relations to include into the response. If the relation depth is 1, then all related instances of OrderItem and Customer will be included into each Order object. If the relation depth is 2, then not only OrderItem and Customer instances will be included, but the corresponding Manufacturer and Address objects as well.

Important

Loading relations with relation depth retrieves only a partial set of the related objects (default size of the retrieved related collection is 10). To load additional related objects, use the Relation Paging API .

API methods supporting relations depth

Using Untyped ObjectsCustom Class/Function

Backendless.Data.of( "TABLE-NAME" ).findFirst( relationsDepth )
 .then( function( firstObjectWithRelations ) {
  })
 .catch( function( error ) {
  });

Backendless.Data.of( "TABLE-NAME" ).findLast( relationsDepth )
 .then( function( lastObjectWithRelations ) {
  })
 .catch( function( error ) {
  });

Backendless.Data.of( "TABLE-NAME" ).findById( objectId, relationsDepth )
 .then( function( firstObjectWithRelations ) {
  })
 .catch( function( error ) {
  });

Backendless.Data.of( "TABLE-NAME" ).find( dataQueryBuilder )
 .then( function( objectsWithRelations ) {
  })
 .catch( function( error ) {
  });

Backendless.Data.of( ClassFunctionRef ).findFirst( relationsDepth )
 .then( function( firstObject ) {
  })
 .catch( function( error ) {
  });
Backendless.Data.of( ClassFunctionRef ).findLast( relationsDepth )
 .then( function( lastObject ) {
  })
 .catch( function( error ) {
  });
Backendless.Data.of( ClassFunctionRef ).findById( objectId, relationsDepth )
 .then( function( objectWithId ) {
  })
 .catch( function( error ) {
  });
Backendless.Data.of( ClassFunctionRef ).find( dataQueryBuilder )
 .then( function( objectArray ) {
  })
 .catch( function( error ) {
  });

Example

Using Untyped ObjectsCustom Class/Function

var queryBuilder = Backendless.DataQueryBuilder.create();
queryOptions.setRelationsDepth( 2 );

Backendless.Data.of( "Foo" ).find( queryBuilder )
 .then( function( objectArray ) {
  })
 .catch( function( error ) {
  });

// define the constructor function first
function Foo {
  // Foo properties are declared here
}

var queryBuilder = Backendless.DataQueryBuilder.create();
queryOptions.setRelationsDepth( 2 );

Backendless.Data.of( Foo ).find( queryBuilder )
 .then( function( objectArray ) {
  })
 .catch( function( error ) {
  });

Codeless Reference

Suppose you have set up the hierarchy with the following structure described further:

Data tables hierarchy:

1. employees - general information about employees.

2. uniqueSkills - the names of the skills

3. marketValue - the market value for each skill.

Consider the parent data table called employees.As you probably noticed, the skills column has a relation to the uniqueSkills data table

The uniqueSkills data table presented below has a relation to another data table called marketValue, all relations leading to this table are referenced in the value column.

The last related data table called marketValue has the following structure:

Every data table described above is related/linked to each other forming an hierarchy.

Before proceeding to the example, let's examine the relation of the parent object called 'Alex Lincoln' that is stored in the employees data table. As you can see, the parent object has only one  relation to the child object.

The example below retrieves all related objects in the hierarchy for the 'Alex Lincoln' parent object. Notice how the parent object is retrieved using the where clause condition: to obtain a specific object you must reference one of the desired columns such as "name" and the exact value in the where clause property; in this case, it is "name = 'Alex Lincoln'".

Furthermore, you have to specify the name of the column containing the relation, in the context of this example it is "skills".

The relations depth property is set to 2, indicating that the third data table is the last in the query.

Important

For a detailed description of all input parameters see the Basic Object Retrieval topic of this guide.

After the Codeless logic runs, the operation returns the parent object 'Alex Lincoln' and all underlying related records from all data tables described above: