QuickBlox Documentation

QuickBlox provides powerful Chat API and SDK to add real-time messaging and video calls to your web and mobile apps. Learn how to integrate QuickBlox across multiple platforms.

Custom Objects

Learn how to store and sync data with QuickBlox key-value storage.

🚧

This is our documentation for beta version of QuickBlox Flutter SDK. Please contact our Customer Support Team to provide your feedback, suggestions, and requests to improve this page.

Custom Objects module provides flexibility to define any data structure (schema) you need, build one-to-many relations between schemas and control permissions for all operations made on data. Schema is defined in QuickBlox Dashboard.

There are two key concepts in Custom Objects:
- Class represents your schema and contains field names and types.
- Record represents the data you put into your schema.

Class and Record are similar to table and row in relational database. Every class in Custom Object module comes with five mandatory predefined fields: _id, user_id, parent_id, created_at, and updated_at.

Allowed data types: Integer (or Array of Integer); String (or Array of String); Float (or Array of Float); Boolean (or Array of Boolean); Location (Array of [, ]); File; Date.

Before you begin

  1. Visit our Key Concepts page to get an overall understanding of the most important QuickBlox concepts.
  2. Register a QuickBlox account. This is a matter of a few minutes and you will be able to use this account to build your apps.
  3. Configure QuickBlox SDK for your app. Check out our Setup page for more details.
  4. Create a user session to be able to use QuickBlox functionality. See our Authentication page to learn how to do it.

Create class

To start using Custom Objects module, create a class:

  1. Go to QuickBlox Dashboard.
  2. Follow Custom => Add => Add new class direction. As a result, Add new class popup will appear.
  3. Enter a class name, add any fields you want.
  1. Click Create class button to create a new class.

Create records

The easiest way to create a new record from the QuickBlox Dashboard, do the following:

  1. Follow Custom => Current class => Your Class direction.
  2. Click Add => Add record button and Add new record popup will appear.
  3. Fill in any fields you want.
  4. Click Add record button and a new record will be added and shown in the table.

To create a single object, use the code snippet below.

Map<String, Object> fieldsMap = Map();
 fieldsMap['testString'] = "testField";
 fieldsMap['testInteger'] = 123;
 fieldsMap['testBoolean'] = true;

 String className = "TestFlutterClass";

try {
  List<QBCustomObject> customObjectsList = await QB.data.create(
      className: className, 
      fields: fieldsMap);
} on PlatformException catch (e) {
  // Some error occured, look at the exception message for more details
}

Parameters

Description

className

(optional) Name of a custom object class.

fields

(optional) Data fields (Map<String, Object>).

To create a multiple objects, use the code snippet below.

Map<String, Object> fieldsMapOne = Map();
fieldsMapOne['testString'] = "testField1";
fieldsMapOne['testInteger'] = 123;
fieldsMapOne['testBoolean'] = true;

Map<String, Object> fieldsMapTwo = Map();
fieldsMapTwo['testString'] = "testField2";
fieldsMapTwo['testInteger'] = 456;
fieldsMapTwo['testBoolean'] = false;
    
List<Map<String, Object>> objectsList = new List();
objectsList.add(fieldsMapOne);
objectsList.add(fieldsMapTwo);

String className = "TestFlutterClass";

try {
  List<QBCustomObject> customObjectsList = await QB.data.create(
      className: className, 
      objects: objectsList);
} on PlatformException catch (e) {
  // Some error occured, look at the exception message for more details
}

Parameters

Description

className

(optional) Name of a custom object class.

objects

(optional) Custom objects list (List<Map<String, Object>>).

Retrieve records by IDs

To get records with a particular record ID, use the getByIds() method. Set the record ID using the ids object. Go over Filter and Search operators sections to learn about filters and search operators you can use to retrieve records.

String className = "TestFlutterClass";

List<String> ids = ["5d4175afa0eb4715cae5b63f", "5d4175afa0eb4715cae99783"];

