Download the PHP package alirzaj/laravel-elasticsearch-builder without Composer

a query builder for elasticsearch database

This package can build queries for elasticsearch database and provides an easy way to add Eloquent models to an elasticsearch index.

It is not trying to provide Eloquent-like api to work with elasticsearch. instead, it will give you methods that are much like writing a query in elasticsearch but in a more object-oriented and nicer way.

this package contains the queries that I needed on my projects. so if you feel the need of a method or feature please open an issue, and I will try to implement it as soon as possible.

• a query builder for elasticsearch database
• Installation
  • Usage
• define indices
• create indices
• delete indices
• configuration
• making models searchable
• indexing documents without eloquent models and using searchable trait
• bulk indexing documents
• update documents having a condition
• add an item to a nested field
• add an item to an array field
• update a document's nested field items having a condition
• update all documents' nested field items having a condition
• remove item from a nested field in a specific document
• remove item from a nested field by conditions
• delete a document
• delete all documents that meet some conditions
• querying indices
• include an index in query:
• boost the score of some indices
• determine search type
• find a document by its id
• match
• match_all
• multi_match
• nested
• exists
• bool
• term
• terms
• range
• dis_max
• aggregations (aggs)
• working with array fields
• getting results
• determine a size limit for results
• determine from option for getting results (pagination)
• select specific fields
• build queries based on conditions
• debugging
• using the low-level elasticsearch client
• logging
• Testing Helpers
  • refreshing indices state
  • assertions
• Credits
• License

Installation

to install this package, require it via composer:

composer require alirzaj/laravel-elasticsearch-builder

Usage

define indices

first you need to define index classes. an index class must extend the Alirzaj\ElasticsearchBuilder\Index class. here is an example:

if you don't define $name index name will equal to class name.

$propertyTypes array is a map of property names and their data type. key is name of field and value is data type.

$fields is other definitions of a field. for example, you want to save another version of text field to match hashtags (with another analyzer).

$analyzers is custom defined analyzers for index.

$tokenizers contains config for tokenizers. For understanding $staticIndexSettings and $dynamicIndexSettings you can check here: https://www.elastic.co/guide/en/elasticsearch/reference/current/index-modules.html

the only property that you must define is $properties.

If you don't know what other properties do, please refer to doc comment of each property to read more about it.

create indices

to create the indices defined in previous step, run php artisan elastic:create-indices

delete indices

to delete all indices defined via this package, run php artisan elastic:delete-indices

configuration

publish the package's config file using php artisan vendor:publish --provider="Alirzaj\\ElasticsearchBuilder\\ElasticsearchBuilderServiceProvider" command. all options have description in file.

making models searchable

you can use Alirzaj\ElasticsearchBuilder\Searchable trait in Eloquent models. this trait will automatically add & update documents in elasticsearch on the corresponding index. you can override toIndex method on your models to control the attributes that will save on elasticsearch. default behaviour is array representation of the model (toArray).

indexing documents without eloquent models and using searchable trait

in some situations you may need to index or update a document without using searchable trait on Eloquent models. this package offers two jobs for indexing and updating.

bulk indexing documents

update documents having a condition

if you want to update a large field of documents having some condition, be sure to use 4th argument of UpdateDocumentsByCondition job.

add an item to a nested field

add an item to an array field

update a document's nested field items having a condition

update all documents' nested field items having a condition

remove item from a nested field in a specific document

remove item from a nested field by conditions

delete a document

delete all documents that meet some conditions

querying indices

if you have searchable models you can begin to query the corresponding index like this:

you can also start querying indices by instantiating the Query class:

include an index in query:

you can add an index to the indices that are being queried:

boost the score of some indices

determine search type

for more information visit https://www.elastic.co/guide/en/elasticsearch/reference/current/search-search.html

find a document by its id

match

you can use named arguments to only pass the options you need.

match_all

multi_match

nested

exists

bool

you can pass closures to the boolean method and type hint the type of query you want:

term

terms

range

dis_max

aggregations (aggs)

you can build aggregation queries like this: (note that currently, when you use aggregations, you'll get raw elasticsearch results)

working with array fields

this package provides two jobs for updating/removing an item from an array field:

getting results

after writing a query, you can call get() to get the results as a collection.

you can also hydrate the results as eloquent models:

note that the result collection's keys are _id of your documents.

determine a size limit for results

determine from option for getting results (pagination)

for more information visit https://www.elastic.co/guide/en/elasticsearch/reference/current/paginate-search-results.html

select specific fields

only() method will add "_source" to your query.

build queries based on conditions

the query builder uses Laravel's Conditionable trait under the hood which means you can do sth like this:

debugging

you can dump or die the query:

using the low-level elasticsearch client

this package will bind the Elastic\Elasticsearch\Client class to the service container as a singleton, so you can resolve it out of the container whenever you need to use it directly.

logging

when the environment is testing or local, this package will log executed queries in storage/logs/elasticsearch.log file.

Testing Helpers

refreshing indices state

this package provides a RefreshElasticsearchDatabase trait that you can use to clean up the elasticsearch indices after each test.

first, you have to use this trait in your test case.

then you should call two methods. one in your setUp() method and one in tearDown()

assertions

this package provides an InteractsWithElasticsearch trait that you can use in your test cases in order to make assertion on data in elasticsearch indices.

you can assert if a certain document exists in an elasticsearch index:

or make sure that a document is not indexed in elasticsearch:

Credits

• AL!R3Z4
• All Contributors

License

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