Persimmon / Elasticsearch Eloquent

This package allows you to interact with Elasticsearch as you interact with Eloquent models in Laravel.
Feel free to improve the project.

Install

Via Composer

$ composer require isswp101/elasticsearch-eloquent

Usage

Configure dependencies

Warning! First of all you should create a base model and inherit from it their models.

use Elasticsearch\Client;
use Isswp101\Persimmon\DAL\ElasticsearchDAL;
use Isswp101\Persimmon\ElasticsearchModel as Model;
use Isswp101\Persimmon\Event\EventEmitter;

class ElasticsearchModel extends Model
{
    public function __construct(array $attributes = [])
    {
        $dal = new ElasticsearchDAL($this, app(Client::class), app(EventEmitter::class));

        parent::__construct($dal, $attributes);
    }

    public static function createInstance()
    {
        return new static();
    }
}

In this example we use Laravel IoC Container to resolve Elasticsearch\Client dependency as app(Client::class).

Create a new model

You must override static variables index and type to determine the document path.

class Product extends ElasticsearchModel
{
    protected static $_index = 'test';
    protected static $_type = 'test';

    public $name;
    public $price = 0;
}

Here name and price are fields which will be stored in Elasticsearch.

Warning! Don't use field names starting with underscore $_*, for example $_name.

Use the static create() method to create document in Elasticsearch:

$product = Product::create(['id' => 3, 'name' => 'Product 3', 'price' => 30]);

Save the model

$product = new Product();
$product->id = 1;
$product->name = 'Product 1';
$product->price = 20;
$product->save();

Use save() method to store model data in Elasticsearch. Let's see how this looks in Elasticsearch:

{
   "_index": "test",
   "_type": "test",
   "_id": "1",
   "_version": 1,
   "found": true,
   "_source": {
      "name": "Product 1",
      "price": 10,
      "id": 1,
      "user_id": null,
      "created_at": "2016-06-03 08:11:08",
      "updated_at": "2016-06-03 08:11:08"
   }
}

Fields created_at and updated_at were created automatically. The user_id field is persistent field to store user id.

Find existing model

$product = Product::find(1);

If you have big data in Elasticsearch you can specify certain fields to retrieve:

$product = Product::find(1, ['name']);

In this case the price field equals 0 because it's populated as the default value that you specified in the model.

There are the following methods:

• findOrFail() returns ModelNotFoundException exception if no result found.
• findOrNew() returns a new model if no result found.

Model cache

There is a smart model cache when you use methods like find(), findOrFail() and so on.

$product = Product::find(1, ['name']);  // will be retrieved from the elasticsearch
$product = Product::find(1, ['name']);  // will be retrieved from the cache
$product = Product::find(1, ['price']); // elasticsearch
$product = Product::find(1, ['price']); // cache
$product = Product::find(1, ['name']);  // cache

$product = Product::findOrFail(1);      // elasticsearch
$product = Product::find(1);            // cache
$product = Product::find(1, ['name']);  // cache
$product = Product::find(1, ['price']); // cache

Partial update

You can use partial update to update specific fields quickly.

$product = Product::find(1, ['name']);
$product->name = 'Product 3';
$product->save('name');

Delete models

$product = Product::find(1);
$product->delete();

You can use the static method:

Product::destroy(1);

Model events

Out of the box you are provided with a simple implementation of events.
You can override the following methods to define events:

• saving() is called before saving, updating, creating the model
• saved() is called after saving, updating, creating the model
• deleting() is called before deleting the model
• deleted() is called after deleting the model

For example:

class Product extends ElasticsearchModel
{
    public static $_index = 'test';
    public static $_type = 'test';

    public $name;
    public $price = 0;

    protected function saving()
    {
        if ($this->price <= 0) {
            return false;
        }

        return true;
    }

    protected function deleting()
    {
        if (!$this->canDelete()) {
            throw new LogicException('No permissions to delete the model');
        }

        return true;
    }
}

Basic search

There are helpers to search documents:

The first($query) method returns the first document according to the query or null.

$product = Product::first($query);

The firstOrFail($query) method returns ModelNotFoundException exception if first($query) returns null.

$product = Product::firstOrFail($query);

The search($query) method returns documents (default 50 items) according to the query.

$products = Product::search($query);

The map($query, callable $callback) method returns all documents (default 50 items per request) according to the query.

$total = Product::map([], function (Product $product) {
    // ...
});

The all($query) method returns all documents according to the query.

$products = Product::all($query);

If $query is not passed the query will be as match_all query.

Query Builder

use Isswp101\Persimmon\QueryBuilder\QueryBuilder;

$query = new QueryBuilder();

Simple usage:

$query = new QueryBuilder(['query' => ['match' => ['name' => 'Product']]]);
$products = Product::search($query);

The match query:

