Lists
Use Lists to store large amounts of data. List is a quick way to get and search data. Also list is preferred way for organize statistics.
List - it is a collection of properties or users.
Examples:
  • history (orders history, transactions, payments history, locations history, etc)
  • large price lists
  • table of cities with population
  • results for Inline Bot​
  • referrals list
Do not use JSON property to collect a large array. This is a very bad practice.
"Execution timeout" error - it is typical error if you use JSON prop for large data.
Use a List.

List initialization

Before using the list (new or existing), you need to initialize it.
List can be global for Bot:
1
let list = new List({ name: "MyList" })
2
​
3
Bot.inspect(list.exist) // false for new List, true for already exist list
Copied!
or can be personal for user:
1
let list = new List({ name: "MyList", user: user })
2
​
3
// or for user id
4
let list = new List({ name: "MyList", user_id: user.id })
Copied!
After it you can perform another list methods

Create new list

1
// for list saving
2
if(!list.exist){
3
list.create()
4
}
Copied!

Remove list

1
list.remove();
Copied!

Recount list

Recalculate all statistical data in list.
Can spent 5-30 seconds and more for big list. So you need perform this task on background once in week/day or hour.
1
if (list.isRecountNeeded()) {
2
list.recount({
3
// this command will be runned after recount
4
// onComplete: 'onCompleteListRecount'
5
});
6
}
Copied!
you can get delay time in ms:
1
// total delay in ms
2
list.recount_delay.total
3
​
4
// need to wait for next recount in ms
5
list.recount_delay.current_value
Copied!
recount lag:
1
// you can change lag for next recount
2
// it is 1000 ms by default
3
// prefer to use 1000 - 2000
4
list.recount_delay.lag = 1000;
Copied!

Calculate the amount of all props and users

Need recount before
1
list.count; // integer value
Copied!

Properties management

Add bot property to bot list

Bot property can be added to List for bot
Example. Bot can have price list.
1
Bot.setProperty({
2
name: 'product1',
3
value: 'Nano Cloud',
4
type: 'string',
5
list: 'PaidPlans' // bot list will be created if not exist
6
});
Copied!

Add user property to user list

User property can be added to List for user
Example. User can have Orders list
1
User.setProperty({
2
name: "order125",
3
value: { product_id: "product1", price: 28 },
4
type: "json",
5
list: "Orders", // bot list will be created if not exist
6
});
Copied!

Add user property to bot list

User property can be added to List for bot
Example. Bot can have top customers list.
1
let list = new List({ name: "TopCustomers" })
2
if(!list.exist){ list.create() }
3
​
4
User.setProperty({
5
name: "customer" + user.id,
6
value: 20, // total income in USD
7
type: "float",
8
list: list,
9
// you can set this prop for other user also:
10
// user_id: other_user.id
11
});
Copied!
​

Reject property

Reject property from list without destroying by prop name
1
list.rejectProperty("stringProp");
Copied!

Remove property

Reject property from list and destroy it by prop name
1
list.removeProperty("stringProp");
Copied!

Reject all properties (and all users)

Reject all properties from list
this method reject all properties and all users from list
1
list.rejectAll();
Copied!

Remove all properties (and reject all users)

Remove all properties from list
this method remove all properties and reject all users from list
1
list.rejectAll();
Copied!

Users management

Add user

1
list.addUser(user);
2
​
3
// or if you have id only
4
// list.addUser({ id: user.id });
Copied!

Reject user

Reject user from list
1
list.rejectUser(user);
2
// or by id
3
list.rejectUser({ id: user.id });
Copied!

Reject all users

Reject all users from list
1
list.rejectAllUsers();
Copied!

Getting data

Getting props from list

1
let props = list.get();
2
Bot.inspect(props[0])
3
​
4
/* result will be like:
5
{
6
"name": "stringProp",
7
"value": "Bad Apple",
8
"user": {
9
"id": null
10
},
11
"created_at": "2020-11-09T01:46:52.270Z",
12
"updated_at": "2020-11-09T01:46:52.270Z"
13
}
14
*/
Copied!

Getting users from list

1
let users = list.getUsers();
2
Bot.inspect(users[0])
Copied!

Paginating

We have pages for data. Data is given page by page from the first page.
One page have 100 items by default.
1
// page 1
2
let props = list.get();
3
let users = list.getUsers();
4
​
5
// page 2
6
list.page = 2
7
props = list.get(); // getting props from page 2
8
users = list.getUsers(); // getting users from page 2
9
​
10
// it is possible to change default per page
11
list.per_page = 10 // 100 by default
12
​
13
// total pages
14
let total_pages = list.total_pages;
Copied!

Ordering

Default order is ascending by id (prop's id)
1
// default order is ascending by id
2
let props = list.get();
3
props[0] // oldest prop in list
4
​
5
// Change order to descending:
6
list.order_ascending = false;
7
props[0] // newest prop in list
Copied!
Ordering method can be changed from id (default) to other method:
1
list.order_by = "integer_value";
2
​
3
// list.order_by = "user_id";
4
// list.order_by = "size";
5
// etc - see table
6
​
7
list.order_ascending = true;
8
props[0] // prop with lowest value
Copied!
list.ordering_by
Ordering props by
user_id
order by user_id
name
order by name
integer_value
order by integer value
float_value
order by float value
datetime_value
order by datetime value
boolean_value
order by boolean value
string_value
order by string value
text_value
order by text value
value_type
ordering by value type (integer, float and etc)
size
order by value size

Users ordering

1
let users = list.getUsers();
2
​
3
// you can order users only by user id
4
list.order_ascending = false;
5
Bot.inspect(users[0])
Copied!

Searching

Searching for text props

Searching is available for list's properties. (String and text props)
1
// search prop with text value "Apple"
2
// case sensetive by default
3
let props = list.search("Apple");
4
​
5
// case insensentive
6
list.case_sensitive = false;
7
// search props with text value "Apple", "apple", "aPpLe" and etc
8
props = list.search("Apple");
9
​
10
// search props started with text "apple"
11
props = list.search("%Apple");
12
​
13
// search props ended with text "apple"
14
props = list.search("Apple%");
15
​
16
// search props contains text "apple"
17
props = list.search("%Apple%");
18
​
19
​
Copied!
  • Percent sign ( %) matches any sequence of zero or more characters.
  • Underscore sign ( _) matches any single character.
​Ordering and paginating also works with searching
1
list.page = 2;
2
list.order_ascending = false;
3
let props = list.search("Apple");
Copied!

User searching

Getting user by id from list

1
// getting user from list if exist
2
list.getUser({ id: user.id })
Copied!

Checking the user's existence in the list

1
list.haveUser(user)
2
​
3
// or by id:
4
list.haveUser({ id: user.id })
Copied!

Statistics

Is available for integer and float props
Need recount before
1
list.count // total props + users count
2
list.total_value // sum of all props
3
list.average_value // average of all props
4
list.max_value
5
list.min_value
Copied!
​