Class QueryBuilder

Namespace: Cake\ElasticSearch

Method Summary

_parseQuery() protected

Parses a field name containing an operator into a Filter object.
and() public

Combines all the passed arguments in a single bool query using the "must" clause.
and_() public deprecated

Combines all the passed arguments in a single bool query using the "must" clause.
between() public

Returns a Range query object setup to query documents having the field between a from and a to value
bool() public

Returns a bool query that can be chained with the addMust(), addShould(), addFilter and addMustNot() methods.
exists() public

Returns an Exists query object setup to query documents having a property present or not set to null.
geoBoundingBox() public

Returns a GeoBoundingBox query object setup to query documents having a property bound by two coordinates.
geoDistance() public

Returns an GeoDistance query object setup to query documents having a property in the radius distance of a coordinate.
geoPolygon() public

Returns an GeoPolygon query object setup to query documents having a property enclosed in the polygon induced by the passed geo points.
geoShape() public

Returns an GeoShapeProvided query object setup to query documents having a property enclosed in the specified geometrical shape type.
geoShapeIndex() public

Returns an GeoShapePreIndex query object setup to query documents having a property enclosed in the specified geometrical shape type.
gt() public

Returns a Range query object setup to query documents having the field greater than the provided value.
gte() public

Returns a Range query object setup to query documents having the field greater than or equal the provided value.
hasChild() public

Accepts a query and the child type to run against, and results in parent documents that have child docs matching the query.
hasParent() public

Query by child documents having parent documents matching the query
ids() public

Query documents that only have the provided ids.
limit() public

Limits the number of documents (per shard) to execute on.
lt() public

Returns a Range query object setup to query documents having the field smaller than the provided value.
lte() public

Returns a Range query object setup to query documents having the field smaller or equals than the provided value.
match() public

Returns a Match query object that query documents that have fields containing a match.
matchAll() public

A query that returns all documents.
nested() public

Returns a Nested query object setup to query sub documents by a path.
not() public

Returns a BoolQuery query with must_not field that is typically ussed to negate another query expression
or() public

Combines all the passed arguments in a single BoolQuery query using should clause.
or_() public deprecated

Combines all the passed arguments in a single BoolQuery query using should clause.
parse() public

Converts an array into a single array of query objects
prefix() public

Returns a Prefix query to query documents that have fields containing terms with a specified prefix
range() public

Returns a Range query object setup to query documents having the field greater than the provided values.
regexp() public

Returns a Regexp query to query documents based on a regular expression.
script() public

Returns a Script query object that allows to query based on the return value of a script.
simpleQueryString() public

Returns a SimpleQueryString object that allows to query based on a search string.
term() public

Returns a Term query object that query documents that have fields containing a term.
terms() public

Returns a Terms query object that query documents that have fields containing some terms.

Method Detail

_parseQuery() ¶ protected

_parseQuery(string $field, mixed $value): Elastica\Query\AbstractQuery

Parses a field name containing an operator into a Filter object.

Parameters

string $field: The filed name containing the operator
mixed $value: The value to pass to the query

Returns

Elastica\Query\AbstractQuery

and() ¶ public

and(Elastica\Query\AbstractQuery ...$queries): Elastica\Query\BoolQuery

Combines all the passed arguments in a single bool query using the "must" clause.

Example:

{{{ $bool = $builder->and( $builder->terms('tags', ['cool', 'stuff']), $builder->exists('comments') ); }}}

Parameters

Elastica\Query\AbstractQuery ...$queries: Queries to compare.

Returns

Elastica\Query\BoolQuery

and_() ¶ public

and_(Elastica\Query\AbstractQuery ...$queries): Elastica\Query\BoolQuery

Combines all the passed arguments in a single bool query using the "must" clause.

Example:

{{{ $bool = $builder->and( $builder->terms('tags', ['cool', 'stuff']), $builder->exists('comments') ); }}}

Parameters

Elastica\Query\AbstractQuery ...$queries: Queries to compare.

Returns

Elastica\Query\BoolQuery

between() ¶ public

between(string $field, mixed $from, mixed $to): Elastica\Query\Range

Returns a Range query object setup to query documents having the field between a from and a to value

Parameters

string $field: The field to query by.
mixed $from: The lower bound value.
mixed $to: The upper bound value.

Returns

Elastica\Query\Range

bool() ¶ public

bool(): Elastica\Query\BoolQuery

Returns a bool query that can be chained with the addMust(), addShould(), addFilter and addMustNot() methods.

Returns

Elastica\Query\BoolQuery

exists() ¶ public

