triadev/laravel-elasticsearch-dsl

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

v1.1.4 2019-01-08 19:02 UTC

This package is auto-updated.

Last update: 2024-03-09 13:17:44 UTC


README

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

Software license Travis Coveralls CodeCov

Scrutinizer Code Quality Code Coverage Build Status

Latest stable Latest development Monthly installs

Supported laravel versions

Laravel 5.5 Laravel 5.6 Laravel 5.7

Supported elasticsearch versions

Elasticsearch 6.0 Elasticsearch 6.1 Elasticsearch 6.2 Elasticsearch 6.3 Elasticsearch 6.4

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

Other

Project related links

License

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