Search

Basic usage : query string

Launching a 'query_string' search request is simple : call the search() method from your client, with your query as the first parameter.

$request = $client->search('jim morrison') ;

Structure of a request

A search request in ES is defined by 3 main elements :

• query : the search query, witch scores the results
• filters : additional filters, on values or exact terms for example. Faster than query, and doesn't score the results
• facets : get faceted results, compacted with the rest of the response

You can define these elements calling the corresponding methods :

$request = $client->search() ;
$request
  ->query('jim morrison')
  ->filter()
    ->field('age')->value('27')
  ->facet('first_name')

There are many supported call formats, you can find some of them in the unit tests. I have tried to keep the interface as simple as I can, so you should find ways to create a request that suits your needs.

For each different element, you can define the request content by passing it to the API an array with your content, or calling sub-methods with the fluid interface.

This two examples give the same result :

//Insert examples here

What you have to understand is that all the mechanisms are built around a fluid interface : the API keeps track of what you called in order to respond to your method calls as you think it would. For example, the options() method won't do the same job if you call it directly after a request instanciation (it will configure the global request options) or after a query() call (in this case it will configure the query options).

$request->options(array('index' => 'singers')) ;             // Global options
$request->query('jim')->options(array('type' => 'term')) ;   // Query options (set the query type)

Query

The query is the scored part of your request : the clauses defined here will be applied on the results set and on all the facets computation.

The 2 main elements you have to give when querying are what you are searching (the query), and where it is located (field). In Simples, you can define these elements with different methods :

• where : field(), fields(), in()
• what : value(), values(), match()

This let you construct readable requests in human language :

$request->query()->match('jim')->in('username') ;
// Equivalent to :
$request->query()->field('username')->value('jim') ;

The ES requests definition is not coherent here : request construction depends of data types, and the JSON waited structure can be really different from one type to another. Simples helps you a lot. It can automagically define the query type depending on the data type you give :

$request->query()->field('type')->value('admin') ;                     // Term clause
$request->query()->field('type')->value(array('admin','connected')) ;  // Terms clause

You can force the query type by specifying the 'type' option :

$request->query()->field('type')->value('admin')->options(array('type' => 'text') ; // Force to "text" type

Currently, not all the search types are supported. Here is the current list :

• match_all
• query_string
• term / terms / text
• prefix
• exists / missing
• ids
• geo_bounding_box
• geo_distance
• range

I'll add missing types as I need. If you want to add one for your use, fork the project, add it to Criteria.php (with unit tests) and make a pull request !

Multiple query clauses

In real life, you will have to create requests with multiples queries. Simples default mode automatically merges queries wich are mergeable, and adds new subqueries when it cannot merge 2 calls.

$request->query()
  ->field('type')   // New clause  
  ->value('admin')  // No value set : it can merge
  ->field('name')   // Already a field set : new clause
  ->value('jim*')   // No value set in the new clause : it can merge

You can force new clauses addition with the add() method : each time it's called, it will create and push a new clause to your query. Useful in loops or complex requests construction :

$query = $request->query() ;
foreach($search_form as $value) {
  $query->add()->match($value);
}

Please, please, I want to keep my arrays !

Yeah, I know. In a lot of cases, you want to work with arrays : you translate your form data, your ORM returns arrays, or you just like working with arrays. I have a good news : all you can do using fluid interface can be done with arrays.

You just have to directly pass an array when you are calling a query (or a filter, or a facet, this is the same principle) :

$request->query(array('value' => 10, 'in' => 'age')) ;
$request->query()
  ->add(array('value' => 10, 'in' => 'age'))
  ->add(array('value' => 'jim', 'in' => 'name')) ;

Filters

Facets