HowToSearch.md

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.

$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, filters and aggregations objects.

Form a Query

Lets take a simple query example with MatchAllQuery.

$matchAllQuery = new MatchAllQuery();

To add query to the Search simply call addQuery function.

$search->addQuery($matchAllQuery);

At the end it will form this query:

{
  "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.

$matchAllFilter = new MatchAllFilter();

And simply add to the Search:

$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:

{
  "query": {
      "filtered": {
          "filter": {
              "match_all": {}
          }
      }
  }
}

Multiple 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:

$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:

{
  "query": {
    "bool": {
        "must": [
            {
                "term": { "tag": "wow" }
            },
            {
                "term": { "tag": "elasticsearch" }
            }
        ]
        "should": [
            {
                "term": { "tag": "dsl" }
            }
        ]
    }
  }
}

More info how to form bool queries find in Bool Query chapter.

The same way it works with a Filter. Take a look at this example:

$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:

{
  "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.

//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.