DATAES-263 - Inner Hits support. (spring-projects#473)

original PR: spring-projects#473

Author: sothawo

src/main/asciidoc/reference/elasticsearch-operations.adoc

@@ -134,6 +134,7 @@ Contains the following information:
 * Score
 * Sort Values
 * Highlight fields
+* Inner hits (this is an embedded `SearchHits` object containing eventually returned inner hits)
 * The retrieved entity of type <T>
 
 .SearchHits<T>

src/main/java/org/springframework/data/elasticsearch/core/AbstractElasticsearchTemplate.java

@@ -624,7 +624,7 @@ public ReadSearchDocumentResponseCallback(Class<T> type, IndexCoordinates index)
 		@Override
 		public SearchHits<T> doWith(SearchDocumentResponse response) {
 			List<T> entities = response.getSearchDocuments().stream().map(delegate::doWith).collect(Collectors.toList());
-			return SearchHitMapping.mappingFor(type, elasticsearchConverter.getMappingContext()).mapHits(response, entities);
+			return SearchHitMapping.mappingFor(type, elasticsearchConverter).mapHits(response, entities);
 		}
 	}
 
@@ -644,8 +644,7 @@ public ReadSearchScrollDocumentResponseCallback(Class<T> type, IndexCoordinates
 		@Override
 		public SearchScrollHits<T> doWith(SearchDocumentResponse response) {
 			List<T> entities = response.getSearchDocuments().stream().map(delegate::doWith).collect(Collectors.toList());
-			return SearchHitMapping.mappingFor(type, elasticsearchConverter.getMappingContext()).mapScrollHits(response,
-					entities);
+			return SearchHitMapping.mappingFor(type, elasticsearchConverter).mapScrollHits(response, entities);
 		}
 	}
 	// endregion

src/main/java/org/springframework/data/elasticsearch/core/ReactiveElasticsearchTemplate.java

@@ -878,7 +878,7 @@ public ReadSearchDocumentCallback(Class<T> type, IndexCoordinates index) {
 		@Override
 		public Mono<SearchHit<T>> doWith(SearchDocument response) {
 			return delegate.doWith(response)
-					.map(entity -> SearchHitMapping.mappingFor(type, converter.getMappingContext()).mapHit(response, entity));
+					.map(entity -> SearchHitMapping.mappingFor(type, converter).mapHit(response, entity));
 		}
 	}
 

src/main/java/org/springframework/data/elasticsearch/core/SearchHit.java

@@ -23,6 +23,7 @@
 import java.util.Map;
 import java.util.stream.Collectors;
 
+import org.springframework.data.elasticsearch.core.document.NestedMetaData;
 import org.springframework.lang.Nullable;
 import org.springframework.util.Assert;
 
