diff --git a/documentation/src/main/asciidoc/reference/architecture.asciidoc b/documentation/src/main/asciidoc/reference/architecture.asciidoc index fd4a8fc8378..7c159cae803 100644 --- a/documentation/src/main/asciidoc/reference/architecture.asciidoc +++ b/documentation/src/main/asciidoc/reference/architecture.asciidoc @@ -276,7 +276,7 @@ allowing retries for as long as necessary. ** the possibility of out-of-sync indexes caused by <> that affects other architectures is eliminated here, because <> -before being reindexed. +before being re-indexed. * Easy to extend: you can easily access most Elasticsearch features, even those that are not exposed by Hibernate Search, by providing your own JSON. See for example <>, diff --git a/documentation/src/main/asciidoc/reference/backend-elasticsearch.asciidoc b/documentation/src/main/asciidoc/reference/backend-elasticsearch.asciidoc index e0c0c394f20..d3cc43e0d62 100644 --- a/documentation/src/main/asciidoc/reference/backend-elasticsearch.asciidoc +++ b/documentation/src/main/asciidoc/reference/backend-elasticsearch.asciidoc @@ -112,7 +112,7 @@ Alternatively, it is possible to define both the protocol and hosts as one or mo hibernate.search.backend.uris = http://localhost:9200 ---- -This property may be set to a String representing an URI such as `http://localhost` or `https://es.mycompany.com:4400`, +This property may be set to a String representing a URI such as `http://localhost` or `https://es.mycompany.com:4400`, or a String containing multiple such URI strings separated by commas, or a `Collection` containing such URI strings. @@ -193,7 +193,7 @@ you will find it requires a proprietary authentication method: https://docs.aws.amazon.com/elasticsearch-service/latest/developerguide/es-request-signing.html[request signing]. While request signing is not supported by default, -you can enable it with an additional dependency and a little bit of configuration. +you can enable it with an additional dependency and a bit of configuration. You will need to add this dependency: @@ -320,7 +320,7 @@ include::{sourcedir}/org/hibernate/search/documentation/backend/elasticsearch/cl <1> The class has to implement the `ElasticsearchHttpClientConfigurer` interface. <2> The `configure` method provides the access to the `ElasticsearchHttpClientConfigurationContext`. <3> From the context it is possible to get the `HttpAsyncClientBuilder`. -<4> Finally you can use the builder to configure the client with your custom settings. +<4> Finally, you can use the builder to configure the client with your custom settings. ==== .Define a custom http client configurer in the properties @@ -550,7 +550,7 @@ specifying the data type and capabilities of each "property" (called an "index f For the most part, the Elasticsearch mapping is inferred from <>, -which are generic and independent from Elasticsearch. +which are generic and independent of Elasticsearch. Aspects that are specific to the Elasticsearch backend are explained in this section. @@ -813,7 +813,7 @@ e.g. if link:{hibernateDocUrl}#multitenacy[a multi-tenancy strategy is selected However, it is possible to enable multi-tenancy manually. -The multi-tenancy strategy is set a the backend level: +The multi-tenancy strategy is set at the backend level: [source] ---- @@ -838,8 +838,8 @@ The Elasticsearch ID of each document is set to the concatenation of the tenant When indexing, two fields are populated transparently for each document: -* `_tenant_id`: the "discriminator" field holding the tenant ID. -* `_tenant_doc_id`: a field holding the the original (tenant-scoped) document ID. +* `+_tenant_id+`: the "discriminator" field holding the tenant ID. +* `+_tenant_doc_id+`: a field holding the original (tenant-scoped) document ID. When searching, a filter targeting the tenant ID field is added transparently to the search query to only return search hits for the current tenant. @@ -851,14 +851,23 @@ The ID field is used to retrieve the original document IDs. [[backend-elasticsearch-mapping-custom-basics]] ==== Basics -Hibernate Search can <>, but by default created indexes will only include the bare minimum required to index and search: the mapping, and the analysis settings. -Should you need to customize some link:{elasticsearchDocUrl}/mapping-params.html[mapping parameters], it is possible to provide a custom mapping to Hibernate Search: it will include the custom mapping when creating an index. +Hibernate Search can <>, +but by default created indexes will only include the bare minimum required to index and search: +the mapping, and the analysis settings. +Should you need to customize some link:{elasticsearchDocUrl}/mapping-params.html[mapping parameters], +it is possible to provide a custom mapping to Hibernate Search: +it will include the custom mapping when creating an index. [CAUTION] ==== -The consistency of the custom Elasticsearch mapping with the Hibernate Search mapping will not get checked in any way. You are responsible for making sure that any override in your mapping can work, e.g. that you're not changing the type of an index field from `text` to `integer`, or disabling `doc_values` on a field used for sorting. +The consistency of the custom Elasticsearch mapping with the Hibernate Search mapping will not get checked in any way. +You are responsible for making sure that any override in your mapping can work, +e.g. that you're not changing the type of an index field from `text` to `integer`, +or disabling `doc_values` on a field used for sorting. -An invalid custom mapping may not trigger any exception on bootstrap, but later while indexing or querying. In the worst case, it could not trigger any exception, but simply lead to incorrect search results. Exercise extreme caution. +An invalid custom mapping may not trigger any exception on bootstrap, but later while indexing or querying. +In the worst case, it could not trigger any exception, but simply lead to incorrect search results. +Exercise extreme caution. ==== [source] @@ -882,7 +891,8 @@ include::{resourcesdir}/custom/index-mapping.json[] Properties that are only defined in the custom mappings file but not mapped by Hibernate Search will not be visible to Hibernate Search. -This means Hibernate Search will throw exceptions if you try to reference these properties in the <>, or when <> +This means Hibernate Search will throw exceptions if you try to reference these properties in the <>, +or when <> ==== The file does not need to contain the full mapping: Hibernate Search will automatically inject @@ -915,7 +925,7 @@ has a `String name` property annotated with `@FullTextField`. ==== [[_disable_source]] Disabling `_source` Using this feature it is possible to link:{elasticsearchDocUrl}/mapping-source-field.html[disable the `_source` field]. -For instance you could pass a `custom/index-mapping.json` file like the following: +For instance, you could pass a `custom/index-mapping.json` file like the following: .Possible content of `custom/index-mapping.json` file to disable the `_source` field ==== diff --git a/documentation/src/main/asciidoc/reference/backend-lucene.asciidoc b/documentation/src/main/asciidoc/reference/backend-lucene.asciidoc index 8ad01defbde..cdf3fb10d57 100644 --- a/documentation/src/main/asciidoc/reference/backend-lucene.asciidoc +++ b/documentation/src/main/asciidoc/reference/backend-lucene.asciidoc @@ -203,7 +203,7 @@ See `org.apache.lucene.store.NativeFSLockFactory`. Locks using a Java object held in the JVM's heap. Since the lock is only accessible by the same JVM, this strategy will only work properly when it is known -that only a single application will ever try to accesses the indexes. +that only a single application will ever try to access the indexes. + This is the default strategy for the `local-heap` directory type. + @@ -325,15 +325,15 @@ This creates a dependency to the Lucene index format. The Lucene developers of course attempt to keep a stable index format, but sometimes a change in the format can not be avoided. In those cases you either have to re-index all your data or use an index upgrade tool. -Sometimes, Lucene is also able to read the old format so you don't need to take specific actions -(besides making backup of your index). +Sometimes, Lucene is also able to read the old format, so you don't need to take specific actions +(beside making backup of your index). While an index format incompatibility is a rare event, it can happen more often that Lucene's Analyzer implementations might slightly change its behavior. This can lead to some documents not matching anymore, even though they used to. To avoid this analyzer incompatibility, -Hibernate Search allows to configure to which version of Lucene +Hibernate Search allows configuring to which version of Lucene the analyzers and other Lucene classes should conform their behavior. This configuration property is set at the backend level: @@ -379,7 +379,7 @@ in order to remember which predicates/projections/sorts can be applied to each f For the most part, the schema is inferred from <>, -which are generic and independent from Elasticsearch. +which are generic and independent of Lucene. Aspects that are specific to the Lucene backend are explained in this section. @@ -391,16 +391,16 @@ Aspects that are specific to the Lucene backend are explained in this section. [NOTE] ==== -Some types are not supported directly by the Elasticsearch backend, +Some types are not supported directly by the Lucene backend, but will work anyway because they are "bridged" by the mapper. For example a `java.util.Date` in your entity model is "bridged" to `java.time.Instant`, -which is supported by the Elasticsearch backend. +which is supported by the Lucene backend. See <> for more information. ==== [NOTE] ==== -Field types that are not in this list can still be used with a little bit more work: +Field types that are not in this list can still be used with a bit more work: * If a property in the entity model has an unsupported type, but can be converted to a supported type, you will need a bridge. @@ -531,7 +531,7 @@ e.g. if link:{hibernateDocUrl}#multitenacy[a multi-tenancy strategy is selected However, it is possible to enable multi-tenancy manually. -The multi-tenancy strategy is set a the backend level: +The multi-tenancy strategy is set at the backend level: [source] ---- @@ -791,7 +791,7 @@ it is expected that there will be a lot of "indexing" operations to create/updat We generally want to preserve the relative order of these requests when they are about the same documents. -For this reasons, Hibernate Search pushes these operations to internal queues and applies them in batches. +For this reason, Hibernate Search pushes these operations to internal queues and applies them in batches. Each index maintains 10 queues holding at most 1000 elements each. Queues operate independently (in parallel), but each queue applies one operation after the other, so at any given time there can be at most 10 batches of indexing requests being applied for each index. @@ -1204,7 +1204,7 @@ otherwise it won't exist. ==== Alternatively, you can also retrieve the (composite) analyzers for a whole index. -These analyzers behaves differently for each field, +These analyzers behave differently for each field, delegating to the analyzer configured in the mapping for each field. .Retrieving the Lucene analyzers for a whole index diff --git a/documentation/src/main/asciidoc/reference/concepts.asciidoc b/documentation/src/main/asciidoc/reference/concepts.asciidoc index 5e4d46de6f1..f0b9b17dd0f 100644 --- a/documentation/src/main/asciidoc/reference/concepts.asciidoc +++ b/documentation/src/main/asciidoc/reference/concepts.asciidoc @@ -191,7 +191,7 @@ when the backend decides to refresh the index reader. This behavior can be customized by setting a different <>. * The <> will not require any commit or refresh until the very end of mass indexing, -so as to maximize indexing throughput. +to maximize indexing throughput. * Whenever there are no particular commit or refresh requirements, backend defaults will apply: ** See <>. @@ -210,7 +210,7 @@ After a refresh, *all* changes to the index are taken into account: those committed to the index, but also those that are still buffered in the index writer. For this reason, commits and refreshes can be treated as completely orthogonal concepts: -certain setups will occasionally lead to committed changes not being be visible in search queries, +certain setups will occasionally lead to committed changes not being visible in search queries, while others will allow even uncommitted changes to be visible in search queries. ==== diff --git a/documentation/src/main/asciidoc/reference/configuration.asciidoc b/documentation/src/main/asciidoc/reference/configuration.asciidoc index e84f3df6875..93963b113af 100644 --- a/documentation/src/main/asciidoc/reference/configuration.asciidoc +++ b/documentation/src/main/asciidoc/reference/configuration.asciidoc @@ -118,7 +118,7 @@ Here are the definitions of all property types. or a reference by type as a `java.lang.Class` (see <>) |See <> -|Multi-valued bean reference of type T +|Multivalued bean reference of type T |A `java.util.Collection` containing bean references (see above) |Comma-separated string containing bean references (see above) |=============== @@ -173,7 +173,7 @@ property to `ignore`. [[configuration-bean]] == Beans -Hibernate Search allows to plug in references to custom beans in various places: +Hibernate Search allows plugging in references to custom beans in various places: configuration properties, mapping annotations, arguments to APIs, ... This section describes <>, @@ -210,7 +210,7 @@ the type is implicitly set to whatever interface Hibernate Search expects for th ==== For experienced users, Hibernate Search also provides the `org.hibernate.search.engine.environment.bean.BeanReference` type, which is accepted in configuration properties and APIs. -This interface allows to plug in custom instantiation and cleanup code. +This interface allows plugging in custom instantiation and cleanup code. See the javadoc of this interface for details. ==== @@ -265,7 +265,7 @@ the reference is resolved using the DI framework (see <>, -resolves to any bean known from CDI/Spring of type `IndexLayoutStrategy` and annotated with `@Named("myShardinStrategy")`. +resolves to any bean known from CDI/Spring of type `IndexLayoutStrategy` and annotated with `@Named("myLayoutStrategy")`. ** Otherwise, if a name is given, and that name is a fully-qualified class name, and a managed bean of that type exists, that bean is used. + diff --git a/documentation/src/main/asciidoc/reference/coordination.asciidoc b/documentation/src/main/asciidoc/reference/coordination.asciidoc index 1e6d1c36211..d565ebe7bd5 100644 --- a/documentation/src/main/asciidoc/reference/coordination.asciidoc +++ b/documentation/src/main/asciidoc/reference/coordination.asciidoc @@ -117,7 +117,7 @@ this behavior means that <>. + [[mapper-orm-indexing-automatic-concepts-notransaction-flush]] -NOTE: When entity changes happen outside of any transaction (not recommended), +NOTE: When entity changes happen outside any transaction (not recommended), indexes are updated immediately upon session `flush()`. Without that flush, indexes will not be updated automatically. [[coordination-none-indexing-visibility]] @@ -194,7 +194,7 @@ Indexing happens in a background thread:: When a Hibernate ORM session is flushed, Hibernate Search will persist entity change events within the same Hibernate ORM session and the same transaction. + -A <> polls the database for new entity change events, +An <> polls the database for new entity change events, and asynchronously performs reindexing of the appropriate entities when it finds new events (i.e. after the transaction is committed). + @@ -214,7 +214,7 @@ The background processor responsible for reindexing entities does not have access to the state of the link:{hibernateDocUrl}#best-practices-caching[first level cache] when the entity change occurred, because it occurred in a different session. + -This means each time an entity changes and has to be reindexed, +This means each time an entity changes and has to be re-indexed, the background process will load that entity in full. Depending on your mapping, it may also need to load lazy associations to other entities. + @@ -238,7 +238,7 @@ and that the indexes will be updated accordingly, but only when (if) the transaction succeeds. + [[coordination-outbox-polling-indexing-guarantee-notransaction]] -NOTE: When entity changes happen outside of any transaction (not recommended), +NOTE: When entity changes happen outside any transaction (not recommended), events indexes are sent immediately after the session `flush()`. Without that flush, indexes will not be updated automatically. [[coordination-outbox-polling-indexing-visibility]] @@ -332,7 +332,7 @@ For more details about dynamic and static sharding, see the following sections. Among agents of the `outbox-polling` coordination strategy executing in the background, the most important one is the event processor: it polls the outbox table for events -and then reindexes the corresponding entities when new events are found. +and then re-indexes the corresponding entities when new events are found. The event processor can be configured using the following configuration properties: diff --git a/documentation/src/main/asciidoc/reference/getting-started.asciidoc b/documentation/src/main/asciidoc/reference/getting-started.asciidoc index 2af32a49746..580330504ca 100644 --- a/documentation/src/main/asciidoc/reference/getting-started.asciidoc +++ b/documentation/src/main/asciidoc/reference/getting-started.asciidoc @@ -75,7 +75,7 @@ make sure to check out the http://hibernate.org/search/documentation/migrate/[mi ==== **To Hibernate Search 5 users** -If you pull our artifacts from a Maven repository and you come from Hibernate Search 5, +If you pull our artifacts from a Maven repository, and you come from Hibernate Search 5, be aware that just bumping the version number will not be enough. In particular, the group IDs changed from `org.hibernate` to `org.hibernate.search`, @@ -148,7 +148,7 @@ you still have problems (e.g. `NoClassDefFoundError`) with some of Hibernate Sea look for the version of that dependency in https://search.maven.org/artifact/org.springframework.boot/spring-boot-dependencies/{testSpringBootVersion}/pom[Spring Boot's POM] and https://search.maven.org/artifact/org.hibernate.search/hibernate-search-parent/{hibernateSearchVersion}/pom[Hibernate Search's POM]: -there will probably be a mistmatch, +there will probably be a mismatch, and generally overriding Spring Boot's version to match Hibernate Search's version will work fine. ==== @@ -200,7 +200,7 @@ link:http://sourceforge.net/projects/hibernate/files/hibernate-search/{hibernate In order to use Hibernate Search, you will need at least two direct dependencies: * a dependency to the "mapper", which extracts data from your domain model and maps it to indexable documents; -* and a dependency to the "backend", which allows to index and search these documents. +* and a dependency to the "backend", which allows indexing and searching these documents. Below are the most common setups and matching dependencies for a quick start; read <> for more information. @@ -353,7 +353,7 @@ Here, the `Author` class defines a single indexed field, `name`. Thus adding `@IndexedEmbedded` to the `authors` property of `Book` will add a single field named `authors.name` to the `Book` index. This field will be populated automatically based on the content of the `authors` property, -and the books will be reindexed automatically whenever the `name` property of their author changes. +and the books will be re-indexed automatically whenever the `name` property of their author changes. See <> for more information. <7> Entities that are only `@IndexedEmbedded` in other entities, but do not require to be searchable by themselves, do not need to be annotated with `@Indexed`. @@ -429,7 +429,7 @@ TIP: If no data is initially present in the database, mass indexing is not neces Hibernate Search will transparently index every entity persisted, updated or removed through Hibernate ORM. -Thus this code would transparently populate your index: +Thus, this code would transparently populate your index: .Using Hibernate ORM to persist data, and implicitly indexing it through Hibernate Search ==== @@ -642,7 +642,7 @@ include::{sourcedir}/org/hibernate/search/documentation/gettingstarted/withhsear and set the `analyzer` parameter to the name of the custom analyzer configured earlier. ==== -That's it! Now, once the entities will be reindexed, you will be able to search for the terms +That's it! Now, once the entities will be re-indexed, you will be able to search for the terms "Refactor", "refactors", "refactored" or "refactoring", and the book entitled "Refactoring: Improving the Design of Existing Code" will show up in the results. @@ -688,7 +688,7 @@ When querying, you will probably want to know more about You can also have a look at sample applications: -* The <> give an idea of how data flows inside and outside of a Hibernate Search application. +* The <> give an idea of how data flows inside and outside a Hibernate Search application. * The link:https://github.com/quarkusio/quarkus-quickstarts/tree/main/hibernate-search-orm-elasticsearch-quickstart[Quarkus quickstart], a sample application using Hibernate Search with the [Quarkus](https://quarkus.io/) framework. * The link:https://github.com/hibernate/hibernate-search/tree/main/integrationtest/showcase/library["Library" showcase], diff --git a/documentation/src/main/asciidoc/reference/limitations.asciidoc b/documentation/src/main/asciidoc/reference/limitations.asciidoc index 22affe561ad..a60ce318b84 100644 --- a/documentation/src/main/asciidoc/reference/limitations.asciidoc +++ b/documentation/src/main/asciidoc/reference/limitations.asciidoc @@ -11,7 +11,7 @@ With the default settings (<>), if two entity instances are <> in the same "index-embedding" entity, and these two entity instance are updated in parallel transactions, there is a small risk that the transaction commits happen in just the wrong way, -leading to the index-embedding entity being reindexed with only part of the updates. +leading to the index-embedding entity being re-indexed with only part of the updates. For example, consider indexed entity A, which index-embeds B and C. The following course of events involving two parallel transactions (T1 and T2) @@ -154,13 +154,13 @@ One can just set `B.a` to `null` in order to remove the association between `A` and the effect on the database will be exactly what we want. However, Hibernate Search will only be able to detect that `B.a` changed, -and by the time it tries to infer which entities need to be reindexed, +and by the time it tries to infer which entities need to be re-indexed, it will no longer be able to know what `B.a` used to refer to. That change in itself is useless to Hibernate Search: -Hibernate Search will not know that `A`, specifically, needs to be reindexed. +Hibernate Search will not know that `A`, specifically, needs to be re-indexed. It will "forget" to reindex `A`, leading to an out-of-sync index where `A.b` still contains `B`. -In the end, the only way for Hibernate Search to know that `A` needs to be reindexed +In the end, the only way for Hibernate Search to know that `A` needs to be re-indexed is to also set `A.b` to `null`, which will cause Hibernate Search to detect that `A.b` changed, and thus that `A` changed too. @@ -199,7 +199,7 @@ but is long-term goal. When <> is enabled, Hibernate Search collects entity change events to build an "indexing plan" inside the ORM `EntityManager`/`Session`. -The indexing plan holds information relative to which entities need to be reindexed, +The indexing plan holds information relative to which entities need to be re-indexed, and sometimes documents that have not been indexed yet. The indexing plan cannot be serialized. diff --git a/documentation/src/main/asciidoc/reference/mapper-orm-bridge-basics.asciidoc b/documentation/src/main/asciidoc/reference/mapper-orm-bridge-basics.asciidoc index a707ad1c298..1b0b1097ca2 100644 --- a/documentation/src/main/asciidoc/reference/mapper-orm-bridge-basics.asciidoc +++ b/documentation/src/main/asciidoc/reference/mapper-orm-bridge-basics.asciidoc @@ -8,7 +8,7 @@ For example, when `@GenericField` is applied to a property of a custom enum type a built-in bridge will be used to convert this enum to a string when indexing, and to convert the string back to an enum when projecting. -Similarly, when a entity identifier of type `Long` is mapped to a document identifier, +Similarly, when an entity identifier of type `Long` is mapped to a document identifier, a built-in bridge will be used to convert the `Long` to a `String` (since all document identifiers are strings) when indexing, @@ -21,7 +21,7 @@ to a single field, is backed by another built-in bridge. While built-in bridges are provided for a wide range of standard types, they may not be enough for complex models. -This is why bridges are really interesting: +This is why bridges are really useful: it is possible to implement custom bridges and to refer to them in the Hibernate Search mapping. Using custom bridges, custom types can be mapped, even complex types that require user code to execute at indexing time. diff --git a/documentation/src/main/asciidoc/reference/mapper-orm-bridge-bridgeelement-dependencies.asciidoc b/documentation/src/main/asciidoc/reference/mapper-orm-bridge-bridgeelement-dependencies.asciidoc index b1f29921104..4e309b62dbc 100644 --- a/documentation/src/main/asciidoc/reference/mapper-orm-bridge-bridgeelement-dependencies.asciidoc +++ b/documentation/src/main/asciidoc/reference/mapper-orm-bridge-bridgeelement-dependencies.asciidoc @@ -25,9 +25,9 @@ and declares a dependency to the paper author's last name and first name. include::{sourcedir}/org/hibernate/search/documentation/mapper/orm/bridge/dependencies/simple/AuthorFullNameBinder.java[tags=binder] ---- <1> Start the declaration of dependencies. -<2> Declare that the bridge will acess the paper's `author` property, +<2> Declare that the bridge will access the paper's `author` property, then the author's `firstName` property. -<3> Declare that the bridge will acess the paper's `author` property, +<3> Declare that the bridge will access the paper's `author` property, then the author's `lastName` property. ==== @@ -57,8 +57,8 @@ and that association has no inverse side in the other entity, an exception will + For example, when you declare a dependency to path `author.lastName`, Hibernate Search infers that whenever the last name of an author changes, -its books need to be reindexed. -Thus when it detects an author's last name changed, Hibernate Search will need to retrieve the books to reindex them. +its books need to be re-indexed. +Thus, when it detects an author's last name changed, Hibernate Search will need to retrieve the books to reindex them. That's why the `author` association in entity `ScientificPaper` needs to have an inverse side in entity `Author`, e.g. a `books` association. + diff --git a/documentation/src/main/asciidoc/reference/mapper-orm-bridge-index-field-dsl.asciidoc b/documentation/src/main/asciidoc/reference/mapper-orm-bridge-index-field-dsl.asciidoc index de912563465..95d7a7519e0 100644 --- a/documentation/src/main/asciidoc/reference/mapper-orm-bridge-index-field-dsl.asciidoc +++ b/documentation/src/main/asciidoc/reference/mapper-orm-bridge-index-field-dsl.asciidoc @@ -69,22 +69,22 @@ include::{sourcedir}/org/hibernate/search/documentation/mapper/orm/bridge/docume ==== [[mapper-orm-bridge-index-field-dsl-multi-valued-fields]] -== [[_multi_valued_fields]] Multi-valued fields +== [[_multi_valued_fields]] Multivalued fields Fields are considered single-valued by default: if you attempt to add multiple values to a single-valued field during indexing, an exception will be thrown. In order to add multiple values to a field, -this field must be marked as multi-valued during its declaration: +this field must be marked as multivalued during its declaration: -.Declaring a field as multi-valued +.Declaring a field as multivalued ==== [source, JAVA, indent=0, subs="+callouts"] ---- include::{sourcedir}/org/hibernate/search/documentation/mapper/orm/bridge/document/model/dsl/simple/MultiValuedNamesBinder.java[tags=bind] ---- -<1> Declare the field as multi-valued. +<1> Declare the field as multivalued. ==== [[mapper-orm-bridge-index-field-dsl-object]] @@ -99,7 +99,7 @@ string, integer, date, ... * Object fields, which hold a composite value. Object fields are declared similarly to value fields, -with an additional step to declare each sub-field, +with an additional step to declare each subfield, as shown below. .Declaring an object field @@ -111,23 +111,23 @@ include::{sourcedir}/org/hibernate/search/documentation/mapper/orm/bridge/docume <1> Declare an object field with `objectField`, passing its name in parameter. <2> Get a reference to the declared object field and pass it to the bridge for later use. -<3> Create sub-fields, get references to these fields +<3> Create subfields, get references to these fields and pass them to the bridge for later use. ==== [NOTE] ==== -The sub-fields of an object field can include object fields. +The subfields of an object field can include object fields. ==== [NOTE] ==== Just as value fields, object fields are single-valued by default. Be sure to call `.multiValued()` during the object field definition -if you want to make it multi-valued. +if you want to make it multivalued. ==== -Object fields as well as their sub-fields are each assigned a reference, +Object fields as well as their subfields are each assigned a reference, which will be used by the bridge to write to documents, as shown in the example below. @@ -139,7 +139,7 @@ include::{sourcedir}/org/hibernate/search/documentation/mapper/orm/bridge/docume ---- <1> Add an object to the `summary` object field for the current document, and get a reference to that object. -<2> Add a value to the sub-fields for the object we just added. +<2> Add a value to the subfields for the object we just added. Note we're calling `addValue` on the object we just added, not on `target`. ==== @@ -164,10 +164,10 @@ include::{sourcedir}/org/hibernate/search/documentation/mapper/orm/bridge/docume <1> Declare an object field with `objectField`. <2> Define the name of the object field. <3> Define the structure of the object field, here `NESTED`. -<4> Define the object field as multi-valued. +<4> Define the object field as multivalued. <5> Get a reference to the declared object field and pass it to the bridge for later use. -<6> Create sub-fields, get references to these fields +<6> Create subfields, get references to these fields and pass them to the bridge for later use. ==== @@ -184,7 +184,7 @@ The fields, then, are considered _dynamic_. Dynamic fields are not declared on bootstrap, but need to match a field _template_ that is declared on bootstrap. -The template includes the field types and structural information (multi-valued or not, ...), +The template includes the field types and structural information (multivalued or not, ...), but omits the field names. A field template is always declared in a binder: either in a <> diff --git a/documentation/src/main/asciidoc/reference/mapper-orm-bridge-propertybridge.asciidoc b/documentation/src/main/asciidoc/reference/mapper-orm-bridge-propertybridge.asciidoc index 76cd7ab409c..5fabf4c5a73 100644 --- a/documentation/src/main/asciidoc/reference/mapper-orm-bridge-propertybridge.asciidoc +++ b/documentation/src/main/asciidoc/reference/mapper-orm-bridge-propertybridge.asciidoc @@ -57,10 +57,10 @@ See <> for more information about declaring dependencies. <4> Declare the fields that are populated by this bridge. In this case we're creating a `summary` object field, -which will have multiple sub-fields (see below). +which will have multiple subfields (see below). See <> for more information about declaring index fields. -<5> Declare the type of the sub-fields. +<5> Declare the type of the subfields. We're going to index monetary amounts, so we will use a `BigDecimal` type with two digits after the decimal point. See <> @@ -68,9 +68,9 @@ for more information about declaring index field types. <6> Call `context.bridge(...)` to define the property bridge to use, and pass an instance of the bridge. <7> Pass a reference to the `summary` object field to the bridge. -<8> Create a sub-field for the `total` amount of the invoice, -a sub-field for the sub-total for `books`, -and a sub-field for the sub-total for `shipping`. +<8> Create a subfield for the `total` amount of the invoice, +a subfield for the subtotal for `books`, +and a subfield for the subtotal for `shipping`. Pass references to these fields to the bridge. [source, JAVA, indent=0, subs="+callouts"] @@ -94,7 +94,7 @@ Note the `summary` field was declared at the root, so we call `addObject` directly on the `target` argument. <6> Add a value to each of the `summary.total`, `summary.books` and `summary.shipping` fields. -Note the fields were declared as sub-fields of `summary`, +Note the fields were declared as subfields of `summary`, so we call `addValue` on `summaryValue` instead of `target`. [source, JAVA, indent=0, subs="+callouts"] diff --git a/documentation/src/main/asciidoc/reference/mapper-orm-bridge-resolver.asciidoc b/documentation/src/main/asciidoc/reference/mapper-orm-bridge-resolver.asciidoc index 829813e5126..726b9f257bc 100644 --- a/documentation/src/main/asciidoc/reference/mapper-orm-bridge-resolver.asciidoc +++ b/documentation/src/main/asciidoc/reference/mapper-orm-bridge-resolver.asciidoc @@ -18,7 +18,7 @@ which will return an appropriate bridge, or fail if there isn't any. It is possible to customize the bridge resolver, to override existing default bridges (indexing `java.util.Date` differently, for example) -or to define default bridges for additional types (a geo-spatial type from an external library, for example). +or to define default bridges for additional types (a geospatial type from an external library, for example). To that end, define a mapping configurer as explained in <>, then define bridges as shown below: diff --git a/documentation/src/main/asciidoc/reference/mapper-orm-bridge-typebridge.asciidoc b/documentation/src/main/asciidoc/reference/mapper-orm-bridge-typebridge.asciidoc index 97efc1f92f4..c3f41ada90b 100644 --- a/documentation/src/main/asciidoc/reference/mapper-orm-bridge-typebridge.asciidoc +++ b/documentation/src/main/asciidoc/reference/mapper-orm-bridge-typebridge.asciidoc @@ -121,7 +121,7 @@ include::{sourcedir}/org/hibernate/search/documentation/mapper/orm/bridge/typebr Getting the param using the `param` method assumes that the param has been defined. Alternatively it is possible to use `paramOptional` to get the `java.util.Optional` of the param. <2> In the `bind` method, use the value of parameters. -Here use the `sortField` parameter to decide whether to add a additional, sortable field, +Here use the `sortField` parameter to decide whether to add another, sortable field, but we could pass parameters for any purpose: defining the field name, defining a normalizer,custom annotation @@ -173,7 +173,7 @@ include::{sourcedir}/org/hibernate/search/documentation/mapper/orm/bridge/typebr <1> Implement setters in the binder. Alternatively, we could expose a parameterized constructor. <2> In the `bind` method, use the value of parameters. -Here use the `sortField` parameter to decide whether to add a additional, sortable field, +Here use the `sortField` parameter to decide whether to add another, sortable field, but we could pass parameters for any purpose: defining the field name, defining a normalizer,custom annotation diff --git a/documentation/src/main/asciidoc/reference/mapper-orm-bridge-valuebridge.asciidoc b/documentation/src/main/asciidoc/reference/mapper-orm-bridge-valuebridge.asciidoc index 85bf198ec97..ce31ab5f9d9 100644 --- a/documentation/src/main/asciidoc/reference/mapper-orm-bridge-valuebridge.asciidoc +++ b/documentation/src/main/asciidoc/reference/mapper-orm-bridge-valuebridge.asciidoc @@ -65,7 +65,7 @@ but also when parameters to the search DSL < This this is unrelated to the value bridge, +<1> This is unrelated to the value bridge, but necessary in order for Hibernate ORM to store the data correctly in the database. <2> Map the property to an index field. <3> Instruct Hibernate Search to use our custom value bridge. @@ -152,7 +152,7 @@ include::{sourcedir}/org/hibernate/search/documentation/mapper/orm/bridge/valueb ---- include::{sourcedir}/org/hibernate/search/documentation/mapper/orm/bridge/valuebridge/projection/Book.java[tags=include;!getters-setters] ---- -<1> This this is unrelated to the value bridge, +<1> This is unrelated to the value bridge, but necessary in order for Hibernate ORM to store the data correctly in the database. <2> Map the property to an index field. <3> Instruct Hibernate Search to use our custom value bridge. @@ -181,7 +181,7 @@ The bridge may throw exceptions for invalid strings. ---- include::{sourcedir}/org/hibernate/search/documentation/mapper/orm/bridge/valuebridge/indexnullas/Book.java[tags=include;!getters-setters] ---- -<1> This this is unrelated to the value bridge, +<1> This is unrelated to the value bridge, but necessary in order for Hibernate ORM to store the data correctly in the database. <2> Map the property to an index field. <3> Instruct Hibernate Search to use our custom value bridge. @@ -253,7 +253,7 @@ but you are obviously free to implement it in a separate java file. ---- include::{sourcedir}/org/hibernate/search/documentation/mapper/orm/bridge/valuebridge/binder/Book.java[tags=include;!getters-setters] ---- -<1> This this is unrelated to the value bridge, +<1> This is unrelated to the value bridge, but necessary in order for Hibernate ORM to store the data correctly in the database. <2> Map the property to an index field. <3> Instruct Hibernate Search to use our custom value binder. diff --git a/documentation/src/main/asciidoc/reference/mapper-orm-indexing-jsr352.asciidoc b/documentation/src/main/asciidoc/reference/mapper-orm-indexing-jsr352.asciidoc index abcb5a6a6fc..cc4d052f865 100644 --- a/documentation/src/main/asciidoc/reference/mapper-orm-indexing-jsr352.asciidoc +++ b/documentation/src/main/asciidoc/reference/mapper-orm-indexing-jsr352.asciidoc @@ -162,20 +162,20 @@ include::{sourcedir}/org/hibernate/search/documentation/mapper/orm/indexing/Hibe ---- <1> Start building parameters for a mass-indexing job. <2> Define the entity type to be indexed. -<3> Restrict the scope of the job using a HQL restriction. +<3> Restrict the scope of the job using an HQL restriction. <4> Get `JobOperator` form the framework. <5> Start the job. ==== While the full indexing is useful when you perform the very first indexing, or -after extensive changes to your whole database, it may also be time consuming. +after extensive changes to your whole database, it may also be time-consuming. If your want to reindex only part of your data, you need to add restrictions using HQL: they help you to define a customized selection, and only the entities inside that selection will be indexed. A typical use-case is to index the new entities appeared since yesterday. Note that, as detailed below, some features may not be supported depending on the indexing mode. -.Comparaison of each indexing mode +.Comparison of each indexing mode |=== | Indexing mode | Scope | Parallel Indexing @@ -444,6 +444,6 @@ mass indexer: [CAUTION] ==== -If you set the `hibernate.session_factory_name` property in the Hibernate configuration +If you set the `hibernate.session_factory_name` property in the Hibernate configuration, and you don't use JNDI, you will also have to set `hibernate.session_factory_name_is_jndi` to `false`. ==== diff --git a/documentation/src/main/asciidoc/reference/mapper-orm-indexing-manual.asciidoc b/documentation/src/main/asciidoc/reference/mapper-orm-indexing-manual.asciidoc index ce822724c71..f4e0204b07f 100644 --- a/documentation/src/main/asciidoc/reference/mapper-orm-indexing-manual.asciidoc +++ b/documentation/src/main/asciidoc/reference/mapper-orm-indexing-manual.asciidoc @@ -146,7 +146,7 @@ Note we're relying on automatic indexing to index the entity, but this would work just as well if automatic indexing was disabled, only requiring an extra call to index the entity. See <>. -<4> After after a `flush()`/`clear()`, call `indexingPlan.execute()`. +<4> After a `flush()`/`clear()`, call `indexingPlan.execute()`. The entities will be processed and *the changes will be sent to the indexes immediately*. Hibernate Search will wait for index changes to be "completed" as required by the configured <>. @@ -248,7 +248,7 @@ Some index operations are not about a specific entity/document, but rather about a large number of documents, possibly all of them. This includes, for example, purging the index to remove all of its content. -The operations are performed *outside* of the context of an ORM session, +The operations are performed *outside* the context of an ORM session, using the `SearchWorkspace` interface. The `SearchWorkspace` can be retrieved from the `SearchMapping`, diff --git a/documentation/src/main/asciidoc/reference/mapper-orm-indexing-massindexer.asciidoc b/documentation/src/main/asciidoc/reference/mapper-orm-indexing-massindexer.asciidoc index dc3abe1d895..7ded0d0ec6a 100644 --- a/documentation/src/main/asciidoc/reference/mapper-orm-indexing-massindexer.asciidoc +++ b/documentation/src/main/asciidoc/reference/mapper-orm-indexing-massindexer.asciidoc @@ -57,14 +57,14 @@ or to commit a transaction after it is done. ==== A note to MySQL users: the `MassIndexer` uses forward only scrollable results to iterate on the primary keys to be loaded, -but MySQL's JDBC driver will pre-load all values in memory. +but MySQL's JDBC driver will preload all values in memory. To avoid this "optimization" set the <> to `Integer.MIN_VALUE`. ==== You can also select entity types when creating a mass indexer, -so as to reindex only these types (and their indexed subtypes, if any): +to reindex only these types (and their indexed subtypes, if any): .Reindexing selected types using a `MassIndexer` ==== @@ -209,7 +209,7 @@ otherwise, you will end up with duplicates in the index. |`mergeSegmentsAfterPurge(boolean)` |`true` |Force merging of each index into a single segment after the initial index purge, just before indexing. -This setting has no effect if {@code purgeAllOnStart} is set to false. +This setting has no effect if `purgeAllOnStart` is set to false. |`mergeSegmentsOnFinish(boolean)` |`false` @@ -339,11 +339,11 @@ for the parameters that affect parallelism: Should probably be a low value, like 1 or 2, depending on how much of your CPUs have spare cycles and how slow a database round trip will be. `threadsToLoadObjects`:: -Higher increases the pre-loading rate for the picked entities from +Higher increases the preloading rate for the picked entities from the database, but also increases memory usage and the pressure on the threads working on subsequent indexing. Note that each thread will extract data from the entity to reindex, -which depending on your mapping might require to access lazy associations +which depending on your mapping might require accessing lazy associations and load associated entities, thus making blocking calls to the database, so you will probably need a high number of threads working in parallel. diff --git a/documentation/src/main/asciidoc/reference/mapper-orm-mapping-changes.asciidoc b/documentation/src/main/asciidoc/reference/mapper-orm-mapping-changes.asciidoc index 3c5a88e1d63..2feb614bc29 100644 --- a/documentation/src/main/asciidoc/reference/mapper-orm-mapping-changes.asciidoc +++ b/documentation/src/main/asciidoc/reference/mapper-orm-mapping-changes.asciidoc @@ -8,7 +8,7 @@ i.e. its _schema_. Hibernate Search does *not* handle this structure change automatically, so manual intervention is required. -The simplest solution when the index structure needs to change is to simply: +The simplest solution when the index structure needs to change is to: 1. Drop and re-create the index and its schema, either manually by deleting the filesystem directory for Lucene diff --git a/documentation/src/main/asciidoc/reference/mapper-orm-mapping-containerextractor.asciidoc b/documentation/src/main/asciidoc/reference/mapper-orm-mapping-containerextractor.asciidoc index 0a585870d52..a93850c4194 100644 --- a/documentation/src/main/asciidoc/reference/mapper-orm-mapping-containerextractor.asciidoc +++ b/documentation/src/main/asciidoc/reference/mapper-orm-mapping-containerextractor.asciidoc @@ -36,7 +36,7 @@ in `org.hibernate.search.mapper.pojo.extractor.builtin.BuiltinContainerExtractor ---- include::{sourcedir}/org/hibernate/search/documentation/mapper/orm/containerextractor/Book.java[tags=explicit-extractor] ---- -<1> This annotation, and those below, are just Hibernate ORM configuration. +<1> This annotation -- and those below -- are just Hibernate ORM configuration. <2> Declare an index field based on the `priceByFormat` property. <3> By default, Hibernate Search would index the map values (the book prices). This uses the `extraction` attribute to specify that map keys (the book formats) diff --git a/documentation/src/main/asciidoc/reference/mapper-orm-mapping-directfieldmapping.asciidoc b/documentation/src/main/asciidoc/reference/mapper-orm-mapping-directfieldmapping.asciidoc index c7099ffea0f..f3bbdddd64c 100644 --- a/documentation/src/main/asciidoc/reference/mapper-orm-mapping-directfieldmapping.asciidoc +++ b/documentation/src/main/asciidoc/reference/mapper-orm-mapping-directfieldmapping.asciidoc @@ -71,8 +71,8 @@ match fields regardless of case, match fields ignoring diacritics, ... + -Full-text fields should assigned an <>, referenced by its name. -By default the analyzer named `default` will be used. +Full-text fields should be assigned an <>, referenced by its name. +By default, the analyzer named `default` will be used. See <> for more details about analyzers and full-text analysis. + Note you can also define <> @@ -180,7 +180,7 @@ Disabled by default. + [IMPORTANT] ==== -The replacement is defined as a String. Thus its value has to be parsed. +The replacement is defined as a String. Thus, its value has to be parsed. Look up the column _Parsing method for 'indexNullAs'_ in <> to find out the format used when parsing. ==== @@ -257,7 +257,7 @@ Only available on `@ScaledNumberField`. To index numbers that have significant digits after the decimal point, set the `decimalScale` to the number of digits you need indexed. The decimal point will be shifted that many times to the right before indexing, preserving that many digits from the decimal part. To index very large numbers that cannot fit in a long, set the decimal point to a negative value. -The decimal point will shifted that many times to the left before indexing, dropping all digits from the decimal part. +The decimal point will be shifted that many times to the left before indexing, dropping all digits from the decimal part. + `decimalScale` with strictly positive values is allowed only for `BigDecimal`, since `BigInteger` values have no decimal digits. + diff --git a/documentation/src/main/asciidoc/reference/mapper-orm-mapping-geopoint.asciidoc b/documentation/src/main/asciidoc/reference/mapper-orm-mapping-geopoint.asciidoc index 87fa8de97de..c3e11e23994 100644 --- a/documentation/src/main/asciidoc/reference/mapper-orm-mapping-geopoint.asciidoc +++ b/documentation/src/main/asciidoc/reference/mapper-orm-mapping-geopoint.asciidoc @@ -105,7 +105,7 @@ include::{sourcedir}/org/hibernate/search/documentation/mapper/orm/spatial/geopo ---- include::{sourcedir}/org/hibernate/search/documentation/mapper/orm/spatial/geopointbinding/property/Author.java[tags=include;!getters-setters] ---- -<1> Model the geo-point as an embeddable. +<1> Model the geo-point as embeddable. An entity would work as well. <2> In the geo-point type, apply `@Latitude` to the property holding the latitude. <3> In the geo-point type, apply `@Longitude` to the property holding the longitude. diff --git a/documentation/src/main/asciidoc/reference/mapper-orm-mapping-identifiermapping.asciidoc b/documentation/src/main/asciidoc/reference/mapper-orm-mapping-identifiermapping.asciidoc index 17dada1321a..2a08bf5d82c 100644 --- a/documentation/src/main/asciidoc/reference/mapper-orm-mapping-identifiermapping.asciidoc +++ b/documentation/src/main/asciidoc/reference/mapper-orm-mapping-identifiermapping.asciidoc @@ -111,7 +111,7 @@ using seconds and nanoseconds only (e.g. `PT1.000000123S`). |- |java.time.YearMonth |Formatted according to the https://en.wikipedia.org/wiki/ISO_8601#Calendar_dates[ISO 8601 format for a Year-Month] -(e.g. `2017-11` for November, 2017). +(e.g. `2017-11` for November 2017). |- |java.time.MonthDay |Formatted according to the https://en.wikipedia.org/wiki/ISO_8601#Calendar_dates[ISO 8601 format for a Month-Day] diff --git a/documentation/src/main/asciidoc/reference/mapper-orm-mapping-indexedembedded.asciidoc b/documentation/src/main/asciidoc/reference/mapper-orm-mapping-indexedembedded.asciidoc index 37bec7f71b3..a0d1fe167d6 100644 --- a/documentation/src/main/asciidoc/reference/mapper-orm-mapping-indexedembedded.asciidoc +++ b/documentation/src/main/asciidoc/reference/mapper-orm-mapping-indexedembedded.asciidoc @@ -78,7 +78,7 @@ map that identifier to a field explicitly using `@GenericField` or another `@*Fi ==== When `@IndexedEmbedded` is applied to an association, i.e. to a property that refers to entities (like the example above), -*the association must be bi-directional*. +*the association must be bidirectional*. Otherwise, Hibernate Search will throw an exception on startup. See <> for the reasons behind this restriction @@ -87,7 +87,7 @@ and ways to circumvent it. Index-embedding can be nested on multiple levels; for example you can decide to index-embed the place of birth of authors, -so as to be able to search for books written by Russian authors exclusively: +to be able to search for books written by Russian authors exclusively: [[example-nested-index-embedded]] .Nesting multiple `@IndexedEmbedded` @@ -229,7 +229,7 @@ When the "embedded" entity changes, Hibernate Search will handle reindexing of the "embedding" entity. This will work transparently most of the time, -as long as the association `@IndexedEmbedded` is applied to is bi-directional +as long as the association `@IndexedEmbedded` is applied to is bidirectional (uses Hibernate ORM's `mappedBy`). When Hibernate Search is unable to handle an association, @@ -274,10 +274,10 @@ The number of levels of indexed-embedded that will have all their fields include and for which all fields of the indexed-embedded element will be included, even if these fields are not included explicitly through `includePaths`: + - * `includeDepth=0` means fields of the indexed-embedded element are *not* included, + * `includeDepth=0` means that fields of the indexed-embedded element are *not* included, nor is any field of nested indexed-embedded elements, unless these fields are included explicitly through `includePaths`. - * `includeDepth=1` means fields of the indexed-embedded element *are* included, + * `includeDepth=1` means that fields of the indexed-embedded element *are* included, but *not* fields of nested indexed-embedded elements, unless these fields are included explicitly through `includePaths`. * And so on. @@ -342,17 +342,17 @@ This mapping will declare the following fields in the `Human` index: (so `parents.parents.*` is included implicitly). * `parents.parents.parents.name`: *not* implicitly included at depth `2` because `includeDepth = 2` (so `parents.parents.parents` is included implicitly, -but sub-fields can only be included explicitly) +but subfields can only be included explicitly) but explicitly included because `includePaths` on `parents` includes `parents.parents.name`. The following fields in particular are excluded: * `parents.parents.parents.nickname`: *not* implicitly included at depth `2` because `includeDepth = 2` -(so `parents.parents.parents` is included implicitly, but sub-fields must be included explicitly) +(so `parents.parents.parents` is included implicitly, but subfields must be included explicitly) and *not* explicitly included either because `includePaths` on `parents` does not include `parents.parents.nickname`. * `parents.parents.parents.parents.name`: *not* implicitly included at depth `3` because `includeDepth = 2` (so `parents.parents.parents` is included implicitly, -but `parents.parents.parents.parents` and sub-fields can only be included explicitly) +but `parents.parents.parents.parents` and subfields can only be included explicitly) and *not* explicitly included either because `includePaths` on `parents` does not include `parents.parents.parents.name`. [source, JAVA, indent=0, subs="+callouts"] @@ -371,7 +371,7 @@ assuming the class `Book` is annotated with `@Indexed` and its `authors` property is annotated with `@IndexedEmbedded`: * Book instance -** title = Levianthan Wakes +** title = Leviathan Wakes ** authors = *** Author instance **** firstName = Daniel @@ -389,7 +389,7 @@ meaning that the tree structure is not preserved. The book instance mentioned above would be indexed with a structure roughly similar to this: * Book document - ** title = Levianthan Wakes + ** title = Leviathan Wakes ** authors.firstName = [Daniel, Ty] ** authors.lastName = [Abraham, Frank] @@ -414,7 +414,7 @@ for each indexed-embedded element. The book instance mentioned above would be indexed with a structure roughly similar to this: * Book document - ** title = Levianthan Wakes + ** title = Leviathan Wakes ** Nested documents *** Nested document #1 for "authors" **** authors.firstName = Daniel diff --git a/documentation/src/main/asciidoc/reference/mapper-orm-mapping-programmatic.asciidoc b/documentation/src/main/asciidoc/reference/mapper-orm-mapping-programmatic.asciidoc index bb8efc0f3f2..2d7cc61502b 100644 --- a/documentation/src/main/asciidoc/reference/mapper-orm-mapping-programmatic.asciidoc +++ b/documentation/src/main/asciidoc/reference/mapper-orm-mapping-programmatic.asciidoc @@ -6,7 +6,7 @@ Most examples in this documentation use annotation-based mapping, which is generally enough for most applications. -However, some applications have needs that go beyond the what annotations can offer: +However, some applications have needs that go beyond what annotations can offer: * a single entity type must be mapped differently for different deployments -- e.g. for different customers. * many entity types must be mapped similarly, without code duplication. diff --git a/documentation/src/main/asciidoc/reference/mapper-orm-mapping-reindexing.asciidoc b/documentation/src/main/asciidoc/reference/mapper-orm-mapping-reindexing.asciidoc index 57b65da15cc..d929152736b 100644 --- a/documentation/src/main/asciidoc/reference/mapper-orm-mapping-reindexing.asciidoc +++ b/documentation/src/main/asciidoc/reference/mapper-orm-mapping-reindexing.asciidoc @@ -31,10 +31,10 @@ and that document must include the `name` property of the `Author` entity Hibernate Search will need to track changes to the author's name, and whenever that happens, it will need to _retrieve all the books of that author_, -so as to reindex these books automatically. +to reindex these books automatically. In practice, this means that whenever an entity mapping relies on an association to another entity, -this association must be bi-directional: +this association must be bidirectional: if `Book.authors` is `@IndexedEmbedded`, Hibernate Search must be aware of an inverse association `Author.books`. An exception will be thrown on startup if the inverse association cannot be resolved. @@ -45,7 +45,7 @@ to resolve the inverse side of an association, so this is all handled transparently. In some rare cases, with the more complex mappings, -it is possible that even Hibernate ORM is not aware that an association is bi-directional, +it is possible that even Hibernate ORM is not aware that an association is bidirectional, because `mappedBy` cannot be used. A few solutions exist: @@ -54,7 +54,7 @@ This means the index will be out of date whenever associated entities change, but this can be an acceptable solution if the index is rebuilt periodically. See <> for more information. -* If the association is actually bi-directional, +* If the association is actually bidirectional, its inverse side can be specified to Hibernate Search explicitly using `@AssociationInverseSide`. See <> for more information. @@ -66,7 +66,7 @@ Given an association from an entity type `A` to entity type `B`, `@AssociationInverseSide` defines the inverse side of an association, i.e. the path from `B` to `A`. -This is mostly useful when a bi-directional association +This is mostly useful when a bidirectional association is not mapped as such in Hibernate ORM (no `mappedBy`). .Mapping the inverse side of an association with `@AssociationInverseSide` @@ -83,7 +83,7 @@ include::{sourcedir}/org/hibernate/search/documentation/mapper/orm/reindexing/as where the keys are `BookEdition` entities and the values are the price of that edition. <2> Index-embed the editions that are actually for sale. <3> In Hibernate ORM, it is not possible to use `mappedBy` for an association modeled by a `Map` key. -Thus we use `@AssociationInverseSide` to tell Hibernate Search what the inverse side +Thus, we use `@AssociationInverseSide` to tell Hibernate Search what the inverse side of this association is. <4> We could have applied the `@AssociationInverseSide` annotation here instead: either side will do. @@ -162,7 +162,7 @@ include::{sourcedir}/org/hibernate/search/documentation/mapper/orm/reindexing/re There are potentially thousands of books for each category, so calling a `getBooks()` method would lead to loading thousands of entities into the Hibernate ORM session at once, and would perform badly. -Thus there isn't any `getBooks()` method to list all books in a category. +Thus, there isn't any `getBooks()` method to list all books in a category. ==== With this mapping, Hibernate Search will not be able to reindex all books when the category name changes: @@ -187,7 +187,7 @@ See the modified mapping below: include::{sourcedir}/org/hibernate/search/documentation/mapper/orm/reindexing/reindexonupdate/shallow/correct/Book.java[tags=include;!getters-setters] ---- <1> We use `ReindexOnUpdate.SHALLOW` to tell Hibernate Search that `Book` -should be reindexed automatically when it's assigned a new category (`book.setCategory( newCategory )`), +should be re-indexed automatically when it's assigned a new category (`book.setCategory( newCategory )`), but not when properties of its category change (`category.setName( newName )`). ==== @@ -264,7 +264,7 @@ Hibernate Search will *not* reindex the sensor automatically. [[mapper-orm-reindexing-programmatic]] == Programmatic mapping -You can control reindexing through through the <> too. +You can control reindexing through the <> too. Behavior and options are identical to annotation-based mapping. .Mapping the inverse side of an association with `.associationInverseSide(...)` diff --git a/documentation/src/main/asciidoc/reference/mapper-orm-schema.asciidoc b/documentation/src/main/asciidoc/reference/mapper-orm-schema.asciidoc index 73444439649..141524e23e9 100644 --- a/documentation/src/main/asciidoc/reference/mapper-orm-schema.asciidoc +++ b/documentation/src/main/asciidoc/reference/mapper-orm-schema.asciidoc @@ -167,7 +167,7 @@ This method is synchronous and will only return after the operation is complete. ==== You can also select entity types when creating a schema manager, -so as to manage the indexes of these types only (and their indexed subtypes, if any): +to manage the indexes of these types only (and their indexed subtypes, if any): .Reinitializing only some indexes using a `SearchSchemaManager` ==== diff --git a/documentation/src/main/asciidoc/reference/search-dsl-paths.asciidoc b/documentation/src/main/asciidoc/reference/search-dsl-paths.asciidoc index 2677f4d0484..b78bdf1caec 100644 --- a/documentation/src/main/asciidoc/reference/search-dsl-paths.asciidoc +++ b/documentation/src/main/asciidoc/reference/search-dsl-paths.asciidoc @@ -49,7 +49,7 @@ include::components/incubating-warning.asciidoc[] In some cases, one may want to pass relative paths instead. This can be useful when calling reusable methods that can apply the same predicate -on different object fields that have same structure (same sub-fields). +on different object fields that have same structure (same subfields). By calling the `withRoot(String)` method on a factory, you can create a new factory which interprets paths as relative to the object field passed as argument to the method. diff --git a/documentation/src/main/asciidoc/reference/search-dsl-predicate.asciidoc b/documentation/src/main/asciidoc/reference/search-dsl-predicate.asciidoc index 79e5e793af5..025be2ebacc 100644 --- a/documentation/src/main/asciidoc/reference/search-dsl-predicate.asciidoc +++ b/documentation/src/main/asciidoc/reference/search-dsl-predicate.asciidoc @@ -691,7 +691,7 @@ include::{sourcedir}/org/hibernate/search/documentation/search/predicate/Predica ---- ==== -With `matchingAll` we require that all of the provided terms match. +With `matchingAll` we require that all the provided terms match. Functionally, this is somewhat similar to a <> with one <> predicate per term, but the syntax for a single `terms` predicate is more concise. NOTE: `matchingAll` expects to be passed *terms*, not just any string. The given terms will not be analyzed. See <>. @@ -708,7 +708,7 @@ It is possible to raise this limit through backend-specific configuration: However, keep in mind the limit is there for a reason: attempts to match very large numbers of terms will perform poorly and could lead to crashes. ==== -.Matching all of the provided terms +.Matching all the provided terms ==== [source, JAVA, indent=0, subs="+callouts"] ---- @@ -717,7 +717,7 @@ include::{sourcedir}/org/hibernate/search/documentation/search/predicate/Predica ==== [[search-dsl-predicate-terms-analysis]] -=== Terms predicates and analysis +=== `terms` predicates and analysis NOTE: For an introduction to analysis and how to configure it, refer to the <> section. @@ -833,17 +833,17 @@ they will have a `title` field matching the text `robot` A `bool` predicate with only `must` clauses will behave as an `AND` operator. -.Matching a document that matches all of multiple given predicates (~`AND` operator) +.Matching a document that matches all the multiple given predicates (~`AND` operator) ==== [source, JAVA, indent=0, subs="+callouts"] ---- include::{sourcedir}/org/hibernate/search/documentation/search/predicate/PredicateDslIT.java[tags=bool-and] ---- <1> The hits *must* have a `title` field matching the text `robot`, -independently from other clauses in the same boolean predicate. +independently of other clauses in the same boolean predicate. <2> The hits *must* have a `description` field matching the text `crime`, -independently from other clauses in the same boolean predicate. -<3> All returned hits will match *all* of the clauses above: +independently of other clauses in the same boolean predicate. +<3> All returned hits will match *all* the clauses above: they will have a `title` field matching the text `robot` *and* they will have a `description` field matching the text `crime`. ==== @@ -858,10 +858,10 @@ they will have a `title` field matching the text `robot` include::{sourcedir}/org/hibernate/search/documentation/search/predicate/PredicateDslIT.java[tags=bool-mustNot] ---- <1> The hits *must* have a `title` field matching the text `robot`, -independently from other clauses in the same boolean predicate. +independently of other clauses in the same boolean predicate. <2> The hits *must not* have a `description` field matching the text `investigation`, -independently from other clauses in the same boolean predicate. -<3> All returned hits will match *all* of the clauses above: +independently of other clauses in the same boolean predicate. +<3> All returned hits will match *all* the clauses above: they will have a `title` field matching the text `robot` *and* they will not have a `description` field matching the text `investigation`. @@ -916,7 +916,7 @@ and their only purpose is to increase the score of documents that match these cl include::{sourcedir}/org/hibernate/search/documentation/search/predicate/PredicateDslIT.java[tags=bool-mustAndShould] ---- <1> The hits *must* have a `title` field matching the text `robot`, -independently from other clauses in the same boolean predicate. +independently of other clauses in the same boolean predicate. <2> The hits *should* have a `description` field matching the text `crime`, but they might not, because matching the `must` clause above is enough. However, matching this `should` clause will improve the score of the document. @@ -1198,7 +1198,7 @@ include::{sourcedir}/org/hibernate/search/documentation/search/predicate/Predica ==== NOTE: Other distance units are available, in particular `METERS`, `YARDS` and `MILES`. -When the distance unit is omitted, it defaults to meters. +When the distance unit is omitted, it defaults to `METERS`. You can also pass the coordinates of the center as two doubles (latitude, then longitude). diff --git a/documentation/src/main/asciidoc/reference/search-dsl-projection.asciidoc b/documentation/src/main/asciidoc/reference/search-dsl-projection.asciidoc index a56637bed7a..9814d835320 100644 --- a/documentation/src/main/asciidoc/reference/search-dsl-projection.asciidoc +++ b/documentation/src/main/asciidoc/reference/search-dsl-projection.asciidoc @@ -42,8 +42,8 @@ so that it is correctly stored in the index. While `field` projections are certainly the most common, they are not the only type of projection. -Other projections allow to -<>, +Other projections allow +<>, get references to the <> or the <>, or get information related to the search query itself @@ -155,8 +155,8 @@ include::{sourcedir}/org/hibernate/search/documentation/search/projection/Projec ---- ==== -NOTE: Hibernate Search will throw an exception when building the query if you do this on a multi-valued field. -To project on multi-valued fields, see <>. +NOTE: Hibernate Search will throw an exception when building the query if you do this on a multivalued field. +To project on multivalued fields, see <>. You can omit the "field type" argument, but then you will get projections of type `Object`: @@ -169,13 +169,13 @@ include::{sourcedir}/org/hibernate/search/documentation/search/projection/Projec ==== [[search-dsl-projection-field-multivalued]] -=== Multi-valued fields +=== Multivalued fields -To return multiple values, and thus allow projection on multi-valued fields, use `.multi()`. +To return multiple values, and thus allow projection on multivalued fields, use `.multi()`. This will change the return type of the projection to `List` where `T` is what the single-valued projection would have returned. -.Returning field values from matched documents, for multi-valued fields +.Returning field values from matched documents, for multivalued fields ==== [source, JAVA, indent=0, subs="+callouts"] ---- @@ -259,8 +259,8 @@ include::{sourcedir}/org/hibernate/search/documentation/search/projection/Projec ---- ==== -NOTE: Hibernate Search will throw an exception when building the query if you do this on a multi-valued field. -To project on multi-valued fields, see <>. +NOTE: Hibernate Search will throw an exception when building the query if you do this on a multivalued field. +To project on multivalued fields, see <>. The returned distance is in meters by default, but you can pick a different unit: @@ -273,12 +273,12 @@ include::{sourcedir}/org/hibernate/search/documentation/search/projection/Projec ==== [[search-dsl-projection-distance-multivalued]] -=== Multi-valued fields +=== Multivalued fields -To return multiple values, and thus allow projection on multi-valued fields, use `.multi()`. +To return multiple values, and thus allow projection on multivalued fields, use `.multi()`. This will change the return type of the projection to `List`. -.Returning the distance to a point, for multi-valued fields +.Returning the distance to a point, for multivalued fields ==== [source, JAVA, indent=0, subs="+callouts"] ---- diff --git a/documentation/src/main/asciidoc/reference/search-dsl-query.asciidoc b/documentation/src/main/asciidoc/reference/search-dsl-query.asciidoc index bab5429a9c8..0652932ac80 100644 --- a/documentation/src/main/asciidoc/reference/search-dsl-query.asciidoc +++ b/documentation/src/main/asciidoc/reference/search-dsl-query.asciidoc @@ -107,7 +107,7 @@ expecting those entity types to implement the `Person` interface (Hibernate Sear [[search-dsl-query-fetching-results-basics]] === [[_result_size]] Basics -In Hibernate Search, the default search result is a little bit more complicated than just "a list of hits". +In Hibernate Search, the default search result is a bit more complicated than just "a list of hits". This is why the default methods return a composite `SearchResult` object offering getters to retrieve the part of the result you want, as shown in the example below. @@ -233,7 +233,11 @@ include::{sourcedir}/org/hibernate/search/documentation/search/query/QueryDslIT. When working with large result sets, counting the number of hits exactly can be very resource-consuming. -When sorting by score (the default) and retrieving the result through `fetch(...)`, it is possible to yield significant performance improvements by allowing Hibernate Search to return a lower-bound estimate of the total hit count, instead of the exact total hit count. In that case, the underlying engine (Lucene or Elasticsearch) will be able to skip large chunks of non-competitive hits, leading to fewer index scans and thus better performance. +When sorting by score (the default) and retrieving the result through `fetch(...)`, +it is possible to yield significant performance improvements by allowing Hibernate Search to return +a lower-bound estimate of the total hit count, instead of the exact total hit count. +In that case, the underlying engine (Lucene or Elasticsearch) will be able to skip large chunks of non-competitive hits, +leading to fewer index scans and thus better performance. To enable this performance optimization, call `totalHitCountThreshold(...)` when building the query, as shown in the example below. @@ -444,7 +448,7 @@ then mention that the persistence context and second level cache should be check before entities are loaded from the database. <3> Fetch the results. The more entities found in the persistence context or second level cache, -the less entities will be loaded from the database. +the fewer entities will be loaded from the database. ==== [[search-dsl-query-fetch-size]] @@ -471,7 +475,7 @@ include::{sourcedir}/org/hibernate/search/documentation/search/query/QueryDslIT. <2> Access the loading options of the query, then set the fetch size to an arbitrary value (must be `1` or more). <3> Fetch the results, limiting to the top 200 hits. -One query will be executed to load the hits if there are less hits than the given fetch size; +One query will be executed to load the hits if there are fewer hits than the given fetch size; two queries if there are more hits than the fetch size but less than twice the fetch size, etc. ==== diff --git a/documentation/src/main/asciidoc/reference/search-dsl-sort.asciidoc b/documentation/src/main/asciidoc/reference/search-dsl-sort.asciidoc index 56938e5b672..201718f9d62 100644 --- a/documentation/src/main/asciidoc/reference/search-dsl-sort.asciidoc +++ b/documentation/src/main/asciidoc/reference/search-dsl-sort.asciidoc @@ -120,7 +120,7 @@ For text fields, "lower" means "lower in the alphabetical order". In order for the `field` sort to be available on a given field, you need to mark the field as <> in the mapping. -<> fields cannot be marked as sortable; +<> fields cannot be marked as sortable; refer to the <> for these fields. <> (multi-word text fields) @@ -148,7 +148,7 @@ include::{sourcedir}/org/hibernate/search/documentation/search/sort/SortDslIT.ja but can be <>. * The behavior on missing values can be <>. -* The behavior on multi-valued fields +* The behavior on multivalued fields can be <>. * For fields in nested objects, all nested objects are considered by default, but that can be <>. @@ -183,7 +183,7 @@ include::{sourcedir}/org/hibernate/search/documentation/search/sort/SortDslIT.ja * The sort order is ascending by default, but can be <>. -* The behavior on multi-valued fields +* The behavior on multivalued fields can be <>. * For fields in nested objects, all nested objects are considered by default, but that can be <>. @@ -207,7 +207,7 @@ the relative order of books with the same genre is undetermined, and may change from one query execution to the other. <3> Add a `field` sort on the `title_sort` field. When two books have the same genre, -their relative order will by determined by comparing their titles. +their relative order will be determined by comparing their titles. If two books can have the same title, we can <>. <4> The hits will be sorted by genre, then by title. @@ -377,7 +377,7 @@ By default: * For <>, the documents that do not have any value for a sort field will appear in the last position. * For <>, the documents that do not have any value for a sort field - will be treated as they were at plus infinite distance from the given point. + will be treated as if their distance from the given point was infinite. The behavior for missing values can be controlled explicitly through the `.missing()` option: @@ -387,9 +387,10 @@ The behavior for missing values can be controlled explicitly through the `.missi [NOTE] ==== -All these options are supported in case of sort by field values or in case of sort by distance to a point +All these options are supported for sorts by field values and sorts by distance to a point using the Lucene backend. -In case of sort by distance to a point using the Elasticsearch backend, due to limitations of the Elasticsearch APIs, + +When sorting by distance to a point using the Elasticsearch backend, due to limitations of the Elasticsearch APIs, only the following combinations are supported: * `.missing().first()` using a descending order. @@ -438,7 +439,7 @@ but if you ever need to bypass conversion and pass an unconverted argument to `.use(...)`, see <>. [[search-dsl-sort-common-multi-value-mode]] -=== Sort mode for multi-valued fields +=== Sort mode for multivalued fields Documents that have multiple values for a sort field can be sorted too. A single value is picked for each document in order to compare it with order documents. diff --git a/documentation/src/main/asciidoc/reference/search-dsl-type-compatibility.asciidoc b/documentation/src/main/asciidoc/reference/search-dsl-type-compatibility.asciidoc index e4fa54a3848..3b4c8d297db 100644 --- a/documentation/src/main/asciidoc/reference/search-dsl-type-compatibility.asciidoc +++ b/documentation/src/main/asciidoc/reference/search-dsl-type-compatibility.asciidoc @@ -53,7 +53,7 @@ Then we will not have an `AuthenticationOutcome` instance to pass to the DSL, on In that case, we will first need to assign some text to each enum. This can be achieved by defining a custom <`>> -and applying it to the `outcome` property so as to index a textual description of the outcome, +and applying it to the `outcome` property to index a textual description of the outcome, instead of the default `Enum#name()`. Then, we will need to tell Hibernate Search that the value passed to the DSL should not be passed to the DSL converter, @@ -83,7 +83,7 @@ See <> or <> for [[search-dsl-projected-value-type]] == Type of projected values -Generally the type of values returned by projections argument should be rather obvious: +Generally the type of values returned by projections should be rather obvious: for example if you created a field by mapping an `Integer` property, then an `Integer` value will be returned when projecting; if you mapped a `java.time.LocalDate`, then a `java.time.LocalDate` will be returned, @@ -220,7 +220,7 @@ you will just pass the "index" value to the DSL (using the same example, a `Stri === [[_incompatible_projection_converters]] Incompatible projection converters If, in a search query targeting multiple indexes, -a field is encoded in a compatible way in every indexes (for example both as `String`), +a field is encoded in a compatible way in every index (for example both as `String`), but that has a different projection converters (for example the first one converts from `String` to `String`, but the second one converts from `String` to `Integer`), you can still project on this field, but you will need to disable the projection converter diff --git a/documentation/src/test/java/org/hibernate/search/documentation/mapper/orm/reindexing/derivedfrom/DerivedFromIT.java b/documentation/src/test/java/org/hibernate/search/documentation/mapper/orm/reindexing/derivedfrom/DerivedFromIT.java index 07d5600f0db..dd0b335ccdd 100644 --- a/documentation/src/test/java/org/hibernate/search/documentation/mapper/orm/reindexing/derivedfrom/DerivedFromIT.java +++ b/documentation/src/test/java/org/hibernate/search/documentation/mapper/orm/reindexing/derivedfrom/DerivedFromIT.java @@ -58,7 +58,7 @@ public void setup() { public void smoke() { OrmUtils.withinJPATransaction( entityManagerFactory, entityManager -> { Book book = new Book(); - book.setTitle( "Levianthan Wakes" ); + book.setTitle( "Leviathan Wakes" ); book.getAuthors().add( "Daniel Abraham" ); book.getAuthors().add( "Ty Frank" ); diff --git a/engine/src/main/java/org/hibernate/search/engine/backend/types/ObjectStructure.java b/engine/src/main/java/org/hibernate/search/engine/backend/types/ObjectStructure.java index 05d9593efde..1d3c6466396 100644 --- a/engine/src/main/java/org/hibernate/search/engine/backend/types/ObjectStructure.java +++ b/engine/src/main/java/org/hibernate/search/engine/backend/types/ObjectStructure.java @@ -26,7 +26,7 @@ public enum ObjectStructure { *

