Maps Laravel Eloquent models to Elasticsearch types



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.


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 :)


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

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

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.


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

To get started, add Elasticquent to you composer.json file:

"elasticquent/elasticquent": "dev-master"

Once you've run a composer update, you need to register Laravel service provider, in your config/app.php:

'providers' => [

We also provide a facade for elasticsearch-php client (which has connected using our settings), add following to your config/app.php if you need so.

'aliases' => [
    'Es' => Elasticquent\ElasticquentElasticsearchFacade::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"

return array(

    | Custom Elasticsearch Client Configuration
    | This array will be passed to the Elasticsearch client.
    | See configuration options here:

    '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',


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.

If you want a simple way to create indexes, Elasticquent models have a function for that:

Book::createIndex($shards = null, $replicas = null);

For custom analyzer, you can set an indexSettings property in your model and define the analyzers from there:

     * The elasticsearch settings.
     * @var array
    protected $indexSettings = [
        'analysis' => [
            'char_filter' => [
                'replace' => [
                    'type' => 'mapping',
                    'mappings' => [
                        '&=> and '
            'filter' => [
                'word_delimiter' => [
                    'type' => 'word_delimiter',
                    'split_on_numerics' => false,
                    'split_on_case_change' => true,
                    'generate_word_parts' => true,
                    'generate_number_parts' => true,
                    'catenate_all' => true,
                    'preserve_original' => true,
                    'catenate_numbers' => true,
            'analyzer' => [
                'default' => [
                    'type' => 'custom',
                    'char_filter' => [
                    'tokenizer' => 'whitespace',
                    'filter' => [

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

protected $mappingProperties = array(
   'title' => array(
        '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:


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


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


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 array(

   // 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:


You can also index a collection of models:

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

You can index individual entries as well:

    $book = Book::find($id);

You can also reindex an entire model:



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)


    $books = Book::searchByQuery(array('match' => array('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(array(
        'body' => array(
            'query' => array(
                'match' => array(
                    'title' => 'Moby Dick'

This is the equivalent to:

    $books = Book::searchByQuery(array('match' => array('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:


Access the shards array:


Access the max score:


Access the timed out boolean property:


And access the took property:


And access search aggregations - See Aggregations for details:


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:


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


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(array('match' => array('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 = array(
    '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 array(
        '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;


Elasticquent currently needs:

  • Tests that mock ES API calls.
  • Support for routes
  • Compatibility with Elasticsearch 5.0.0

    Compatibility with Elasticsearch 5.0.0

    illegal_argument_exception: The parameter [fields] is no longer supported, please use [stored_fields] to retrieve stored fields or _source filtering if the field is not stored

    It seems that Elastiquent is not compatible with the latest version of Elasticsearch. Or did I something wrong?

    version 1.0 
    opened by Sennik 34
  • Still Laravel 4 compatible?

    Still Laravel 4 compatible?

    I'm in the need of extending an existing L4 app, and tried to follow the setup procedure, but as soon as I copy the "providers" declaration, I get a:

    Call to undefined method Elasticquent\ElasticquentServiceProvider::publishes()

    pointing to

     public function boot()
                __DIR__.'/config/elasticquent.php' => config_path('elasticquent.php'),

    I have an /app/config/elasticquent.php file in place, but that doesn't seem to make any difference.

    Is this a L5-only-app problem? Any specific branch I can target to get L4 support?

    Thanks in advance!

    Laravel 4 
    opened by MarcosBL 24
  • Content-Type header [] is not supported

    Content-Type header [] is not supported

    $enterprise = Enterprise::where('id','<',200)->get();

    response error

    Content-Type header [] is not supported

    How to specify the head of a request ? like this curl -H "Content-Type: application/json;charset=UTF-8" -XGET '' -d '{"query":{"match_all":{}}}'

    Content-type header can be specified here

    not like curl -XGET '' -d '{"query":{"match_all":{}}}' Otherwise it will be wrong:

      "error" : "Content-Type header [application/x-www-form-urlencoded] is not supported",
      "status" : 406

    How should I solve it, Who can help me? Oh,the problem is in the elasticsearch 6.0.0

    opened by etertime 12
  • Fixed matching BelongsTo hydrate

    Fixed matching BelongsTo hydrate

    Started working with the new recursive hydrator. This works great except for the BelongsTo relation.

    This relationship matches the model back on the foreignKey, see \Illuminate\Database\Eloquent\Relations\BelongsTo line 215/222

    opened by BertvanHoekelen 11
  • Resolve a problem whereby a large amount of data for a given model wo…

    Resolve a problem whereby a large amount of data for a given model wo…

    Resolve a problem whereby a large amount of data for a given model would result in a "Request size exceeded 10485760 bytes" error in AWS Elastic Search (and potentially other configurations)

    Ran into this issue today, quite annoying. I re-factored the code to send the data in lots of 1000 database records/models, and it works like a charm.

    opened by specialtactics 7
  • problem mappingProperties

    problem mappingProperties

    Hi, I have just started using this package and I am getting:

    Fatal error: App\Part and Elasticquent\ElasticquentTrait define the same property ($mappingProperties) in the composition of App\Part. However, the definition differs and is considered incompatible. Class was composed in /var/www/html/testProject/app/Part.php on line 27

     protected $mappingProperties = array(
            'PART_NO' => [
                'type' => 'string',
                "analyzer" => "standard",
            'DESCRIPTION' => [
                'type' => 'string',
                "analyzer" => "standard",

    Am I doing something wrong?


    opened by ArtisanTinkerer 7
  • multiple match question

    multiple match question

        "bool" : {
            "must" : [{
                "match" : {
                    "user_id" : "1"
                "match" : {
                    "name" : "John"

    How can i handle such requests? I mean a several match in it.

    opened by galexth 6
  • Field [_id] is a metadata field and cannot be added inside a document. Use the index API request parameters.

    Field [_id] is a metadata field and cannot be added inside a document. Use the index API request parameters.

    Hi, I tried a bulk add as shown is your readme but instead I get this error:

    "error" => array:2 [ "type" => "mapper_parsing_exception" "reason" => "Field [_id] is a metadata field and cannot be added inside a document. Use the index API request parameters." ]

    The model I'm trying to add is just a test model, and it's something like:

    "title" => "MRdTvVwMTGSl" "updated_at" => "2016-04-04 15:58:29" "created_at" => "2016-04-04 15:58:29" "_id" => "57028f25633db3473d0041c8"

    I have ElasticSearch 2.1 and it's under Mac OSX 10.11.3 Any advice?

    opened by sfolador 6
  • Yesterdays merge created this error for me.

    Yesterdays merge created this error for me.

    Everything was working fine before this morning.

    This commit:

    Error: Missing argument 1 for Illuminate\Database\Eloquent\Model::updated(), called in /vendor/elasticquent/elasticquent/src/ElasticquentTrait.php on line 693 and defined

    Little more data:

    • DB : (Mongo) using "jenssegers/mongodb": "3.0.*" plugin
    • Elasticquent Version : "elasticquent/elasticquent": "dev-master"
    • Laravel Version : "laravel/framework": "5.2.*"

    I will see if i can modify the commit to work for my set up and commit my changes for a possible fix. for production I will just going to revert the commit on my side for now to get the app back up but i thought i should share for future development.

    Edit: So I believe i have figured out the issue i am having. jenssegers/mongodb puts a modifier on the model obj. which changes the "updated_at" "created_at" to mongo date type obj.

    opened by Thedigit 5
  • Can not use map on ElasticquentResultCollection

    Can not use map on ElasticquentResultCollection

    This code will not work:

    $books = Book::search('moby dick');
    $titles = $books->map(function ($book) {
        return $book->title;

    This is the error that is thrown:

    PHP warning:  Missing argument 2 for Elasticquent\ElasticquentResultCollection::__construct(), called in /app/bootstrap/cache/compiled.php on line 12523 and defined in /app/vendor/elasticquent/elasticquent/src/ElasticquentResultCollection.php on line 22
    opened by onbjerg 5
  • Is there a way of storing related models with a document?

    Is there a way of storing related models with a document?

    Not sure if this is directly related to this library however I am using Elasticquent to store products and index them. Each of these products also has related models such as the user that created them, the images, the locations etc.

    Is there a way using Elastiquent to store these in the same document as the product itself and possibly make them searchable? Im not sure how exactly you would go about doing this though.

    opened by TomCaserta 5
  • Update ElasticSearch to 8.4 and support for routing

    Update ElasticSearch to 8.4 and support for routing

    This also fixes some bugs with pagination. Cleaned up and removed functions that ES has removed. Fixed the tests so they correspond to what ES returns.

    As ES 7 forward has removed types, this change will incorporate the type (table name) into the index name.

    This probably needs to be tagged as version 2.x as it will destroy backwards compatibility.

    If there's something you want me to do in a different way, just give me the heads up and I'll look into it!

    opened by Parsk 0
  • Multi tenancy custom routing

    Multi tenancy custom routing


    I would like to know your approach to using Elastic Search with multi-tenancy. According to this link the best approach is custom routing for every client. Given every tenant has an id how would you use custom routing with this package.

    Thank you in advance.

    opened by hassanazimi 0
  • insert a document directly into elasticsearch index

    insert a document directly into elasticsearch index

    I used this method But it insert data into Mysql firstly $books = Book::where('id', '<', 200)->get(); $books->addToIndex(); The aim is to insert directly into ElasticSearch Index

    opened by mheni 0
  • v1.0.7(Jun 24, 2019)

  • v1.0.6(Jan 28, 2016)

    Fix two regressions from v1.0.5

    This should be us done for the v1.0 series. Now it's time to start working on 1.1 :+1:

    Fixes & Changes

    • #24 Full namespaces removed from use statements caused compatibility issues
    • #27 Elasticquent would not install on Laravel 5.0 and Laravel 5.1
    Source code(tar.gz)
    Source code(zip)
  • v1.0.5(Jan 27, 2016)

  • v1.0.4(Jan 11, 2016)

  • v1.0.3(Aug 21, 2015)

  • v1.0.2(Jul 13, 2015)

Search among multiple models with ElasticSearch and Laravel Scout

For PHP8 support use php8 branch For Laravel Framework < 6.0.0 use 3.x branch The package provides the perfect starting point to integrate ElasticSear

Sergey Shlyakhov 592 Dec 25, 2022
Laravel 8.* Elasticsearch Eloquent

Elasticsearch Installation composer require etsetra/elasticsearch Create config file $ php artisan vendor:publish --tag="etsetra-elasticsearch-config

Etsetra 2 Jan 14, 2022
Laravel Scout provides a driver based solution to searching your Eloquent models.

Introduction Laravel Scout provides a simple, driver-based solution for adding full-text search to your Eloquent models. Once Scout is installed and c

The Laravel Framework 1.3k Dec 31, 2022
Laravel package to search through multiple Eloquent models. Supports sorting, pagination, scoped queries, eager load relationships and searching through single or multiple columns.

Laravel Cross Eloquent Search This Laravel package allows you to search through multiple Eloquent models. It supports sorting, pagination, scoped quer

Protone Media 844 Dec 25, 2022
Elasticsearch driver for Laravel Scout

Elasticsearch driver for Laravel Scout. Contents Compatibility Installation Configuration Basic Usage Advanced Search Migrations Pitfalls Compatibilit

Ivan Babenko 197 Dec 19, 2022
Elasticsearch migrations for Laravel

Elastic Migrations Elasticsearch migrations for Laravel allow you to easily modify and share indices schema across the application's environments. Con

Ivan Babenko 151 Dec 20, 2022
Official PHP low-level client for Elasticsearch.

elasticsearch-php Official low-level client for Elasticsearch. Its goal is to provide common ground for all Elasticsearch-related code in PHP; because

elastic 5k Dec 31, 2022
Elastica is a PHP client for elasticsearch

Elastica: elasticsearch PHP Client All documentation for Elastica can be found under If you have questions, don't hesitate to ask them on

Nicolas Ruflin 2.2k Dec 23, 2022
Store and retrieve objects from Algolia or Elasticsearch

Store and retrieve objects from a search index This is an opinionated Laravel 5.1 package to store and retrieve objects from a search index. Currently

Spatie 440 Dec 30, 2022
Build and execute an Elasticsearch search query using a fluent PHP API

PACKAGE IN DEVELOPMENT, DO NOT USE YET Build and execute ElasticSearch queries using a fluent PHP API This package is a lightweight query builder for

Spatie 94 Dec 14, 2022
This package offers advanced functionality for searching and filtering data in Elasticsearch.

Scout Elasticsearch Driver ?? Introducing a new Elasticsearch ecosystem for Laravel. ?? This package offers advanced functionality for searching and f

Ivan Babenko 1.2k Dec 20, 2022
Official PHP low-level client for Elasticsearch.

elasticsearch-php Official low-level client for Elasticsearch. Its goal is to provide common ground for all Elasticsearch-related code in PHP; because

elastic 5k Jan 1, 2023
This modules provides a Search API Backend for Elasticsearch.

Search API ElasticSearch This modules provides a Search API Backend for Elasticsearch. This module uses the official Elasticsearch PHP Client. Feature

null 1 Jan 20, 2022
Search products, categories, brands or tags with ElasticSearch

ElasticSearch for Shopaholic This plugin allows you to use ElasticSearch as search engine for Shopaholic. Benefits Easy to install, easy to use Opened

Biz-Mark 4 Feb 18, 2022
Query Builder for Elasticsearch

Query Builder for Elasticsearch

wangzhiqiang 5 Mar 2, 2022
A php trait to search laravel models

Searchable, a search trait for Laravel Searchable is a trait for Laravel 4.2+ and Laravel 5.0 that adds a simple search function to Eloquent Models. S

Nicolás López Jullian 2k Dec 27, 2022
Think-scout - A driver based solution to searching your models. Inspired By Laravel Scout

前言 whereof/think-scout根据thinkphp设计思想参考laravel/scout进行扩展 whereof/think-scout 为模型的全文搜索提供了一个简单的、基于驱动程序的解决方案。 目前,Scout 自带了一个 Elasticsearch 驱动;而编写自定义驱动程序很简

wangzhiqiang 6 Mar 18, 2022
[Deprecated] We now recommend using Laravel Scout, see =>

[DEPRECATED] Algolia Search API Client for Laravel Algolia Search is a hosted full-text, numerical, and faceted search engine capable of delivering re

Algolia 240 Nov 25, 2022
A search package for Laravel 5.

Search Package for Laravel 5 This package provides a unified API across a variety of different full text search services. It currently supports driver

Mark Manos 354 Nov 16, 2022