Commit 3a86270d by Carsten Brandt

updated docs

parent 31fece56
......@@ -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
-----------------------------
......
......@@ -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)
......@@ -177,3 +174,17 @@ enabled, it is sufficient to just add the panels configuration):
```
![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
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment