Download the PHP package shisun/laravel-elasticsearch-query-builder without Composer

Laravel Elasticsearch Query Builder

Query Elasticsearch by using Eloquent

This Laravel package is developed to simplify the process of querying Elasticsearch. Eloquent is a powerful tool to access and manipulate data in RDB. However, it is not designed to query no-sql DB like Elasticsearch. This package is made to fill the gap between the most popular ORM in Laravel and Elasticsearch.

The package only relies on the official PHP Elasticsearch package(v6).

PHP version

The package is developed and tested under PHP v7.1. It should be also compatible with v7.*. Please email me if you find any compatibility issue.

Elasticsearch version

The package is developed and tested under Elasticsearch v6.*. It should be also compatible with v5.*. Please email me if you find any compatibility issue. It is confirmed that the package does not support versions before v5.*.

Installation

• Add the following to your composer.json file:

• Run composer update in terminal

• Add the package to your app.php file in the config folder:

• If your Elasticsearch is not accessible at localhost:9200 then you have to publish the config file by running:

• (Optional) Change the ES_HOSTS in config/laravel-elasticsearch-query-builder.php to the address of your Elasticsearch

• Use with Eloquent Model

  • Add EsTrait to your model

  • Enable validation(Optional)

  • Set model-level Index and Type name. Add follow two functions to your model.(Optional)
• Use without Eloquent

Usage

Table of Contents

• Init & Configs
  • __construct
  • setOptions
  • getters
    • getIndexName
    • getTypeName
    • getValidation
    • getMappingProperties
  • setters
    • setIndexName
    • setTypeName
    • setValidation
    • setMappingProperties
• Query Clauses
  • where
  • orWhere
  • whereMatch
  • whereDoesntMatch
  • orWhereMatch
  • whereHas
  • whereHasNull
  • orWhereHas
  • whereIn
  • orWhereIn
  • whereNotIn
  • orWhereNotIn
  • whereBetween
  • orWhereBetween
• Order
  • orderBy
• Pagination
  • page
  • limit
  • offset
• Aggregation
  • aggregate
  • aggregateAll
  • aggregateOn
  • groupBy
  • min
  • max
  • avg
  • sum
• Other Filters
  • minScore
  • with
  • withOut
• Execute Query
  • get
  • scroll
  • count
  • first
  • find
  • delete
• Results Manipulation
  • toArray
  • toEloquent
  • rawResults
  • aggregations
  • getAggregationBuckets
  • paginate
• Direct Query Output
  • getQuery
  • getBody
  • getAggs

Init & Configs

__construct

• You do not need to use this function if you use Eloquent

• Parameters

  Name	Required	Type	Default	Description
  model		Eloquent,null | null

• Output

  self

• Examples
  1. basic example

setOptions

• You do not need to use this function if you use Eloquent

• Parameters

  Name	Required	Type	Default	Description
  options	Y	array

• Output

  self

• Examples
  1. Basic

Query Clauses

where

• Parameters

  Name	Required	Type	Default	Description
  column	Y	callable,string
  operator		string | null | =,>,<,<=,>=,!=,*
  value		mixed | null
  or		bool | false
  boost		bool,int | false	The weight of the column

• Output

  self

• Examples

  1. = can be ignored

  2. * is the wildcard operator

  3. column can be a function

whereNull

• Parameters

  Name	Required	Type	Default	Description
  column	Y	string		Column or relation

• Output

  self

• Examples

  1. Find all users with no name

  2. Find all users who don't have address

whereNotNull

• Parameters

  Name	Required	Type	Default	Description
  column	Y	string		Column or relation

• Output

  self

• Examples

  1. Find all users with a name

  2. Find all users who have at least one address

orWhere

• Parameters

  Name	Required	Type	Default	Description
  column	Y	callable,string
  operator		string | null | =,>,<,<=,>=,like,!=,*
  value		mixed | null
  boost		bool,int | false	The weight of the column

• Output

  self

• Examples

  1. = can be ignored

  2. column can be a function

whereMatch

• It is used to make fuzzy text search. This function should only be applied on text fields.

• Parameters

  Name	Required	Type	Default	Description
  column	Y	string
  value		mixed | null
  options		array | [] | matchquery options. Check elasticsearch Docs for references

• Output

  self

• Examples

  1. without options

  2. with options

whereDoesntMatch

• Parameters

  Name	Required	Type	Default	Description
  column	Y	string
  value		mixed | null
  options		array | [] | matchquery options. Check elasticsearch Docs for references

• Output

  self

• Examples

  1. without options

  2. with options

orWhereMatch

• Parameters

  Name	Required	Type	Default	Description
  column	Y	string
  value		mixed | null
  options		array | [] | matchquery options. Check elasticsearch Docs for references

• Output

  self

• Examples

  1. without options

  2. with options

whereHas

• Parameters

  Name	Required	Type	Default	Description
  relation	Y	string, callable		Must be capitalized
  closure		callable, null | null | from and to cannot be both null
  or		boolean | null	for internal use. See orWhereHas
  boost		boolean,integer | false	Used to adjust the weight of the condition

• Output

  self

• Examples

  1. basic example

  2. first parameter can be a function

orWhereHas

• Parameters

  Name	Required	Type	Default	Description
  relation	Y	string, callable		Must be capitalized
  closure		callable, null | null | from and to cannot be both null
  boost		boolean,integer | false	Used to adjust the weight of the condition

• Output

  self

• Examples
  1. basic example

whereHasNull

• Parameters

  Name	Required	Type	Default	Description
  relation	Y	string		Must be capitalized
  closure		null, callable |null

• Output

  self

• Examples

  1. basic example

  2. with sub query

orWhereHasNull

• Parameters

  Name	Required	Type	Default	Description
  relation	Y	string		Must be capitalized
  closure		null, callable |null

• Output

  self

• Examples
  1. basic example

whereIn

• Parameters

  Name	Required	Type	Default	Description
  column	Y	string
  values	Y	array

• Output

  self

• Examples
  1. basic example

orWhereIn

• Parameters

  Name	Required	Type	Default	Description
  column	Y	string
  values	Y	array

• Output

  self

• Examples
  1. basic example

whereNotIn

• Parameters

  Name	Required	Type	Default	Description
  column	Y	string
  values	Y	array

• Output

  self

• Examples
  1. basic example

orWhereNotIn

• Parameters

  Name	Required	Type	Default	Description
  column	Y	string
  values	Y	array

• Output

  self

• Examples
  1. basic example

whereBetween

• Parameters

  Name	Required	Type	Default	Description
  column	Y	string
  from		numeric | null | from and to cannot be both null
  to		numeric | null

• Output

  self

• Examples
  1. basic example

orWhereBetween

• Parameters

  Name	Required	Type	Default	Description
  column	Y	string
  from		numeric | null | from and to cannot be both null
  to		numeric | null

• Output

  self

• Examples
  1. basic example

Order

orderBy

• Parameters

  Name	Required	Type	Default	Description
  column	Y	string
  order		numeric | asc | either asc or desc
  script		array,boolean | false

• Output

  self

• Examples

  1. basic example

  2. script

Pagination

page

• Parameters

  Name	Required	Type	Default	Description
  page	Y	integer
  per_page	Y	integer

• Output

  self

• Examples
  1. basic example

limit

• Parameters

  Name	Required	Type	Default	Description
  limit	Y	integer

• Output

  self

• Examples
  1. basic example

offset

• Parameters

  Name	Required	Type	Default	Description
  limit	Y	integer

• Output

  self

• Examples
  1. basic example

Aggregations

aggregate

• Parameters

  Name	Required	Type	Default	Description
  name	Y	string
  agg	Y	callable

• Output

  self

• Examples

  1. basic example

  2. with filters

aggregateAll

• Parameters

  Name	Required	Type	Default	Description
  name	Y	string
  agg	Y	callable

• Output

  self

