Skip to content

Relation Paging

API operations described above provide a way to retrieve a limited (initial) set of related data. In most real world scenarios, there may be more related objects than returned by Single Step, Two Step or Relation Depth Retrieval APIs. To obtain a complete set of related objects Backendless supports Relation Paging API described below.

Important

  1. To understand the concept of paged data retrieval, see the Data retrieval with Paging section of the documentation.
    2. When working with paging, it may be important to know the total size of the related collection. See the Get Object Count section for details on how to get the related objects count.

iOS applications must use the LoadRelationsQueryBuilder class which facilitates retrieval of related objects for a parent object. The class is responsible for maintaining the page size and offset parameters used in the paging process.

Before an instance of LoadRelationsQueryBuilder can be used in a data retrieval request, it must be initialized as shown below. Notice the setRelationName call which identifies a related column for which the related objects will be loaded:

LoadRelationsQueryBuilder *queryBuilder = [[LoadRelationsQueryBuilder alloc] initWithEntityClass:[CHILDCLASS class] relationName:@"NAME-OF-RELATED-COLUMN"];
let queryBuilder = LoadRelationsQueryBuilder(entityClass: CHILDCLASS.self, relationName: "NAME-OF-RELATED-COLUMN")

LoadRelationsQueryBuilder *queryBuilder = [[LoadRelationsQueryBuilder alloc] initWithRelationName:@"NAME-OF-RELATED-COLUMN"];
let queryBuilder = LoadRelationsQueryBuilder(relationName: "NAME-OF-RELATED-COLUMN")

where:

Argument                Description
CHILDCLASS Used in the "Custom Class" approach only. An Objective-C or Swift class which identifies the related table.
NAME-OF-RELATED-COLUMN Name of the related column in the parent table for which the related objects will be retrieved.

Once a query builder object is created, the following API can be used to retrieve a page of related objects:

- (void)loadRelationsWithObjectId:(NSString * _Nonnull)objectId queryBuilder:(LoadRelationsQueryBuilder * _Nonnull)loadRelationsQueryBuilder responseHandler:^(NSArray * _Nonnull)responseHandler errorHandler:^(Fault * _Nonnull)errorHandler;
func loadRelations(objectId: String, queryBuilder: LoadRelationsQueryBuilder, responseHandler: (([Any]) -> Void)!, errorHandler: ((Fault) -> Void)!)

- (void)loadRelationsWithObjectId:(NSString * _Nonnull)objectId queryBuilder:(LoadRelationsQueryBuilder * _Nonnull)loadRelationsQueryBuilder responseHandler:^(NSArray<NSDictionary<NSString *,id> *> * _Nonnull)responseHandler errorHandler:^(Fault * _Nonnull)errorHandler;
func loadRelations(objectId: String, queryBuilder: LoadRelationsQueryBuilder, responseHandler: (([[String : Any]]) -> Void)!, errorHandler: ((Fault) -> Void)!)

where:

Argument                Description
objectId  id of the parent object for which the related objects will be retrieved.
loadRelationsQueryBuilder LoadRelationsQueryBuilder initialized as shown above. Used in subsequent calls to request additional pages of related data objects.

The LoadRelationsQueryBuilder class contains methods which recalculate offset in order to obtain next, previous or a specific page. After loadRelationsQueryBuilder is modified, call the API shown above to get next, previous or a specific page of data.

LoadRelationsQueryBuilder *queryBuilder = // initialized as shown above

// sets page size which will be used in subsequent related object retrieval
[queryBuilder setPageSizeWithPageSize:(NSInteger)pageSize];

// calculates offset of the next page based on set page size
[queryBuilder prepareNextPage];

// calculates offset of the previous page based on set page size
[queryBuilder preparePreviousPage];

// sets offset explicitly
[queryBuilder setOffsetWithOffset:(NSInteger)offset];
let queryBuilder = // initialized as shown above

// sets page size which will be used in subsequent related object retrieval
queryBuilder.setPageSize(pageSize: Int)

// calculates offset of the next page based on set page size
queryBuilder.prepareNextPage()

// calculates offset of the previous page based on set page size
queryBuilder.preparePreviousPage()

// calculates offset of the previous page based on set page size
queryBuilder.setOffset(offset: Int)