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 relationName call which identifies a related column for which the related objects will be loaded:

Custom Class ApproachDictionary/Map Approach

Objective-CSwift

LoadRelationsQueryBuilder *queryBuilder = [[LoadRelationsQueryBuilder alloc] initWithEntityClass:[CHILDCLASS class] relationName:@"NAME-OF-RELATED-COLUMN"];

let queryBuilder = LoadRelationsQueryBuilder(entityClass: CHILDCLASS.self, relationName: "NAME-OF-RELATED-COLUMN")

Objective-CSwift

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:

Custom Class ApproachDictionary/Map Approach

Objective-CSwift

- (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)!)

Objective-CSwift

- (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.

Objective-CSwift

LoadRelationsQueryBuilder *queryBuilder = // initialized as shown above

// sets page size which will be used in subsequent related object retrieval
queryBuilder.pageSize = 10;

// 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.offset = 1;

let queryBuilder: LoadRelationsQueryBuilder = // initialized as shown above

// sets page size which will be used in subsequent related object retrieval
queryBuilder.pageSize = 10

// 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.offset = 1

Codeless Reference

where:

Argument	Description
table name	Name of the data table from where the objects are retrieved.
parent object id	Unique identifier (objectId) of the record.
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.
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	When set to true, returns 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.

Returns the a list containing related children objects.

Consider the following data table called teacher. This data table has the related column called students, that contains the related children objects.

Now, consider the school data table which is referenced in the students column presented above. The school data table stores the names of the students that are linked to the parent object('Sophia Perez') in the teacher data table.

The example below retrieves the first five related children objects from the students data table. As you can see, the parent object is stored in the teacher data table.

After the Codeless logic runs, the operation returns the first five related objects from the students data table.

You can also skip a number of records from the beginning of the data table and retrieve only those records that match your criteria. The example below skips the first five records, and returns the last five objects since the data table students has only 10 related objects.

After the Codeless logic runs, the operation skips the first five records and returns the last five related objects from the students data table.