* For instance this structure: *

    - *
  • title = Levianthan Wakes
    • + *
  • title = Leviathan Wakes
    • *
  • authors = *
      *
    • (first element) @@ -46,7 +46,7 @@ public enum ObjectStructure { *
    * Will become: *
      - *
    • title = Levianthan Wakes
      • + *
    • title = Leviathan Wakes
      • *
    • authors.firstName = *
        *
      • (first element) Daniel
        • diff --git a/mapper/pojo-base/src/main/java/org/hibernate/search/mapper/pojo/mapping/definition/annotation/IndexedEmbedded.java b/mapper/pojo-base/src/main/java/org/hibernate/search/mapper/pojo/mapping/definition/annotation/IndexedEmbedded.java index 2e05798e3ee..661943c3a8a 100644 --- a/mapper/pojo-base/src/main/java/org/hibernate/search/mapper/pojo/mapping/definition/annotation/IndexedEmbedded.java +++ b/mapper/pojo-base/src/main/java/org/hibernate/search/mapper/pojo/mapping/definition/annotation/IndexedEmbedded.java @@ -52,9 +52,9 @@ * of documents created for {@code Book} entities. *

        * How exactly this embedding will happen depends on the configured {@link #structure() structure}. - * Let's consider this representation of the book "Levianthan Wakes": + * Let's consider this representation of the book "Leviathan Wakes": *

          - *
        • title = Levianthan Wakes
          • + *
        • title = Leviathan Wakes
          • *
        • authors = *
            *
          • (first element) @@ -76,7 +76,7 @@ * With the default {@link ObjectStructure#FLATTENED flattened structure} (more efficient), * the document structure will be a little different from what one would expect: *
              - *
            • title = Levianthan Wakes
              • + *
            • title = Leviathan Wakes
              • *
            • authors.firstName = *
                *
              • (first element) Daniel