Class yii\elasticsearch\ActiveRecord
Inheritance | yii\elasticsearch\ActiveRecord » yii\db\BaseActiveRecord |
---|---|
Available since version | 2.0 |
ActiveRecord is the base class for classes representing relational data in terms of objects.
This class implements the ActiveRecord pattern for the fulltext search and data storage elasticsearch.
For defining a record a subclass should at least implement the attributes() method to define
attributes.
The primary key (the _id
field in elasticsearch terms) is represented by getId()
and setId()
.
The primary key is not part of the attributes.
The following is an example model called Customer
:
class Customer extends \yii\elasticsearch\ActiveRecord
{
public function attributes()
{
return ['id', 'name', 'address', 'registration_date'];
}
}
You may override index() and type() to define the index and type this record represents.
Public Methods
Protected Methods
Method | Description | Defined By |
---|---|---|
primaryKeysByCondition() | Performs a quick and highly efficient scroll/scan query to get the list of primary keys that
satisfy the given condition. If condition is a list of primary keys
(e.g.: ['_id' => ['1', '2', '3']] ), the query is not performed for performance considerations. |
yii\elasticsearch\ActiveRecord |
updateInternal() | yii\elasticsearch\ActiveRecord |
Method Details
A list of attributes that should be treated as array valued when retrieved through yii\elasticsearch\ActiveQuery::fields().
If not listed by this method, attributes retrieved through yii\elasticsearch\ActiveQuery::fields() will converted to a scalar value when the result array contains only one value.
public string[] arrayAttributes ( ) | ||
return | string[] | List of attribute names. Must be a subset of attributes(). |
---|
Returns the list of all attribute names of the model.
This method must be overridden by child classes to define available attributes.
Attributes are names of fields of the corresponding elasticsearch document.
The primaryKey for elasticsearch documents is the _id
field by default which is not part of the attributes.
You may define path mapping
for the _id
field so that it is part of the _source
fields and thus becomes part of the attributes.
public string[] attributes ( ) | ||
return | string[] | List of attribute names. |
---|---|---|
throws | \yii\base\InvalidConfigException | if not overridden in a child class. |
public integer|boolean delete ( $options = [] ) | ||
$options | array | Options given in this parameter are passed to elasticsearch as request URI parameters. These are among others:
Please refer to the elasticsearch documentation for more details on these options. The following parameters are Yii specific:
|
return | integer|boolean | The number of rows deleted, or false if the deletion is unsuccessful for some reason. Note that it is possible the number of rows deleted is 0, even though the deletion execution is successful. |
---|---|---|
throws | \yii\db\StaleObjectException | if optimistic locking is enabled and the data being deleted is outdated. |
throws | yii\elasticsearch\Exception | in case delete failed. |
Deletes rows in the table using the provided conditions.
WARNING: If you do not specify any condition, this method will delete ALL rows in the table.
For example, to delete all customers whose status is 3:
Customer::deleteAll(['status' => 3]);
See also [[yii\elasticsearch\ActiveRecord::primaryKeysByCondition()]].
public static integer deleteAll ( $condition = [] ) | ||
$condition | array | The conditions that will be passed to the |
return | integer | The number of rows deleted |
---|---|---|
throws | yii\elasticsearch\Exception | on error. |
public static yii\elasticsearch\ActiveQuery find ( ) | ||
return | yii\elasticsearch\ActiveQuery | The newly created yii\elasticsearch\ActiveQuery instance. |
---|
public static void findAll ( $condition ) | ||
$condition |
public static void findOne ( $condition ) | ||
$condition |
Gets a record by its primary key.
public static static|null get ( $primaryKey, $options = [] ) | ||
$primaryKey | mixed | The primaryKey value |
$options | array | Options given in this parameter are passed to elasticsearch as request URI parameters. Please refer to the elasticsearch documentation for more details on these options. |
return | static|null | The record instance or null if it was not found. |
---|
Returns the database connection used by this AR class.
By default, the "elasticsearch" application component is used as the database connection. You may override this method if you want to use a different database connection.
public static yii\elasticsearch\Connection getDb ( ) | ||
return | yii\elasticsearch\Connection | The database connection used by this AR class. |
---|
public array|null getExplanation ( ) | ||
return | array|null | An explanation for each hit on how its score was computed. |
---|
public array|null getHighlight ( ) | ||
return | array|null | A list of arrays with highlighted excerpts indexed by field names. |
---|
public void getOldPrimaryKey ( $asArray = false ) | ||
$asArray |
public void getPrimaryKey ( $asArray = false ) | ||
$asArray |
public float getScore ( ) | ||
return | float | Returns the score of this record when it was retrieved via a find() query. |
---|
public static string index ( ) | ||
return | string | The name of the index this record is stored in. |
---|
Inserts a document into the associated index using the attribute values of this record.
This method performs the following steps in order:
- call \yii\elasticsearch\beforeValidate() when
$runValidation
is true. If validation fails, it will skip the rest of the steps; - call \yii\elasticsearch\afterValidate() when
$runValidation
is true. - call \yii\elasticsearch\beforeSave(). If the method returns false, it will skip the rest of the steps;
- insert the record into database. If this fails, it will skip the rest of the steps;
- call \yii\elasticsearch\afterSave();
In the above step 1, 2, 3 and 5, events \yii\elasticsearch\EVENT_BEFORE_VALIDATE, \yii\elasticsearch\EVENT_BEFORE_INSERT, \yii\elasticsearch\EVENT_AFTER_INSERT and \yii\elasticsearch\EVENT_AFTER_VALIDATE will be raised by the corresponding methods.
Only the \yii\elasticsearch\dirtyAttributes will be inserted into database.
If the primary key is not set (null) during insertion, it will be populated with a randomly generated value after insertion.
For example, to insert a customer record:
$customer = new Customer;
$customer->name = $name;
$customer->email = $email;
$customer->insert();
public boolean insert ( $runValidation = true, $attributes = null, $options = ['op_type' => 'create'] ) | ||
$runValidation | boolean | Whether to perform validation before saving the record. If the validation fails, the record will not be inserted into the database. |
$attributes | array | List of attributes that need to be saved. Defaults to null, meaning all attributes will be saved. |
$options | array | Options given in this parameter are passed to elasticsearch as request URI parameters. These are among others:
Please refer to the elasticsearch documentation for more details on these options. By default the |
return | boolean | Whether the attributes are valid and the record is inserted successfully. |
---|
Creates an active record instance.
This method is called together with populateRecord() by yii\elasticsearch\ActiveQuery. It is not meant to be used for creating new records directly.
You may override this method if the instance being created depends on the row data to be populated into the record. For example, by creating a record based on the value of a column, you may implement the so-called single-table inheritance mapping.
public static static instantiate ( $row ) | ||
$row | array | Row data to be populated into the record. This array consists of the following keys:
|
return | static | The newly created active record |
---|
Gets a list of records by its primary keys.
public static array mget ( array $primaryKeys, $options = [] ) | ||
$primaryKeys | array | An array of primaryKey values |
$options | array | Options given in this parameter are passed to elasticsearch as request URI parameters. Please refer to the elasticsearch documentation for more details on these options. |
return | array | The record instances, or empty array if nothing was found |
---|
This method has no effect in Elasticsearch ActiveRecord.
Elasticsearch ActiveRecord uses native Optimistic locking. See update() for more details.
public void optimisticLock ( ) |
public static void populateRecord ( $record, $row ) | ||
$record | yii\elasticsearch\ActiveRecord | The record to be populated. In most cases this will be an instance created by instantiate() beforehand. |
$row | array | Attribute values (name => value) |
This method defines the attribute that uniquely identifies a record.
The primaryKey for elasticsearch documents is the _id
field by default. This field is not part of the
ActiveRecord attributes so you should never add _id
to the list of attributes.
You may override this method to define the primary key name when you have defined
path mapping
for the _id
field so that it is part of the _source
and thus part of the attributes.
Note that elasticsearch only supports one attribute to be the primary key. However to match the signature of the \yii\db\ActiveRecordInterface this methods returns an array instead of a single string.
public static string[] primaryKey ( ) | ||
return | string[] | Array of primary key attributes. Only the first element of the array will be used. |
---|
Performs a quick and highly efficient scroll/scan query to get the list of primary keys that
satisfy the given condition. If condition is a list of primary keys
(e.g.: ['_id' => ['1', '2', '3']]
), the query is not performed for performance considerations.
See also:
protected static array primaryKeysByCondition ( $condition ) | ||
$condition | array | Please refer to yii\elasticsearch\ActiveQuery::where() on how to specify this parameter |
return | array | Primary keys that correspond to given conditions |
---|
Sets the primary key
public void setPrimaryKey ( $value ) | ||
$value | mixed | |
throws | \yii\base\InvalidCallException | when record is not new |
---|
public static string type ( ) | ||
return | string | The name of the type of this record. |
---|
Destroys the relationship in current model.
This method is not supported by elasticsearch.
public void unlinkAll ( $name, $delete = false ) | ||
$name | ||
$delete |
public integer|boolean update ( $runValidation = true, $attributeNames = null, $options = [] ) | ||
$runValidation | boolean | Whether to perform validation before saving the record. If the validation fails, the record will not be inserted into the database. |
$attributeNames | array | List of attribute names that need to be saved. Defaults to null, meaning all attributes that are loaded from DB will be saved. |
$options | array | Options given in this parameter are passed to elasticsearch as request URI parameters. These are among others:
Please refer to the elasticsearch documentation for more details on these options. The following parameters are Yii specific:
|
return | integer|boolean | The number of rows affected, or false if validation fails or \yii\elasticsearch\beforeSave() stops the updating process. |
---|---|---|
throws | \yii\db\StaleObjectException | if optimistic locking is enabled and the data being updated is outdated. |
throws | \yii\base\InvalidParamException | if no \yii\elasticsearch\version is available and optimistic locking is enabled. |
throws | yii\elasticsearch\Exception | in case update failed. |
Updates all records whos primary keys are given.
For example, to change the status to be 1 for all customers whose status is 2:
Customer::updateAll(['status' => 1], ['status' => 2]);
See also [[yii\elasticsearch\ActiveRecord::primaryKeysByCondition()]].
public static integer updateAll ( $attributes, $condition = [] ) | ||
$attributes | array | Attribute values (name-value pairs) to be saved into the table |
$condition | array | The conditions that will be passed to the |
return | integer | The number of rows updated |
---|---|---|
throws | yii\elasticsearch\Exception | on error. |
Updates all matching records using the provided counter changes and conditions.
For example, to add 1 to age of all customers whose status is 2,
Customer::updateAllCounters(['age' => 1], ['status' => 2]);
See also [[yii\elasticsearch\ActiveRecord::primaryKeysByCondition()]].
public static integer updateAllCounters ( $counters, $condition = [] ) | ||
$counters | array | The counters to be updated (attribute name => increment value). Use negative values if you want to decrement the counters. |
$condition | array | The conditions that will be passed to the |
return | integer | The number of rows updated |
---|---|---|
throws | yii\elasticsearch\Exception | on error. |
See also update().
protected integer|false updateInternal ( $attributes = null, $options = [] ) | ||
$attributes | array | Attributes to update |
$options | array | Options given in this parameter are passed to elasticsearch as request URI parameters. See update() for details. |
return | integer|false | The number of rows affected, or false if \yii\elasticsearch\beforeSave() stops the updating process. |
---|---|---|
throws | \yii\db\StaleObjectException | if optimistic locking is enabled and the data being updated is outdated. |
throws | \yii\base\InvalidParamException | if no \yii\elasticsearch\version is available and optimistic locking is enabled. |
throws | yii\elasticsearch\Exception | in case update failed. |