Japanese guide updated

docs/guide-ja/README.md

@@ -1,25 +1,22 @@
-Yii 2.0 elasticsearch エクステンション
-======================================
+# Yii 2.0 elasticsearch エクステンション
 
-このエクステンションは、Yii 2 フレームワークに対する [elasticsearch](https://www.elastic.co/products/elasticsearch) の統合を提供します。
+このエクステンションは、Yii 2 フレームワークに対する [Elasticsearch](https://www.elastic.co/products/elasticsearch) の統合を提供します。
 基本的なクエリや検索をサポートするとともに、`ActiveRecord` パターンを実装して、
-アクティブレコードを elasticsearch に保存することを可能にしています。
+アクティブレコードを Elasticsearch に保存することを可能にしています。
 
-始めよう
---------
+
+## 始めよう
 
 * [インストール](installation.md)
 
-使用方法
---------
+
+## 使用方法
+
 * [データのマッピングとインデクシング](mapping-indexing.md)
 * [クエリを使う](usage-query.md)
-* [アクティブレコードを使う](usage-ar.md)
+* [アクティブレコード/アクティブクエリを使う](usage-ar.md)
 * [データ・プロバイダを扱う](usage-data-providers.md)
 
-追加のトピック
---------------
+## 追加のトピック
 
 * [Elasticsearch デバッグ・パネルを使う](topics-debug.md)
-* プライマリ・キーが属性に含まれていないレコードとのリレーションの定義
-* さまざまな index/type からレコードを取得する

docs/guide-ja/installation.md

@@ -1,13 +1,20 @@
-インストール
-============
+#インストール
 
 ## 必要条件
 
-Elasticsearch のバージョン 1.6.0 以上 1.7.6 以下が必要です。以下を `config/elasticsearch.yml` に追加しなければなりません。
+このエクステンションは Elasticsearch のバージョン 5.0 以上 をサポートするべく設計されています。
+Elasticsearch 5.x, 6.x, そして 7.x のブランチでテストされています。
+
+
+## Elasticsearch を構成する
+
+このエクステンションはその機能のいくつか(たとえば [[yii\elasticsearch\ActiveRecord::updateAllCounters()|updateAllCounters()]]
+メソッド)のためにインライン・スクリプトを使用します。
+このスクリプトは `painless` で書かれ、Elasticsearch によってサンドボックス内で実行されます。
+普通はデフォルトで有効にされていますので、特別な構成は必要ありません。
+しかし、古いバージョンの Elasticsearch (5.0など) では、この機能をサポートするためにインライン・スクリプトを有効にする必要があるかも知れません。
+詳細は [Elasticsearch documentation](https://www.elastic.co/guide/en/elasticsearch/reference/current/modules-scripting-security.html) を参照して下さい。
 
-```
-script.disable_dynamic: false
-```
 
 ## Composer パッケージを取得する
 
@@ -17,11 +24,10 @@ script.disable_dynamic: false
 composer require --prefer-dist yiisoft/yii2-elasticsearch
 ```
 
-を追加してください。
 
 ## アプリケーションを構成する
 
-このエクステンションを使用するためには、アプリケーションの構成情報で `Connection` クラスを構成する必要があります。
+このエクステンションを使用するためには、アプリケーションの構成情報で [[yii\elasticsearch\Connection|Connection]] クラスを構成する必要があります。
 
 ```php
 return [
@@ -33,17 +39,32 @@ 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]] を `false` に設定することによって無効化することが出来ます。
+その場合はアクティブなノードは構成で指定されたノードの中からランダムに選ばれることになります。
+
+> クラスタの自動検出が正しく働くためには、構成情報で指定されたノードに対する `GET / _nodes` リクエストが
+> 各ノードの `http_address` フィールドが返されなければなりません。
+> このフィールドは、デフォルトでは、素の Elasticsearch インスタンスによって返される筈のものですが、AWS のような環境では取得できないことが報告されています。
+> そのような場合には、クラスタの自動検出を無効にして、ホストを手作業で指定しなければなりません。
+>
+
+> パフォーマンス上の理由からもクラスタの自動検出を無効にする方が有益であるかもしれません。
+> クラスタに専用の [コーディネイトだけのノード](https://www.elastic.co/guide/en/elasticsearch/reference/current/modules-node.html#coordinating-only-node) が一つしかない場合は、全てのリクエストをそのノードに向けるのが合理的でしょう。
+> クラスタに数個のノードしかなくて、そのアドレスも判っている場合は、アドレスを明示的に指定する方が良いでしょう。
 
-クラスタの自動検出が正しく働くためには、設定情報で指定されたノードに対する `GET / _nodes` リクエストに対して、
-各ノードの `http_address` フィールドが返されなければならないことに留意して下さい。
-このフィールドは、デフォルトでは、素の elasticsearch インスタンスによって返される筈のものですが、AWS のような環境では取得できないことが報告されています。
-そのような場合には、クラスタの自動検出を無効にして、ホストを手作業で指定しなければなりません。
+エクステンションがサーバと交信するのに使用するドメイン固有言語のバージョンをしていしなければなりません。
+設定値は Elasticsearch サーバのバージョンと対応します。
+5.x ブランチでは [[yii\elasticsearch\Connection::$dslVersion|$dslVersion]] を `5` に設定します。
+6.x ブランチは `6`、7.x ブランチは `7` です。デフォルト値は `5` です。

docs/guide-ja/mapping-indexing.md

@@ -1,14 +1,56 @@
-マッピングとインデクシング
-==========================
+# マッピングとインデクシング
 
-## インデックスとマッピングを生成する
+## SQL との比較
 
-Elasticsearch のマッピングを漸進的に更新することは常に可能であるとは限りません。ですから、あなたのモデルの中に、インデックスの生成と更新を扱ういくつかの静的なメソッドを作っておくというのは、良いアイデアです。どのようにすればそれが出来るかの一例を次に示します。
+[Elasticsearch のドキュメント](https://www.elastic.co/guide/en/elasticsearch/reference/current/_mapping_concepts_across_sql_and_elasticsearch.html) では Elasticsearch と SQL の概念について広範囲にわたって解説しています。
+私たちは基本に注力しましょう。
+
+Elasticsearch クラスタは一つ以上の 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()]] は無視されて、API によって「型」が要求される場所では暗黙の内に `_doc` に置き換えられます。
+
+
+## ヘルパ・メソッドを作成する
+
+私たちが推奨するのは、インデクスの作成と更新を扱う幾つかのスタティックなメソッドを [[yii\elasticsearch\ActiveRecord|ActiveRecord]] モデルに作成することです。
+以下に、どのようにしてそれが可能か、一例を示します。
 
 ```php
-Class Book extends yii\elasticsearch\ActiveRecord
+class Customer extends yii\elasticsearch\ActiveRecord
 {
-    // クラスのその他の属性とメソッド
+    // クラスの他の属性とメソッド
     // ...
 
     /**
@@ -17,21 +59,22 @@ Class Book extends yii\elasticsearch\ActiveRecord
     public static function mapping()
     {
         return [
-            static::type() => [
-                'properties' => [
-                    'name'           => ['type' => 'text'],
-                    'author_name'    => ['type' => 'text'],
-                    'publisher_name' => ['type' => 'text'],
-                    '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'],
+            ]
         ];
     }
 
     /**
-     * このモデルのマッピングを設定(更新)する
+     * このモデルのマッピングを設定（更新）する
      */
     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` へ) した場合は、Elasticsearch はマッピングを更新することが出来ません。
+この場合は、(`Customer::deleteIndex()` を呼んで) インデクスを削除し、(`Customer::createIndex()` を呼んで) 更新後のマッピングでインデクスを再作成して、
+それからデータを再投入する必要があります。

docs/guide-ja/topics-debug.md

@@ -1,8 +1,7 @@
-Elasticsearch デバッグ・パネルを使う
-------------------------------------
+# Elasticsearch デバッグ・パネルを使う
 
-Yii 2 elasticsearch エクステンションは、yii のデバッグ・モジュールと統合可能な `DebugPanel` を提供しています。
-これは、実行された elasticsearch のクエリを表示するだけでなく、
+Yii 2 Elasticsearch エクステンションは、yii のデバッグ・モジュールと統合可能な `DebugPanel` を提供しています。
+これは、実行された Elasticsearch のクエリを表示するだけでなく、
 クエリを実行して結果を表示することも出来ます。
 
 `DebugPanel` を有効にするためには、下記の構成をアプリケーションの構成情報に追加してください
@@ -24,4 +23,4 @@ Yii 2 elasticsearch エクステンションは、yii のデバッグ・モジ
     // ...
 ```
 
-![elasticsearch DebugPanel](images/debug.png)
+![Elasticsearch デバッグ・パネル](images/debug.png)