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¶
Non-blocking methods:
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( "TABLE-NAME" ).findFirstSync( relationsDepth );
Backendless.Data.of( "TABLE-NAME" ).findLastSync( relationsDepth );
Backendless.Data.of( "TABLE-NAME" ).findByIdSync( objectId, relationsDepth );
Backendless.Data.of( "TABLE-NAME" ).findSync( dataQueryBuilder );
Non-blocking methods:
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 ) {
});
var firstObject = Backendless.Data.of( ClassFunctionRef ).findFirstSync( relationsDepth );
var lastObject = Backendless.Data.of( ClassFunctionRef ).findLastSync( relationsDepth );
var objectWithId = Backendless.Data.of( ClassFunctionRef ).findByIdSync( objectId, relationsDepth );
var objectArray = Backendless.Data.of( ClassFunctionRef ).findSync( dataQueryBuilder );
Example¶
var queryBuilder = Backendless.DataQueryBuilder.create();
queryOptions.setRelationsDepth( 2 );
// non-blocking call
Backendless.Data.of( "Foo" ).find( queryBuilder )
.then( function( objectArray ) {
})
.catch( function( error ) {
});
// blocking call
var objectArray = Backendless.Data.of( "Foo" ).findSync( queryBuilder );
// define the constructor function first
function Foo {
// Foo properties are declared here
}
var queryBuilder = Backendless.DataQueryBuilder.create();
queryOptions.setRelationsDepth( 2 );
// non-blocking call
Backendless.Data.of( Foo ).find( queryBuilder )
.then( function( objectArray ) {
})
.catch( function( error ) {
});
// blocking call
var objectArray = Backendless.Data.of( Foo ).find( queryBuilder );