eden/elastic

Elastic Search library

Eden Elastic Search

NOTE Other advance Elasticsearch API functionalities are not yet documented., _(*1)

• Install
• Introduction
• Low Level Request
• Data Manipulation
• Searching Data
• Query Builder
• Model
• Collection
• Contributing

, _(*2)

Install

composer install eden\elastic, _(*3)

Enable Eden

The following documentation uses eden() in its example reference. Enabling this function requires an extra step as descirbed in this section which is not required if you access this package using the following., _(*4)

Eden\Elastic\Index::i([HOST:PORT], [INDEX]);

When using composer, there is not an easy way to access functions from packages. As a workaround, adding this constant in your code will allow eden() to be available after., _(*5)

Eden::DECORATOR;

For example:, _(*6)

Eden::DECORATOR;

eden()->inspect('Hello World');

, _(*7)

Introduction

Eden's Elasticsearch API is very simple and very easy to use, some of the most spectacular functionalities from Eden's MySQL ORM can be seen and use in this library, e.g Model, Collection and some of the known magical methods of Eden MySQL., _(*8)

Figure 1. ElasticSearch Resource Conenction, _(*9)

$client = eden('elastic', '[HOST:PORT]', '[INDEX]');

The above code show's how simple it is to define a resource/connection for Elasticsearch., _(*10)

Note Eden's Elasticsearch is only getting the host and index information upon initialization, no actual test request made to check if the host exists, this way we can avoid overhead., _(*11)

, _(*12)

Low Level Request

Figure 2. Low level request using Eden\Elastic\Resource class, _(*13)

If you want to do some basic to advance request that is not provided in Eden Elasticsearch API, you are always free to access the low level resource class., _(*14)

$response = $client
// set the host (optional)
->setHost('http://localhost:9200')
// set the index name
->setIndex('twitter')
// set the index type
->setType('tweet')
// set the endpoint
->setEndpoint('_create')
// set the request body
->setBody(array(
    'user'      => 'Kimchy',
    'message'   => 'Eden Elasticsearch API!',
    'active'    => 1
))
// set the parameter
->setParam('routing', 'Charles')
// set the method
->setMethod(\Eden\Elastic\Index::PUT)
// set custom request header
->setHeaders('Content-Type', 'application/json')
// send the request
->send();

, _(*15)

Data Manipulation

Basic Create/Index, Remove, Update, Delete is very easy to access, the following example will show how we could do such simple task in a simple way., _(*16)

Figure 3. Indexing Single Data, _(*17)

$tweet = array(
    '_id'       => 1,
    'user'      => 'Charles',
    'message'   => 'Elasticsearch is cool!'
);

$response = $client->insert($tweet, 'tweet');

Figure 4. Indexing Multiple Data, _(*18)

$tweets = array(
    array(
        '_id'       => 1,
        'user'      => 'Charles',
        'message'   => 'Elasticsearch is cool!'
    ),
    array(
        '_id'       => 2,
        'user'      => 'Kimchy',
        'message'   => 'Yes @czamora it is cool!'
    )
);

$response = $client->insertRows($tweets, 'tweet');

Figure 5. Update Single Data by id, _(*19)

$user = array(
    '_id'       => 45,
    'firstname' => 'Charles',
    'lastname'  => 'Zamora'
);

$response = $client->update($user, 'user');

Figure 6. Update Multiple Data by id, _(*20)

$tweets = array(
    array(
        '_id'       => 1,
        'active'    => 0
    ),
    array(
        '_id'       => 2,
        'active'    => 1
    )
);

$response = $client->updateRows($tweets, 'tweet');

Figure 7. Remove Single Data by id, _(*21)

$tweet = array('_id' => 1);

$response = $client->remove($tweet, 'tweet');

Figure 8. Remove Multiple Data by id, _(*22)

$tweets = array(array('_id' => 1), array('_id' => 2));

$response = $client->removeRows($tweets, 'tweet');

Figure 9. Get Single Data by id, _(*23)

$response = $client->get(1, 'tweet');

Figure 10. Get Multiple Documents by id, _(*24)

$tweets = array(array('_id' => 1), array('_id' => 2));

$response = $client->getRows($tweets, 'tweet');

NOTE The _id field is very important because it will be the basis of all the basic crud functionality., _(*25)

, _(*26)

Searching Data

The code below will show how simple it is to search for an indexed data using Eden Elasticsearch Search class., _(*27)

Figure 10. Basic Searching using Search class, _(*28)

$user = $client
->search('tweet')
->filterByUser('Charles')
->sortByActive('desc')
->setStart(0)
->setRange(1)
->getRows();

Most of the magical *Eden MySQL's search functionality can be accessed in search class e.g filterBy, sortBy, setStart, setRange etc., _(*29)

Other useful methods, _(*30)

