Skip to main content
Version: 2025.4

Upgrade Information

Following steps are necessary during updating to newer versions.

Upgrade to 2.5.15​

  • [Indexing] New index status: IndexStatusServiceInterface reports per index whether it is complete, rebuilding (with the progress in percent), copying, degraded, incomplete or missing, with the counts it is derived from; IndexCompleteEvent fires in the messenger worker that processes the last batch of a queued full rebuild. See Index Status.
  • [Commands] generic-data-index:status shows the status of every index and the number of failed messages, and has new options: --index, --json, --check (exit code 1 while an index is not complete) and --wait (block until complete). Its leftover warning no longer lists an index whose odd/even copy is running. Without options the output and the exit code are unchanged.
  • [Indexing] A full rebuild queued by EnqueueServiceInterface (class save with a mapping change, update:index, deployment:reindex) is now marked in the settings store until its last batch is processed; the mark is what tells a rebuild from the normal lag of asynchronous indexing.
  • [Indexing] The progress of a running odd/even copy is logged every minute (documents copied so far).
  • [Database] A new migration adds an index on generic_data_index_queue.elementIndexName (the status counts the entries per index). Please make sure to execute migrations.
  • [Indexing] New methods on @internal interfaces, relevant only for custom implementations of them: SearchIndexServiceInterface::countDocuments() and getReindexTasks(), SettingsStoreServiceInterface::removeIndexState(), replaceIndexState() and removeIndexStateIfEquals(), IndexStateServiceInterface::isMappingCurrent().

Upgrade to 2.5.14​

  • [Permissions] Fixed: a workspace now only applies to its own path and the paths below it. Before, the permission check also applied it to any path that merely contained the workspace path (for example /Products to /Archive/Products/2024), and the search query treated a workspace such as /Products2 as lying below /Products. Effective permissions and search results for elements below such paths change accordingly.
  • [Commands] generic-data-index:deployment:reindex has new opt-in options (--all, --assets, --dry-run, …) that also cover the folder, asset and document indices and index_settings. Without options nothing changes. See Deployment and Index Management.
  • [Indexing] A native reindex now fails if the new index cannot be created (e.g. invalid index_settings) instead of switching to an index with dynamic mapping.

Upgrade to 2.5.13​

  • [Commands] Added generic-data-index:snapshot:export and generic-data-index:snapshot:import. Export writes every search index into a portable, gzipped JSON-lines bundle (plus a manifest) in a configurable Flysystem storage, so a bundle can be moved between installations without a full reindex. Import recreates the local indices from the bundle and replays the documents through the bulk API; it never enqueues elements, and refuses the import (unless --force is given) when a class's mapping checksum in the manifest does not match the local class definition. Snapshots are not rotated: they accumulate in the storage until an operator deletes them. See Index snapshots for the commands and configuration.
  • [Configuration] Added the pimcore_generic_data_index.snapshot node (storage, page_size, page_bytes, bulk_size, bulk_bytes, import_workers — the import sends bulk requests through 4 worker processes by default) and a default private Flysystem storage pimcore.generic_data_index_snapshot.storage under var/generic-data-index/snapshots.
  • [Bug] generic-data-index:status (and any caller of IndexStatsService::getStats()) no longer fails with "Undefined array key aggregations" when no search index exists yet.

Upgrade to 2.5.9​

  • [Indexing] Moving or renaming an element with children now rewrites the children's path/fullPath in the search index for all element types: data objects are rewritten across all per-class indexes (previously only the folder index was updated, so concrete objects kept their old path after a folder move), and documents are rewritten for any parent document type (previously only moves of document folders were handled, so children of a moved/renamed page kept their old path). Stale index paths also affected path-based workspace permission filtering of search results.
  • [Configuration] BC break: the undocumented max_synchronous_children_rename_limit setting (pimcore_generic_data_index.index_service.search_settings) was removed, together with SearchIndexConfigServiceInterface::getMaxSynchronousChildrenRenameLimit() (@internal). Above that limit the children path rewrite was silently skipped and never performed by any asynchronous process, leaving the index permanently stale — the rewrite now always runs. Remove the setting from your configuration if you had set it; Symfony will otherwise fail with an "Unrecognized option" error on container build.
  • [Commands] generic-data-index:update:index now exits with a non-zero status code when one or more of its update sections (class definition, asset index, full update) fail, instead of always returning 0. All sections are still attempted and the queue is still dispatched; the command only reports the failure at the end. Deployment pipelines that treated a partial failure as success will now fail visibly — this mirrors the same change made for generic-data-index:deployment:reindex and generic-data-index:reindex in 2.5.6.
  • [Commands] Added a read-only generic-data-index:status command that reports the index queue depth (and whether items are still pending dispatch), every live index with its document count and size, and a warning for any index present in both the -even and -odd version at once (the fingerprint of an interrupted reindex).
  • [Logging] Generic Data Index now logs to a dedicated pimcore_generic_data_index Monolog channel, so its output can be filtered, raised to debug, or routed separately. Handlers without a channel restriction pick it up automatically; if you restrict a handler to an explicit channel allow-list (e.g. channels: ["pimcore"]), add pimcore_generic_data_index to that list so its records are not dropped.
  • [Logging] Failure paths (index checksum read, queue enqueue, dispatch handler) now log with structured context and the original exception, a claimed queue batch's dispatch id is logged across dispatch and processing for correlation, and the per-class mapping-checksum reindex decision (skip vs. reindex, with stored vs. current checksum) is logged.

