crowdskout / es-search-builder

Simplified Elasticsearch search api and results parsing for queries and aggregations

es-search-builder

This package provides simplified api and results parsing for Elasticsearch search queries and aggregations. It builds upon the official elasticsearch-php library here: https://github.com/elastic/elasticsearch-php.

Quick example - Query api

    $query = Query::terms('intField', [1, 2, 3, 4, 5, 6])
    print_r($query);

The query api provides simpler, less verbose query generation.

    Array
    (
        [terms] => Array
            (
                [intField] => Array
                    (
                        [0] => 1
                        [1] => 2
                        [2] => 3
                        [3] => 4
                        [4] => 5
                        [5] => 6
                    )
    
            )
    
    )

Quick example - Agg builder api

    use Crowdskout\EsSearchBuilder\Agg as AggBuilder;
    
    $aggBuilder = new AggBuilder();
    
    $agg = $aggBuilder->nested('parentField', $aggBuilder->terms('parentField.subField'));
    $aggQuery = $agg->generateQuery();

    print_r($aggQuery);

Aggregations can be nested with each other

Array
(
    [parentField_nested_agg] => Array
        (
            [nested] => Array
                (
                    [path] => parentField
                )

            [aggs] => Array
                (
                    [parentField.subField_terms_agg] => Array
                        (
                            [terms] => Array
                                (
                                    [field] => parentField.subField
                                )

                        )

                )

        )

)

Use the agg object to parse the results from Elasticsearch as well

    // ... (code from above)
    
    // Aggregation results from Elasticsearch
    $elasticResult = [
         'parentField_nested_agg' => [
             'doc_count' => 5,
             'parentField.subField_terms_agg' => [
                 'buckets' => [
                     [
                         'key' => 'subFieldValue1',
                         'doc_count' => 3
                     ],
                     [
                         'key' => 'subFieldValue2',
                         'doc_count' => 2
                     ]
                 ]
             ]
         ]
     ];

    $parsedResult = $agg->generateResults($elasticResult);
    print_r($parsedResult);

    Array
    (
        [Total] => 5
        [options] => Array
            (
                [subFieldValue1] => 3
                [subFieldValue2] => 2
            )
    
    )

Installation using Composer

If you don't have composer, please install it - https://getcomposer.org/

Add this package to your project from the terminal.

composer require crowdskout/es-search-builder

If your project is not already setup to autoload composer libraries, you can put this at the top of your boostrap file or script

    use Crowdskout\EsSearchBuilder\Agg as AggBuilder;
    use Crowdskout\EsSearchBuilder\Query;

    require 'vendor/autoload.php';

    // Query
    $query = Query::terms('intField', [1, 2, 3, 4, 5, 6])
    
    // Agg
    $aggBuilder = new AggBuilder();
        
    $agg = $aggBuilder->nested('parentField', $aggBuilder->terms('parentField.subField'));
    $aggQuery = $agg->generateQuery();

Usage with elasticsearch-php

This library creates simple arrays to pass into the body portion of Elasticsearch search queries. You can pass the aggregation portion of the search result into the generateQuery function of the aggregation.

    use Crowdskout\EsSearchBuilder\Agg as AggBuilder;
    use Crowdskout\EsSearchBuilder\Query;
    use Elasticsearch\ClientBuilder;
    
    // Build a query
    $query = Query::terms('intField', [1, 2, 3, 4, 5, 6])
    
    // Build an aggregation
    $aggBuilder = new AggBuilder();
    $agg = $aggBuilder->nested('parentField', $aggBuilder->terms('parentField.subField'));
    
    // Initialize the Elasticsearch client
    $client = ClientBuilder::create()->build()
    
    // Run the search query
    $params = [
            'index' => 'my_index',
            'type' => 'my_type',
            'body' => [
                'query' => $query,
                'aggs' => $agg->generateQuery()
            ]
        ];
    $response = $client->search($params);
    
    // Parse the results
    $parsedResult = $agg->generateResults($response['aggregations']);

This library does not currently support all queries and aggregations

The current supported queries are here: https://github.com/crowdskout/es-search-builder/blob/master/src/Query.php.

The current supported aggregations are here: https://github.com/crowdskout/es-search-builder/blob/master/src/AggQuery.php.

If there's a query or or aggregation that you would like to see supported, please open an issue. You can also take a stab at writing it and open a pull request :).

Additional examples

You can see other, more complex examples of queries and aggregations in the tests/ directory. You can also see an example of a custom agg results generator in tests/AggGeneratorTest.php/