• ->getRow() - Get the results limit by 1
• ->getCollection() - Get the results as a collection
• ->getModel() - Get the results as a model
• ->getQuery() - Returns the current search query
• ->getTotal() - Returns the total records of search query
• ->exists() - Returns a response whether a record based on query exists

NOTE The magic methods from the search class is using the Query Builder class internally, so if you are going to do something like ->setAnything(value) the anything key will be added to the query builder instance inside the search instance together with it's value. Another thing to consider is that the ->getModel() method will return a single Eden\Elastic\Model instance the same as ->getCollection() that will return the Eden\Elastic\Collection instance so that way we can make the search functionality more flexible., _(*31)

, _(*32)

Query Builder

Elasticsearch's Query DSL is a complex query data structure, in Eden Elasticsearch we make this more simple using the Query Builder class. The query builder class contains simple API functionalities that will help you build a simple to complex query data structure. below is an example on how it works., _(*33)

Figure 11. Building Complex queries using Query Builder, _(*34)

$query = $client
->query()
->setTree('query.bool.must.term.user', 'kimchy')
->setTree('query.bool.should.term.user', 'charles')
->setTree('query.filter.or.0.term.active', 1)
->addTree('query.filter.or', array(
    'term' => array('user' => 'Charles')
))
->getQuery();

Query Output:, _(*35)

Array
(
    [query] => Array
        (
            [bool] => Array
                (
                    [must] => Array
                        (
                            [term] => Array
                                (
                                    [user] => kimchy
                                )

                        )

                    [should] => Array
                        (
                            [term] => Array
                                (
                                    [user] => charles
                                )

                        )

                )

            [filter] => Array
                (
                    [or] => Array
                        (
                            [0] => Array
                                (
                                    [term] => Array
                                        (
                                            [active] => 1
                                        )

                                )

                            [1] => Array
                                (
                                    [term] => Array
                                        (
                                            [user] => Charles
                                        )

                                )

                        )

                )

        )

)

Figure 12. Using the Query Builder output in search class, _(*36)

$query = $client
->setTree('query.bool.term.user', 'kimchy')
->setTree('sort.0.active.order', 'desc')
->getQuery();

$response = $client
->search('tweet')
->setBody($query)
->getRows();

, _(*37)

Model

The model class of Eden Elasticsearch is derived from the awesome Eden MySQL Model class, most of the functionality is the same as how the Eden MySQL Model works except the fact that setting the '_id' field has it's own functionality. Let's take a look on how it works., _(*38)

Figure 13. Basic Elasticsearch Model, _(*39)

$user = array(
    '_id'       => 10,
    'user'      => 'Foo',
    'message'   => 'I am foo!'
);

$response = $client
->model($user)
->save('tweet')
->get(false);

Figure 14. Setting Model data magically, _(*40)

$response = $client
->model()
->setId(10) // IMPORTANT
->setUser('charles')
->setMessage('This is created using a model!')
->save('tweet')
->get(false);

Other useful methods, _(*41)

• ->insert('tweet') - No upsert, strict data insertion only
• ->remove('tweet') - Remove the model from the index type tweet
• ->update('tweet') - Update the model from the index type tweet
• ->get(false) - Returns the model

, _(*42)

Collection

The collection class is also derived from the awesome Eden MySQL Collection class, the collection class do exactly what the models can do, except the fact that it can process or manipulate bulk or collection of models in a simple manner. Below will show how collection works with Elasticsearch., _(*43)

Figure 15. Basic Elasticsearch Collection, _(*44)

$tweets = array(
  array(
      '_id'         => 10,
      'user'        => 'Foo',
      'message'     => 'I am foo!'
  ),
  array(
      '_id'         => 11,
      'user'        => 'Foo 2',
      'message'     => 'I am foo 2!'
  )
);

$collection = $client
->collection($tweets)
->save('tweet');

Other useful methods, _(*45)

• ->insert('tweet') - Insert the collection of model to index type tweet, no upserts, just strict data insertion
• ->update('tweet') - Updates the collection of model from index type tweet
• ->remove('tweet') - Remove the collection of model from index type tweet
• ->add(array) - Add an array or model to the collection
• ->set(array) - Set the collection of array or model
• ->get(false) - Get the collection data

, _(*46)

Contributing to Eden

Contributions to Eden are following the Github work flow. Please read up before contributing., _(*47)

Setting up your machine with the Eden repository and your fork

1. Fork the repository
2. Fire up your local terminal create a new branch from the v4 branch of your fork with a branch name describing what your changes are. Possible branch name types:
   • bugfix
   • feature
   • improvement
3. Make your changes. Always make sure to sign-off (-s) on all commits made (git commit -s -m "Commit message")

Making pull requests

1. Please ensure to run phpunit before making a pull request.
2. Push your code to your remote forked version.
3. Go back to your forked version on GitHub and submit a pull request.
4. An Eden developer will review your code and merge it in when it has been classified as suitable.