try {
  List<QBCustomObject> customObjects = await QB.data.getByIds(
      className, 
      ids;
} on PlatformException catch (e) {
  // Some error occured, look at the exception message for more details
}

Parameters

Description

className

Name of a custom object class.

ids

Custom objects IDs.

Retrieve records

You can search for records of a particular class using filters and/or search operators.

String className = "TestFlutterClass";

QBFilter qbFilter = QBFilter();
qbFilter.operator = QBCustomObjectsStringSearchTypes.CTN;
qbFilter.value = "1000";
qbFilter.type = QBCustomObjectsFilterTypes.STRING;
qbFilter.field = "version";

QBSort qbSort = new QBSort();
qbSort.ascending = false;
qbSort.field = "created_at";

int limit = 50;
int skip = 10;

try {
  List<QBCustomObject> customObjects = await QB.data.get(
      className, 
      sort: qbSort, 
      filter: qbFilter, 
      limit: limit, 
      skip: skip);
} on PlatformException catch (e) {
  // Some error occured, look at the exception message for more details
}

Filters

Here are the filters that you can use to retrieve records.

Filter

Applicable to types

Description

{field_name}

All types

Search records with the field which contains the specified value.

{field_name}[{search_operator}]

All types

Search a record with the field which contains the value according to the specified value and operator.

sort_asc

All types

Search results will be sorted by the specified field in ascending order.

sort_desc

All types

Search results will be sorted by the specified field in descending order.

skip

Integer

Skip N records in search results. Useful for pagination. Default (if not specified): 0.

limit

Integer

Limit search results to N records. Useful for pagination. Default value: 100. If limit is equal to 1, only the last record will be returned.

count

Integer

Count search results. Response will contain only count of records found.

output[include]

All types

The output parameter takes the form of a record with a list of fields for inclusion or exclusion from the result set. output[include] specifies the fields to include. The _id field is, by default, included in the result set. To exclude the _id field from the result set, you need to specify in the output[exclude] value the exclusion of the _id field.

output[exclude]

All types

The output parameter takes the form of a record with a list of fields for inclusion or exclusion from the result set. output[exclude] specifies the fields to exclude. The _id field is, by default, included in the result set. To exclude the _id field from the result set, you need to specify in the output[exclude] value the exclusion of the _id field.

near

Location

Search records in a specific radius with current position in meters. Format: field_name, longitude, latitude, radius (in meters).

Search operators

Here are the search operators that you can use to retrieve records.

Search operators

Applicable to types

Description

lt

Integer, Float

Less Than operator.

lte

Integer, Float

Less Than or Equal to operator.

gt

Integer, Float

Greater Than operator.

gte

Integer, Float

Greater Than or Equal to operator.

ne

Integer, Float, String, Boolean

Not Equal to operator.

in

Integer, Float, String

IN array operator.

nin

Integer, Float, String

Not IN array operator.

all

Array

ALL are contained in array.

or

Integer, Float, String

All records that contain a value 1 or value 2.

ctn

String

All records that contain a particular substring.

Update records

To update a single record with a particular record ID, use the code snippet below.

String className = "TestFlutterClass";

String objectId = "5d4175afa0eb4715cae5b63f";
    
Map<String, Object> fieldsMap = Map();
fieldsMap['testString'] = "testField1";
fieldsMap['testInteger'] = 123;
fieldsMap['testBoolean'] = true;

try {
  QBCustomObject customObject = await QB.data.update(
      className, 
      id: objectId, 
      fields: fieldsMap);
} on PlatformException catch (e) {
  // Some error occured, look at the exception message for more details
}

Parameters

Description

className

Name of a custom object class.

id

(optional) Custom object ID.

fields

(optional) List of updating fields.

You can update multiple records using the code snippet below.

String className = "TestFlutterClass";

Map<String, Object> fieldsMapOne = Map();
fieldsMapOne['testString'] = "testField1";
fieldsMapOne['testInteger'] = 123;
fieldsMapOne['testBoolean'] = true;

Map<String, Object> fieldsMapTwo = Map();
fieldsMapTwo['testString'] = "testField2";
fieldsMapTwo['testInteger'] = 456;
fieldsMapTwo['testBoolean'] = false;
    
List<Map<String, Object>> objectsList = new List();
objectsList.add(fieldsMapOne);
objectsList.add(fieldsMapTwo);

try {
  QBCustomObject customObject = await QB.data.update(
      className,  
      objects: objectsList);
} on PlatformException catch (e) {
  // Some error occured, look at the exception message for more details
}

Parameters

Description

className

Name of a custom object class.

objects

(optional) Custom objects list (Map<String, Object>).

Delete records

To delete a single record, use the code snippet below.

List<String> ids = ["5d4175afa0eb4715cae5b63f"];

try {
  await QB.data.remove(className, idsList);
} on PlatformException catch (e) {
  // Some error occured, look at the exception message for more details
}

Parameters

Description

className

Name of a custom object class.

idsList

Custom objects IDs list (List<String>).

To delete a multiple records, use the code snippet below.

List<String> ids = ["5d4175afa0eb4715cae5b63f", "5d4175afa0eb4715cae99783"];

try {
  await QB.data.remove(className, idsList);
} on PlatformException catch (e) {
  // Some error occured, look at the exception message for more details
}

Parameters

Description

className

Name of a custom object class.

idsList

Custom objects IDs list (List<String>).

Relations

It is possible to create a relation between objects of two different classes via _parent_id field.

For example, we have the class Rating that contains score, review, and comment fields. We also have a Movie class. So we can create a record of class Rating that will point to the record of the class Movie via its _parent_id field, so the _parent_id field will contain the ID of record from class Movie.

🚧

This is not a simple soft link. This is actually a hard link. When you delete the Movie class record then all its children (records of class Rating with _parent_id field set to the Movie class record ID) will be automatically deleted as well.

📘

If you need to retrieve all children, you can retrieve records with the filter _parent_id=<id_of_parent_class_record>.

Updated a day ago


What's Next

Address Book

Custom Objects


Learn how to store and sync data with QuickBlox key-value storage.

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.