Skip to content

Commit

Permalink
HSEARCH-4287 Remove an obsolete limitation from the documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
yrodiere committed Aug 11, 2021
1 parent 6b52cb9 commit c9a11f5
Show file tree
Hide file tree
Showing 2 changed files with 1 addition and 44 deletions.
Expand Up @@ -117,7 +117,7 @@ See <<search-dsl>> for details.
.2+|Limitations
3+|Automatic indexing ignores: <<limitations-changes-in-session,JPQL/SQL queries>>, <<limitations-changes-asymmetric-association-updates,asymmetric association updates>>
2+d|Out-of-sync indexes in rare situations: <<limitations-parallel-embedded-update,concurrent `@IndexedEmbedded`>>, <<limitations-backend-indexing-error,backend I/O errors>>
|Out-of-sync indexes <<limitations-database-polling-event-order,in very rare situations with some databases>>.
|No other known limitation
|===

[[architecture-examples-single-node-lucene]]
Expand Down
43 changes: 0 additions & 43 deletions documentation/src/main/asciidoc/reference/limitations.asciidoc
Expand Up @@ -210,46 +210,3 @@ Avoid serializing an ORM `EntityManager`/`Session` after changing entities.

There are no plans to address this limitation.
We do not intend to support `Session` serialization when Hibernate Search is enabled.

[[limitations-database-polling-event-order]]
== With database-polling coordination, in rare cases, rapid deletion then re-creation of an entity may lead to out-of-sync indexes

=== Description

With <<coordination-database-polling,database-polling coordination>>,
entity change events are always processed in the order they happen
(or in an order that is close enough to produce the same indexing results),
except in the following case:

* An entity is deleted, then re-created with the same identifier.
* The deletion and re-creation happen very rapidly one after another,
so rapidly that the database date/time functions do not have enough resolution
to assign a different timestamp to the two events.
This generally means the two events happen **within ~1 microsecond** of each other.
* The deletion event is automatically assigned an identifier higher than the re-creation event.
This generally means link:{hibernateDocUrl}#identifiers-generators-optimizer[identifier generator optimizers] are used;
they may lead to out-of-order ID generation.

In this **very** specific case, the entity may end up being deleted from the index,
and not added until another change happens for that entity.

=== Solutions and workarounds

The following solutions can help circumvent this limitation:

1. Do not reuse identifiers when an indexed entity is deleted then re-created:
assign a different identifier to the re-created entity.
This should be the case with the vast majority of applications,
as long as they rely on automatically generated identifiers.
2. OR if you do reuse an identifier, ensure the entity re-creation
happens significantly more than 1 microsecond after its deletion.
3. OR schedule a <<mapper-orm-indexing-massindexer,full reindexing>> of your database periodically (e.g. every night)
to get the index back in sync with the database.

=== Roadmap

Several countermeasures are already in place,
and they are the reason the problem only occurs when the entity re-creation
happens shortly after (~1 microsecond) after the deletion.

https://hibernate.atlassian.net/browse/HSEARCH-4287[HSEARCH-4287] is expected to get rid of the limitation completely.

0 comments on commit c9a11f5

Please sign in to comment.