exists(string $field): Elastica\Query\Exists

Returns an Exists query object setup to query documents having a property present or not set to null.

Parameters

string $field: The field to check for existance.

Returns

Elastica\Query\Exists

geoBoundingBox() ¶ public

geoBoundingBox(string $field, array|string $topLeft, array|string $bottomRight): Elastica\Query\GeoBoundingBox

Returns a GeoBoundingBox query object setup to query documents having a property bound by two coordinates.

Example:

{{{ $query = $builder->geoBoundingBox('location', [40.73, -74.1], [40.01, -71.12]);

$query = $builder->geoBoundingBox( 'location', ['lat => 40.73, 'lon' => -74.1], ['lat => 40.01, 'lon' => -71.12] );

$query = $builder->geoBoundingBox('location', 'dr5r9ydj2y73', 'drj7teegpus6'); }}}

Parameters

string $field: The field to compare.
array|string $topLeft: The top left coordinate.
array|string $bottomRight: The bottom right coordinate.

Returns

Elastica\Query\GeoBoundingBox

geoDistance() ¶ public

geoDistance(string $field, array|string $location, string $distance): Elastica\Query\GeoDistance

Returns an GeoDistance query object setup to query documents having a property in the radius distance of a coordinate.

Example:

{{{ $query = $builder->geoDistance('location', ['lat' => 40.73, 'lon' => -74.1], '10km');

$query = $builder->geoBoundingBox('location', 'dr5r9ydj2y73', '5km'); }}}

Parameters

string $field: The field to compare.
array|string $location: The coordinate from which to compare.
string $distance: The distance radius.

Returns

Elastica\Query\GeoDistance

geoPolygon() ¶ public

geoPolygon(string $field, array $geoPoints): Elastica\Query\GeoPolygon

Returns an GeoPolygon query object setup to query documents having a property enclosed in the polygon induced by the passed geo points.

Example:

{{{ $query= $builder->geoPolygon('location', [ ['lat' => 40, 'lon' => -70], ['lat' => 30, 'lon' => -80], ['lat' => 20, 'lon' => -90], ]);

$query = $builder->geoPolygon('location', [ 'drn5x1g8cu2y', ['lat' => 30, 'lon' => -80], '20, -90', ]); }}}

Parameters

string $field: The field to compare.
array $geoPoints: List of geo points that form the polygon

Returns

Elastica\Query\GeoPolygon

geoShape() ¶ public

geoShape(string $field, array $geoPoints, string $type = Elastica\Query\GeoShapeProvided::TYPE_ENVELOPE): Elastica\Query\GeoShapeProvided

Returns an GeoShapeProvided query object setup to query documents having a property enclosed in the specified geometrical shape type.

Example:

{{{ $query = $builder->geoShape('location', [[13.0, 53.0], [14.0, 52.0]], 'envelope');

$query = $builder->geoShape('location', [ [[-77.03653, 38.897676], [-77.009051, 38.889939]], 'linestring' ]); }}}

You can read about the supported shapes and how they are created here: https://www.elastic.co/guide/en/elasticsearch/reference/current/geo-shape.html

Parameters

string $field: The field to compare.
array $geoPoints: List of geo points that form the shape.
string $type optional: The shape type to use (envelope, linestring, polygon, multipolygon...)

Returns

Elastica\Query\GeoShapeProvided

geoShapeIndex() ¶ public

geoShapeIndex(string $field, string $id, string $index = 'shapes', string $path = 'shape'): Elastica\Query\GeoShapePreIndexed

Returns an GeoShapePreIndex query object setup to query documents having a property enclosed in the specified geometrical shape type.

Example:

{{{ $query = $builder->geoShapeIndex('location', 'DEU', 'countries', 'shapes', 'location'); }}}

Parameters

string $field: The field to compare.
string $id: The ID of the document containing the pre-indexed shape.
string $index optional: Name of the index where the pre-indexed shape is.
string $path optional: The field specified as path containing the pre-indexed shape.

Returns

Elastica\Query\GeoShapePreIndexed

gt() ¶ public

gt(string $field, mixed $value): Elastica\Query\Range

Returns a Range query object setup to query documents having the field greater than the provided value.

Parameters

string $field: The field to query by.
mixed $value: The value to compare with.

Returns

Elastica\Query\Range

gte() ¶ public

gte(string $field, mixed $value): Elastica\Query\Range

Returns a Range query object setup to query documents having the field greater than or equal the provided value.

Parameters

string $field: The field to query by.
mixed $value: The value to compare with.

Returns

Elastica\Query\Range

hasChild() ¶ public