Upgrade to 2.5.8​

  • [Indexing] The class mapping checksum is now calculated independently of the array key order, so that a changed order of e.g. the configured system languages no longer marks unchanged class definitions as changed and triggers a native reindex. Checksums stored by earlier versions are recognised and updated automatically, so upgrading by itself does not reindex existing class definitions. Only if the mapping actually changes in the same deployment as the upgrade — including a changed key order, since the previous checksum still depends on it — are the affected class definitions reindexed once, as they would have been before. From then on, order-only changes no longer trigger a reindex.
  • [Indexing] A failed native reindex no longer triggers a forced recreation of the live index. Recreation now only happens when the reindex reports that the existing documents are incompatible with the new mapping (e.g. after a field type change); genuine errors — unreachable search cluster, timeouts, rejected requests — propagate and fail the operation instead, so a transient connection failure during deployment can no longer purge the index.
  • [Indexing] Transient failures of single task-status requests during a long-running reindex are now retried instead of aborting the reindex, and an aborted reindex cancels the server-side task before cleaning up its target index.
  • [Indexing] SearchIndexServiceInterface::reindex() (@internal) now returns a ReindexResult enum instead of void.

Upgrade to 2.5.6​

  • [Commands] generic-data-index:deployment:reindex and generic-data-index:reindex now exit with a non-zero status code when reindexing fails, instead of always returning 0. Deployment pipelines executing these commands will now fail visibly on reindex errors — previously such errors were only printed while the process reported success.
  • [Indexing] Reindexing failures are no longer silently swallowed: if both the reindex and the fallback index recreation fail, the exception now propagates and the mapping checksum is not stored, so the reindex of the class definition is retried on the next run.

Upgrade to 2.5.4​

  • [Searching] The full-text search (FullTextSearch modifier) now defaults to default_operator: AND and flags: PHRASE|WHITESPACE for better relevance and to treat characters like - and . as literal text.

Upgrade to 2.5.3​

  • [Indexing] Added isReferenced field to asset index to support filtering for unreferenced assets.
  • [Indexing] Fixed: Unpublished data objects are now correctly indexed in relation fields (ManyToOne, ManyToMany, AdvancedManyToMany)

Re-indexing required​

After upgrading, execute the following command to re-index elements to include all modifications:

bin/console generic-data-index:update:index -r

Upgrade to 2.2.0​

  • [Indexing] Added id column as new primary key to generic_data_index_queue. Please make sure to execute migrations.
  • [Searching] Added trackTotalHits parameter to DefaultSearchService and SearchExecutionService. The default value is true, which means that total hits will always be computed accurately, even if they exceed the search engines threshold for accurate hit calculation. Change this parameter to null, to use the default threshold, pass an integer value to set a specific one.

Upgrade to 2.1.0​

  • Added support for Symfony 7
  • [Indexing] Added sort index for documents
  • [Indexing] Improved indexing of field collections to prevent mapping conflicts when properties have the same name but different types
  • Execute the following command to reindex all elements to be able to use all new features: bin/console generic-data-index:update:index -r

Upgrade to 2.0.0​

  • [Indexing] Added inherited fields indicator to data object indexing
  • [Indexing] Added functionality to enqueue dependent items
  • [Indexing] Added class ID field for data object elements
  • [Indexing] Added prefix for index names of data objects, these names changed from e.g. pimcore_car to pimcore_data-object_car. Old indexes are not deleted automatically. You need to delete them manually if necessary.
  • [Searching] Added new ClassIdsFilter modifier to search for data object elements by class ID or class name
  • Added a new method isElementLocked() to the ElementLockService, which provides functionality to retrieve element locked status based on the index data
  • Execute the following command to reindex all elements to be able to use all new features: bin/console generic-data-index:update:index -r

