Advanced Object Retrieval

Top  Previous  Next

Advanced search use-cases supported by Backendless include:

Search with a query (a "where clause" search) -retrieves data objects which satisfy a condition;
Paged data retrieval - retrieves a "page" of data of the given size from the specified offset.
Sorted data object retrieval - retrieves a collection of data objects sorted by specified properties.

Additionally, Backendless supports retrieval of related data objects.

Method:

GET

URL:

https://api.backendless.com/<version>/data/<table-name>?props=prop1,prop2&loadRelations=relprop1,relprop2&where=whereClause&pageSize=XX&sortBy=prop1,prop2&offset=ZZ

where:

<version>- name of the application's version. Application versions can be managed using Backendless Console. Login to the console, select an application, click Manage, then Versioning. Backendless automatically creates version "v1" for any new application.
<table-name>- name of the table where to search for the object.
props- references object properties which should be returned with every object. In this example, objects in the result will contain only the "prop1" and "prop2" properties.
loadRelations- references object properties which are relations and should be initialized and returned with the parent object. By default relations are not returned with the parent object and require a separate API call to load. Using the loadRelations query parameter Backendless pre-initializes the specified relations and returns them with the parent object.
where- contains an SQL query (the where clause part) which is used to search for the objects. The value must be URL encoded.
pageSize- sets the page size which is the number of objects to be returned in the response.
sortBy- lists properties by which the returned collection should be sorted by.
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 continually.

Request Headers:

application-id: app-id-value
secret-key: secret-key-value
application-type: REST

where:

application-id- the ID of your application generated upon its creation. You can find this header in the Manage > App Settings section of the Backendless Console. This header is mandatory. Please refer to the Setup section for information on how to obtain the values for the header.
secret-key - the key of your application generated upon its creation. You can find this header in the Manage > App Settings section of the Backendless Console. This header is mandatory. Please refer to the Setup section for information on how to obtain the values for the header.
application-type- the static value, should be set to REST. This header is mandatory.

Request Body:

None

Sample Response Body:

Without related objects:

{
 "nextPage":null,
 "data":[
  {
    "updated":null,
    "created":"02/05/2014 18:13:40 GMT+0000",
    "ownerId":null,
    "objectId":"6FAF3CE5-6F55-1B32-FF83-D333252D0300",
    "name":"Bob",
    "age":20
  },
  {
    "updated":null,
    "created":"02/04/2014 19:40:10 GMT+0000",
    "ownerId":null,
    "objectId":"28325E9F-2DED-D3CA-FFC6-C76911AFBB00",
    "name":"Frank",
    "age":26
  }],
 "offset":0,
 "totalObjects":2
}

With related objects:

{
 "nextPage":null,
 "data":[
    {
      "updated":null,
      "created":"02/06/2014 20:49:43 GMT+0000",
      "ownerId":null,
      "objectId":"1C887354-F487-5B90-FF7D-ABB452FCA600",
      "name":"Bob",
      "age":20,
      "myAddress":
        {
          "created":"02/06/2014 20:49:43 GMT+0000",
          "updated":null,
          "objectId":"90474FA5-FB34-651B-FF6E-5CAF8B4B1E00",
          "ownerId":null,
          "state":"TX",
          "___class":"MyAddress",
          "city":"Dallas"
        },
      "__meta":"myAddress:90474FA5-FB34-651B-FF6E-5CAF8B4B1E00"
    },
    {
      "updated":null,
      "created":"02/06/2014 20:48:44 GMT+0000",
      "ownerId":null,
      "objectId":"72D277BD-495C-73A9-FFE8-1E6976D66A00",
      "name":"Frank",
      "age":33,
      "myAddress":
        {
          "created":"02/06/2014 20:48:44 GMT+0000",
          "updated":null,
          "objectId":"8DB0DDB6-6662-A517-FFD4-FFFD32421A00",
          "ownerId":null,
          "state":"NY",
          "___class":"MyAddress",
          "city":"New York"
        },
      "__meta":"myAddress:8DB0DDB6-6662-A517-FFD4-FFFD32421A00"
    },
 ],
 "offset":0,
 "totalObjects":4
}

where:

nextPage- contains an endpoint URI which can be used to retrieve the next "page" of data. If all data is returned in the current call and no more data is available in the table, the value is null.
data- is an array of objects returned in the response
offset- index of the first object in the "data" collection.
totalObjects- total number of objects in the persistent store. This may be different than the number of objects in the "data" array. Backendless returns data in the "paged" format - meaning only a subset of data objects is returned at a time.
__meta- special property used by Backendless to manage changes in relationship collections. Specifically, the property is used to determine when a new related object is added or removed to/from a collection.
___class- contains the name of the table the object belongs to.

Example:

Consider the following object which represents a person:

{
"name":"string value",
"age":number,
}

Assuming objects like this are stored in a table called Person:

person-table

The following APIs would apply:

Find all contacts where the value of the "age" property equals 20:

The where parameter contains a URL encoded value of "age = 20";

curl
-H application-id:application-id-value-from-console
-H secret-key:secret-key-value-from-console
-X GET
-v https://api.backendless.com/v1/data/Person?where=age%3D20

Find all contacts where the value of the "age" property is greater than 21:

The where parameter contains a URL encoded value of "age > 21";

curl
-H application-id:application-id-value-from-console
-H secret-key:secret-key-value-from-console
-X GET
-v https://api.backendless.com/v1/data/Person?where=age%3E21

Find all contacts where the value of the "age" property is between 21 and 40:

The where parameter contains a URL encoded value of "age >= 21 AND age <=30";