hasChild(string|Elastica\Query|Elastica\Query\AbstractQuery $query, string $type): Elastica\Query\HasChild

Accepts a query and the child type to run against, and results in parent documents that have child docs matching the query.

Parameters

string|Elastica\Query|Elastica\Query\AbstractQuery $query: The query.
string $type: The child type to query against.

Returns

Elastica\Query\HasChild

hasParent() ¶ public

hasParent(string|Elastica\Query|Elastica\Query\AbstractQuery $query, string $type): Elastica\Query\HasParent

Query by child documents having parent documents matching the query

Parameters

string|Elastica\Query|Elastica\Query\AbstractQuery $query: The query.
string $type: The parent type to query against.

Returns

Elastica\Query\HasParent

ids() ¶ public

ids(array $ids = []): Elastica\Query\Ids

Query documents that only have the provided ids.

Parameters

array $ids optional: The list of ids to query by.

Returns

Elastica\Query\Ids

limit() ¶ public

limit(int $limit): Elastica\Query\Limit

Limits the number of documents (per shard) to execute on.

Parameters

int $limit: The maximum number of documents to query.

Returns

Elastica\Query\Limit

lt() ¶ public

lt(string $field, mixed $value): Elastica\Query\Range

Returns a Range query object setup to query documents having the field smaller than the provided value.

Parameters

string $field: The field to query by.
mixed $value: The value to compare with.

Returns

Elastica\Query\Range

lte() ¶ public

lte(string $field, mixed $value): Elastica\Query\Range

Returns a Range query object setup to query documents having the field smaller or equals than the provided value.

Parameters

string $field: The field to query by.
mixed $value: The value to compare with.

Returns

Elastica\Query\Range

match() ¶ public

match(string $field, string $value): Elastica\Query\MatchQuery

Returns a Match query object that query documents that have fields containing a match.

Example:

{{{ $builder->match('user.name', 'jose'); }}}

Parameters

string $field: The field to query by.
string $value: The match to find in field.

Returns

Elastica\Query\MatchQuery

matchAll() ¶ public

matchAll(): Elastica\Query\MatchAll

A query that returns all documents.

Returns

Elastica\Query\MatchAll

nested() ¶ public

nested(string $path, Elastica\Query\AbstractQuery $query): Elastica\Query\Nested

Returns a Nested query object setup to query sub documents by a path.

Example:

{{{ $builder->nested('comments', $builder->term('author', 'mark')); }}}

Parameters

string $path: A dot separated string denoting the path to the property to query.
Elastica\Query\AbstractQuery $query: The query conditions.

Returns

Elastica\Query\Nested

not() ¶ public

not(Elastica\Query\AbstractQuery|array $query): Elastica\Query\BoolQuery

Returns a BoolQuery query with must_not field that is typically ussed to negate another query expression

Parameters

Elastica\Query\AbstractQuery|array $query: The query to negate

Returns

Elastica\Query\BoolQuery

or() ¶ public

or(Elastica\Query\AbstractQuery ...$queries): Elastica\Query\BoolQuery

Combines all the passed arguments in a single BoolQuery query using should clause.

Example:

{{{ $bool = $builder->or( $builder->not($builder->exists('tags')), $builder->exists('comments') ); }}}

Parameters

Elastica\Query\AbstractQuery ...$queries: Queries to compare.

Returns

Elastica\Query\BoolQuery

or_() ¶ public

or_(Elastica\Query\AbstractQuery ...$queries): Elastica\Query\BoolQuery

Combines all the passed arguments in a single BoolQuery query using should clause.

Example:

{{{ $bool = $builder->or( $builder->not($builder->exists('tags')), $builder->exists('comments') ); }}}

Parameters

Elastica\Query\AbstractQuery ...$queries: Queries to compare.

Returns

Elastica\Query\BoolQuery

parse() ¶ public

parse(array|Elastica\Query\AbstractQuery $conditions): array

Converts an array into a single array of query objects

Parsing a single array:

