GetEntityPage

Retrieves the first page of custom entities from the server based on the custom entity type and specified query context.

Note that for collections with > 1,000 records, it is recommended that doCount be set to false for better performance.

Example context object:

{
  "pagination": {
    "rowsPerPage": 50,
    "pageNumber": 1,
    "doCount": false
  },
  "searchCriteria": {
    "data.position": "defense"
  },
  "sortCriteria": {
  }
}

caution

Note that one has to be careful when using GetEntityPage() with owned entities.

The system's behaviour will vary depending upon the setting of the new compatibility flag:

[ ] Include shared objects in Owned Custom Entity GetEntityPage queries (warning: can be slow). Can be overwritten by specifying 'ownedOnly' in query context 'options'.

If the flag is enabled (i.e. checked), the system will look for all objects that match the search criteria that:

• are owned by the user, and...
• are accessible by the user (i.e. acl.other is not 0)

That second part of the search criteria is a waste if you are only looking for objects owned by the user - which is normally the case. (It can also be very slow and CPU intensive if the search query is too broad in that context.)

For this reason, it is highly recommended that all apps un-check this compatibility flag - so that the default query syntax is as efficient as possible, by focusing on objects owned by the user only.

Once un-checked, it is still possible to search for shared entities (i.e. entities whose acl.other is not 0) by including a special ownedOnly option in the query:

Example context object with ownedOnly option:

{
  "pagination": {
    "rowsPerPage": 50,
    "pageNumber": 1,
    "doCount": false
  },
  "searchCriteria": {
    "data.position": "defense"
  },
  "sortCriteria": {
  },
  "options": {
    "ownedOnly": false
  }
}

info

In all cases, having proper custom indexes defined for your queries is essential for best performance. Developers are encouraged to contact support to have our team examine your entities and indexes before significant launches / feature releases. We are happy to help!

info

Developers are now able to access Atlas “explain” information for Custom Entity GetPage() queries – via the API Explorer ONLY!

This can be useful when evaluating whether your indexes are sufficient to cover specific queries. The explain results can tell you what indexes Atlas will utilize for the query – and stats on the resulting query performance.

To request the explain data for a GetEntityPage() query – simply supply an “options” section under "context" field with the desired “explain” level. For example:

{
  "pagination": {
    "rowsPerPage": 50,
    "pageNumber": 1,
    "doCount": false
  },
  "searchCriteria": {
    "data.position": "defense"
  },
  "sortCriteria": {},
  "options": {
    "explain": "QUERY_PLANNER"
  }
}

The following 3 levels are supported:

QUERY_PLANNER – MongoDB runs the query optimizer to choose the winning plan for the operation under evaluation – and returns the queryPlanner information for the evaluated method.

EXECUTION_STATS – MongoDB runs the query optimizer to choose the winning plan, executes the winning plan to completion, and returns statistics describing the execution of the winning plan.

ALL_PLANS_EXECUTION – MongoDB runs the query optimizer to choose the winning plan and executes the winning plan to completion. In “allPlansExecution” mode, MongoDB returns statistics describing the execution of the winning plan as well as statistics for the other candidate plans captured during plan selection.

The explain results are returned in a map named explain under the data section of the results JSON.

Service	Operation
customEntity	GET_ENTITY_PAGE

Method Parameters

Parameter	Description
entityType	The type of custom entity being retrieved.
context	A context object describing the desired paging behaviour

Usage

http://localhost:3000

C#

string entityType = "athletes";
string context = "{\"pagination\":{\"rowsPerPage\":50,\"pageNumber\":1},\"searchCriteria\":{\"data.position\":\"defense\"},\"sortCriteria\":{\"createdAt\":1,\"updatedAt\":-1}}";

SuccessCallback successCallback = (response, cbObject) =>
{
    Debug.Log(string.Format("Success | {0}", response));
};
FailureCallback failureCallback = (status, code, error, cbObject) =>
{
    Debug.Log(string.Format("Failed | {0}  {1}  {2}", status, code, error));
};

_bc.CustomEntityService.GetEntityPage(entityType, context, successCallback, failureCallback);

C++

const char *entityType = "athletes";
const char *context = "{\"pagination\":{\"rowsPerPage\":50,\"pageNumber\":1},\"searchCriteria\":{\"data.position\":\"defense\"},\"sortCriteria\":{\"createdAt\":1,\"updatedAt\":-1}}";

_bc->getCustomEntityService()->getEntityPage(entityType, context, this);

Objective-C