curl
-H application-id:application-id-value-from-console
-H secret-key:secret-key-value-from-console
-X GET
-v https://api.backendless.com/v1/data/Person?where=age%3E%3D21%20AND%20age%20%3C%3D%2040

Find all contacts whose "age" property is 30 or 10:

Use the IN operator to identify several values of the "age" property for the search. That is, the "where" parameter should be set to "=age in (30,10)". Numbers in the parenthesis define the age groups, for which you will be searching. You can specify more than two groups if necessary. If an object value matches any of the values in the parenthesis, the object will be included into the search response.

curl
-H application-id:application-id-value-from-console
-H secret-key:secret-key-value-from-console
-X GET
-v https://api.backendless.com/v1/data/Person?where=age%2Bin%2B(30%2C10)

Find all contacts by name:

The where parameter contains a URL encoded value of "name = 'Bob'";

curl
-H application-id:application-id-value-from-console
-H secret-key:secret-key-value-from-console
-X GET
-v https://api.backendless.com/v1/data/Person?where=name%20%3D%20%27Bob%27

Find all contacts whose name is Tom or Kate:

Use the IN operator to identify several values of the "name" property for the search. That is, the "where" parameter should be set to "=name in ('Tom','Kate')". The value of the "where" parameter should URL-encoded. Values in the parenthesis define the names, for which you will be searching. You can specify more than two values if necessary. if an object value matches any of the values in the parenthesis, the object will be included into the search response.

curl
-H application-id:application-id-value-from-console
-H secret-key:secret-key-value-from-console
-X GET
-v https://api.backendless.com/v1/data/Users?where=name%20in%20(%27Tom%27%2C%27Kate%27)

Find all contacts by partial name match:

The where parameter contains a URL encoded value of "name LIKE 'J%'";

curl
-H application-id:application-id-value-from-console
-H secret-key:secret-key-value-from-console
-X GET
-v https://api.backendless.com/v1/data/Person?where=name%20LIKE%20%27J%25%27

Find objects within certain distance from a geo point

With the ability to link data objects with geo points, you can search for data objects by distance. This type of search returns all data objects which satisfy the whereClause condition and located within the specified distance. Distance-based search uses a special function in whereClause of the search request. The syntax of the function is:

distance( 
   center point latitude, 
   center point longitude, 
   columnname which contains geo point.latitude,
   columnname which contains geo point.longitude )<operator> units-function(value)

where:

<operator>- Possible values are <, >, =, >=, <=
units-function- Defines the units of measure for the distance. Possible values are:
ft( X ) - the distance value X is expressed in feet
km( X ) - the distance value X is expressed in kilometers
mi( X ) - the distance value X is expressed in miles
yd( X ) -  the distance value X is expressed in yards

For example, the following whereClause expression searches for data objects located within 200 miles from the point at 30.26715, -97.74306. Each data object must have the "coordinates" property of type GeoPoint. It is important that the entire whereClause which contains the distance function is URL-encoded.

distance( 30.26715, -97.74306, coordinates.latitude, coordinates.longitude ) < mi(200)

The following example demonstrates a search-by-distance query. The example uses three data objects stored in the Friend table: Bob, Jane, and Fred who respectively live in Austin, Houston, San Antonio. The search query in the example finds all friends who live within the specified distance. Before running the search query, create the objects in the data storage with the corresponding geo points.

Run the following query/code to store a data object representing Bob with a link to his home in Austin, TX:

 

-H application-id:application-id-value-from-console
-H secret-key:secret-key-value-from-console
-H Content-Type:"application/json"
-H application-type:REST
-X POST
-v "http://api.backendless.com/v1/data/Person"
-d '{"name":"Bob", "age":33, "phoneNumber":"512-555-1212", "coordinates": {"___class":"GeoPoint","latitude":30.26715,"longitude":-97.74306,"categories":["Home"],"metadata":{"description":"Bob's home"}}}'

Run the following query/code to store a data object representing Jane with a link to his home in Houston, TX:

-H application-id:application-id-value-from-console
-H secret-key:secret-key-value-from-console
-H Content-Type:"application/json"
-H application-type:REST
-X POST
-v "http://api.backendless.com/v1/data/Person"
-d '{"name":"Jane", "age":28, "phoneNumber":"281-555-1212", "coordinates": {"___class":"GeoPoint","latitude":29.76328,"longitude":-95.36327,"categories":["Home"],"metadata":{"description":"Jane's home"}}}'

Run the following query/code to store a data object representing Fred with a link to his home in San Antonio, TX:

-H application-id:application-id-value-from-console
-H secret-key:secret-key-value-from-console
-H Content-Type:"application/json"
-H application-type:REST
-X POST
-v "http://api.backendless.com/v1/data/Person"
-d '{"name":"Fred", "age":35, "phoneNumber":"210-555-1212", "coordinates": {"___class":"GeoPoint","latitude":29.42412,"longitude":-98.49363,"categories":["Home"],"metadata":{"description":"Fred's home"}}}'

 

Once the data is in the persistent object and geo location storage, run the following code/query to perform a distance-based search:

-H application-id:application-id-value-from-console
-H secret-key:secret-key-value-from-console
-H Content-Type:"application/json"
-H application-type:REST
-X GET
-v "http://api.backendless.com/v1/data/Person?where=distance(%2030.26715%2C%20-97.74306%2C%20coordinates.latitude%2C%20coordinates.longitude%20)%20%3C%20mi(200)"

 

The search returns all data objects within the specified distance. Each data object has the Coordinates property containing the coordinates of a geo point associated with this data 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.: