CustomEntity.GetEntityPage() Improvement
The Challenge
Last week we became aware of a potential issue when using GetEntityPage() with owned entities.
The issue is related to how brainCloud handles ACL permissions. As you may or may not know, all entities in brainCloud support ACL permissions – and you can set the global accessibility of an object by setting the acl.other permission to one of the following:
- 0 = no access
- 1 = read-only access
- 2 = read + write access
In loose terms, any object with acl.other != 0 is shared with (or accessible by) all users of the app.
This has large implications when dealing with Owned Custom Entities and the GetEntityPage() call – because by the previous default – the call would look for all entities that meet the search criteria that:
- Are owned by the current user
- Are accessible by the current user
Owned is simple – we simply add “ownerId”:
Accessible is not so simple – the database must look at all of the objects that the player doesn’t own, and specifically examine each objects ACL to see if acl.other != 0 !!! This is incredibly slow, and exponentially so! Especially since 99.9% of the time, a developer is only looking for the entities owned by the current user!
The Solution
To address this issue, we are changing to the default behaviour of `GetEntityPage() so that it no longer considers shared entities (by default) for Owned Custom Entities.
Thus, a query with the following criteria will now only return objects that are owned by the current user:
{
"pagination": {
"rowsPerPage": 50,
"pageNumber": 1
},
"searchCriteria": {
"data.position": "defense"
},
"sortCriteria": {
}
}Going forward, if an app wants to modify this default behaviour to include accessible (i.e. shared) objects that are owned by other users – they can add the new ownedOnly: false option. For example:
{
"pagination": {
"rowsPerPage": 50,
"pageNumber": 1
},
"searchCriteria": {
"data.position": "defense"
},
"sortCriteria": {
},
"options": {
"ownedOnly": false
}
}
Compatibility Flag
Because this is a change to the previous brainCloud behaviour, we have introduced a new compatibility flag. When enabled, the following flag preserves the old functionality – where both objects owned and accessible by the user will be returned.
The new compatibility flag can be found in the Design | Core App Info | Advanced Settings page:
[ x ] Include shared objects in Owned Custom Entity GetEntityPage queries (warning: can be slow). Can be overwritten by specifying ‘ownedOnly’ in query context ‘options’.
When enabled, the default for ownedOnly is false – and when disabled, the default for ownedOnly is true.
We believe strongly that this new-and-improved GetEntityPage behaviour is the better + safer default – and thus highly recommend that all developers whose owned queries are only expecting objects owned by the current user go to this compatibility flag and immediately “uncheck” it to enable the new behaviour!
Remember – this option does not affect queries for Un-owned Custom Entities. It also does not affect Sys calls. So both of those scenarios will continue to return objects not owned by the current user – regardless of the compatibility setting.
If you have any questions – please reach out to the support team.
Cheers!
