From 3a86270de90b51a94bc86cde0ae1ce0b1d2ace2d Mon Sep 17 00:00:00 2001
From: Carsten Brandt <mail@cebe.cc>
Date: Fri, 10 Jan 2014 15:51:25 +0100
Subject: [PATCH] updated docs

---
 extensions/yii/elasticsearch/CHANGELOG.md |  3 ++-
 extensions/yii/elasticsearch/README.md    | 37 ++++++++++++++++++++-----------
 2 files changed, 26 insertions(+), 14 deletions(-)

diff --git a/extensions/yii/elasticsearch/CHANGELOG.md b/extensions/yii/elasticsearch/CHANGELOG.md
index 04db504..55d52af 100644
--- a/extensions/yii/elasticsearch/CHANGELOG.md
+++ b/extensions/yii/elasticsearch/CHANGELOG.md
@@ -5,7 +5,8 @@ Yii Framework 2 elasticsearch extension Change Log
 ----------------------------
 
 - Enh #1382: Added a debug toolbar panel for elasticsearch (cebe)
-- Chg: Changed handling of ActiveRecord primary keys (cebe)
+- Enh #1765: Added support for primary key path mapping, pk can now be part of the attributes when mapping is defined (cebe)
+- Chg #1765: Changed handling of ActiveRecord primary keys, removed getId(), use getPrimaryKey() instead (cebe)
 
 2.0.0 alpha, December 1, 2013
 -----------------------------
diff --git a/extensions/yii/elasticsearch/README.md b/extensions/yii/elasticsearch/README.md
index d299736..f2ba8d9 100644
--- a/extensions/yii/elasticsearch/README.md
+++ b/extensions/yii/elasticsearch/README.md
@@ -56,13 +56,11 @@ For general information on how to use yii's ActiveRecord please refer to the [gu
 For defining an elasticsearch ActiveRecord class your record class needs to extend from `yii\elasticsearch\ActiveRecord` and
 implement at least the `attributes()` method to define the attributes of the record.
 The handling of primary keys is different in elasticsearch as the primary key (the `_id` field in elasticsearch terms)
-is not part of the attributes by default. However it is possible to define a [mapping](TODO link to ES docs)
-for the `_id` field to be part of the attributes. See [...TODO...] on how to do this.
+is not part of the attributes by default. However it is possible to define a [path mapping](http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/mapping-id-field.html)
+for the `_id` field to be part of the attributes.
+See [elasticsearch docs](http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/mapping-id-field.html) on how to define it.
 The `_id` field of a document/record can be accessed using [[ActiveRecord::getPrimaryKey()]] and [[ActiveRecord::setPrimaryKey()]].
-
- primary key can be defined via [[primaryKey()]] which defaults to `id` if not specified.
-The primaryKey needs to be part of the attributes so make sure you have an `id` attribute defined if you do
-not specify your own primary key.
+When path mapping is defined, the attribute name can be defined using the [[primaryKey()]] method.
 
 The following is an example model called `Customer`:
 
@@ -74,6 +72,7 @@ class Customer extends \yii\elasticsearch\ActiveRecord
      */
     public function attributes()
     {
+        // path mapping for '_id' is setup to field 'id'
         return ['id', 'name', 'address', 'registration_date'];
     }
 
@@ -107,25 +106,23 @@ It supports the same interface and features except the following limitations and
   and [type](http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/glossary.html#glossary-type) to query against.
 - `select()` has been replaced with `fields()` which basically does the same but `fields` is more elasticsearch terminology.
   It defines the fields to retrieve from a document.
-- `via`-relations can not be defined via a table as there are not tables in elasticsearch. You can only define relations via other records.
-- As elasticsearch is a data storage and search engine there is of course support added for search your records.
+- `via`-relations can not be defined via a table as there are no tables in elasticsearch. You can only define relations via other records.
+- As elasticsearch is not only a data storage but also a search engine there is of course support added for search your records.
   There are `query()`, `filter()` and `addFacets()` methods that allows to compose an elasticsearch query.
   See the usage example below on how they work and check out the [Query DSL](http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/query-dsl.html)
   on how to compose `query` and `filter` parts.
 - It is also possible to define relations from elasticsearch ActiveRecords to normal ActiveRecord classes and vice versa.
 
-Elasticsearch separates primary key from attributes. You need to set the `id` property of the record to set its primary key.
-
 Usage example:
 
 ```php
 $customer = new Customer();
-$customer->id = 1;
+$customer->primaryKey = 1; // in this case equivalent to $customer->id = 1;
 $customer->attributes = ['name' => 'test'];
 $customer->save();
 
 $customer = Customer::get(1); // get a record by pk
-$customers = Customer::get([1,2,3]); // get a records multiple by pk
+$customers = Customer::mget([1,2,3]); // get multiple records by pk
 $customer = Customer::find()->where(['name' => 'test'])->one(); // find by query
 $customers = Customer::find()->active()->all(); // find all by query (using the `active` scope)
 
@@ -176,4 +173,18 @@ enabled, it is sufficient to just add the panels configuration):
 	// ...
 ```
 
-![elasticsearch DebugPanel](README-debug.png)
\ No newline at end of file
+![elasticsearch DebugPanel](README-debug.png)
+
+
+Relation definitions with records whose primary keys are not part of attributes
+-------------------------------------------------------------------------------
+
+TODO
+
+
+Patterns
+--------
+
+### Fetching records from different indexes/types
+
+TODO