Skip to content

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:

relation-depth

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

DataQueryBuilder *queryBuilder = [DataQueryBuilder new];
[queryBuilder setRelationsDepthWithRelationsDepth:(NSInteger)relationsDepth];

DataStoreFactory *dataStore = [Backendless.shared.data of:[YOUR-CLASS class]]; 

[dataStore findWithQueryBuilder:queryBuilder responseHandler:^(NSArray * _Nonnull)responseHandler errorHandler:^(Fault * _Nonnull)errorHandler];

[dataStore findFirstWithQueryBuilder:queryBuilder responseHandler:^(id _Nonnull)responseHandler errorHandler:^(Fault * _Nonnull)errorHandler];

[dataStore findLastWithQueryBuilder:queryBuilder responseHandler:^(id _Nonnull)responseHandler errorHandler:^(Fault * _Nonnull)errorHandler];

[dataStore findByIdWithObjectId:(NSString * _Nonnull)objectId queryBuilder:queryBuilder responseHandler:^(id _Nonnull)responseHandler errorHandler:^(Fault * _Nonnull)errorHandler];
let queryBuilder = DataQueryBuilder()
queryBuilder.setRelationsDepth(relationsDepth: Int)

let dataStore = Backendless.shared.data.of(YOUR-CLASS.self)

dataStore.find(queryBuilder: queryBuilder, responseHandler: (([Any]) -> Void)!, errorHandler: ((Fault) -> Void)!)

dataStore.findFirst(queryBuilder: queryBuilder, responseHandler: ((Any) -> Void)!, errorHandler: ((Fault) -> Void)!)

dataStore.findLast(queryBuilder: queryBuilder, responseHandler: ((Any) -> Void)!, errorHandler: ((Fault) -> Void)!)

dataStore.findById(objectId: String, queryBuilder: queryBuilder, responseHandler: ((Any) -> Void)!, errorHandler: ((Fault) -> Void)!)

DataQueryBuilder *queryBuilder = [DataQueryBuilder new];
[queryBuilder setRelationsDepthWithRelationsDepth:(NSInteger)relationsDepth];

MapDrivenDataStore *dataStore = [Backendless.shared.data ofTable:@"TABLE-NAME"];

[dataStore findWithQueryBuilder:queryBuilder responseHandler:^(NSArray<NSDictionary<NSString *,id> *> * _Nonnull)responseHandler errorHandler:^(Fault * _Nonnull)errorHandler];

[dataStore findFirstWithQueryBuilder:queryBuilder responseHandler:^(NSDictionary<NSString *,id> * _Nonnull)responseHandler errorHandler:^(Fault * _Nonnull)errorHandler];

[dataStore findLastWithQueryBuilder:queryBuilder responseHandler:^(NSDictionary<NSString *,id> * _Nonnull)responseHandler errorHandler:^(Fault * _Nonnull)errorHandler];

[dataStore findByIdWithObjectId:(NSString * _Nonnull)objectId queryBuilder:queryBuilder responseHandler:^(NSDictionary<NSString *,id> * _Nonnull)responseHandler errorHandler:^(Fault * _Nonnull)errorHandler];
let queryBuilder = DataQueryBuilder()
queryBuilder.setRelationsDepth(relationsDepth: Int)

let dataStore = Backendless.shared.data.ofTable("TABLE-NAME")

dataStore.find(queryBuilder: queryBuilder, responseHandler: (([[String : Any]]) -> Void)!, errorHandler: ((Fault) -> Void)!)

dataStore.findFirst(queryBuilder: queryBuilder, responseHandler: (([String : Any]) -> Void)!, errorHandler: ((Fault) -> Void)!)

dataStore.findLast(queryBuilder: queryBuilder, responseHandler: (([String : Any]) -> Void)!, errorHandler: ((Fault) -> Void)!)

dataStore.findById(objectId: String, queryBuilder: queryBuilder, responseHandler: (([String : Any]) -> Void)!, errorHandler: ((Fault) -> Void)!)

Example

DataQueryBuilder *queryBuilder = [DataQueryBuilder new];
[queryBuilder setRelationsDepthWithRelationsDepth:2];

DataStoreFactory *dataStore = [Backendless.shared.data of:[Foo class]];
[dataStore findWithQueryBuilder:queryBuilder responseHandler:^(NSArray *foundObjects) {
    NSLog(@"Found objects: %@", foundObjects);
} errorHandler:^(Fault *fault) {
    NSLog(@"Error: %@", fault.message);
}];
let queryBuilder = DataQueryBuilder()
queryBuilder.setRelationsDepth(relationsDepth: 2)

let dataStore = Backendless.shared.data.of(Foo.self)
dataStore.find(queryBuilder: queryBuilder, responseHandler: { foundObjects in
    print("Found objects: \(foundObjects)")
}, errorHandler: { fault in
    print("Error: \(fault.message ?? "")")
})

DataQueryBuilder *queryBuilder = [DataQueryBuilder new];
[queryBuilder setRelationsDepthWithRelationsDepth:2];

MapDrivenDataStore *dataStore = [Backendless.shared.data ofTable:@"Foo"];
[dataStore findWithQueryBuilder:queryBuilder responseHandler:^(NSArray *foundObjects) {
    NSLog(@"Found objects: %@", foundObjects);
} errorHandler:^(Fault *fault) {
    NSLog(@"Error: %@", fault.message);
}];
let queryBuilder = DataQueryBuilder()
queryBuilder.setRelationsDepth(relationsDepth: 2)

let dataStore = Backendless.shared.data.ofTable("Foo")
dataStore.find(queryBuilder: queryBuilder, responseHandler: { foundObjects in
    print("Found objects: \(foundObjects)")
}, errorHandler: { fault in
    print("Error: \(fault.message ?? "")")
})