Build and execute an Elasticsearch search query using a fluent PHP API

Overview

PACKAGE IN DEVELOPMENT, DO NOT USE YET

Build and execute ElasticSearch queries using a fluent PHP API

Latest Version on Packagist GitHub Tests Action Status GitHub Code Style Action Status Total Downloads


This package is a lightweight query builder for ElasticSearch. It was specifically built for our elasticsearch-search-string-parser so it covers most use-cases but might lack certain features. We're always open for PRs if you need anything specific!

use Spatie\ElasticsearchQueryBuilder\Aggregations\MaxAggregation;
use Spatie\ElasticsearchQueryBuilder\Builder;
use Spatie\ElasticsearchQueryBuilder\Queries\MatchQuery;

$client = Elasticsearch\ClientBuilder::create()->build();

$companies = (new Builder($client))
    ->index('companies')
    ->addQuery(MatchQuery::create('name', 'spatie', fuzziness: 3))
    ->addAggregation(MaxAggregation::create('score'))
    ->search();

Support us

We invest a lot of resources into creating best in class open source packages. You can support us by buying one of our paid products.

We highly appreciate you sending us a postcard from your hometown, mentioning which of our package(s) you are using. You'll find our address on our contact page. We publish all received postcards on our virtual postcard wall.

Installation

You can install the package via composer:

composer require spatie/elasticsearch-query-builder

Basic usage

The only class you really need to interact with is the Spatie\ElasticsearchQueryBuilder\Builder class. It requires an \Elasticsearch\Client passed in the constructor. Take a look at the ElasticSearch SDK docs to learn more about connecting to your ElasticSearch cluster.

The Builder class contains some methods to add queries, aggregations, sorts, fields and some extras for pagination. You can read more about these methods below. Once you've fully built-up the query you can use $builder->search() to execute the query or $builder->getPayload() to get the raw payload for ElasticSearch.

use Spatie\ElasticsearchQueryBuilder\Queries\RangeQuery;
use Spatie\ElasticsearchQueryBuilder\Builder;

$client = Elasticsearch\ClientBuilder::create()->build();

$builder = new Builder($client);

$builder->addQuery(RangeQuery::create('age')->gte(18));

$results = $builder->search(); // raw response from ElasticSearch

Adding queries

The $builder->addQuery() method can be used to add any of the available Query types to the builder. The available query types can be found below or in the src/Queries directory of this repo. Every Query has a static create() method to pass its most important parameters.

The following query types are available:

ExistsQuery

https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-exists-query.html

\Spatie\ElasticsearchQueryBuilder\Queries\ExistsQuery::create('terms_and_conditions');

MatchQuery

https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-match-query.html

\Spatie\ElasticsearchQueryBuilder\Queries\MatchQuery::create('name', 'john doe', fuzziness: 2);

MultiMatchQuery

https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-multi-match-query.html

\Spatie\ElasticsearchQueryBuilder\Queries\MultiMatchQuery::create('john', ['email', 'email'], fuzziness: 'auto');

NestedQuery

https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-nested-query.html

\Spatie\ElasticsearchQueryBuilder\Queries\NestedQuery::create(
    'user', 
    new \Spatie\ElasticsearchQueryBuilder\Queries\MatchQuery('name', 'john')
);

RangeQuery

https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-range-query.html

\Spatie\ElasticsearchQueryBuilder\Queries\RangeQuery::create('age')
    ->gte(18)
    ->lte(1337);

TermQuery

https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-term-query.html

\Spatie\ElasticsearchQueryBuilder\Queries\TermQuery::create('user.id', 'flx');

WildcardQuery

