Learn how to store and sync data with QuickBlox key-value storage.
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 [< longitude >, < latitude >]); File; Date.
Visit Key Concepts page to learn the most important QuickBlox concepts.
To start using Custom Objects module, create a class:
Here is the easiest way to create a new record from the QuickBlox Dashboard:
You can also create a new record/records using the create()
method. To create a single record, use the code snippet below.
To create multiple records, use the code snippet below.
Argument | Required | Description |
---|---|---|
className | yes | A name of a custom object class. |
data | yes | Data records that will be created. |
function() | yes | Specifies a callback function that accepts an error and result. |
You can get records with a particular record ID using the list()
method.
Argument | Required | Descriptions |
---|---|---|
className | yes | A name of a custom object class. |
ids | yes | Records IDs. |
function() | yes | Specifies a callback function that accepts an error and result. |
You can search for records of a particular class. The request below will return records of the Note
class with specific IDs in the array.
Argument | Required | Description |
---|---|---|
className | yes | A name of a custom object class. |
filter | yes | Specifies filtering criteria for the field. |
function() | yes | Specifies a callback function that accepts an error and result. |
If you want to retrieve only records updated after some specific date time and order the search results, you can apply operators. Thus, you can apply search and sort operators to list records on the page so that it is easier to view specific records.
If you want to get a paginated list of dialogs from the server, you can set the following fields of the filter
:
Field | Required | Description |
---|---|---|
skip | no | Skip N records in search results. Useful for pagination. Default (if not specified): 0. Should be an Integer. |
limit | no | Limit search results to N records. Useful for pagination. Default value: 100. |
You can use search operators to get more specific search results. The request below will return two records of the GameOfThrones
by the age
field with a value greater than 20
, limited to 2 records on the page.
Here are the search operators that you can use to search for the exact data that you need.
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. |
You can use sort operators to order the search results. The request below will return records of GameOfThrones
class sorted in descending order by the created_at
field.
Here are the sort options that you can use to sort the search results.
Sort options | Applicable to types | Description |
---|---|---|
sort_asc | All types | Search results will be sorted in ascending order by the specified field. |
sort_desc | All types | Search results will be sorted in descending order by the specified field. |
You can use an aggregation operator to count search results. The request below will return a count of all records of the GameOfThrones
class.
Here are the aggregation operators you can use to count records:
Aggregation operator | Description |
---|---|
count | Count search results. The response will contain only a count of records found. Set count to 1 to apply. |
You can update a single record using the update()
method. You should know the record ID in this case.
You can update multiple records using the code snippet below.
To delete a record/records, use the delete()
method. To delete a single record, use the code snippet below.
Argument | Required | Description |
---|---|---|
className | yes | A name of a custom object class. |
id | yes | ID of the record. |
function() | yes | Specifies a callback function that accepts an error and result. |
To delete multiple records, use the code snippet below.
Argument | Required | Description |
---|---|---|
className | yes | A name of a custom object class. |
ids | yes | Records IDs. |
function() | yes | Specifies a callback function that accepts an error and result. |
To delete a record by criteria, use the code snippet below.
Argument | Required | Description |
---|---|---|
className | yes | A name of a custom object class. |
criteria | yes | Specifies criteria fields that should be set. |
function() | yes | Specifies a callback function that accepts an error and result. |
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>
.
Access control list (ACL) is a list of permissions attached to some object. An ACL specifies which users have access to objects as well as what operations are allowed on given objects. Each entry in a typical ACL specifies a subject and an operation. ACL models may be applied to collections of objects as well as to individual entities within the system hierarchy.
Access Control list available only for Custom Objects module.
QuickBlox Permission schema contains five permissions levels:
There are two access levels in the Permissions schema: Class and Record.
Only the Account Administrator can create a class in the Custom object module and make all possible actions with it. Operations with Class entity are not allowed in API.
All actions (Create, Read, Update, and Delete) are available for the class entity and are applicable for all records in the class. Every action has a separate permission level available. The exception is a Create action that is not available for the Owner permission level.
To set a permission schema for the Class, do the following:
Default Class permission schema is used while creating a class:
Mark checkboxes to enable class permissions.
A record is an entity within the class in the Custom Objects module that has its own permission levels. You can create a record in the Dashboard and API (see Create Record request for more details). All permission levels except for the Not Allowed are available for the record and there are only three actions available and applicable for the record: Read, Update, and Delete.
Default Record permission schema is used while creating a class:
To set a permission level open the required Class and click the record to edit it.
Only one permission level can be applicable to the record: class permission schema or record permission schema. To apply class permission levels to all records in the class, tick the checkbox in the Use Class permissions column near the required Action in the Dashboard.
Using a class permission schema means that a record permission schema will not affect a reсord.
In case, the Admin does not tick the checkbox in the Dashboard a user has a possibility to change permission levels for every separate record in the table or create a new one with the ACL that a user requires.
Let’s create a record with the next permissions:
Let’s update record permissions to next:
Argument | Required | Description |
---|---|---|
className | yes | A name of a custom object class. |
payload | yes | Specifies payload fileds that should be set. |
function() | yes | Specifies a callback function that accepts an error and result. |
Custom Objects module supports the File
field type. It is created to work easily with content from the Custom Objects module. There is an ability to upload, download, update and delete the content of file fields.
Use the code lines below to upload/update a file.
To download a file, use the code snippet below.
To delete a file, use the code snippet below.
Learn how to store and sync data with QuickBlox key-value storage.
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 [< longitude >, < latitude >]); File; Date.
Visit Key Concepts page to learn the most important QuickBlox concepts.
To start using Custom Objects module, create a class:
Here is the easiest way to create a new record from the QuickBlox Dashboard:
You can also create a new record/records using the create()
method. To create a single record, use the code snippet below.
To create multiple records, use the code snippet below.
Argument | Required | Description |
---|---|---|
className | yes | A name of a custom object class. |
data | yes | Data records that will be created. |
function() | yes | Specifies a callback function that accepts an error and result. |
You can get records with a particular record ID using the list()
method.
Argument | Required | Descriptions |
---|---|---|
className | yes | A name of a custom object class. |
ids | yes | Records IDs. |
function() | yes | Specifies a callback function that accepts an error and result. |
You can search for records of a particular class. The request below will return records of the Note
class with specific IDs in the array.
Argument | Required | Description |
---|---|---|
className | yes | A name of a custom object class. |
filter | yes | Specifies filtering criteria for the field. |
function() | yes | Specifies a callback function that accepts an error and result. |
If you want to retrieve only records updated after some specific date time and order the search results, you can apply operators. Thus, you can apply search and sort operators to list records on the page so that it is easier to view specific records.
If you want to get a paginated list of dialogs from the server, you can set the following fields of the filter
:
Field | Required | Description |
---|---|---|
skip | no | Skip N records in search results. Useful for pagination. Default (if not specified): 0. Should be an Integer. |
limit | no | Limit search results to N records. Useful for pagination. Default value: 100. |
You can use search operators to get more specific search results. The request below will return two records of the GameOfThrones
by the age
field with a value greater than 20
, limited to 2 records on the page.
Here are the search operators that you can use to search for the exact data that you need.
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. |
You can use sort operators to order the search results. The request below will return records of GameOfThrones
class sorted in descending order by the created_at
field.
Here are the sort options that you can use to sort the search results.
Sort options | Applicable to types | Description |
---|---|---|
sort_asc | All types | Search results will be sorted in ascending order by the specified field. |
sort_desc | All types | Search results will be sorted in descending order by the specified field. |
You can use an aggregation operator to count search results. The request below will return a count of all records of the GameOfThrones
class.
Here are the aggregation operators you can use to count records:
Aggregation operator | Description |
---|---|
count | Count search results. The response will contain only a count of records found. Set count to 1 to apply. |
You can update a single record using the update()
method. You should know the record ID in this case.
You can update multiple records using the code snippet below.
To delete a record/records, use the delete()
method. To delete a single record, use the code snippet below.
Argument | Required | Description |
---|---|---|
className | yes | A name of a custom object class. |
id | yes | ID of the record. |
function() | yes | Specifies a callback function that accepts an error and result. |
To delete multiple records, use the code snippet below.
Argument | Required | Description |
---|---|---|
className | yes | A name of a custom object class. |
ids | yes | Records IDs. |
function() | yes | Specifies a callback function that accepts an error and result. |
To delete a record by criteria, use the code snippet below.
Argument | Required | Description |
---|---|---|
className | yes | A name of a custom object class. |
criteria | yes | Specifies criteria fields that should be set. |
function() | yes | Specifies a callback function that accepts an error and result. |
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>
.
Access control list (ACL) is a list of permissions attached to some object. An ACL specifies which users have access to objects as well as what operations are allowed on given objects. Each entry in a typical ACL specifies a subject and an operation. ACL models may be applied to collections of objects as well as to individual entities within the system hierarchy.
Access Control list available only for Custom Objects module.
QuickBlox Permission schema contains five permissions levels:
There are two access levels in the Permissions schema: Class and Record.
Only the Account Administrator can create a class in the Custom object module and make all possible actions with it. Operations with Class entity are not allowed in API.
All actions (Create, Read, Update, and Delete) are available for the class entity and are applicable for all records in the class. Every action has a separate permission level available. The exception is a Create action that is not available for the Owner permission level.
To set a permission schema for the Class, do the following:
Default Class permission schema is used while creating a class:
Mark checkboxes to enable class permissions.
A record is an entity within the class in the Custom Objects module that has its own permission levels. You can create a record in the Dashboard and API (see Create Record request for more details). All permission levels except for the Not Allowed are available for the record and there are only three actions available and applicable for the record: Read, Update, and Delete.
Default Record permission schema is used while creating a class:
To set a permission level open the required Class and click the record to edit it.
Only one permission level can be applicable to the record: class permission schema or record permission schema. To apply class permission levels to all records in the class, tick the checkbox in the Use Class permissions column near the required Action in the Dashboard.
Using a class permission schema means that a record permission schema will not affect a reсord.
In case, the Admin does not tick the checkbox in the Dashboard a user has a possibility to change permission levels for every separate record in the table or create a new one with the ACL that a user requires.
Let’s create a record with the next permissions:
Let’s update record permissions to next:
Argument | Required | Description |
---|---|---|
className | yes | A name of a custom object class. |
payload | yes | Specifies payload fileds that should be set. |
function() | yes | Specifies a callback function that accepts an error and result. |
Custom Objects module supports the File
field type. It is created to work easily with content from the Custom Objects module. There is an ability to upload, download, update and delete the content of file fields.
Use the code lines below to upload/update a file.
To download a file, use the code snippet below.
To delete a file, use the code snippet below.