laravel-elasticsearch-dsl

A service provider for laravel with a fluent elasticsearch query and aggregation dsl.

Supported laravel versions

Supported elasticsearch versions

Main features

• Query (TermLevel, Fulltext, Geo, Compound, Joining, Specialized, InnerHit)
• Aggregation (Bucketing, Metric, Pipeline)
• Suggestion

Installation

Composer

composer require triadev/laravel-elasticsearch-dsl

Application

The package is registered through the package discovery of laravel and Composer.

https://laravel.com/docs/5.7/packages

Once installed you can now publish your config file and set your correct configuration for using the package.

php artisan vendor:publish --provider="Triadev\Es\Dsl\Provider\ServiceProvider" --tag="config"

This will create a file config/laravel-elasticsearch-dsl.php.

Configuration

Key	Env	Value	Default
index	LARAVEL_ELASTICSEARCH_DSL_INDEX	STRING	default_index
metrics.enabled	LARAVEL_ELASTICSEARCH_DSL_METRICS	BOOL	false
metrics.buckets.search	---	ARRAY	array of buckets in milliseconds
metrics.buckets.suggest	---	ARRAY	array of buckets in milliseconds

Metrics

Metrics are generated with the package: LaravelPrometheusExporter
Detailed configuration options are documented in the readme of the package.

The following metrics are generated as long as metrics.enabled = true:

Namespace: triadev_laravel_elasticsearch_dsl

Histogram

Name	Handler	Description
query_duration_milliseconds	search	execution time of search query
query_duration_milliseconds	suggest	execution time of suggestion query

Usage

This package offers a dsl for elasticsearch. The entry point for each query / aggregation is a facade.

Triadev\Es\Dsl\Facade\ElasticDsl;

Each query / aggregation returns an object containing the search result and aggregation.

Triadev\Es\Dsl\Model\SearchResult

int: time needed to execute the query
$result->took();

bool
$result->timedOut();

float
$result->maxScore();

int: number of matched documents
$result->totalHits();

Illuminate\Support\Collection: collection of searchable eloquent models
$result->hits();

array|null
$result->aggregation();

Bool

For every query that is based on bool, the bool status can be changed.

Default bool state: must

ElasticDsl::search()->termLevel()
    ->must()
        ->term('FIELD', 'VALUE')
    ->mustNot()
        ->term('FIELD', 'VALUE')
    ->should()
        ->term('FIELD', 'VALUE')
    ->filter()
        ->term('FIELD', 'VALUE')
})->get()

Nested bool query

A nested query is realized with bool(\Closure $closure).

ElasticDsl::search()
    ->termLevel()
        ->term('FIELD', 'VALUE')
        ->bool(function (Search $search) {
            $search->termLevel()
                ->term('FIELD', 'VALUE')
                ->bool(function (Search $search) {
                    $search->fulltext()
                        ->match('FIELD1', 'QUERY1')
                        ->matchPhrase('FIELD2', 'QUERY2');
                });
            })
        ->prefix('FIELD', 'VALUE')
    ->get();

--------------------------------------------------
[
    "query" => [
        "bool" => [
            "must" => [
                [
                    "term" => [
                        "FIELD" => "VALUE"
                    ]
                ],
                [
                    "bool" => [
                        "must" => [
                            [...],
                            [...]
                        ]
                    ]
                ],
                [
                    "prefix" => [
                        "FIELD" => [
                            "value" => "VALUE"
                        ]
                    ]
                ]
            ]
        ]
    ]
]

TermLevel

matchAll, exists, fuzzy, ids, prefix, range, regexp, term, terms, type, wildcard

ElasticDsl::search()->termLevel()->filter()->term('FIELD', 'VALUE')->get();

Fulltext

match, matchPhrase, matchPhrasePrefix, multiMatch, queryString, simpleQueryString, commonTerms

ElasticDsl::search()->fulltext()->must()->match('FIELD', 'QUERY')->get();

Geo

geoBoundingBox, geoDistance, geoPolygon, geoShape

ElasticDsl::search()->geo()->filter()->geoDistance('FIELD','10km', new Location(1, 2))->get();

Compound

functionScore, constantScore, boosting, disMax

ElasticDsl::search()->compound()->functionScore(
    function (Search $search) {
        $search->termLevel()->term('FIELD1', 'VALUE1');
    },
    function (FunctionScore $functionScore) {
        $functionScore->simple([]);
    }
)->get();

Joining

nested, hasChild, hasParent

ElasticDsl::search()->joining()->nested('PATH', function (Search $search) {
   $search->termLevel()->filter()->term('FIELD', 'VALUE');
})->get();

Specialized

moreLikeThis

ElasticDsl::search()->specialized()->moreLikeThis('LIKE')->toDsl();

InnerHit

nestedInnerHit, parentInnerHit

ElasticDsl::search()->nestedInnerHit('NAME', 'PATH', function (Search $search) {
    $search->termLevel()->term('FIELD', 'VALUE');
})->get();

Individual index and type

To set an individual index or type per query you have two overwrite methods.

ElasticDsl::search()
    ->overwriteIndex('INDEX')
    ->overwriteType('TYPE')
    ->termLevel()
        ->matchAll()
    ->get();

Aggregation

Bucketing, Metric, Pipeline

ElasticDsl::search()->aggregation(function (Aggregation $aggregation) {
    $aggregation->metric(function (Aggregation\Metric $metric) {
        ...
    });
})->get();

ElasticDsl::search()->aggregation(function (Aggregation $aggregation) {
    $aggregation->bucketing(function (Aggregation\Bucketing $metric) {
        ...
    });
})->get();

ElasticDsl::search()->aggregation(function (Aggregation $aggregation) {
    $aggregation->pipeline(function (Aggregation\Pipeline $metric) {
        ...
    });
})->get();

Suggestions

term, phrase, completion

ElasticDsl::suggest()->term('NAME', 'TEXT', 'FIELD')->get();

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

Testing

1. docker-compose -f docker-compose.yml up
2. composer test

Contributing

Please see CONTRIBUTING for details.

Credits

• Christopher Lorke
• All Contributors

Other

Project related links

• Wiki
• Issue tracker

License

The code for laravel-elasticsearch-dsl is distributed under the terms of the MIT license (see LICENSE).