[https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-wildcard-query.html](https://www. elastic.co/guide/en/elasticsearch/reference/current/query-dsl-wildcard-query.html)

\Spatie\ElasticsearchQueryBuilder\Queries\WildcardQuery::create('user.id', '*doe');

BoolQuery

https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-bool-query.html

\Spatie\ElasticsearchQueryBuilder\Queries\BoolQuery::create()
    ->add($matchQuery, 'must_not')
    ->add($existsQuery, 'must_not');

Chaining multiple queries

Multiple addQuery() calls can be chained on one Builder. Under the hood they'll be added to a BoolQuery with occurrence type must. By passing a second argument to the addQuery() method you can select a different occurrence type:

$builder
    ->addQuery(
        MatchQuery::create('name', 'billie'), 
        'must_not' // available types: must, must_not, should, filter
    )
    ->addQuery(
        MatchQuery::create('team', 'eillish')
    );

More information on the boolean query and its occurrence types can be found in the ElasticSearch docs.

Adding aggregations

The $builder->addAggregation() method can be used to add any of the available Aggregations to the builder. The available aggregation types can be found below or in the src/Aggregations directory of this repo. Every Aggregation has a static create() method to pass its most important parameters and sometimes some extra methods.

use Spatie\ElasticsearchQueryBuilder\Aggregations\TermsAggregation;
use Spatie\ElasticsearchQueryBuilder\Builder;

$results = (new Builder(Elasticsearch\ClientBuilder::create()->build()))
    ->addAggregation(TermsAggregation::create('genres', 'genre'))
    ->search();

$genres = $results['aggregations']['genres']['buckets'];

The following query types are available:

CardinalityAggregation

\Spatie\ElasticsearchQueryBuilder\Aggregations\CardinalityAggregation::create('team_agg', 'team_name');

FilterAggregation

https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations-bucket-filter-aggregation.html

\Spatie\ElasticsearchQueryBuilder\Aggregations\FilterAggregation::create(
    'tshirts',
    \Spatie\ElasticsearchQueryBuilder\Queries\TermQuery::create('type', 'tshirt'),
    \Spatie\ElasticsearchQueryBuilder\Aggregations\MaxAggregation::create('max_price', 'price')
);

MaxAggregation

https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations-metrics-max-aggregation.html

\Spatie\ElasticsearchQueryBuilder\Aggregations\MaxAggregation::create('max_price', 'price');

MinAggregation

https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations-metrics-min-aggregation.html

\Spatie\ElasticsearchQueryBuilder\Aggregations\MinAggregation::create('min_price', 'price');

NestedAggregation

https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations-bucket-nested-aggregation.html

\Spatie\ElasticsearchQueryBuilder\Aggregations\NestedAggregation::create(
    'resellers',
    'resellers',
    \Spatie\ElasticsearchQueryBuilder\Aggregations\MinAggregation::create('min_price', 'resellers.price'),
    \Spatie\ElasticsearchQueryBuilder\Aggregations\MaxAggregation::create('max_price', 'resellers.price'),
);

ReverseNestedAggregation

https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations-bucket-reverse-nested-aggregation.html

\Spatie\ElasticsearchQueryBuilder\Aggregations\ReverseNestedAggregation::create(
    'name',
    ...$aggregations
);

TermsAggregation

https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations-bucket-terms-aggregation.html

\Spatie\ElasticsearchQueryBuilder\Aggregations\TermsAggregation::create(
    'genres',
    'genre'
)
    ->size(10)
    ->order(['_count' => 'asc'])
    ->missing('N/A')
    ->aggregation(/* $subAggregation */);

TopHitsAggregation

https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations-metrics-top-hits-aggregation.html

\Spatie\ElasticsearchQueryBuilder\Aggregations\TopHitsAggregation::create(
    'top_sales_hits',
    size: 10,
);

Adding sorts

The Builder (and some aggregations) has a addSort() method that takes a Sort instance to sort the results. You can read more about how sorting works in the ElasticSearch docs.

use Spatie\ElasticsearchQueryBuilder\Sorts\Sort;

$builder
    ->addSort(Sort::create('age', Sort::DESC))
    ->addSort(
        Sort::create('score', Sort::ASC)
            ->unmappedType('long')
            ->missing(0)
    );

Retrieve specific fields

The fields() method can be used to request specific fields from the resulting documents without returning the entire _source entry. You can read more about the specifics of the fields parameter in the ElasticSearch docs.

$builder->fields('user.id', 'http.*.status');

Pagination

Finally the Builder also features a size() and from() method for the corresponding ElasticSearch search parameters. These can be used to build a paginated search. Take a look the following example to get a rough idea:

use Spatie\ElasticsearchQueryBuilder\Builder;

$pageSize = 100;
$pageNumber = $_GET['page'] ?? 1;

$pageResults = (new Builder(\Elasticsearch\ClientBuilder::create()))
    ->size($pageSize)
    ->from(($pageNumber - 1) * $pageSize)
    ->search();

Testing

composer test

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

License

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

You might also like...
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

Maps Laravel Eloquent models to Elasticsearch types

Elasticquent Elasticsearch for Eloquent Laravel Models Elasticquent makes working with Elasticsearch and Eloquent models easier by mapping them to Ela

Elasticsearch driver for Laravel Scout
Elasticsearch driver for Laravel Scout

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

Elasticsearch migrations for Laravel
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

Laravel 8.* Elasticsearch Eloquent
Laravel 8.* Elasticsearch Eloquent

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

Sphinx Search library provides SphinxQL indexing and searching features

Sphinx Search Sphinx Search library provides SphinxQL indexing and searching features. Introduction Installation Configuration (simple) Usage Search I

Unmaintained: Laravel Searchy makes user driven searching easy with fuzzy search, basic string matching and more to come!

!! UNMAINTAINED !! This package is no longer maintained Please see Issue #117 Here are some links to alternatives that you may be able to use (I do no

This is an open source demo of smart search feature implemented with Laravel and Selectize plugin
This is an open source demo of smart search feature implemented with Laravel and Selectize plugin

Laravel smart search implementation See demo at: http://demos.maxoffsky.com/shop-search/ Tutorial at: http://maxoffsky.com/code-blog/laravel-shop-tuto

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

Comments
  • feat(api): add terms query

    feat(api): add terms query

    Thank you for this excellent package. Exactly what I needed while battling raw arrays with the native elasticsearch php client.

    I missed the terms query, I have this logic running locally using a custom implementation. Maybe you're interested in it being included in the package. Please mention me if you need more information as my GitHub notifications pile up too quickly to use the normal way of using them.

    Adds support for the v7 terms query in dsl, see https://www.elastic.co/guide/en/elasticsearch/reference/7.15/query-dsl-terms-query.html

    opened by luceos 2
  • Fix `Builder::search()` return data type

    Fix `Builder::search()` return data type

    This PR fixes issue #22 introduced by PR #19.

    The return data type of the search method was changed from array on v7.x to Elasticsearch|Promise in v8.x.

    opened by imdhemy 1
Releases(2.0.1)
Owner
Spatie
We create products and courses for the developer community
Spatie
SphinxQL Query Builder generates SphinxQL, a SQL dialect, which is used to query the Sphinx search engine. (Composer Package)

Query Builder for SphinxQL About This is a SphinxQL Query Builder used to work with SphinxQL, a SQL dialect used with the Sphinx search engine and it'

FoolCode 318 Oct 21, 2022
Laravel search is package you can use it to make search query easy.

Laravel Search Installation First, install the package through Composer. composer require theamasoud/laravel-search or add this in your project's comp

Abdulrahman Masoud 6 Nov 2, 2022
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
Query Builder for Elasticsearch

Query Builder for Elasticsearch

wangzhiqiang 5 Mar 2, 2022
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
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
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
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 Dec 31, 2022
Elastica is a PHP client for elasticsearch

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

Nicolas Ruflin 2.2k Dec 23, 2022