• Examples
  1. with filters

aggregateOn

• Parameters

  Name	Required	Type	Default	Description
  relation	Y	string		Must be capitalized
  agg	Y	callable
  custom_name		string | null

• Output

  self

• Examples
  1. basic example

groupBy

• Parameters

  Name	Required	Type	Default	Description
  column	Y	string
  size		integer | 10	The limit of number of groups. Default to 10 groups

• Output

  self

• Check aggregate clause for examples

min

• Parameters

  Name	Required	Type	Default	Description
  column	Y	string
  custom_name		string | null

• Output

  self

• Examples
  1. basic example

max

• Parameters

  Name	Required	Type	Default	Description
  column	Y	string
  custom_name		string | null
  missing_value		numeric | null	This value will be used to replace null values

• Output

  self

• Examples
  1. basic example

avg

• Parameters

  Name	Required	Type	Default	Description
  column	Y	string
  custom_name		string | null
  missing_value		numeric | null	This value will be used to replace null values

• Output

  self

• Examples
  1. basic example

sum

• Parameters

  Name	Required	Type	Default	Description
  column		string | Empty
  custom_name		string | null
  missing_value		numeric | null	This value will be used to replace null values
  script		array | null	Check official Doc as reference

• Output

  self

• Examples
  1. basic example

Other Filters

minScore

• Parameters

  Name	Required	Type	Default	Description
  score	Y	numeric		Only get items with _score greater than this value

• Output

  self

• Examples
  1. basic example

with

• Parameters

  Name	Required	Type	Default	Description
  relations	Y	list		include these relations in results. All relations are included by default.

• Output

  self

• Examples
  1. basic example

withOut

• Parameters

  Name	Required	Type	Default	Description
  relations	Y	list		Exclude these relations in results. All relations are included by default.

• Output

  self

• Examples
  1. basic example

Execute Query

get

scroll

• Parameters

  Name	Required	Type	Default	Description
  scroll_alive		string |5m	This specifies the life span of the scroll session.
  scroll_size		integer |500	This specifies the number of records retrieved from Elasticsearch per batch.
  json		boolean |false	If encode the results from each batch in JSON format. Fetching data and put the data in PHP array can consume a lot of memory. This option can greatly reduce the memory usage.

• Output

  array

• Examples
  1. basic example

count

• Output

  integer

• Examples
  1. basic example

first

• Parameters

  Name	Required	Type	Default	Description
  eloquent		boolean |false	get result in array or Eloquent. Returns array if not provided.

• Output

  array|Eloquent

• Examples
  1. basic example

find

• Parameters

  Name	Required	Type	Default	Description
  key	Y	mixed

• Output

  array

• Examples
  1. basic example

delete

• Delete a record from elasticsearch. Returns false if the record does not exist.

• Parameters

  Name	Required	Type	Default	Description
  key	Y	mixed

• Output

  array

• Examples
  1. basic example

Results Manipulation

toArray

• Output

  array

toEloquent

Warning: This function does not work if you don't use the package with Eloquent.

• Output

  Eloquent

rawResults

Get raw results from Elasticsearch

• Output

  array

aggregations

Get aggregation results

• Output

  array

getAggregationBuckets

This is a helper function to get buckets from the aggregation specified by agg_name

• Parameters

  Name	Required	Type	Default	Description
  agg_name	Y	mixed
  agg		mixed | null

• Output

  array

• Examples
  1. basic example

paginate

Returns pagination information

• Parameters

  Name	Required	Type	Default	Description
  per_page		mixed		The value can be ignored if per_page is set by limit() or page(). Otherwise, it's required.

• Output

  array

• Example
  1. basic

Direct Query Output

getQuery

Returns the query part of the body

getBody

Returns the body

getAggs

Returns the aggregation part of the body

Release History

Meta

Shisun(Leo) Xia - [email protected]

Distributed under the GNU V3 license. See LICENSE for more information.

https://github.com/ShisunXia/Laravel-Elasticsearch-Query-Builder