diff --git a/docs/HowTo/HowToSearch.md b/docs/HowTo/HowToSearch.md new file mode 100644 index 0000000000000000000000000000000000000000..f3ab99e8ae587f9287dd6f324199b695780aa835 --- /dev/null +++ b/docs/HowTo/HowToSearch.md @@ -0,0 +1,180 @@ +# How to search with Elasticsearch DSL + +In this chapter we will take a look how to perform a search via objective way with Elasticsearch DSL. Well, the good news is that is very simple. That's why we created this library ;). + +To start a search you have to create a `Search` object. + +```php +$search = new Search(); +``` + +> We won't include namespaces in any examples. Don't worry all class's names are unique, so any IDE editor should autocomplete and include it for you ;). + +So, when we have a `Search` object we can start add something to it. Usually you will add `Query`, `Filter` and `Aggregation`. + +> More info how create [queries](../Query/index.md), [filters](../Filter/index.md) and [aggregations](../Aggregation/index.md) objects. + +### Form a Query + +Lets take a simple query example with `MatchAllQuery`. + +```php +$matchAllQuery = new MatchAllQuery(); +``` + +To add query to the `Search` simply call `addQuery` function. + +```php +$search->addQuery($matchAllQuery); +``` + +At the end it will form this query: + +```JSON +{ + "query": { + "match_all": {} + } +} +``` + + +> There is no limits to add queries or filters or anything. + +### Form a Filter + +To add a filter is the same way like a query. First, lets create some `Filter` object. + +```php +$matchAllFilter = new MatchAllFilter(); +``` + +And simply add to the `Search`: + +```php +$search->addFilter($matchAllFilter); +``` + +Unlike `Query`, when we add a `Filter` with our DSL library it will add a query and all necessary stuff for you. So when we add one filter we will get this query: + +```JSON +{ + "query": { + "filtered": { + "filter": { + "match_all": {} + } + } + } +} +``` + +### Multpile queries and filters + +As you know there is possible to use multiple filters and queries in elasticsearch. No problem, if you have several filters just add it to the search. `ElasticsearchDSL` will form a `Bool` query or filter for you when you add more than one. + +Lets take an example with `Query`: + +```php +$search = new Search(); +$termQueryForTag1 = new TermQuery("tag", "wow"); +$termQueryForTag2 = new TermQuery("tag", "elasticsearch"); +$termQueryForTag3 = new TermQuery("tag", "dsl"); + +$search->addQuery($termQueryForTag1); +$search->addQuery($termQueryForTag2); +$search->addQuery($termQueryForTag3, BoolQuery::SHOULD); +``` +The query will look like: + +```JSON +{ + "query": { + "bool": { + "must": [ + { + "term": { "tag": "wow" } + }, + { + "term": { "tag": "elasticsearch" } + } + ] + "should": [ + { + "term": { "tag": "dsl" } + } + ] + } + } +} +``` +> More info how to form bool queries find in [Bool Query](../Query/Bool.md) chapter. + +The same way it works with a `Filter`. Take a look at this example: + +```php +$search = new Search(); +$termFilter = new TermFilter('name', 'ongr'); +$missingFilter = new MissingFilter('disabled'); +$existsFilter = new ExistsFilter('tag'); +$search->addFilter($termFilter); +$search->addFilter($missingFilter); +$search->addFilter($existsFilter, BoolFilter::MUST_NOT); +``` + +Elasticsearch DSL will form this query: + +```JSON +{ + "query": { + "filtered": { + "filter": { + "bool": { + "must": [ + { + "term": { + "name": "ongr" + } + }, + { + "missing": { + "field": "disabled" + } + } + ], + "must_not": [ + { + "exists": { + "field": "tag" + } + } + ] + } + } + } + } +} +``` + +### Modify queries + + + + +### Sent request to the elasticsearch +And finaly we can pass it to `elasticsearch-php` client. To generate an array for the client we call `toArray()` function. + +```php +//from elasticsearch/elasticsearch package +$client = new Elasticsearch\Client(); + +$searchParams = [ + 'index' => 'people', + 'type' => 'person', + 'body' => $search->toArray(), +]; + +$docs = $client->search($searchParams); +``` + +> This example is for elasticsearch/elasticsearch ~1.0 version.