$query = new QueryBuilder();
$query->match('name', 'Product');
$products = Product::search($query);    

The range query:

$query = new QueryBuilder();
$query->betweenOrEquals('price', 20, 30)->greaterThan('price', 15);
$products = Product::search($query);

Filters

Feel free to add your own filters.

The TermFilter filter:

$query = new QueryBuilder();
$query->filter(new TermFilter('name', '2'));
$products = Product::search($query);

The IdsFilter filter:

$query = new QueryBuilder();
$query->filter(new IdsFilter([1, 3]));
$products = Product::search($query);

The RangeOrExistFilter filter:

$query = new QueryBuilder();
$query->filter(new RangeOrExistFilter('price', ['gte' => 20]));
$products = Product::search($query);

Aggregations

Feel free to add your own aggregations.

$query = new QueryBuilder();
$query->aggregation(new TermsAggregation('name'));
$products = Product::search($query);
$buckets = $products->getAggregation('name');
// Usage: $buckets[0]->getKey() and $buckets[0]->getCount()

Parent-Child Relationship

The parent-child relationship is similar in nature to the nested model: both allow you to associate one entity with another. The difference is that, with nested objects, all entities live within the same document while, with parent-child, the parent and children are completely separate documents.

Let's create two models:

1. PurchaseOrder has many PurchaseOrderLine models
2. PurchaseOrderLine belongs to PurchaseOrder model

class PurchaseOrder extends ElasticsearchModel
{
    protected static $_index = 'test_parent_child_rel';
    protected static $_type = 'orders';

    public $name;

    public function lines()
    {
        return $this->hasMany(PurchaseOrderLine::class);
    }
}

class PurchaseOrderLine extends ElasticsearchModel
{
    protected static $_index = 'test_parent_child_rel';
    protected static $_type = 'lines';
    
    protected static $_parentType = 'orders';

    public $name;

    public function po()
    {
        return $this->belongsTo(PurchaseOrder::class);
    }
}

To save() models you can use the following code:

$po = new PurchaseOrder(['id' => 1, 'name' => 'PO1']);
$line = new PurchaseOrderLine(['id' => 1, 'name' => 'Line1']);

$po->save();
$po->lines()->save($line);

You can use the associate() method to save models:

$po = new PurchaseOrder(['id' => 1, 'name' => 'PO1']);
$line = new PurchaseOrderLine(['id' => 1, 'name' => 'Line1']);

$po->save();
$line->po()->associate($po);
$line->save();

To get parent you can use the following code:

$line = PurchaseOrderLine::findWithParentId(1, 1);
$po = $line->po()->get();

To get children you can use the following code:

$po = PurchaseOrder::findOrFail(1);
$line = $po->lines()->find(1); // by id
$lines = $po->lines()->get(); // all children

Inner hits

The parent/child and nested features allow the return of documents that have matches in a different scope. In the parent/child case, parent document are returned based on matches in child documents or child document are returned based on matches in parent documents. In the nested case, documents are returned based on matches in nested inner objects.

You can get parent model using only one request with InnerHitsFilter filter:

$query = new QueryBuilder();
$query->filter(new InnerHitsFilter(PurchaseOrderLine::getParentType()));
$line = PurchaseOrderLine::search($query)->first();
$po = $line->po()->get(); // will be retrieved from inner_hits cache

Logging and data access layer events

To debug all elasticsearch queries to search you can use own DALEmitter class:

use Isswp101\Persimmon\DAL\DALEvents;
use Isswp101\Persimmon\Event\EventEmitter;

class DALEmitter extends EventEmitter
{
    public function __construct()
    {
        $this->on(DALEvents::BEFORE_SEARCH, function (array $params) {
            Log::debug('Elasticsearch query', $params);
        });
    }
}

And configure it in your service provider:

use Elasticsearch\Client;
use Isswp101\Persimmon\DAL\ElasticsearchDAL;
use Isswp101\Persimmon\ElasticsearchModel as Model;
use Isswp101\Persimmon\Test\Models\Events\DALEmitter;

class ElasticsearchModel extends Model
{
    public function __construct(array $attributes = [])
    {
        $dal = new ElasticsearchDAL($this, app(Client::class), app(DALEmitter::class));

        parent::__construct($dal, $attributes);
    }
    // ...
}

There are the following events:

• DALEvents::BEFORE_SEARCH is triggered before any search.
• DALEvents::AFTER_SEARCH is triggered after any search.

TO BE CONTINUED...

@TODO:

• Add documentation about filters

Change log

Please see CHANGELOG for more information what has changed recently.

Testing

$ composer test

Contributing

Please see CONTRIBUTING and CONDUCT for details.

Security

If you discover any security related issues, please email isswp101@gmail.com instead of using the issue tracker.

Credits

• Sergey Sorokin
• All Contributors

License

The MIT License (MIT). Please see License File for more information.