Package org.hibernate.search.mapper.pojo.mapping.definition.annotation

Annotation Type IndexedEmbedded

@Documented @Repeatable(List.class) @Target({METHOD,FIELD}) @Retention(RUNTIME) @PropertyMapping(processor=@PropertyMappingAnnotationProcessorRef(type=org.hibernate.search.mapper.pojo.mapping.definition.annotation.processing.impl.IndexedEmbeddedProcessor.class,retrieval=CONSTRUCTOR)) public @interface IndexedEmbedded
Maps a property to an object field whose fields are the same as those defined in the property type.

This allows search queries on a single index to use data from multiple entities.

For example, let's consider this (incomplete) mapping: 


 {@literal @}Indexed
 public class Book {
     {@literal @}GenericField
     private String title;
     {@literal @}IndexedEmbedded
     private List<Author> authors;
 }
 public class Author {
     {@literal @}GenericField
     private String firstName;
     {@literal @}GenericField
     private String lastName;
     private List<Book> books;
 }

The names of authors are stored in different objects, thus by default they would not be included in documents created for Book entities. But we added the @IndexedEmbedded annotation to the authors property, so Hibernate Search will embed this data in a authors field of documents created for Book entities.

How exactly this embedding will happen depends on the configured structure. Let's consider this representation of the book "Leviathan Wakes":

  • title = Leviathan Wakes
  • authors =
    • (first element)
      • firstName = Daniel
      • lastName = Abraham
    • (second element)
      • firstName = Ty
      • lastName = Frank

With the default flattened structure (more efficient), the document structure will be a little different from what one would expect:

  • title = Leviathan Wakes
  • authors.firstName =
    • (first element) Daniel
    • (second element) Ty
  • authors.lastName =
    • (first element) Abraham
    • (second element) Frank

To get the original structure, the nested structure must be used, but this has an impact on performance and how queries must be structured. See the reference documentation for more information.

  • Element Details

    • prefix

      @Deprecated @Search5DeprecatedAPI String prefix
      Deprecated.
      Use name() instead. Note that name() does not allow dots.
      Returns:
      The prefix used when embedding. Defaults to <property name>., meaning an object field with the same name as the property will be defined in the parent document to host the value of the child document. Must not be set if name() is set.
      Default:
      ""

    • name

      String name
      Returns:
      The name of the object field created to represent this @IndexedEmbedded. Defaults to the property name. Must not be set if prefix() is set.
      Default:
      ""

    • includePaths

      String[] includePaths
      The paths of index fields from the indexed-embedded element that should be embedded.

      This takes precedence over includeDepth().

      By default, if none of includePaths, excludePaths or includeDepth() are defined, all index fields are included.

      Cannot be used when excludePaths() contains any paths.

      Returns:
      The paths of index fields to include explicitly. Provided paths must be relative to the indexed-embedded element, i.e. they must not include the name(). Paths must lead to a field and cannot end with some prefix used to construct a field name.
      Default:
      {}

    • excludePaths

      @Incubating String[] excludePaths
      The paths of index fields from the indexed-embedded element that should not be embedded.

      This takes precedence over includeDepth().

      By default, if none of includePaths, excludePaths or includeDepth() are defined, all index fields are included.

      Cannot be used when includePaths() contains any paths.

      Returns:
      The paths of index fields to exclude explicitly. Provided paths must be relative to the indexed-embedded element, i.e. they must not include the name(). Paths must lead to a field and cannot end with some prefix used to construct a field name.
      Default:
      {}

    • includeDepth

      int includeDepth
      The number of levels of indexed-embedded that will have all their fields included by default.

      includeDepth is the number of `@IndexedEmbedded` that will be traversed and for which all fields of the indexed-embedded element will be included, even if these fields are not included explicitly through includePaths, unless these fields are excluded explicitly through excludePaths:

      • includeDepth=0 means fields of this 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 this indexed-embedded element are included, unless these fields are explicitly excluded through excludePaths, but not fields of nested indexed-embedded elements (@IndexedEmbedded within this @IndexedEmbedded), unless these fields are included explicitly through includePaths().
      • includeDepth=2 means fields of this indexed-embedded element are included, and so are fields of the immediately nested indexed-embedded elements (@IndexedEmbedded within this @IndexedEmbedded), unless these fields are explicitly excluded through excludePaths, but not fields of nested indexed-embedded elements beyond that (@IndexedEmbedded within an @IndexedEmbedded within this @IndexedEmbedded), unless these fields are included explicitly through includePaths().
      • And so on.
      The default value depends on the value of includePaths() attributes:
      • if includePaths() is empty, the default is Integer.MAX_VALUE (include all fields at every level)
      • if includePaths() is not empty, the default is 0 (only include fields included explicitly).
      Returns:
      The number of levels of indexed-embedded that will have all their fields included by default.
      Default:
      -1

    • includeEmbeddedObjectId

      boolean includeEmbeddedObjectId
      Whether the identifier of embedded objects should be included as an index field.

      The index field will be defined as if the following annotation was put on the identifier property of the embedded type: @GenericField(searchable = Searchable.YES, projectable = Projectable.YES). The name of the index field will be the name of the identifier property. Its bridge will be the identifier bridge referenced by the embedded type's DocumentId annotation, if any, or the default value bridge for the identifier property's type, by default.

      If you need more advanced mapping (custom name, custom bridge, sortable, ...), define the field explicitly in the embedded type by annotating the identifier property with GenericField or a similar field annotation, and make sure the field is included by @IndexedEmbedded by configuring includeDepth() and/or includePaths().

      Returns:
      Whether the identifier of embedded objects should be included as an index field.
      Default:
      false

    • structure

      ObjectStructure structure
      Returns:
      How the structure of the object field created for this indexed-embedded is preserved upon indexing.
      See Also:
      Default:
      DEFAULT

    • extraction

      ContainerExtraction extraction
      Returns:
      A definition of container extractors to be applied to the property, allowing the definition of an indexed-embedded for container elements. This is useful when the property is of container type, for example a Map<TypeA, TypeB>: defining the extraction as @ContainerExtraction(BuiltinContainerExtractors.MAP_KEY) allows referencing map keys instead of map values. By default, Hibernate Search will try to apply a set of extractors for common container types.
      See Also:
      Default:
      @org.hibernate.search.mapper.pojo.extractor.mapping.annotation.ContainerExtraction

    • targetType

      Class<?> targetType
      Returns:
      A type indexed-embedded elements should be cast to. When relying on container extraction, the extracted values are cast, not the container. By default, no casting occurs.
      Default:
      void.class