User to Geo Relations

Top  Previous  Next

Backendless Geo Service manages application's geo location data and provides APIs to work with Geo points. Backendless supports integration between user objects managed by User Service and geo points for the scenarios when a logical connection between the two entity types must exist in an application.

Relations between a user object and a geo point are built the same way as between a data object and a geo point. The User-to-Geo integration is implemented through object relations. A user table schema may declare a table column with a special data type - "GeoPoint Relationship". As a result, the user objects in the table may contain a reference to one or more GeoPoints. When a user object with a related GeoPoint is saved, Backendless persists information about both the user object and the geopoint in the corresponding persistent systems and sets up the relationship. Likewise, when a user object is retrieved by using the API, any related geopoints can be retrieved by using the same principle for loading  user relations. The user-to-geo relation is bidirectional, it means a geopoint may reference a user object in its metadata. You can learn more about it in the Relations with Data Objects section of the Geolocation documentation.

Relation between a user object and a geopoint (or a collection of) can be established by using either the "code first" or the "schema first" approaches. With the former, the relationship is determined by the data structure persisted with the API. If a user object references a GeoPoint (or a collection of) in one of its properties, Backendless interprets it as a relation and, as a result, will create a relation column in the user table schema. With the latter ("schema first") approach, application developer can declare a user-to-geo property first. In either one of these approaches, once a relationship is declared, user objects and geopoints may be linked together by using the Backendless console as well.

This chapter consists of the following sections:

Declaring a User-to-Geo Relationship in Table Schema

Linking a User Object with GeoPoints

Updating Relations

Deleting Relation in Schema

Deleting User-to-Geo Relation between Objects

Creating User-to-Geo Relations with API

Declaring a User-to-Geo Relationship in Table Schema

To declare a user-to-geo user property:

1.In the Backendless Console click the Users icon. The User Properties section is selected by default.
2.Click the Add Custom Property button. The pop-up window will display:

user-geo1.zoom50

3.Enter the name of the property (column) in the Name field. The property (column) will represent a user-to-geo relationship.
4.Select the Geopoint Relationship option from the Type drop-down list.

user-geo2.zoom50

5.Once GEOPOINT RELATIONSHIP is selected, new menu options become available. Select the cardinality of the relation from the corresponding drop-down menu. The one-to-one relation means a user account can be linked with only one geopoint, while the one-to-many relation means the column of a user account may reference multiple geopoints.

user-geo3.zoom50

6.Click the Save button to save the changes.

Linking a User Object with GeoPoints

Once a user-to-geo relation is declared (see the instructions above), user objects can be linked with geopoint(s):

1.On the Data Management page, click the Users table.
2.Table columns representing the user-to-geo relations are identified as "GEOPOINTS relationship" in the header row. The cardinality of the relation is visualized as one red line for the one-to-one relations and three parallel lines for the one-to-many relations:

user-geo4.zoom50

3.Click the plus icon in the cell at the intersection of the GEOPOINTS relationship column and the user account row. The Set Related GeoPoint(s) pop-up window will display a list of the geopoints.

user-geo5.zoom50

4.Use the Geo Category drop-down list to select a geo category from which the points should be displayed.
5.For the one-to-one user-to-geo relationships a geopoint can be selected using a radio button. For the one-to-many relationship, use check-boxes.
6.Click the Set Related GeoPoint button to save the changes.

Once a relation is established, it is shown in the data browser as a hyperlink. The hyperlink for the one-to-one relations displays the coordinates of the related geopoint. For the one-to-many relations the link says "multiple Geopoints". In both cases, the link opens the Geolocation page displaying the related geopoint(s).

Updating Relations

To update a user-to-geo relation:

1.On the Data Management screen, click the Users table. When the table displays, click the plus icon next to a relation.

user-geo6.zoom50

2.The Set Related GeoPoint pop-up window will display. Use the radio-buttons (one-to-one relations) or check-boxes (one-to-many relations) to select/deselect the geopoints.
3.Click the Update Related GeoPoint button to save the changes.

Deleting Relation in Schema

A user-to-geo relation can be removed at the schema level. To remove the relation, delete the column that represents it. When a column is removed, the relation identified by the column between the user objects and geopoints is removed as well.

To delete a relationship between a data table and the geopoints:

