[5pt] Indexes: Community review

[Onvember]

Indexes: Community review

Product: Tarantool
Since: latest
Audience/target: all Tarantool users
Root document: https://www.tarantool.io/en/doc/latest/book/box/indexes/
https://www.tarantool.io/en/doc/latest/reference/reference_lua/box_space/create_index/
SME:
Peer reviewer: @NickVolynkin

Details

This is the forth step in revising our documentation about indexes. (See #1691, #1820 and #1871.)
Here we want to understand whether the revised documents became more informative and clear or not and what is left to write.
We have some concerns about the structure and the completeness of the provided information.

We suggest answering the following questions:

1. Can you easily find any information about indexes you need via this page?
2. Do you think the current structure of the document is appropriate?
3. Should we write a special section about index features (such as, functional, multikey indexes, partial search, etc.)?
4. What features did we lost?
5. How can we improve the page about index creation?

Please, leave your feedback here in comments.

Definition of done

• collect feedback from developers and users
• rewrite dubious places

To be done with: #1782 #1737

[Heroidjsjs]

По просьбе @NickVolynkin выкладываю сюда замечания (позже еще выложу по оставшейся теории из раздела)

По индексам: https://www.tarantool.io/ru/doc/latest/book/box/indexes/

Индекс может быть многокомпонентным, то есть можно объявить, что ключ индекса состоит из двух или более полей в кортеже в любом порядке. Например, для обычного TREE-индекса максимальное количество частей равно 255.

Я бы постаралась донести простыми словами, i.e.: В Tarantool индекс может быть также многокомпонентным, то есть состоять из двух или более полей кортежа. Для индекса типа TREE максимальное количество полей ключа - 255.

И следующий абзац тоже бы упростить в повествовании, да и лучше бы попробовать в этом разделе донести информацию до пользователей как понял бы и простой дурак. :)

Раздел "Создание индекса" предполагает собой пример, который и приведен, но тут есть фраза, предполагающая full table scan, и избыточна, на мой взгляд:

You can call select() without arguments, and it will return all tuples. Be careful! Using select() for huge spaces hangs your instance.

Вижу ссылку на типы индексируемых полей, но вот уже на ваше усмотрение: смотрите, с одной стороны было бы проще видеть эту информацию тут, хотя это скорее всего моя прерогатива.

Типы индексов переместить бы чуть выше созданий и операций с ними. Правда, в операциях приведены secondary, partial ключи, но я не смогла найти что же такое partial в контексте Tarantool.
Из HASH-индексов убрать бы рубрику "вредных советов", i.e. стоит оставить непосредственные возможности использования HASH-индексов в базе.

[Heroidjsjs]

R-TREE: https://www.tarantool.io/ru/doc/latest/book/box/indexes/

С одной стороны, для меня материал не кажется трудным, с другой, в первом абзаце раздела переиграла бы изложение следующим образом:

R-TREE - многомерный индекс для пространственного поиска по такой информации как географические объекты, поддерживает до 20 измерений. Пример использования R-TREE индекса можно посмотреть здесь.

RTREE-индекс не может быть первичным и не может быть уникальным. - тавтология, на мой взгляд. Also, стоило бы ввести термины для distance и dimension, а далее по тексту использовать термины (или русский, или английский).

Про итераторы в Примере 1 переделать бы таблицей со структурой по столбцам: итератор - как ищет - пример на основании итератора.

BITSET: https://www.tarantool.io/ru/doc/latest/book/box/indexes/#bitset-indexes
Материал по данному типу индекса подан скомкано, я вижу примеры, но не понимаю практического смысла, то есть неплохо обозначить, когда и где можно применить BITSET-индексы.

[vrogach2020]

Index Operations

Кажется недостаточно структурированным.

Сейчас раздел состоит из следующих частей:
1 демо работы с tree индексом
2 Что умеет селект:
2.1 итераторы (виды сравнения) для tree индекса
2.2 вторичные индексы
2.3 поиск по частичному ключу

По сути это описание возможностей tree индекса. Я бы предложил перенести это в раздел 'TREE indexes'.
Мне нравится предложения Артура описать в Index operations все возможные операции в общих чертах
(как с самими индексами, так и с данными).
Список итераторов также дублируется в index_object:pairs().

краткое описание и детали

Ещё есть отдельная страница space_object:create_index(),
которая содержит кучу деталей и примеров и кажется пересекается с разделом Index Types.

Предлагаю на главной минимизировать количество информации, а все детали перенести в create_index и описания
других апишек, таких как select / pairs (или отдельную страницу). При этом проверить чтобы инфа не дублировалась.

итераторы

Не совсем понятно является ли итератор независимой сущностью или итераторы работают по разному в каждом индексе ?
Т.е. есть один общий набор итераторов на весь тарантул или у каждого индекса свои итераторы ?
Это важно чтобы понимать какой итератор с каким индексом будет работать.
Может стоит описывать итераторы как подраздел в каждом индексе, а на главной дать общую концепцию что есть вот
итераторы, и у каждого индекса свои, а за деталями идите в индекс.