Would you like to contribute to the Titanium docs? To get started, sign up for an account on the Appcelerator Wiki and sign our CLA.

Skip to end of metadata
Go to start of metadata
This document provides information about custom objects and field, 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 simply 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, simply include JSON encoding of custom_fields

For example, to associate the above custom fields in user create

 Expand source

Custom Data are 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

TypeExample
Boolean    true or false
String    "blue"
Number    23 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-ddThh: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.

TypeExample
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 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 search, there is a predefined custom field, coordinates, 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 update, simply 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 has 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.

Availability

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

iOS

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
String    "blue"    NString
Number    123 or 1.234[NSNumber numberWithInt:] or [NSNumber numberWithDouble:]    
Boolean    true 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.

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