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:
let list = new List({ name: "MyList" })
​
Bot.inspect(list.exist) // false for new List, true for already exist list
or can be personal for user:
let list = new List({ name: "MyList", user: user })
​
// or for user id
let list = new List({ name: "MyList", user_id: user.id })
After it you can perform another list methods
Create new list
// for list saving
if(!list.exist){
  list.create()
}
Remove list
list.remove();
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.
if (list.isRecountNeeded()) {
    list.recount({
        // this command will be runned after recount
        // onComplete: 'onCompleteListRecount'
    });
}
you can get delay time in ms:
// total delay in ms
list.recount_delay.total
​
// need to wait for next recount in ms
list.recount_delay.current_value
recount lag:
// you can change lag for next recount
// it is 1000 ms by default 
// prefer to use 1000 - 2000
list.recount_delay.lag = 1000; 
Calculate the amount of all props and users
Need recount before
list.count;  // integer value
Properties management
Add bot property to bot list
Bot property can be added to List for bot
Example. Bot can have price list.
Bot.setProperty({
  name: 'product1',
  value: 'Nano Cloud',
  type: 'string',
  list: 'PaidPlans'  // bot list will be created if not exist
});
Add user property to user list
User property can be added to List for user 
Example. User can have Orders list 
User.setProperty({
  name: "order125",
  value: { product_id: "product1", price: 28 },
  type: "json",
  list: "Orders",  // bot list will be created if not exist
});
Add user property to bot list
User property can be added to List for bot
Example. Bot can have top customers list.
let list = new List({ name: "TopCustomers" })
if(!list.exist){ list.create() }
​
User.setProperty({
  name: "customer" + user.id,
  value: 20, // total income in USD
  type: "float",
  list: list,
  // you can set this prop for other user also:
  // user_id: other_user.id
});
​
Reject property
Reject property from list without destroying by prop name
list.rejectProperty("stringProp");
Remove property
Reject property from list and destroy it by prop name
list.removeProperty("stringProp");
Reject all properties (and all users)
Reject all properties from list
this method reject all properties and all users from list
list.rejectAll();
Remove all properties (and reject all users)
Remove all properties from list
this method remove all properties and reject all users from list
list.rejectAll();
Users management
Add user
list.addUser(user);
​
// or if you have id only
// list.addUser({ id: user.id });
Reject user
Reject user from list
list.rejectUser(user);
// or by id
list.rejectUser({ id: user.id });
Reject all users
Reject all users from list
list.rejectAllUsers();
Getting data
Getting props from list
let props = list.get();
Bot.inspect(props[0])
​
/* result will be like:
  {
    "name": "stringProp",
    "value": "Bad Apple",
    "user": {
      "id": null
    },
    "created_at": "2020-11-09T01:46:52.270Z",
    "updated_at": "2020-11-09T01:46:52.270Z"
  }
*/
Getting users from list
let users = list.getUsers();
Bot.inspect(users[0])
Paginating
We have pages for data. Data is given page by page from the first page.
One page have 100 items by default.
// page 1
let props = list.get();
let users = list.getUsers();
​
// page 2
list.page = 2
props = list.get();  // getting props from page 2
users = list.getUsers(); // getting users from page 2
​
// it is possible to change default per page
list.per_page = 10 // 100 by default
​
// total pages
let total_pages = list.total_pages;
Ordering
Default order is ascending by id (prop's id)
// default order is ascending by id
let props = list.get();
props[0] // oldest prop in list
​
// Change order to descending:
list.order_ascending = false;
props[0] // newest prop in list
Ordering method can be changed from id (default) to other method:
list.order_by = "integer_value";
​
// list.order_by = "user_id";
// list.order_by = "size";
// etc - see table
​
list.order_ascending = true;
props[0] // prop with lowest value
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
let users = list.getUsers();
​
// you can order users only by user id
list.order_ascending = false;
Bot.inspect(users[0])
Searching
Searching for text props
Searching is available for list's properties. (String and text props)
// search prop with text value "Apple"
// case sensetive by default
let props = list.search("Apple");
​
// case insensentive
list.case_sensitive = false;
// search props with text value "Apple", "apple", "aPpLe" and etc
props = list.search("Apple");
​
// search props started with text "apple"
props = list.search("%Apple");
​
// search props ended with text "apple"
props = list.search("Apple%");
​
// search props contains text "apple"
props = list.search("%Apple%");
​
​
Percent sign ( %) matches any sequence of zero or more characters.
Underscore sign ( _)  matches any single character.
​Ordering and paginating also works with searching
list.page = 2;
list.order_ascending = false;
let props = list.search("Apple");
User searching
Getting user by id from list
// getting user from list if exist
list.getUser({ id: user.id })
Checking the user's existence in the list
list.haveUser(user)
​
// or by id:
list.haveUser({ id: user.id })
Statistics
Is available for integer and float props
Need recount before
list.count  // total props + users count 
list.total_value  // sum of all props
list.average_value  // average of all props 
list.max_value
list.min_value
​

Variables

Migration from properties to list

Last modified 8mo ago

Copy link

On this page

List initialization

Create new list

Remove list

Recount list

Calculate the amount of all props and users

Properties management

Add bot property to bot list

Add user property to user list

Add user property to bot list

Reject property

Remove property

Reject all properties (and all users)

Remove all properties (and reject all users)

Users management

Add user

Reject user

Reject all users

Getting data

Getting props from list

Getting users from list

Paginating

Ordering

Searching

Searching for text props

User searching

Getting user by id from list

Checking the user's existence in the list

Statistics