Skip to end of metadata
Go to start of metadata
This document provides information about custom objects and fields, how to create custom objects, adding and removing custom fields, and supported data types.

Custom objects and custom fields

Mobile Backend Services (MBS) provides many types of commonly used predefined objects such as Users and Photos. However, you may want to create custom data types or store custom fields on predefined MBS objects. Custom Objects and Custom Data Fields provide your application with this ability.

Creating custom objects

If you would like to create custom objects with a custom object type, please refer to CustomObjects to get a list of API calls that can be used to create and access custom objects.

Adding custom fields to predefined objects

If you would like to store additional custom data into any predefined MBS objects, you can pass in JSON encoded custom_fields. Any number of custom fields can be specified for an instance of a predefined object.

For example, if you are using the Users API and want to store the age and favorite color of each user, include JSON encoding of custom_fields.

For example, to associate the above custom fields to users:

 Expand source

Custom Data is returned in the custom_fields JSON response field in the type that was specified. Attempting to define custom fields using invalid types or an incorrect naming convention will be silently ignored.

Supported data types

Booleantrue or false
Number23 or 1.234
Date"2011-11-02 17:07:37 -0700". If a string value matches date format "yyyy-mm-dd hh:mm:ss+zzzz" or "yyyy-mm-dd:hh:mm:ss+zzzz", it will be converted to Date type on the API Builder backend

You could also store more complex data types, such as Array and Hash. Hash and Array can be embedded into each other. Currently, data stored inside a Hash is not queryable.

Hash{"age":23,"scores":{"math":90, "physics":100}, "my_favorite_colors":["blue","red"]}
Array["nissan", "honda"] or [2006, 2008], [{"age":28}, {"color":"blue"}]

Indexing size limit for custom objects and fields

To support efficient data query operations, MBS indexes the field names and values of each custom object, or custom fields you add to a predefined object. For example, suppose you create a custom object, cars, with the fields make and model. Mobile Backend Services will create two index entries in the MongoDB database, one for each field. The total size of an index entry, including meta-data added by MBS, must be less than 1024 bytes (1KB).

If a custom field's name or value exceeds this size, then no index entry for that field is created. Consequently, if you run a custom query against that field, nothing will be returned.

For instance, in the previous example, suppose the string value assigned to the model was greater than 1KB. If you queried the cars collection for objects whose model matched that value, no objects would be returned:

Geographic coordinates in custom fields

To enable geographical searches, there is a predefined custom coordinates field for optionally storing geographic coordinates. The coordinates field can store a single location as an array ( [longitude, latitude] ) or multiple locations as an array of arrays ( [[longitude1,latitude1], [longitude2, latitude2]] ). So for the above example, to store location information about the user, we might have:

Remove a field

If you wish to remove a custom field during an update, set the field value to null.

Querying custom fields

Data stored in custom fields other than Array and Hash can be queried together with predefined fields. Please refer to Query for more information. If you define a custom field name that is the same as one of the predefined fields, you will be able to store and retrieve it, but you won't be able to query on it since the query action would be performed on the predefined field instead. For example, Users have a predefined field called first_name, if you define a custom field also called first_name, when you try to query first_name, it will only query against the predefined first_name field.


The following MBS objects allow you to add one or more extra data fields during create and update actions:


If you are using the iOS APS SDK to create an object's custom fields, use an NSDictionary to construct the custom data you want to associate with the object.

The following table lists the data types you can define with the iOS APS SDK:

TypeExampleiOS Class
Number123 or 1.234[NSNumber numberWithInt:] or [NSNumber numberWithDouble:]
Booleantrue or false[NSNumber numberWithBool:]
Date"2011-11-02 17:07:37 -0700"NSString
Hash{"age": 23, "color": "blue"}NSDictionary
Array[123, 234] or ["mike", "joe"]NSArray
Geo-coordinates[lng, lat], e.g. [122.33, 37.48]NSArray with two NSNumber elements

For example, if you want to create a user with custom fields, such as eye_color, enrolled_at, etc., you can put all the custom fields in an NSDictionary.

 Expand source

If you would like to use your custom data type, you need to provide a class method to JSON to encode the data of your object.