Collections
Every app or game has data which is specific to the project.
This information must be stored for each user, as well as updated, retrieved, and displayed within various parts of a UI. For this purpose the server incorporates a storage engine with a design optimized for object ownership, access permissions, and batch operations.
Data is stored in collections with one or more objects which contain a unique key with JSON content. A collection is created without any configuration required. This creates a simple nested namespace which represents the location of a object.
This design gives great flexibility for developers to group sets of information which belong together within a game or app.
Collection
+---------------------------------------------------------------------+
| Object |
| +----------+------------+-------------+-----+-------------------+ |
| | ?UserId? | Identifier | Permissions | ... | Value | |
| +---------------------------------------------------------------+ |
+---------------------------------------------------------------------+
The Collection and Key are used to identify the object itself. The UserId is used to identify the owner of an object, and to check for the needed read/write permissions when calling those operations on a object from the client.
Writing custom SQL is discouraged in favor of using the built-in features of the Storage Engine. If custom SQL is needed for your use case, please contact Heroic Labs before proceeding.
The creation of custom tables is strongly discouraged.
Write objects
A user can write one or more objects which will be stored in the database server. These objects will be written in a single transaction which guarantees the writes succeed together.
Conditional writes
When objects are successfully stored a version is returned which can be used with further updates to perform concurrent modification checks with the next write. This is known as a conditional write.
A conditional write ensures a client can only update the object if they’ve seen the previous version of the object. The purpose is to prevent a change to the object if another client has changed the value between the first client’s read and its next write.
We support another kind of conditional write which is used to write an object only if none already exists for that object’s collection and key.
Read objects
Just like with writing objects you can read one or more objects from the database server.
Each object has an owner and permissions. An object can only be read if the permissions allow it. An object which has no owner can be fetched with "null" and is useful for global objects which all users should be able to read.
List objects
You can list objects in a collection and page through results.
The objects returned can be filtered to those owned by a specific user, or "null" for all public records.
Remove objects
A user can remove an object if it has the correct permissions and they own it.
You can also conditionally remove an object if the object version matches the version sent by the client.