Skip to content

Retrieving objects

This operation retrieves data objects from a database table. The retrieval is performed according to the provided options, which allow you to:

  • Retrieve objects with a query
  • Using paging
  • Using sorting
  • With related objects
{
  "isolationLevelEnum" : "REPEATABLE_READ" | "READ_COMMITTED" | "READ_UNCOMMITTED" | "SERIALZABLE",
  "operations": [ 
    {
      "operationType": "FIND",
      "table": "TABLENAME",
      "opResultId": "OPRESULT-ID",
      "payload": {
         "pageSize" : VALUE,
         "offset" : VALUE,
         "properties" : ["prop1","prop2"],
         "whereClause" : "where clause",
         "groupBy" : ["prop1","prop2"]
         "havingClause" : "having clause",
         "queryOptions" : {
            "sortBy" : ["prop1","prop2"],
            "related" : ["rel11","rel2"],
            "relationsDepth" : VALUE,
            "relationsPageSize" : VALUE
         }
      }
    }
  ]
}

where:

Argument                Description
"operationType" The value must be "FIND", this designates the operation as "retrieving objects".
"table" The value must contain the name of the table where the object will be saved. The table must exist in the database before the transaction is executed.
"opResultId" This is an optional property. If present, must contain an Id for this operation. An operation Id is a free-form string that must be unique within the transaction. If the result of this operation is to be used as an input in another operation within the same transaction, the Id will be used to reference the result.
"payload" The value is mandatory. At the very minimum it must contain an empty JSON object - {}. Additional properties listed below may be added to form a query.
"pageSize" A numeric value. If set, specifies how many objects the server should return starting from the offset index. The first object has the index of 0.
"offset" A numeric value. If set, specifies from what index the objects should be returned. The first object has the index of 0.
"properties" A JSON array. If set, contains a list of property/column names as string values instructing the server to return the specified properties/columns.
"whereClause" A string value. If set, is a query which identifies the objects to be returned. The server returns only the objects which match the query. See the Search with the Where Clause section for more information.
"groupBy" A JSON array. If set, contains a list of property/column names to group the result by. Used with aggregate functions.
"havingClause" A string value. May be used in conjunction with the groupBy property to enable additional data filtering option for aggregate functions. See the Data Filtering section for additional details.
"queryOptions" > "sortBy" A JSON array. If set, contains a list of property/column names the result returned by the server will be sorted by.
"queryOptions" > "related" A JSON array. If set, contains a list of related property/column names for which the related child objects will be returned along with each parent object.
"queryOptions" > "relationsDepth" A numeric value. If set, specifies the depth of related objects the server should include into the response. For example, if relationsDepth is set to 2, and the chain of relations is objects from table A have related objects from table B and objects from B have related objects from table C, then the returned objects will include A's which reference B's which reference C's.
"queryOptions" > "relationsPageSize" A numeric value. If set, specifies how many related objects should be returned. The related objects are returned when any of the following conditions is true: (1) the auto-load option is enabled in Backendless Console in the table referenced by the "table" property; (2) "queryOptions" > "related" is present in the request; (3) "queryOptions" > "relationsDepth" is present in the request.

Important

You can retrieve a single object by setting the pageSize option to 1. However, remember the method still returns a collection of objects, therefore if you need to get only one object, you need to use the "resultIndex" property when referencing this operation's result

Return Value

The operation returns a collection of retrieved objects. The collection can be used as an argument in other operations in the same transaction. There are two ways to reference a result from a previous operation - using either {"___ref":true, "opResultId":"VALUE"} to reference the actual collection or {"___ref":true, "opResultId":"VALUE", "resultIndex":VALUE, "propName":"VALUE"} to reference an individual object from the collection or a property value of an object.

Example

The example below demonstrates retrieval of an object and updating its property in a transaction:

Request:

URL: 

POST https://xxxx.backendless.app/api/transaction/unit-of-work
Request header: 
Content-Type:application/json
Request body: 
{
  "isolationLevelEnum" : "SERIALZABLE",
  "operations": [
    {
      "operationType": "FIND",
      "table": "Country",
      "opResultId": "findCountry",
      "payload": {
        "whereClause":"name = 'India'",
        "pageSize":1
      }
    },
    {
      "operationType":"UPDATE",
      "table": "Country",
      "payload": {
         "objectId": { 
             "___ref":true,
             "opResultId":"findCountry",
             "resultIndex":0,
             "propName": "objectId"
         },
        "population": 1339000000
      }
    }
  ]
}

Response:

{
  "success": true,
  "error": null,
  "results": {
    "findCountry": {
      "type": "FIND",
      "result": [
        {
          "name": "India",
          "created": 1579825096648,
          "updated": 1585974596000,
          "objectId": "1359E34B-D4B3-C161-FFD5-928956F78500",
          "population": null,
          "ownerId": null,
          "___class": "Country"
        }
      ]
    },
    "updateCountry1": {
      "type": "UPDATE",
      "result": {
        "population": 1339000000,
        "updated": 1585975072000,
        "___class": "Country",
        "created": 1579825096648,
        "ownerId": null,
        "objectId": "1359E34B-D4B3-C161-FFD5-928956F78500",
        "name": "India"
      }
    }
  }
}