improved docs

yiisoft · Jul 16, 2020 · 84f03d6 · 84f03d6
1 parent e7be812
commit 84f03d6
Show file tree

Hide file tree

Showing 6 changed files with 168 additions and 82 deletions.
diff --git a/docs/guide-ru/README.md b/docs/guide-ru/README.md
@@ -1,22 +1,23 @@
-Расширение Elasticsearch для Yii 2
-=================================
+# Расширение Elasticsearch для Yii 2
 
 Расширение обеспечивает интеграцию [Elasticsearch](https://www.elastic.co/products/elasticsearch) в фреймворк Yii2.
-Включает в себя базовую поддержку запросов/поиска, а также реализует шаблон `ActiveRecord`, который позволяет сохранять активные записи в Elasticsearch.
+Включает в себя базовую поддержку запросов/поиска, а также реализует шаблон `ActiveRecord`, который позволяет сохранять
+активные записи в Elasticsearch.
+
+
+## Как начать
 
-Как начать
-----------
 * [Установка](installation.md)
 
-Использование
-------------- 
-* [Сопоставление данных и индексация](mapping-indexing.md)
+
+## Использование
+
+* [Структура данных и индексы](mapping-indexing.md)
 * [Использование Query](usage-query.md)
-* [Использование ActiveRecord](usage-ar.md)
+* [Использование ActiveRecord/ActiveQuery](usage-ar.md)
 * [Работа с провайдерами данных](usage-data-providers.md)
 
-Дополнительно
--------------
+
+## Дополнительно
+
 * [Использование Elasticsearch DebugPanel](topics-debug.md)
-* Определение отношений с записями, чьи первичные ключи не являются частью атрибутов
-* Получение записей из разных индексов/типов
diff --git a/docs/guide-ru/installation.md b/docs/guide-ru/installation.md
@@ -3,28 +3,33 @@
 
 ## Требования
 
-Требуется версия Elasticsearch 1.0 или выше.
+Расширение поддерживает версии Elasticsearch 5.0 и выше. Совместимость с последними версиями веток Elasticsearch 5.x,
+6.x и 7.x тестируется автоматически.
 
-## Получение с помощью Composer
 
-Предпочтительный способ установки расширения через [composer](http://getcomposer.org/download/).
+## Настройка Elasticsearch
 
-Для этого запустите
-```
-php composer.phar require --prefer-dist yiisoft/yii2-elasticsearch
-```
+Для реализации отдельных функций, таких как [[yii\elasticsearch\ActiveRecord::updateAllCounters()|updateAllCounters()]],
+в расширении используются инлайн-скрипты. Скрипты написаны на языке `painless`, который Elasticsearch обычно выполняет
+в песочнице. В современных версиях сервера запуск таких скриптов разрешен по умолчанию, поэтому специально ничего
+настраивать не нужно. Тем не менее, для более старых серверов, например, версии 5.0, запуск инлайн-скриптов нужно явно
+разрешить. В [документации Elasticsearch](https://www.elastic.co/guide/en/elasticsearch/reference/current/modules-scripting-security.html)
+это описано более подробно.
+
+
+## Установка через Composer
 
-или добавьте
+Предпочтительный способ установки расширения - с помощью [composer](http://getcomposer.org/download/).
 
-```json
-"yiisoft/yii2-elasticsearch": "~2.0.0"
+```
+composer require --prefer-dist yiisoft/yii2-elasticsearch
 ```
 
-в секцию **require** вашего composer.json.
 
 ## Настройка приложения
 
-Для использования расширения, просто добавьте этот код в конфигурацию вашего приложения:
+Для работы с расширением нужно добавить класс [[yii\elasticsearch\Connection|Connection]] к компонентам приложения и
+настроить его:
 
 ```php
 return [
@@ -36,14 +41,31 @@ return [
                 ['http_address' => '127.0.0.1:9200'],
                 //настройте несколько хостов, если у вас есть кластер
             ],
+            // установите autodetectCluster = false, чтобы не определять адреса узлов в кластере автоматически
+            // 'autodetectCluster' => false,
+            'dslVersion' => 7, // по умолчанию - 5
         ],
-    ]
+    ],
 ];
 ```
 
-Соединение поддерживает автоматическое обнаружение кластера Elasticsearch, который включен по умолчанию.
-Вам не нужно указывать все узлы кластера вручную, Yii будет обнаруживать другие узлы кластера и подключаться к случайно выбранному узлу по умолчанию. Вы можете отключить эту функцию, установив [[yii\elasticsearch\Connection::$autodetectCluster]] в `false`.
+В параметрах соединения нужно задать хотя бы один узел. По умолчанию выполняется автоматическое определение узлов
+кластера. Расширение выполняет запрос `GET /_nodes` к первому узлу из списка и получает адреса всех узлов в кластере.
+Затем из этих узлов случайным образом выбирается активный узел.
+
+Такое поведение можно отключить, установив параметр [[yii\elasticsearch\Connection::$autodetectCluster|$autodetectCluster]]
+равным `false`. Тогда активным станет произвольный узел из тех, что заданы в конфигурации.
+
+> Для нормальной работы автоопределения узлов кластера, в узлах, которые возвращает запрос `GET /_nodes`, должно быть
+> корректно задано поле `http_address`. Со стандартным сервером Elasticsearch обычно не возникает никаких сложностей, но
+> известны случаи, когда нестандартные сборки, особенно в AWS, возвращают некорректные данные. В таком случае можно
+> отключить автоопределение и задать список узлов вручную.
+>
+> Также автоопределение можно отключить чтобы ускорить работу расширения. Если в кластере предусмотрен отдельный
+> [координирующий узел](https://www.elastic.co/guide/en/elasticsearch/reference/current/modules-node.html#coordinating-only-node),
+> можно направлять все запросы только к нему. Для кластеров, в которых всего несколько узлов с известными адресами,
+> целесообразно объявить эти узлы в конфигурации явно и сэкономить время на ненужном запросе.
 
-> **NOTE:** для корректной работы автоматического обнаружения кластера, запрос узлов `GET /_nodes` должен возвращать поле `http_address` для каждого узла.
-По умолчанию они возвращаются настоящими экземплярами Elasticsearch, но, они недоступны в таких средах как AWS.
-В этом случае вам необходимо отключить обнаружение кластера и указать хосты вручную.
+Также в конфигурации нужно задать версию языка, который используется для работы с сервером. Значение параметра соответствует
+версии Elasticsearch. Для ветки 5.x параметр [[yii\elasticsearch\Connection::$dslVersion|$dslVersion]] должен быть равен
+`5`, для ветки 6.x - `6`, для ветки 7.x - `7`. Значение по умолчанию - `5`.
diff --git a/docs/guide-ru/mapping-indexing.md b/docs/guide-ru/mapping-indexing.md
@@ -1,37 +1,80 @@
-Сопоставление и индексация
-==================
+# Структура данных и индексы
 
-## Создание индексов и сопоставления
 
-Так как не всегда возможно обновлять сопоставления Elasticsearch поэтапно, рекомендуется создать несколько статических методов в вашей модели, которые занимаются созданием и обновлением индекса. Вот пример того, как это можно сделать.
+## Сравнение с SQL
+
+[В документации Elasticsearch](https://www.elastic.co/guide/en/elasticsearch/reference/current/_mapping_concepts_across_sql_and_elasticsearch.html) подробно описаны основные понятия Elasticsearch и баз данных SQL, и как они соответствуют друг другу. Рассмотрим основное.
+
+Кластер Elasticsearch состоит из отдельных серверов - узлов. Клиент отправляет запросы к одному из них. Узел передает
+запрос остальным узлам кластера, собирает результаты и выдает ответ клиенту. Таким образом, кластер или представляющий
+его узел примерно соответствуют базе данных SQL.
+
+Данные в Elasticsearch хранятся в индексах. Индекс соответствует таблице SQL.
+
+Индекс состоит из документов. Документ подобен строке в таблице SQL. В этом расширении [[yii\elasticsearch\ActiveRecord|ActiveRecord]]
+представляет один документ в индексе. Операция сохранения документа в индекс называется "индексирование".
+
+Схема или структура документа определяется так называемым маппингом. Маппинг задает поля документа, которые
+соответствуют колонкам в таблице SQL. Первичный ключ в Elasticsearch - это специальное системное поле, которое нельзя
+ни удалить, ни переименовать. Другие поля настраиваются разработчиком.
+
+
+## Задание структуры полей
+
+Хотя Elasticsearch и создает новые поля на лету во время индексирования документов, структуру полей желательно
+объявить заранее.
+
+Объявленное поле, как правило, нельзя изменить. Например, если текстовое поле настроено на работу с анализатором
+английского языка, переключить его на другой язык можно только переиндексировав все без исключения документы в индексе.
+
+Отдельные изменения структуры все же допускаются. Подробнее - [в документации](https://www.elastic.co/guide/en/elasticsearch/reference/current/indices-put-mapping.html#updating-field-mappings).
+
+
+## Типы документов
+
+Изначально Elasticsearch разрабатывался как хранилище разнородных документов. Чтобы хранить документы различной
+структуры в одном индексе, было введено понятие "тип". Тем не менее, этот подход себя не зарекомендовал, а с версии
+[Elasticsearch 7.x](https://www.elastic.co/guide/en/elasticsearch/reference/current/removal-of-types.html) типы
+уже не поддерживаются.
+
+В настоящее время рекомендуется в каждом индексе объявлять только один тип. Если расширение настроено на работу с
+Elasticsearch 7 и выше, свойство [[yii\elasticsearch\ActiveRecord::type()|type()]] игнорируется, а в запросах тип
+неявно заменяется на `_doc`.
+
+
+## Создание вспомогательных методов
+
+Мы рекомендуем объявить в моделях [[yii\elasticsearch\ActiveRecord|ActiveRecord]] несколько вспомогательных методов
+для работы с индексами. Ниже показана возможная реализация таких методов.
 
 ```php
-class Book extends yii\elasticsearch\ActiveRecord
+class Customer extends yii\elasticsearch\ActiveRecord
 {
-    //Другие атрибуты и методы класса идут здесь
+    // Другие атрибуты и методы класса
     // ...
 
     /**
-     * @return array Сопоставление для этой модели
+     * @return array Маппинг этой модели
      */
     public static function mapping()
     {
         return [
-            static::type() => [
-                'properties' => [
-                    'name'           => ['type' => 'string'],
-                    'author_name'    => ['type' => 'string'],
-                    'publisher_name' => ['type' => 'string'],
-                    'created_at'     => ['type' => 'long'],
-                    'updated_at'     => ['type' => 'long'],
-                    'status'         => ['type' => 'long'],
-                ]
-            ],
+            // Типы полей: https://www.elastic.co/guide/en/elasticsearch/reference/current/mapping.html#field-datatypes
+            'properties' => [
+                'first_name'     => ['type' => 'text'],
+                'last_name'      => ['type' => 'text'],
+                'order_ids'      => ['type' => 'keyword'],
+                'email'          => ['type' => 'keyword'],
+                'registered_at'  => ['type' => 'date'],
+                'updated_at'     => ['type' => 'date'],
+                'status'         => ['type' => 'keyword'],
+                'is_active'      => ['type' => 'boolean'],
+            ]
         ];
     }
 
     /**
-     * Установка (update) для этой модели
+     * Создание или обновление маппинга модели
      */
     public static function updateMapping()
     {
@@ -41,23 +84,21 @@ class Book extends yii\elasticsearch\ActiveRecord
     }
 
     /**
-     * Создать индекс этой модели
+     * Создание индекса модели
      */
     public static function createIndex()
     {
         $db = static::getDb();
         $command = $db->createCommand();
         $command->createIndex(static::index(), [
-            'settings' => [ /* ... */ ],
-            'mappings' => static::mapping(),
-            //'warmers' => [ /* ... */ ],
             //'aliases' => [ /* ... */ ],
-            //'creation_date' => '...'
+            'mappings' => static::mapping(),
+            //'settings' => [ /* ... */ ],
         ]);
     }
 
     /**
-     * Удалить индекс этой модели
+     * Удаление индекса модели
      */
     public static function deleteIndex()
     {
@@ -68,9 +109,9 @@ class Book extends yii\elasticsearch\ActiveRecord
 }
 ```
 
-Чтобы создать индекс с соответствующими сопоставлениями, вызовите `Book::createIndex()`. Если вы изменили сопоставление таким образом, чтобы оно отображало обновление (например, создало новое свойство), вызовите `Book::updateMapping()`.
-
-Однако, если вы изменили свойство (например, перешли от `string` к` date`), Elasticsearch не сможет обновить сопоставление. В этом случае вам нужно удалить свой индекс (путем вызова `Book::deleteIndex()`), создать его заново с обновленным сопоставлением (путем вызова `Book::createIndex()`) и затем повторно заполнить его данными.
+Для создания индекса с маппингом вызывается метод `Customer::createIndex()`. Если маппинг изменился, но при этом
+сервер позволит обновить его на лету (например, если добавлено новое поле), вызывается метод `Customer::updateMapping()`.
 
-## Индексация
-TBD
+Если изменение значительное (например, переход от типа `string` к `date`), сервер не сможет обновить маппинг
+уже существующего индекса. В таком случае придется удалить индекс с помощью `Customer::deleteIndex()`, затем создать
+индекс с новым маппингом с помощью `Customer::createIndex()`), а после этого заново наполнить индекс данными.
diff --git a/docs/guide/README.md b/docs/guide/README.md
@@ -1,27 +1,23 @@
-Elasticsearch Extension for Yii 2
-=================================
+# Elasticsearch Extension for Yii 2
 
 This extension provides the [Elasticsearch](https://www.elastic.co/elasticsearch/) integration for the Yii2 framework.
 It includes basic querying/search support and also implements the `ActiveRecord` pattern that allows you to store active
 records in Elasticsearch.
 
 
-Getting Started
----------------
+## Getting Started
 
 * [Installation](installation.md)
 
 
-Usage
------------------
+## Usage
 
 * [Data Mapping & Indexing](mapping-indexing.md)
 * [Using the Query](usage-query.md)
 * [Using the ActiveRecord/ActiveQuery](usage-ar.md)
 * [Working with data providers](usage-data-providers.md)
 
 
-Additional topics
------------------
+## Additional topics
 
 * [Using the Elasticsearch DebugPanel](topics-debug.md)