Elasticquent

Elasticsearch for Eloquent Laravel Models

Elasticquent makes working with Elasticsearch and Eloquent models easier by mapping them to Elasticsearch types. You can use the default settings or define how Elasticsearch should index and search your Eloquent models right in the model.

Elasticquent uses the official Elasticsearch PHP API. To get started, you should have a basic knowledge of how Elasticsearch works (indexes, types, mappings, etc).

Elasticsearch Requirements

You must be running at least Elasticsearch 1.0. Elasticsearch 0.9 and below will not work and are not supported.

Contents

• Overview
  • How Elasticquent Works
• Setup
  • Elasticsearch Configuration
  • Indexes and Mapping
  • Setting a Custom Index Name
  • Setting a Custom Type Name
• Indexing Documents
• Artisan Commands
• Searching
  • Search Collections
  • Search Collection Documents
  • Chunking results from Elastiquent
  • Using the Search Collection Outside of Elasticquent
• More Options
  • Document Ids
  • Document Data
  • Using Elasticquent With Custom Collections
• Roadmap

Reporting Issues

If you do find an issue, please feel free to report it with GitHub's bug tracker for this project.

Alternatively, fork the project and make a pull request :)

Overview

Elasticquent allows you take an Eloquent model and easily index and search its contents in Elasticsearch.

    $books = Book::where('id', '<', 200)->get();
    $books->addToIndex();

When you search, instead of getting a plain array of search results, you instead get an Eloquent collection with some special Elasticsearch functionality.

    $books = Book::search('Moby Dick');
    echo $books->totalHits();

Plus, you can still use all the Eloquent collection functionality:

    $books = $books->filter(function ($book) {
        return $book->hasISBN();
    });

Check out the rest of the documentation for how to get started using Elasticsearch and Elasticquent!

How Elasticquent Works

When using a database, Eloquent models are populated from data read from a database table. With Elasticquent, models are populated by data indexed in Elasticsearch. The whole idea behind using Elasticsearch for search is that its fast and light, so you model functionality will be dictated by what data has been indexed for your document.

Setup

Before you start using Elasticquent, make sure you've installed Elasticsearch.

From the command line run:

$ composer require torann/elasticquent

Once installed you need to register the service provider with the application. Open up config/app.php and find the providers key.

'providers' => [
    ...
    Elasticquent\ElasticquentServiceProvider::class,
],

Then add the Elasticquent trait to any Eloquent model that you want to be able to index in Elasticsearch:

use Elasticquent\ElasticquentTrait;

class Book extends Eloquent
{
    use ElasticquentTrait;
}

Now your Eloquent model has some extra methods that make it easier to index your model's data using Elasticsearch.

Elasticsearch Configuration

By default, Elasticquent will connect to localhost:9200 and use default as index name, you can change this and the other settings in the configuration file. You can add the elasticquent.php config file at /app/config/elasticquent.php for Laravel 4, or use the following Artisan command to publish the configuration file into your config directory for Laravel 5:

$ php artisan vendor:publish --provider="Elasticquent\ElasticquentServiceProvider"

<?php

return [

    /*
    |--------------------------------------------------------------------------
    | Custom Elasticsearch Client Configuration
    |--------------------------------------------------------------------------
    |
    | This array will be passed to the Elasticsearch client.
    | See configuration options here:
    |
    | http://www.elasticsearch.org/guide/en/elasticsearch/client/php-api/current/_configuration.html
    */

    'config' => [
        'hosts'     => ['localhost:9200'],
        'retries'   => 1,
    ],

    /*
    |--------------------------------------------------------------------------
    | Default Index Name
    |--------------------------------------------------------------------------
    |
    | This is the index name that Elastiquent will use for all
    | Elastiquent models.
    */

    'default_index' => 'my_custom_index_name',

    /*
    |--------------------------------------------------------------------------
    | Default Index Settings
    |--------------------------------------------------------------------------
    |
    | This is the settings used when creating an Elasticsearch index.
    |
    | 'default_settings' => [
    |     'number_of_shards' => 1,
    |     'analysis' => [
    |         'filter' => [
    |             'autocomplete_filter' => [
    |                 'type' => 'edge_ngram',
    |                 'min_gram' => 1,
    |                 'max_gram' => 20,
    |             ],
    |         ],
    |         'analyzer' => [
    |             'autocomplete' => [
    |                 'type' => 'custom',
    |                 'tokenizer' => 'standard',
    |                 'filter' => [
    |                     'lowercase',
    |                     'autocomplete_filter',
    |                 ],
    |             ],
    |         ],
    |     ],
    | ],
    */

    'default_settings' => null,
];

Indexes and Mapping

While you can definitely build your indexes and mapping through the Elasticsearch API, you can also use some helper methods to build indexes and types right from your models.

For custom analyzer, you can set an default_settings property in the config/elasticquent.php file:

[
    'default_settings' => [
         'number_of_shards' => 1,
         'analysis' => [
             'filter' => [
                 'autocomplete_filter' => [
                     'type' => 'edge_ngram',
                     'min_gram' => 1,
                     'max_gram' => 20,
                 ],
             ],
             'analyzer' => [
                 'autocomplete' => [
                     'type' => 'custom',
                     'tokenizer' => 'standard',
                     'filter' => [
                         'lowercase',
                         'autocomplete_filter',
                     ],
                 ],
             ],
         ],
     ],
]

For mapping, you can set a mappingProperties property in your model and use some mapping functions from there:

protected $mappingProperties = [
   'title' => [
        'type' => 'string',
        'analyzer' => 'standard'
    ]
];

If you'd like to setup a model's type mapping based on your mapping properties, you can use:

    Book::putMapping($ignoreConflicts = true);

