ElasticSearch

The ElasticSearch plugin provides an ORM-like abstraction on top ofelasticsearch. The pluginprovides features that make testing, indexing documents and searching yourindexes easier.

Installation

To install the ElasticSearch plugin, you can use composer. From yourapplication’s ROOT directory (where composer.json file is located) run thefollowing:

  1. php composer.phar require cakephp/elastic-search "@stable"

You will need to add the following line to your application’ssrc/Application.php file:

  1. $this->addPlugin('Cake/ElasticSearch', ['bootstrap' => true]);
  2.  
  3. // Prior to 3.6.0 you need to use Plugin::load()

Additionally, you will need to configure the ‘elastic’ datasource connection inyour config/app.php file. An example configuration would be:

  1. // in config/app.php
  2. 'Datasources' => [
  3.     // other datasources
  4.     'elastic' => [
  5.         'className' => 'Cake\ElasticSearch\Datasource\Connection',
  6.         'driver' => 'Cake\ElasticSearch\Datasource\Connection',
  7.         'host' => '127.0.0.1',
  8.         'port' => 9200,
  9.         'index' => 'my_apps_index',
  10.     ],
  11. ]

Overview

The ElasticSearch plugin makes it easier to interact with an elasticsearch indexand provides an interface similar to the /orm. To get started you shouldcreate a Type object. Type objects are the “Repository” or table-likeclass in elasticsearch:

  1. // in src/Model/Type/ArticlesType.php
  2. namespace App\Model\Type;
  3.  
  4. use Cake\ElasticSearch\Type;
  5.  
  6. class ArticlesType extends Type
  7. {
  8. }

You can then use your type class in your controllers:

  1. public function beforeFilter(Event $event)
  2. {
  3.     parent::beforeFilter($event);
  4.     // Load the Type using the 'Elastic' provider.
  5.     $this->loadModel('Articles', 'Elastic');
  6. }
  7.  
  8. public function add()
  9. {
  10.     $article = $this->Articles->newEntity();
  11.     if ($this->request->is('post')) {
  12.         $article = $this->Articles->patchEntity($article, $this->request->getData());
  13.         if ($this->Articles->save($article)) {
  14.             $this->Flash->success('It saved');
  15.         }
  16.     }
  17.     $this->set(compact('article'));
  18. }

We would also need to create a basic view for our indexed articles:

  1. // in src/Template/Articles/add.ctp
  2. <?= $this->Form->create($article) ?>
  3. <?= $this->Form->control('title') ?>
  4. <?= $this->Form->control('body') ?>
  5. <?= $this->Form->button('Save') ?>
  6. <?= $this->Form->end() ?>

You should now be able to submit the form and have a new document added toelasticsearch.

Document Objects

Like the ORM, the Elasticsearch ODM uses ORM-like classes. Thebase class you should inherit from is Cake\ElasticSearch\Document. Documentclasses are found in the Model\Document namespace in your application orplugin:

  1. namespace App\Model\Document;
  2.  
  3. use Cake\ElasticSearch\Document;
  4.  
  5. class Article extends Document
  6. {
  7. }

Outside of constructor logic that makes Documents work with data fromelasticsearch, the interface and functionality provided by Document are thesame as those in Entities

Searching Indexed Documents

After you’ve indexed some documents you will want to search through them. TheElasticSearch plugin provides a query builder that allows you to build searchqueries:

  1. $query = $this->Articles->find()
  2.     ->where([
  3.         'title' => 'special',
  4.         'or' => [
  5.             'tags in' => ['cake', 'php'],
  6.             'tags not in' => ['c#', 'java']
  7.         ]
  8.     ]);
  9.  
  10. foreach ($query as $article) {
  11.     echo $article->title;
  12. }

You can use the QueryBuilder to add filtering conditions:

  1. $query->where(function ($builder) {
  2.     return $builder->and(
  3.         $builder->gt('views', 99),
  4.         $builder->term('author.name', 'sally')
  5.     );
  6. });

The QueryBuilder sourcehas the complete list of methods with examples for many commonly used methods.

Validating Data & Using Application Rules

Like the ORM, the ElasticSearch plugin lets you validate data when marshallingdocuments. Validating request data, and applying application rules works thesame as it does with the relational ORM. See the validating request dataand Application Rulessections for more information.

Saving New Documents

When you’re ready to index some data into elasticsearch, you’ll first need toconvert your data into a Document that can be indexed:

  1. $article = $this->Articles->newEntity($data);
  2. if ($this->Articles->save($article)) {
  3.     // Document was indexed
  4. }

