Guild Indexes

Guild Indexes are a special data storage designed for storing large arrays of sorted data. This type of storage is suitable for creating ratings (top lists), user note histories, or any other sortable records.

This storage consists of two parts: Indexes и Entries.

An index is a group of entries. A guild can have an unlimited amount of such indexes (groups) with unique names, each of then can contain an unlimited amount of entries with unique keys and their corresponding numerical values.

Indexes are represented by getIndex method and indexes property of Guild data type.

WARNING

You can only access up to 2 guild indexes in single message template and update up to two entries of any index.

Saving Data

In order to save any data into indexes, you should use following construct:

---

{% do guild.getIndex('myIndex').get('entryKey').update(123) %}

We are using:

1. getIndex method of Guild data type to get an index with myIndex name;
2. get method of GuildIndex data type to get an entry with key entryKey;
3. update method of GuildIndexEntry data type to save 123 value into this entry.

You can also batch update up to two entries with a single call of update method of GuildIndex:

---

{% do guild.getIndex('myIndex').update({ entryKey1: 123, entryKey2: 321 }) %}

You can increment or decrement entry value by specified amount using increment and decrement methods:

---

Incrementing value:

{% do guild.getIndex('myIndex').get('entryKey').increment(1) %}

Decrementing value:

{% do guild.getIndex('myIndex').get('entryKey').decrement(1) %}

Accessing Data

Single Value

Indexes and their entries are stored indefinitely and can be accessed as follows:

---

{{ guild.getIndex('myIndex').get('entryKey').value }}

Page

This is the most interesting and the main reason why indexes exist — requesting an entire page of index entries sorted by their values. You can use getPageOf method to do exactly that:

---

{% set page = guild.getIndex('myIndex').getPageOf(0, 10, 'DESC') %}

This way you will get a Page object containing the list of GuildIndexEntry entries, plus some additional information that you can use to build a working pagination!

Pagination example

The following code shows an example of a balance top with pagination navigation.

You need to create a Send Message action in text mode, check the "Edit Component Message" box, and paste the following code, replacing the action UUID in the first line with your own.

{% set actionId = 'ae04dfed-e19c-49d3-84fc-b05cec59976e' %}
{% set targetMember = arguments.targetMember %}

{% if targetMember and not component %}
  {% set newBalance = random(1000) %}
  
  {# Requesting balance entry for member from balances index #}
  {% set balanceEntry = guild.indexes.balances.get(targetMember.id) %}
  {# Updating the balance #}
  {% do balanceEntry.update(newBalance) %}
  
  Balance of {{ targetMember }} has been set to {{ newBalance }}!
{% else %}

  {# Calculating requested page number #}
  {% set wasLast = parameters.get('page.isLast') %}
  {% set pageNum = (parameters.get('page.number')) ?: 0 %}
  {% if component.id == 'next_page' and not wasLast %}
    {% set pageNum += 1 %}
  {% elseif component.id == 'prev_page' and pageNum > 0 %}
    {% set pageNum -= 1 %}
  {% endif %}

  {# Requesting the page from the index, saving some if its data that will be used to calculate next page number #}
  {% set page = guild.indexes.balances.getPageOf(pageNum, 2, 'DESC') %}
  {% do parameters.store('page.number', page.number) %}
  {% do parameters.store('page.isLast', page.isLast) %}
  {% set isEmpty = page.totalPages <= 0 %}
  
  {% if not isEmpty -%}
    {# If we have any data in the index, show page content #}
    Page {{ page.number + 1 }} of {{ page.totalPages }} (total {{ page.totalElements }} entries)
    {% for entry in page %}
      {% set number = loop.index + page.number * page.size -%}
      {{ number }}. <@{{ entry.key }}>: {{ entry.value -}}
    {% endfor %}
  {%- else -%}
    No records
  {%- endif %}

  {# Show pagination buttons #}
  {% set pageLabel = (page.number + 1) ~ ' / ' ~ page.totalPages %}
  {% do button('PRIMARY', 'prev_page', null, '⬅️', actionId, isEmpty or page.isFirst) %}
  {% do button('SECONDARY', 'current_page', pageLabel, null, actionId, true) %}
  {% do button('PRIMARY', 'next_page', null, '➡️', actionId, isEmpty or page.isLast) %}
{% endif %}

Running a command with this template will send a message with a paginated list of balances from the index.

Initially, there are no entries in the index. but you can run this command mentioning different members to set them random balances. Then run the command again without mentioning anyone to get an example of working pagination.

WARNING

You can only request a single page of any index in single message template, containing up to 25 entries.

Clearing Data

In order to clear index entry use clear method of GuildIndexEntry data type:

---

{% do guild.getIndex('myIndex').get('entryKey').clear() %}

We are using:

1. getIndex method of Guild data type to get an index with myIndex name;
2. get method of GuildIndex data type to get an entry with key entryKey;
3. clear method of GuildIndexEntry data type to clear this entry.

If you want to clear every single entry of the index from the server, use clearAll method of GuildIndex data type:

---

{% do guild.getIndex('myIndex').clearAll() %}