Elastic Search client for Yii.
Install via composer, requires php >= 5.3
Add the following to your application config:
'components' => array(
'elasticSearch' => array(
'class' => 'YiiElasticSearch\Connection',
'baseUrl' => 'https://localhost:9200/',
),
...
)
Also make sure, that you include the autoloader of composer. We recommend
to add this line to your index.php
and maybe also your yiic.php
:
// Include composer autoloader
require_once(__DIR__.'/protected/vendor/autoload.php');
Make sure to modify the path so that it matches the location of your vendor/
directory.
Attach the YiiElasticSearch\SearchableBehavior
to any of your ActiveRecords to make it easy
to index and search your normal models with elasticsearch.
class MyModel extends CActiveRecord
{
public function behaviors()
{
return array(
'searchable' => array(
'class' => 'YiiElasticSearch\SearchableBehavior',
),
);
}
}
Now when MyModel instances are saved or deleted they will be automatically indexed or deleted in elasticsearch as appropriate.
By default your records will be stored in an index that uses your sanitized application name
(Yii::app()->name
). To change it you can define
class MyModel extends CActiveRecord
{
public $elasticIndex = 'myindex';
or, if you need more control, create a method
class MyModel extends CActiveRecord
{
public function getElasticIndex()
{
return 'myindex';
}
By default the lower case class name will be used as type name in elasticsearch. If you want to change that you can define
class MyModel extends CActiveRecord
{
public $elasticType = 'mymodel';
or, again, if you need more control, create a method
class MyModel extends CActiveRecord
{
public function getElasticType()
{
return 'mymodel';
}
By default all attributes are stored in the index. If you need to customize the data that should be indexed in elasticsearch, you can override these two methods.
class MyModel extends CActiveRecord
{
/**
* @param DocumentInterface $document the document where the indexable data must be applied to.
*/
public function populateElasticDocument(DocumentInterface $document)
{
$document->setId($this->id);
$document->name = $this->name;
$document->street = $this->street;
}
/**
* @param DocumentInterface $document the document that is providing the data for this record.
*/
public function parseElasticDocument(DocumentInterface $document)
{
// You should always set the match score from the result document
if ($document instanceof SearchResult)
$this->setElasticScore($document->getScore());
$this->id = $document->getId();
$this->name = $document->name;
$this->street = $document->stree;
}
You can specify queries using the YiiElasticSearch\Search
object. This object provides a simple
OO wrapper for the vanilla elasticsearch search API.
For example:
$search = new \YiiElasticSearch\Search("myindex", "mymodel");
$search->query = array(
"match_all" => array()
);
// start returning results from the 20th onwards
$search->offset = 20;
With a search you can either perform a 'raw' query, e.g.
$resultSet = Yii::app()->elasticSearch->search($search);
This will return a result set that is a very simple wrapper around the raw elastic search response.
Alternatively, when combined with a SearchableBehavior
you can use data providers, e.g.
$dataProvider = new \YiiElasticSearch\DataProvider(MyModel::model(), array(
'search' => $search
));
The data from $dataProvider->data
is a list of ActiveRecords, just like from an ordinary
CActiveDataProvider
. So you can use it in any list or grid view.
You can also use the connection component to send raw requests to elasticsearch.
// Will be an instance of a Guzzle\Http\Client
$client = Yii::app()->elasticSearch->client;
$mapping = array(
'country' => array(
'properties' => array(
'name' => array(
'type' => 'string',
),
),
),
// Create a mapping
$request = $client->put('myindex', array("Content-type" => "application/json"));
$request->setBody(array('mapping' => $mapping));
$response = $request->send();
$result = $response->getBody();
The extension comes with two simple maintenance commands that can be helpful to find out
what's going on in your index. To configure them, add this to your console.php
configuration:
'commandMap' => array(
'elastic' => array(
'class' => 'YiiElasticSearch\ConsoleCommand',
),
'zerodowntimeelastic' => array(
'class' => 'YiiElasticSearch\ZeroDowntimeConsoleCommand',
),
),
This will allow you to use yiic elastic
and yiic zerodowntimeelastic
on the console. Here are the commands help:
This is the maintenance command for the elasticSearch component.
ACTIONS
index --model=<model> [--skipExisting]
Add all models <model> to the index. This will replace any previous
entries for this model in the index. Index and type will be auto-detected
from the model class unless --index or --type is set explicitely.
If --skipExisting is used, no action is performed if there are already
documents indexed under this type.
map --model=<model> --map=<filename> [--skipExisting]
map --index=<index> --map=<filename> [--skipExisting]
Create a mapping in the index specified with the <index> or implicitly
through the <model> parameter. The mapping must be available from a JSON
file in <filename> where the JSON must have this form:
{
"tweet" : {
"properties": {
"name" : {"type" : "string"},
...
},
...
}
If --skipExisting is used, no action is performed if there's are already
a mapping for this index.
list [--limit=10] [--offset=0]
list [--model=<name>] [--limit=10] [--offset=0]
list [--index=<name>] [--type=<type>] [--limit=10] [--offset=0]
List all entries in elasticsearch. If a model or an index (optionally with
a type) is specified only entries matching index and type of the model will be listed.
delete --model=<name> [--id=<id>]
Delete a document from an index. If no <id> is specified the whole
index will be deleted.
help
Show this help
This is a zero downtime maintenance command for the elasticSearch component. More details: https://www.elastic.co/blog/changing-mapping-with-zero-downtime
ACTIONS
* index --models=<model1>,...
Add all models to the index.
* status --models=<model1>,...
Displays actual indexes and aliases
* schema --models=<model1>,...
[--version=201512121212] [--forceMigrate=false] [--bulkCopy=true] [--updateAlias=true] [--deleteIndexes=true]
Creates schema for the given models. Steps:
1, compare mapping
2, if migration is needed, create the new schema version, always create new if <forceMigrate> is true
3, bulk copy the previous data if <bulkCopy> is true
4, update aliases if <updateAlias> is true
5, delete indexes if <deleteIndexes> is true
* bulkCopy --from=index/type --to=index2/type [--properties=]
Bulk copy all data
* changeAlias --from=value --to=value [--old=]
Change alias
* deleteIndex --indexesToDelete=value
Delete index with all types
help
Show this help