When marshalling a document, you can specify which embedded documents you wishto marshall using the associated key:

  1. $article = $this->Articles->newEntity($data, ['associated' => ['Comments']]);

Saving a document will trigger the following events:

  • Model.beforeSave - Fired before the document is saved. You can prevent thesave operation from happening by stopping this event.
  • Model.buildRules - Fired when the rules checker is built for the firsttime.
  • Model.afterSave - Fired after the document is saved.

Note

There are no events for embedded documents, as the parent document and allof its embedded documents are saved as one operation.

Updating Existing Documents

When you need to re-index data, you can patch existing entities and re-savethem:

  1. $query = $this->Articles->find()->where(['user.name' => 'jill']);
  2. foreach ($query as $doc) {
  3.     $doc->set($newProperties);
  4.     $this->Articles->save($doc);
  5. }

Deleting Documents

After retrieving a document you can delete it:

  1. $doc = $this->Articles->get($id);
  2. $this->Articles->delete($doc);

You can also delete documents matching specific conditions:

  1. $this->Articles->deleteAll(['user.name' => 'bob']);

Embedding Documents

By defining embedded documents, you can attach entity classes to specificproperty paths in your documents. This allows you to provide custom behavior tothe documents within a parent document. For example, you may want the commentsembedded in an article to have specific application specific methods. You canuse embedOne and embedMany to define embedded documents:

  1. // in src/Model/Type/ArticlesType.php
  2. namespace App\Model\Type;
  3.  
  4. use Cake\ElasticSearch\Type;
  5.  
  6. class ArticlesType extends Type
  7. {
  8.     public function initialize()
  9.     {
  10.         $this->embedOne('User');
  11.         $this->embedMany('Comments', [
  12.             'entityClass' => 'MyComment'
  13.         ]);
  14.     }
  15. }

The above would create two embedded documents on the Article document. TheUser embed will convert the user property to instances ofApp\Model\Document\User. To get the Comments embed to use a class namethat does not match the property name, we can use the entityClass option toconfigure a custom class name.

Once we’ve setup our embedded documents, the results of find() and get()will return objects with the correct embedded document classes:

  1. $article = $this->Articles->get($id);
  2. // Instance of App\Model\Document\User
  3. $article->user;
  4.  
  5. // Array of App\Model\Document\Comment instances
  6. $article->comments;

Getting Type Instances

Like the ORM, the ElasticSearch plugin provides a factory/registry for gettingType instances:

  1. use Cake\ElasticSearch\TypeRegistry;
  2.  
  3. $articles = TypeRegistry::get('Articles');

Flushing the Registry

During test cases you may want to flush the registry. Doing so is often usefulwhen you are using mock objects, or modifying a type’s dependencies:

  1. TypeRegistry::flush();

Test Fixtures

The ElasticSearch plugin provides seamless test suite integration. Just likedatabase fixtures, you can create test fixtures for elasticsearch. We coulddefine a test fixture for our Articles type with the following:

  1. namespace App\Test\Fixture;
  2.  
  3. use Cake\ElasticSearch\TestSuite\TestFixture;
  4.  
  5. /**
  6.  * Articles fixture
  7.  */
  8. class ArticlesFixture extends TestFixture
  9. {
  10.     /**
  11.      * The table/type for this fixture.
  12.      *
  13.      * @var string
  14.      */
  15.     public $table = 'articles';
  16.  
  17.     /**
  18.      * The mapping data.
  19.      *
  20.      * @var array
  21.      */
  22.     public $schema = [
  23.         'id' => ['type' => 'integer'],
  24.         'user' => [
  25.             'type' => 'nested',
  26.             'properties' => [
  27.                 'username' => ['type' => 'string'],
  28.             ]
  29.         ]
  30.         'title' => ['type' => 'string'],
  31.         'body' => ['type' => 'string'],
  32.     ];
  33.  
  34.     public $records = [
  35.         [
  36.             'user' => [
  37.                 'username' => 'billy'
  38.             ],
  39.             'title' => 'First Post',
  40.             'body' => 'Some content'
  41.         ]
  42.     ];
  43. }

The schema property uses the native elasticsearch mapping format.You can safely omit the type name and top level properties key. Once yourfixtures are created you can use them in your test cases by including them inyour test’s fixtures properties:

  1. public $fixtures = ['app.Articles'];