1.Navigate to the Users > User Properties screen.
2.Click the delete icon in the Delete column as shown below:

user-geo7.zoom50

3.Click Yes in the confirmation dialog window.

Deleting User-to-Geo Relation between Objects

To delete relations between a user object and geopoint(s)  using the Backendless Console:

1. On the Data Management screen, click the Users table. When the table displays, click the plus icon next to the relation to be deleted.

user-geo6.zoom50

2.The Set Related GeoPoint pop-up window will display.
3.For the one-to-one relation:
  click the Unlink Relation button.
For the one-to-many relations:
  deselect checkboxes for the geopoints to unlink and click Set Related Geopoints.

Creating User-to-Geo Relations with API

Creating a relationship between a user object and a geopoint (or a collection of) uses the same API as saving a user object with a related entity. In the case of user-to-geo relations, the related entity is a geopoint or a collection of geopoints. The geopoint is also persisted in the Geo Service.

The example below demonstrates how to assign coordinates to a user's location, that is link a user object with one or several geopoints. A user object is retrieved for the example purposes (to have an object the example will be working with).

One-to-one Relation

To create a one-to-one relation, add a geopoint with coordinates latitude:48.85,longitude:2.35 as a property of the user object.

Synchronous call

BackendlessUser user = Backendless.Data.Of<BackendlessUser>().FindFirst();
GeoPoint geoPoint = new GeoPoint( 48.85, 2.35 );
user.AddProperty( "location", geoPoint );
Backendless.Data.Of<BackendlessUser>().Save( user );

Asynchronous call:

AsyncCallback<BackendlessUser> saveUserCallback = new AsyncCallback<BackendlessUser>(
  user =>
  {
    // user object has been updated with geopoint
  },
  error =>
  {
  }
);
AsyncCallback<BackendlessUser> findUserCallback = new AsyncCallback<BackendlessUser>(
  user =>
  {
    GeoPoint geoPoint = new GeoPoint( 48.85, 2.35 );
    user.AddProperty( "location", geoPoint );
    Backendless.Data.Of<BackendlessUser>().Save( user, saveUserCallback );
  },
  error =>
  {
  }
);
Backendless.Data.Of<BackendlessUser>().FindFirst( findUserCallback );

Backendless Console can be used to verify the new relation. The geopoint will show up as a property in the location column of the user object.

One-to-Many Relation

To create a one-to-many relation, add two geopoints with the coordinates latitude:48.85,longitude:2.35 and latitude:40.40,longitude:3.68 to an array. Then, assign this array to the locations property of the user object.

Synchronous call

BackendlessUser user = Backendless.Data.Of<BackendlessUser>().FindFirst();
GeoPoint geoPoint1 = new GeoPoint( 48.85, 2.35 );
GeoPoint geoPoint2 = new GeoPoint( 40.40, 3.68 );
List<GeoPoint> locations = new List<GeoPoint>();
locations.Add( geoPoint1 );
locations.Add( geoPoint2 );
user.AddProperty( "locations", locations );
Backendless.Data.Of<BackendlessUser>().Save( user );

Asynchronous call:

AsyncCallback<BackendlessUser> saveUserCallback = new AsyncCallback<BackendlessUser>(
  user =>
  {
    // user object has been updated with geopoint
  },
  error =>
  {
  }
);
AsyncCallback<BackendlessUser> findUserCallback = new AsyncCallback<BackendlessUser>(
  user =>
  {
    GeoPoint geoPoint1 = new GeoPoint( 48.85, 2.35 );
    GeoPoint geoPoint2 = new GeoPoint( 40.40, 3.68 );
    List<GeoPoint> locations = new List<GeoPoint>();
    locations.Add( geoPoint1 );
    locations.Add( geoPoint2 );
    user.AddProperty( "locations", locations );
    Backendless.Data.Of<BackendlessUser>().Save( user, saveUserCallback );
  },
  error =>
  {
  }
);
Backendless.Data.Of<BackendlessUser>().FindFirst( findUserCallback );

Backendless Console can be used to verify the new relation. The geopoint will show up as a property in the locations column of the user object.


Please let us know how we can improve the documentation by leaving a comment. All technical questions should be posted to the Backendless Support forum. We do not respond to the technical questions on the documentation pages.: