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
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