@@ -41,17 +42,32 @@ public class SearchHit<T> {
 	private final List<Object> sortValues;
 	private final T content;
 	private final Map<String, List<String>> highlightFields = new LinkedHashMap<>();
+	private final Map<String, SearchHits<?>> innerHits = new LinkedHashMap<>();
+	@Nullable private final NestedMetaData nestedMetaData;
 
 	public SearchHit(@Nullable String index, @Nullable String id, float score, @Nullable Object[] sortValues,
 			@Nullable Map<String, List<String>> highlightFields, T content) {
+		this(index, id, score, sortValues, highlightFields, null, null, content);
+	}
+
+	public SearchHit(@Nullable String index, @Nullable String id, float score, @Nullable Object[] sortValues,
+			@Nullable Map<String, List<String>> highlightFields, @Nullable Map<String, SearchHits<?>> innerHits,
+			@Nullable NestedMetaData nestedMetaData, T content) {
 		this.index = index;
 		this.id = id;
 		this.score = score;
 		this.sortValues = (sortValues != null) ? Arrays.asList(sortValues) : new ArrayList<>();
+
 		if (highlightFields != null) {
 			this.highlightFields.putAll(highlightFields);
 		}
 
+		if (innerHits != null) {
+			this.innerHits.putAll(innerHits);
+		}
+
+		this.nestedMetaData = nestedMetaData;
+
 		this.content = content;
 	}
 
@@ -90,6 +106,9 @@ public List<Object> getSortValues() {
 		return Collections.unmodifiableList(sortValues);
 	}
 
+	/**
+	 * @return the map from field names to highlight values, never {@literal null}
+	 */
 	public Map<String, List<String>> getHighlightFields() {
 		return Collections.unmodifiableMap(highlightFields.entrySet().stream()
 				.collect(Collectors.toMap(Map.Entry::getKey, entry -> Collections.unmodifiableList(entry.getValue()))));
@@ -108,6 +127,39 @@ public List<String> getHighlightField(String field) {
 		return Collections.unmodifiableList(highlightFields.getOrDefault(field, Collections.emptyList()));
 	}
 
+	/**
+	 * returns the {@link SearchHits} for the inner hits with the given name. If the inner hits could be mapped to a
+	 * nested entity class, the returned data will be of this type, otherwise
+	 * {{@link org.springframework.data.elasticsearch.core.document.SearchDocument}} instances are returned in this
+	 * {@link SearchHits} object.
+	 * 
+	 * @param name the inner hits name
+	 * @return {@link SearchHits} if available, otherwise {@literal null}
+	 */
+	@Nullable
+	public SearchHits<?> getInnerHits(String name) {
+		return innerHits.get(name);
+	}
+
+	/**
+	 * @return the map from inner_hits names to inner hits, in a {@link SearchHits} object, never {@literal null}
+	 * @since 4.1
+	 */
+	public Map<String, SearchHits<?>> getInnerHits() {
+		return innerHits;
+	}
+
+	/**
+	 * If this is a nested inner hit, return the nested metadata information
+	 * 
+	 * @return {{@link NestedMetaData}
+	 * @since 4.1
+	 */
+	@Nullable
+	public NestedMetaData getNestedMetaData() {
+		return nestedMetaData;
+	}
+
 	@Override
 	public String toString() {
 		return "SearchHit{" + "id='" + id + '\'' + ", score=" + score + ", sortValues=" + sortValues + ", content="

src/main/java/org/springframework/data/elasticsearch/core/SearchHitMapping.java

@@ -16,11 +16,18 @@
 package org.springframework.data.elasticsearch.core;
 
 import java.util.ArrayList;
+import java.util.LinkedHashMap;
+import java.util.LinkedList;
 import java.util.List;
 import java.util.Map;
 import java.util.stream.Collectors;
 
 import org.elasticsearch.search.aggregations.Aggregations;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+import org.springframework.data.elasticsearch.core.convert.ElasticsearchConverter;
+import org.springframework.data.elasticsearch.core.document.Document;
+import org.springframework.data.elasticsearch.core.document.NestedMetaData;
 import org.springframework.data.elasticsearch.core.document.SearchDocument;
 import org.springframework.data.elasticsearch.core.document.SearchDocumentResponse;
 import org.springframework.data.elasticsearch.core.mapping.ElasticsearchPersistentEntity;
@@ -39,36 +46,24 @@
  * @since 4.0
  */
 class SearchHitMapping<T> {
+
+	private static final Logger LOGGER = LoggerFactory.getLogger(SearchHitMapping.class);
+
 	private final Class<T> type;
+	private final ElasticsearchConverter converter;
 	private final MappingContext<? extends ElasticsearchPersistentEntity<?>, ElasticsearchPersistentProperty> mappingContext;
 
-	private SearchHitMapping(Class<T> type,
-			MappingContext<? extends ElasticsearchPersistentEntity<?>, ElasticsearchPersistentProperty> context) {
-
+	private SearchHitMapping(Class<T> type, ElasticsearchConverter converter) {
 		Assert.notNull(type, "type is null");
-		Assert.notNull(context, "context is null");
+		Assert.notNull(converter, "converter is null");
 
 		this.type = type;
-		this.mappingContext = context;
+		this.converter = converter;
+		this.mappingContext = converter.getMappingContext();
 	}
 
-	static <T> SearchHitMapping<T> mappingFor(Class<T> entityClass,
-			MappingContext<? extends ElasticsearchPersistentEntity<?>, ElasticsearchPersistentProperty> context) {
-		return new SearchHitMapping<>(entityClass, context);
-	}
-
-	SearchHit<T> mapHit(SearchDocument searchDocument, T content) {
-
-		Assert.notNull(searchDocument, "searchDocument is null");
-		Assert.notNull(content, "content is null");
-
-		String index = searchDocument.getIndex();
-		String id = searchDocument.hasId() ? searchDocument.getId() : null;
-		float score = searchDocument.getScore();
-		Object[] sortValues = searchDocument.getSortValues();
-		Map<String, List<String>> highlightFields = getHighlightsAndRemapFieldNames(searchDocument);
-
-		return new SearchHit<>(index, id, score, sortValues, highlightFields, content);
+	static <T> SearchHitMapping<T> mappingFor(Class<T> entityClass, ElasticsearchConverter converter) {
+		return new SearchHitMapping<>(entityClass, converter);
 	}
 
 	SearchHits<T> mapHits(SearchDocumentResponse searchDocumentResponse, List<T> contents) {
@@ -105,6 +100,21 @@ private SearchHitsImpl<T> mapHitsFromResponse(SearchDocumentResponse searchDocum
 		return new SearchHitsImpl<>(totalHits, totalHitsRelation, maxScore, scrollId, searchHits, aggregations);
 	}
 
+	SearchHit<T> mapHit(SearchDocument searchDocument, T content) {
+
+		Assert.notNull(searchDocument, "searchDocument is null");
+		Assert.notNull(content, "content is null");
+
+		return new SearchHit<T>(searchDocument.getIndex(), //
+				searchDocument.hasId() ? searchDocument.getId() : null, //
+				searchDocument.getScore(), //
+				searchDocument.getSortValues(), //
+				getHighlightsAndRemapFieldNames(searchDocument), //
+				mapInnerHits(searchDocument), //
+				searchDocument.getNestedMetaData(), //
+				content); //
+	}
+
 	@Nullable
 	private Map<String, List<String>> getHighlightsAndRemapFieldNames(SearchDocument searchDocument) {
 		Map<String, List<String>> highlightFields = searchDocument.getHighlightFields();
@@ -123,4 +133,131 @@ private Map<String, List<String>> getHighlightsAndRemapFieldNames(SearchDocument
 			return property != null ? property.getName() : entry.getKey();
 		}, Map.Entry::getValue));
 	}
+
+	private Map<String, SearchHits<?>> mapInnerHits(SearchDocument searchDocument) {
+
+		Map<String, SearchHits<?>> innerHits = new LinkedHashMap<>();
+		Map<String, SearchDocumentResponse> documentInnerHits = searchDocument.getInnerHits();
+
+		if (documentInnerHits != null && documentInnerHits.size() > 0) {
+
+			SearchHitMapping<SearchDocument> searchDocumentSearchHitMapping = SearchHitMapping
+					.mappingFor(SearchDocument.class, converter);
+
+			for (Map.Entry<String, SearchDocumentResponse> entry : documentInnerHits.entrySet()) {
+				SearchDocumentResponse searchDocumentResponse = entry.getValue();
+
+				SearchHits<SearchDocument> searchHits = searchDocumentSearchHitMapping
+						.mapHitsFromResponse(searchDocumentResponse, searchDocumentResponse.getSearchDocuments());
+
+				// map Documents to real objects
+				SearchHits<?> mappedSearchHits = mapInnerDocuments(searchHits, type);
+
+				innerHits.put(entry.getKey(), mappedSearchHits);
+			}
+
+		}
+		return innerHits;
+	}
+
+	/**
+	 * try to convert the SearchDocument instances to instances of the inner property class.
+	 *
+	 * @param searchHits {@link SearchHits} containing {@link Document} instances
+	 * @param type the class of the containing class
+	 * @return a new {@link SearchHits} instance containing the mapped objects or the original inout if any error occurs
+	 */
+	private SearchHits<?> mapInnerDocuments(SearchHits<SearchDocument> searchHits, Class<T> type) {
+
+		if (searchHits.getTotalHits() == 0) {
+			return searchHits;
+		}
+
+		try {
+			NestedMetaData nestedMetaData = searchHits.getSearchHit(0).getContent().getNestedMetaData();
+			ElasticsearchPersistentEntityWithNestedMetaData persistentEntityWithNestedMetaData = getPersistentEntity(
+					mappingContext.getPersistentEntity(type), nestedMetaData);
+
+			List<SearchHit<Object>> convertedSearchHits = new ArrayList<>();
+
+			if (persistentEntityWithNestedMetaData.entity != null) {
+				Class<?> targetType = persistentEntityWithNestedMetaData.entity.getType();
+				// convert the list of SearchHit<SearchDocument> to list of SearchHit<Object>
+				searchHits.getSearchHits().forEach(searchHit -> {
+					SearchDocument searchDocument = searchHit.getContent();
+
+					Object targetObject = converter.read(targetType, searchDocument);
+					convertedSearchHits.add(new SearchHit<Object>(searchDocument.getIndex(), //
+							searchDocument.getId(), //
+							searchDocument.getScore(), //
+							searchDocument.getSortValues(), //
+							searchDocument.getHighlightFields(), //
+							mapInnerHits(searchDocument), //
+							persistentEntityWithNestedMetaData.nestedMetaData, //
+							targetObject));
+				});
+
+				String scrollId = null;
+				if (searchHits instanceof SearchHitsImpl) {
+					scrollId = ((SearchHitsImpl<?>) searchHits).getScrollId();
+				}
+
+				return new SearchHitsImpl<>(searchHits.getTotalHits(), //
+						searchHits.getTotalHitsRelation(), //
+						searchHits.getMaxScore(), //
+						scrollId, //
+						convertedSearchHits, //
+						searchHits.getAggregations());
+			}
+		} catch (Exception e) {
+			LOGGER.warn("Could not map inner_hits", e);
+		}
+
+		return searchHits;
+	}
+
+	/**
+	 * find a {@link ElasticsearchPersistentEntity} following the property chain defined by the nested metadata
+	 * 
+	 * @param persistentEntity base entity
+	 * @param nestedMetaData nested metadata
+	 * @return The found entity or null
+	 */
+	@Nullable
+	private ElasticsearchPersistentEntityWithNestedMetaData getPersistentEntity(
+			@Nullable ElasticsearchPersistentEntity<?> persistentEntity, @Nullable NestedMetaData nestedMetaData) {
+
+		NestedMetaData currentMetaData = nestedMetaData;
+		List<NestedMetaData> mappedNestedMetaDatas = new LinkedList<>();
+
+		while (persistentEntity != null && currentMetaData != null) {
+			ElasticsearchPersistentProperty persistentProperty = persistentEntity
+					.getPersistentPropertyWithFieldName(currentMetaData.getField());
+
+			if (persistentProperty == null) {
+				persistentEntity = null;
+			} else {
+				persistentEntity = mappingContext.getPersistentEntity(persistentProperty.getActualType());
+				mappedNestedMetaDatas.add(0,
+						NestedMetaData.of(persistentProperty.getName(), currentMetaData.getOffset(), null));
+				currentMetaData = currentMetaData.getChild();
+			}
+		}
+
+		NestedMetaData mappedNestedMetaData = mappedNestedMetaDatas.stream().reduce(null,
+				(result, nmd) -> NestedMetaData.of(nmd.getField(), nmd.getOffset(), result));
+
+		return new ElasticsearchPersistentEntityWithNestedMetaData(persistentEntity, mappedNestedMetaData);
+	}
+
+	private static class ElasticsearchPersistentEntityWithNestedMetaData {
+		@Nullable private ElasticsearchPersistentEntity<?> entity;
+		private NestedMetaData nestedMetaData;
+
+		public ElasticsearchPersistentEntityWithNestedMetaData(@Nullable ElasticsearchPersistentEntity<?> entity,
+				NestedMetaData nestedMetaData) {
+			this.entity = entity;
+			this.nestedMetaData = nestedMetaData;
+		}
+	}
 }