BC-Breaks​

  • Removed deprecated alias generic-data-index.opensearch-client and replaced it with generic-data-index.search-client
  • Removed all deprecated classes from OpenSearch namespaces and replaced them with DefaultSearch namespace instead.
    • Pimcore\Bundle\GenericDataIndexBundle\Model\OpenSearch -> Pimcore\Bundle\GenericDataIndexBundle\Model\DefaultSearch
    • Pimcore\Bundle\GenericDataIndexBundle\Enum\SearchIndex\OpenSearch -> Pimcore\Bundle\GenericDataIndexBundle\Enum\SearchIndex\DefaultSearch
  • Removed deprecated class Pimcore\Bundle\GenericDataIndexBundle\Exception\OpenSearch\SearchFailedException please use Pimcore\Bundle\GenericDataIndexBundle\Exception\OpenSearch\SearchFailedException instead
  • Removed deprecated class Pimcore\Bundle\GenericDataIndexBundle\Attribute\OpenSearch\AsSearchModifierHandler please use Pimcore\Bundle\GenericDataIndexBundle\Attribute\Search\AsSearchModifierHandler instead
  • Removed deprecated class Pimcore\Bundle\GenericDataIndexBundle\SearchIndexAdapter\OpenSearch\Asset\FieldDefinitionAdapter\AbstractAdapter please use Pimcore\Bundle\GenericDataIndexBundle\SearchIndexAdapter\DefaultSearch\Asset\FieldDefinitionAdapter\AbstractAdapter instead
  • Removed deprecated class Pimcore\Bundle\GenericDataIndexBundle\SearchIndexAdapter\OpenSearch\DataObject\FieldDefinitionAdapter\AbstractAdapter please use Pimcore\Bundle\GenericDataIndexBundle\SearchIndexAdapter\DefaultSearch\DataObject\FieldDefinitionAdapter\AbstractAdapter instead
  • Added default prefix data-object_ prefix to all data object class definition index names. This change is necessary to avoid conflicts with other index names.
  • Add element type to the getIds method of Pimcore\Bundle\GenericDataIndexBundle\Model\Search\Element\SearchResult\ElementSearchResult
  • Added getSpecialPermissions method to Pimcore\Bundle\GenericDataIndexBundle\Service\Permission\ElementPermissionServiceInterface to get special permissions workspace language permissions for elements
  • Removed layout permission from Pimcore\Bundle\GenericDataIndexBundle\Permission\DataObjectPermissions as they are not index relevant
  • Removed property isLocked from Index for elements as it needs to be dynamically calculated
  • Changed workspace permissions evaluation in order to align more with the Pimcore Classic bundle permission system

Interface changes​

  • Added PermissionTypes $permissionType parameter with default type PermissionTypes::LIST to
  • AssetSearchServiceInterface::search method
  • DocumentSearchServiceInterface::search method
  • DataObjectSearchServiceInterface::search method
  • ElementSearchServiceInterface::search method
  • Search services byId methods now return elements based on the PermissionTypes::VIEW permission
  • Added type specific interfaces for searches to avoid mixing up different search types in search services
    • AssetSearch now implements AssetSearchInterface
    • DocumentSearch now implements DocumentSearchInterface
    • ElementSearch now implements ElementSearchInterface
  • Search services now require the specific search type for the search
    • AssetSearchServiceInterface::search now requires a AssetSearchInterface
    • DocumentSearchServiceInterface::search now requires a DocumentSearchInterface
    • ElementSearchServiceInterface::search now requires a ElementSearchInterface
  • SearchProviderInterface now returns type specific search interfaces

Upgrade to 1.3.0​

  • [Indexing] Added support for Elasticsearch in parallel to Opensearch. Opensearch remains the default search technology. If you are using Elasticsearch, you need to update your symfony configuration as follows:
pimcore_generic_data_index:
  index_service:
    client_params:
      client_name: default
      client_type: 'elasticsearch'

  • [Indexing] Introduced new service alias generic-data-index.search-client. This will replace deprecated alias generic-data-index.opensearch-client which will be removed in the next major version. The new service alias can be used to inject the search client into your services. This search client is an instance of Pimcore\SearchClient\SearchClientInterface which is a common interface for OpenSearch and Elasticsearch clients.

  • Classes under OpenSearch namespaces are now deprecated and will be removed in the next major version. Please use the classes under the DefaultSearch namespace instead.

  • Execute the following command to reindex all elements to be able to use all new features or when switching between OpenSearch and Elasticsearch:

    bin/console generic-data-index:update:index

Upgrade to 1.1.0​

  • Execute the following command to reindex all elements to be able to use all new features:

    bin/console generic-data-index:update:index