NSString *entityType = @"athletes";
NSString *context = @"{\"pagination\":{\"rowsPerPage\":50,\"pageNumber\":1},\"searchCriteria\":{\"data.position\":\"defense\"},\"sortCriteria\":{\"createdAt\":1,\"updatedAt\":-1}}";

BCCompletionBlock successBlock;      // define callback
BCErrorCompletionBlock failureBlock; // define callback

[[_bc customEntityService] getEntityPage:entityType
                    context:context
            completionBlock:successBlock
       errorCompletionBlock:failureBlock
                   cbObject:nil];

Java

String entityType = "athletes";
String context = "{\"pagination\":{\"rowsPerPage\":50,\"pageNumber\":1},\"searchCriteria\":{\"data.position\":\"defense\"},\"sortCriteria\":{\"createdAt\":1,\"updatedAt\":-1}}";
this; // implements IServerCallback

_bc.getCustomEntityService().getEntityPage(entityType, context, this);

public void serverCallback(ServiceName serviceName, ServiceOperation serviceOperation, JSONObject jsonData)
{
    System.out.print(String.format("Success | %s", jsonData.toString()));
}
public void serverError(ServiceName serviceName, ServiceOperation serviceOperation, int statusCode, int reasonCode, String jsonError)
{
    System.out.print(String.format("Failed | %d %d %s", statusCode,  reasonCode, jsonError.toString()));
}

JavaScript

var entityType = "athletes";
var context = {
    "pagination": {
        "rowsPerPage": 50,
        "pageNumber": 1
    },
    "searchCriteria": {
        "data.position": "defense"
    },
    "sortCriteria": {
        "createdAt": 1,
        "updatedAt": -1
    }
};

_bc.customEntity.getEntityPage(entityType, context, result =>
{
    var status = result.status;
    console.log(status + " : " + JSON.stringify(result, null, 2));
});

Dart

var  entityType = "athletes";
var  context = {
    "pagination": {
        "rowsPerPage": 50,
        "pageNumber": 1
    },
    "searchCriteria": {
        "data.position": "defense"
    },
    "sortCriteria": {
        "createdAt": 1,
        "updatedAt": -1
    }
};

ServerResponse result = await _bc.customEntityService.getEntityPage(entityType:entityType, context:context);

if (result.statusCode == 200) {
    print("Success");
} else {
    print("Failed ${result.error['status_message'] ?? result.error}");
}

Cloud Code

var entityType = "athletes";
var context = {
  "pagination": {
    "rowsPerPage": 50,
    "pageNumber": 1
  },
  "searchCriteria": {
    "data.position": "defense"
  },
  "sortCriteria": {
    "createdAt": 1
  }
};

var customEntityProxy = bridge.getCustomEntityServiceProxy();

var postResult = customEntityProxy.getEntityPage(entityType, context);
if (postResult.status == 200) {
    // Success!
}

Raw

{
    "service": "customEntity",
    "operation": "GET_ENTITY_PAGE",
    "data": {
        "entityType": "athletes",
        "context": {
            "pagination": {
                "rowsPerPage": 50,
                "pageNumber": 1
            },
            "searchCriteria": {
                "data.position": "defense"
            },
            "sortCriteria": {
                "createdAt": 1,
                "updatedAt": -1
            }
        }
  }
}

JSON Response

{
  "status": 200,
  "data": {
    "_serverTime": 1637946319239,
    "context": "lciI6MSwiZG9Db3VudCI6dHJ...",
    "results": {
      "count": 4,
      "page": 1,
      "items": [
        {
          "entityId": "f9d91cda-3ece-447c-bf81-046fa026520c",
          "version": 1,
          "acl": {
            "other": 1
          },
          "ownerId": null,
          "expiresAt": null,
          "timeToLive": null,
          "createdAt": 1573537595505,
          "updatedAt": 1573537595505,
          "data": {
            "firstName": "Super",
            "surName": "Star",
            "position": "defense",
            "goals": 2,
            "assists": 4
          }
        },
        {
          "entityId": "1497cc7e-66cb-4682-9eac-c755523369a8",
          "version": 3,
          "acl": {
            "other": 1
          },
          "ownerId": null,
          "expiresAt": null,
          "timeToLive": null,
          "createdAt": 1573540122600,
          "updatedAt": 1573540445332,
          "data": {
            "firstName": "Super",
            "surName": "Star2",
            "position": "defense",
            "goals": 3,
            "assists": 5
          }
        }
      ],
      "moreAfter": true,
      "moreBefore": false
    }
  }
}