To delete a mapping:

    Book::deleteMapping();

To rebuild (delete and re-add, useful when you make important changes to your mapping) a mapping:

    Book::rebuildMapping();

You can also get the type mapping and check if it exists.

    Book::mappingExists();
    Book::getMapping();

Setting a Custom Index Name

By default, Elasticquent will look for the default_index key within your configuration file(config/elasticquent.php). To set the default value for an index being used, you can edit this file and set the default_index key:

return [

   // Other configuration keys ...
   
   /*
    |--------------------------------------------------------------------------
    | Default Index Name
    |--------------------------------------------------------------------------
    |
    | This is the index name that Elastiquent will use for all
    | Elastiquent models.
    */
    
   'default_index' => 'my_custom_index_name',
];

If you'd like to have a more dynamic index, you can also override the default configuration with a getIndexName method inside your Eloquent model:

function getIndexName()
{
    return 'custom_index_name';
}

Note: If no index was specified, Elasticquent will use a hardcoded string with the value of default.

Setting a Custom Type Name

By default, Elasticquent will use the table name of your models as the type name for indexing. If you'd like to override it, you can with the getTypeName function.

function getTypeName()
{
    return 'custom_type_name';
}

To check if the type for the Elasticquent model exists yet, use typeExists:

    $typeExists = Book::typeExists();

Indexing Documents

To index all the entries in an Eloquent model, use addAllToIndex:

    Book::addAllToIndex();

You can also index a collection of models:

    $books = Book::where('id', '<', 200)->get();
    $books->addToIndex();

You can index individual entries as well:

    $book = Book::find($id);
    $book->addToIndex();

You can also reindex an entire model:

    Book::reindex();

Artisan Commands

es:install

Create the Elasticsearch index.

es:uninstall

Remove the Elasticsearch index.

es:map <action> <model>

Initialize an Eloquent model.

Arguments:

 action              Mapping action to perform (add or remove)
 model               Name or comma separated names of the model(s) to initialize

es:index [options] [--] <model>

Index or reindex all the entries in an Eloquent model.

Arguments:

 model               Name or comma separated names of the model(s) to index

Searching

There are three ways to search in Elasticquent. All three methods return a search collection.

Simple term search

The first method is a simple term search that searches all fields.

    $books = Book::search('Moby Dick');

Query Based Search

The second is a query based search for more complex searching needs:

    public static function searchByQuery($query = null, $aggregations = null, $sourceFields = null, $limit = null, $offset = null, $sort = null)

Example:

    $books = Book::searchByQuery([
        'match' => ['title' => 'Moby Dick']
    ]);

Here's the list of available parameters:

• query - Your ElasticSearch Query
• aggregations - The Aggregations you wish to return. See Aggregations for details.
• sourceFields - Limits returned set to the selected fields only
• limit - Number of records to return
• offset - Sets the record offset (use for paging results)
• sort - Your sort query

Raw queries

The final method is a raw query that will be sent to Elasticsearch. This method will provide you with the most flexibility when searching for records inside Elasticsearch:

    $books = Book::complexSearch([
        'body' => [
            'query' => [
                'match' => [
                    'title' => 'Moby Dick'
                ]
            ]
        ]
    ]);

This is the equivalent to:

    $books = Book::searchByQuery(['match' => ['title' => 'Moby Dick']]);

Search Collections

When you search on an Elasticquent model, you get a search collection with some special functions.

You can get total hits:

    $books->totalHits();

Access the shards array:

    $books->shards();

Access the max score:

    $books->maxScore();

Access the timed out boolean property:

    $books->timedOut();

And access the took property:

    $books->took();

And access search aggregations - See Aggregations for details:

    $books->getAggregations();

Search Collection Documents

Items in a search result collection will have some extra data that comes from Elasticsearch. You can always check and see if a model is a document or not by using the isDocument function:

    $book->isDocument();

You can check the document score that Elasticsearch assigned to this document with:

    $book->documentScore();

Chunking results from Elastiquent

Similar to Illuminate\Support\Collection, the chunk method breaks the Elasticquent collection into multiple, smaller collections of a given size:

    $all_books = Book::searchByQuery(['match' => ['title' => 'Moby Dick']]);
    $books = $all_books->chunk(10);

Using the Search Collection Outside of Elasticquent

If you're dealing with raw search data from outside of Elasticquent, you can use the Elasticquent search results collection to turn that data into a collection.

$client = new \Elasticsearch\Client();

$params = [
    'index' => 'default',
    'type'  => 'books'
];

$params['body']['query']['match']['title'] = 'Moby Dick';

$collection = Book::hydrateElasticsearchResult($client->search($params));

More Options

Document IDs

Elasticquent will use whatever is set as the primaryKey for your Eloquent models as the id for your Elasticsearch documents.

Document Data

By default, Elasticquent will use the entire attribute array for your Elasticsearch documents. However, if you want to customize how your search documents are structured, you can set a getIndexDocumentData function that returns you own custom document array.

function getIndexDocumentData()
{
    return [
        'id'      => $this->id,
        'title'   => $this->title,
        'custom'  => 'variable'
    ];
}

Be careful with this, as Elasticquent reads the document source into the Eloquent model attributes when creating a search result collection, so make sure you are indexing enough data for your the model functionality you want to use.

Using Elasticquent With Custom Collections

If you are using a custom collection with your Eloquent models, you just need to add the ElasticquentCollectionTrait to your collection so you can use addToIndex.

class MyCollection extends \Illuminate\Database\Eloquent\Collection
{
    use ElasticquentCollectionTrait;
}

Roadmap

Elasticquent currently needs:

• Tests that mock ES API calls.