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!
​
Variables
Migration from properties to list
Last modified 4mo ago