yii2-elasticsearch Extension

The yii2-elasticsearch extension provides integration for Elasticsearch within the Yii2 framework. It offers two primary ways to interact with Elasticsearch:

1. Basic Query/Search Support: For executing standard Elasticsearch queries and searches.
2. ActiveRecord Pattern: An implementation of the ActiveRecord pattern that allows you to store and manage your data models directly in Elasticsearch.

The yiisoft/yii2-elasticsearch extension provides integration between the Yii 2 framework and Elasticsearch. It supports two primary use cases:

1. Basic Querying/Search: Direct support for executing searches against Elasticsearch.
2. ActiveRecord Integration: Implements the ActiveRecord pattern, allowing you to treat Elasticsearch documents as active records for easier data manipulation and storage.

Elasticsearch Version Support

This extension is designed to support Elasticsearch version 5.0 and above. It has been tested with Elasticsearch 5.x, 6.x, and 7.x branches.

Inline Scripting (Painless)

Some features, such as the yii\elasticsearch\ActiveRecord::updateAllCounters() method, use inline scripts written in painless. These scripts are executed within a sandbox by Elasticsearch.

In most modern Elasticsearch versions, inline scripting is enabled by default. However, if you are using very old versions (such as Elasticsearch 5.0), you may need to manually enable inline scripting in your Elasticsearch configuration to use these features. Refer to the Elasticsearch documentation for details.

The yii2-elasticsearch extension provides integration between the Yii2 framework and Elasticsearch. It enables two primary workflows:

1. Basic Querying/Search: Direct support for executing searches and queries against Elasticsearch.
2. ActiveRecord Pattern: Implementation of the ActiveRecord pattern, allowing you to treat Elasticsearch documents as active records, enabling seamless storage and retrieval within the Yii2 ecosystem.

When working with yii\elasticsearch\ActiveRecord, it is helpful to map Elasticsearch concepts to familiar SQL concepts:

Note that in Elasticsearch, the primary key field is special: its name and structure cannot be changed, whereas other fields are fully configurable via mappings.

When an Elasticsearch model references a model from a traditional SQL database, the integer primary keys from SQL act as foreign keys.

Best Practice: Do not use numeric types (like integer or long) for these foreign keys in Elasticsearch. Numeric types are optimized for range queries. For foreign keys, use the keyword type in Elasticsearch, as it is optimized for exact term matching (term queries).

While Elasticsearch can create fields on the fly during indexing, it is best practice to define a mapping beforehand. This ensures correct data types (e.g., text, keyword, date, boolean) are used.

Warning: Once an attribute type is defined, it generally cannot be changed (e.g., changing a text field to a different language analyzer). If you must change a field type, you must delete the index and reindex all data.

In Elasticsearch, the primary key is named _id. Unlike SQL databases, the primary key is stored separately from the document structure and cannot be changed once the document is indexed.

• The _id is a string (max 512 bytes).
• You can let Elasticsearch generate a unique ID or specify one explicitly for new records.
• Access _id via getter/setter methods.
• Do not include _id in the attributes() method return value.

In older versions of Elasticsearch, 'types' were used to store different document structures in one index. However, types are no longer supported in Elasticsearch 7.x and above.

If your extension is configured for Elasticsearch 7+, the yii\elasticsearch\ActiveRecord::type() method is ignored, and the type is implicitly replaced with _doc in queries. It is recommended to declare only one type per index.

While Elasticsearch can create fields on-the-fly during indexing, it is best practice to declare your field structure (mapping) in advance.

Important: Once a field is declared, it generally cannot be changed (e.g., changing an analyzer for a text field). Significant changes require re-indexing all documents. Some minor changes (like adding new fields) may be allowed by the server.

The extension uses painless inline scripts for certain features, such as yii\elasticsearch\ActiveRecord::updateAllCounters().

• Modern Elasticsearch versions: Inline scripts are enabled by default and require no additional configuration.
• Older versions (e.g., 5.0): You must explicitly enable inline scripting in your Elasticsearch server settings to allow these operations to function.