{{{ $query = $builder->parse([ 'name' => 'mark', 'age <=' => 35 ]);

// Equivalent to: $query = [ $builder->term('name', 'mark'), $builder->lte('age', 35) ]; }}}

Creating "or" conditions:

{{{ $query = $builder->parse([ 'or' => [ 'name' => 'mark', 'age <=' => 35 ] ]);

// Equivalent to: $query = [$builder->or( $builder->term('name', 'mark'), $builder->lte('age', 35) )]; }}}

Negating conditions:

{{{ $query = $builder->parse([ 'not' => [ 'name' => 'mark', 'age <=' => 35 ] ]);

// Equivalent to: $query = [$builder->not( $builder->and( $builder->term('name', 'mark'), $builder->lte('age', 35) ) )]; }}}

Checking for field existance

{{{ $query = $builder->parse([ 'name is' => null, 'age is not' => null ]);

// Equivalent to: $query = [ $builder->not($builder->exists('name')), $builder->exists('age') ]; }}}

Checking if a value is in a list of terms

{{{ $query = $builder->parse([ 'name in' => ['jose', 'mark'] ]);

// Equivalent to: $query = [$builder->terms('name', ['jose', 'mark'])] }}}

The list of supported operators is:

<, >, <=, >=, in, not in, is, is not, !=

Parameters

array|Elastica\Query\AbstractQuery $conditions: The list of conditions to parse.

Returns

array

prefix() ¶ public

prefix(string $field, string $prefix, float $boost = 1.0): Elastica\Query\Prefix

Returns a Prefix query to query documents that have fields containing terms with a specified prefix

Parameters

string $field: The field to query by.
string $prefix: The prefix to check for.
float $boost optional: The optional boost

Returns

Elastica\Query\Prefix

range() ¶ public

range(string $field, array $args): Elastica\Query\Range

Returns a Range query object setup to query documents having the field greater than the provided values.

The $args array accepts the following keys:

gte: greater than or equal
gt: greater than
lte: less than or equal
lt: less than

Parameters

string $field: The field to query by.
array $args: An array describing the search range

Returns

Elastica\Query\Range

regexp() ¶ public

regexp(string $field, string $regexp, float $boost = 1.0): Elastica\Query\Regexp

Returns a Regexp query to query documents based on a regular expression.

Example:

{{{ $builder->regexp('name.first', 'ma.*'); }}}

Parameters

string $field: The field to query by.
string $regexp: The regular expression.
float $boost optional: Boost

Returns

Elastica\Query\Regexp

script() ¶ public

script(array|string|Elastica\Script\AbstractScript $script): Elastica\Query\Script

Returns a Script query object that allows to query based on the return value of a script.

Example:

{{{ $builder->script("doc['price'].value > 1"); }}}

Parameters

array|string|Elastica\Script\AbstractScript $script: The script.

Returns

Elastica\Query\Script

simpleQueryString() ¶ public

simpleQueryString(array|string $fields, string $string): Elastica\Query\SimpleQueryString

Returns a SimpleQueryString object that allows to query based on a search string.

Example:

{{{ $builder->simpleQueryString(['body'], '"fried eggs" +(eggplant | potato) -frittata'); }}}

Parameters

array|string $fields: The fields to search within
string $string: The pattern to find in the fields

Returns

Elastica\Query\SimpleQueryString

term() ¶ public

term(string $field, string $value): Elastica\Query\Term

Returns a Term query object that query documents that have fields containing a term.

Example:

{{{ $builder->term('user.name', 'jose'); }}}

Parameters

string $field: The field to query by.
string $value: The term to find in field.

Returns

Elastica\Query\Term

terms() ¶ public

terms(string $field, array $values): Elastica\Query\Terms

Returns a Terms query object that query documents that have fields containing some terms.

Example:

{{{ $builder->terms('user.name', ['jose', 'mark']); }}}

Parameters

string $field: The field to query by.
array $values: The list of terms to find in field.

Returns

Elastica\Query\Terms

Namespaces

Class QueryBuilder

Method Summary

_parseQuery() protected

and() public

and_() public deprecated

between() public

bool() public

exists() public

geoBoundingBox() public

geoDistance() public

geoPolygon() public

geoShape() public

geoShapeIndex() public

gt() public

gte() public

hasChild() public

hasParent() public

ids() public

limit() public

lt() public

lte() public

match() public

matchAll() public

nested() public

not() public

or() public

or_() public deprecated

parse() public

prefix() public

range() public

regexp() public

script() public

simpleQueryString() public

term() public

terms() public

Method Detail

_parseQuery() ¶ protected

Parameters

Returns

and() ¶ public

Example:

Parameters

Returns

and_() ¶ public

Example:

Parameters

Returns

between() ¶ public

Parameters

Returns

See Also

bool() ¶ public

Returns

See Also

exists() ¶ public

Parameters

Returns

See Also

geoBoundingBox() ¶ public

Example:

Parameters

Returns

See Also

geoDistance() ¶ public

Example:

Parameters

Returns

See Also

geoPolygon() ¶ public

Example:

Parameters

Returns

See Also

geoShape() ¶ public

Example:

Parameters

Returns

See Also

geoShapeIndex() ¶ public