DATAREDIS-605 - Query by Example for Redis Repositories.

We now support query by example via Redis repositories. We allow case-sensitive, exact matching of singular simple and nested properties, using any/all match modes, value transformation of the criteria value for indexed properties.

We do not support findAll with sorting, case-insensitive properties or string matchers other than exact.

interface PersonRepository extends QueryByExampleExecutor<Person> {
}

class PersonService {

  @Autowired PersonRepository personRepository;

  List<Person> findPeople(Person probe) {
    return personRepository.findAll(Example.of(probe));
  }
}

Original Pull Request: #301

Author: mp911de

src/main/asciidoc/index.adoc

@@ -4,6 +4,7 @@ Costin Leau, Jennifer Hickey, Christoph Strobl, Thomas Darimont, Mark Paluch
 :revdate: {localdate}
 :toc:
 :toc-placement!:
+:spring-data-commons-include: ../../../../spring-data-commons/src/main/asciidoc
 :spring-data-commons-docs: https://raw.githubusercontent.com/spring-projects/spring-data-commons/master/src/main/asciidoc
 
 (C) 2011-2016 The original authors.

src/main/asciidoc/new-features.adoc

@@ -8,6 +8,7 @@ New and noteworthy in the latest releases.
 
 * Unix domain socket connections using <<redis:connectors:lettuce,Lettuce>>.
 * <<redis:write-to-master-read-from-slave, Write to Master read from Slave>> support using Lettuce.
+* <<query-by-example,Query by Example>> integration
 
 [[new-in-2.0.0]]
 == New in Spring Data Redis 2.0

src/main/asciidoc/reference/query-by-example.adoc

@@ -0,0 +1,42 @@
+[[query-by-example.execution]]
+== Executing an example
+
+.Query by Example using a Repository
+====
+[source, java]
+----
+interface PersonRepository extends QueryByExampleExecutor<Person> {
+}
+
+class PersonService {
+
+  @Autowired PersonRepository personRepository;
+
+  List<Person> findPeople(Person probe) {
+    return personRepository.findAll(Example.of(probe));
+  }
+}
+----
+====
+
+Redis Repositories support with their secondary indexes a subset of Spring Data's Query by Example features.
+In particular, only exact, case-sensitive and non-null values are used to construct a query.
+
+Secondary indexes use set-based operations (Set intersection, Set union) to determine matching keys. Adding a property to the query that is not indexed returns no result as no index exists. Query by Example support inspects indexing configuration to only include properties in the query that are covered by an index. This is to prevent accidental inclusion of not indexed properties.
+
+Case-insensitive queries and unsupported ``StringMatcher``s are rejected at runtime.
+
+*Supported Query by Example options*
+
+* Case-sensitive, exact matching of simple and nested properties
+* Any/All match modes
+* Value transformation of the criteria value
+* Exclusion of `null` values from the criteria
+
+*Not supported by Query by Example*
+
+* Case-insensitive matching
+* Regex, prefix/contains/suffix String-matching
+* Querying of Associations, Collection, and Map-like properties
+* Inclusion of `null` values from the criteria
+* `findAll` with sorting

src/main/asciidoc/reference/redis-repositories.adoc

@@ -468,6 +468,8 @@ In the above example the lon/lat values are stored using `GEOADD` using the obje
 
 NOTE: It is **not** possible to combine `near`/`within` with other criteria.
 
+include::../{spring-data-commons-include}/query-by-example.adoc[leveloffset=+1]
+include::query-by-example.adoc[leveloffset=+1]
 
 [[redis.repositories.expirations]]
 == Time To Live

src/main/java/org/springframework/data/redis/core/RedisKeyValueTemplate.java

@@ -35,6 +35,8 @@
  */
 public class RedisKeyValueTemplate extends KeyValueTemplate {
 
+	private final RedisKeyValueAdapter adapter;
+
 	/**
 	 * Create new {@link RedisKeyValueTemplate}.
 	 *
@@ -43,6 +45,15 @@ public class RedisKeyValueTemplate extends KeyValueTemplate {
 	 */
 	public RedisKeyValueTemplate(RedisKeyValueAdapter adapter, RedisMappingContext mappingContext) {
 		super(adapter, mappingContext);
+		this.adapter = adapter;
+	}
+
+	/**
+	 * @return the {@link RedisKeyValueAdapter}.
+	 * @since 2.1
+	 */
+	public RedisKeyValueAdapter getAdapter() {
+		return adapter;
 	}
 
 	/*
@@ -54,6 +65,7 @@ public RedisMappingContext getMappingContext() {
 		return (RedisMappingContext) super.getMappingContext();
 	}
 
+
 	/**
 	 * Retrieve entities by resolving their {@literal id}s and converting them into required type. <br />
 	 * The callback provides either a single {@literal id} or an {@link Iterable} of {@literal id}s, used for retrieving

src/main/java/org/springframework/data/redis/core/RedisQueryEngine.java

@@ -159,20 +159,23 @@ public Collection<?> execute(RedisOperationChain criteria, Comparator<?> sort, l
 	@Override
 	public long count(RedisOperationChain criteria, String keyspace) {
 
-		if (criteria == null) {
+		if (criteria == null || criteria.isEmpty()) {
 			return this.getAdapter().count(keyspace);
 		}
 
 		return this.getAdapter().execute(connection -> {
 
-			String key = keyspace + ":";
-			byte[][] keys = new byte[criteria.getSismember().size()][];
-			int i = 0;
-			for (Object o : criteria.getSismember()) {
-				keys[i] = getAdapter().getConverter().getConversionService().convert(key + o, byte[].class);
+			long result = 0;
+
+			if (!criteria.getOrSismember().isEmpty()) {
+				result += connection.sUnion(keys(keyspace + ":", criteria.getOrSismember())).size();
+			}
+
+			if (!criteria.getSismember().isEmpty()) {
+				result += connection.sInter(keys(keyspace + ":", criteria.getSismember())).size();
 			}
 
-			return (long) connection.sInter(keys).size();
+			return result;
 		});
 	}
 

src/main/java/org/springframework/data/redis/core/convert/MappingRedisConverter.java

@@ -18,17 +18,8 @@
 import lombok.RequiredArgsConstructor;
 
 import java.lang.reflect.Array;
-import java.util.ArrayList;
-import java.util.Collection;
-import java.util.Collections;
-import java.util.Comparator;
-import java.util.HashMap;
-import java.util.Iterator;
-import java.util.List;
-import java.util.Map;
+import java.util.*;
 import java.util.Map.Entry;
-import java.util.Optional;
-import java.util.Set;
 import java.util.regex.Matcher;
 import java.util.regex.Pattern;
 
@@ -990,6 +981,16 @@ public RedisMappingContext getMappingContext() {
 		return this.mappingContext;
 	}
 
+	/*
+	 * (non-Javadoc)
+	 * @see org.springframework.data.redis.core.convert.RedisConverter#getIndexResolver()
+	 */
+	@Nullable
+	@Override
+	public IndexResolver getIndexResolver() {
+		return this.indexResolver;
+	}
+
 	/*
 	 * (non-Javadoc)
 	 * @see org.springframework.data.convert.EntityConverter#getConversionService()

src/main/java/org/springframework/data/redis/core/convert/RedisConverter.java

@@ -19,11 +19,13 @@
 import org.springframework.data.redis.core.mapping.RedisMappingContext;
 import org.springframework.data.redis.core.mapping.RedisPersistentEntity;
 import org.springframework.data.redis.core.mapping.RedisPersistentProperty;
+import org.springframework.lang.Nullable;
 
 /**
  * Redis specific {@link EntityConverter}.
  *
  * @author Christoph Strobl
+ * @author Mark Paluch
  * @since 1.7
  */
 public interface RedisConverter
@@ -35,4 +37,11 @@ public interface RedisConverter
 	 */
 	@Override
 	RedisMappingContext getMappingContext();
+
+	/**
+	 * @return the configured {@link IndexResolver}, may be {@literal null}.
+	 * @since 2.1
+	 */
+	@Nullable
+	IndexResolver getIndexResolver();
 }

src/main/java/org/springframework/data/redis/repository/query/ExampleQueryMapper.java

@@ -0,0 +1,178 @@
+/*
+ * Copyright 2018 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.springframework.data.redis.repository.query;
+
+import java.util.Collections;
+import java.util.EnumSet;
+import java.util.Optional;
+import java.util.Set;
+import java.util.function.Predicate;
+import java.util.stream.Collectors;
+
+import org.springframework.dao.InvalidDataAccessApiUsageException;
+import org.springframework.data.domain.Example;
+import org.springframework.data.domain.ExampleMatcher.MatchMode;
+import org.springframework.data.domain.ExampleMatcher.PropertyValueTransformer;
+import org.springframework.data.domain.ExampleMatcher.StringMatcher;
+import org.springframework.data.mapping.PersistentPropertyAccessor;
+import org.springframework.data.mapping.context.MappingContext;
+import org.springframework.data.redis.core.convert.IndexResolver;
+import org.springframework.data.redis.core.convert.IndexedData;
+import org.springframework.data.redis.core.mapping.RedisPersistentEntity;
+import org.springframework.data.redis.core.mapping.RedisPersistentProperty;
+import org.springframework.data.support.ExampleMatcherAccessor;
+import org.springframework.lang.Nullable;
+import org.springframework.util.Assert;
+import org.springframework.util.StringUtils;
+
+/**
+ * Mapper for Query-by-Example examples to an actual query.
+ * <p/>
+ * This mapper creates a {@link RedisOperationChain} for a given {@link Example} considering exact matches,
+ * {@link PropertyValueTransformer value transformations} and {@link MatchMode} for indexed simple and nested type
+ * properties. {@link java.util.Map} and {@link java.util.Collection} properties are not considered.
+ * <p/>
+ * Example matching is limited to case-sensitive and exact matches only.
+ *
+ * @author Mark Paluch
+ * @since 2.1
+ */
+public class ExampleQueryMapper {
+
+	private final Set<StringMatcher> SUPPORTED_MATCHERS = EnumSet.of(StringMatcher.DEFAULT, StringMatcher.EXACT);
+
+	private final MappingContext<RedisPersistentEntity<?>, RedisPersistentProperty> mappingContext;
+	private final IndexResolver indexResolver;
+
+	/**
+	 * Creates a new {@link ExampleQueryMapper} given {@link MappingContext} and {@link IndexResolver}.
+	 *
+	 * @param mappingContext must not be {@literal null}.
+	 * @param indexResolver must not be {@literal null}.
+	 */
+	public ExampleQueryMapper(MappingContext<RedisPersistentEntity<?>, RedisPersistentProperty> mappingContext,
+			IndexResolver indexResolver) {
+
+		Assert.notNull(mappingContext, "MappingContext must not be null!");
+		Assert.notNull(indexResolver, "IndexResolver must not be null!");
+
+		this.mappingContext = mappingContext;
+		this.indexResolver = indexResolver;
+	}
+
+	/**
+	 * Retrieve a mapped {@link RedisOperationChain} to query secondary indexes given {@link Example}.
+	 *
+	 * @param example must not be {@literal null}.
+	 * @return the mapped {@link RedisOperationChain}.
+	 */
+	public RedisOperationChain getMappedExample(Example<?> example) {
+
+		RedisOperationChain chain = new RedisOperationChain();
+
+		ExampleMatcherAccessor matcherAccessor = new ExampleMatcherAccessor(example.getMatcher());
+
+		applyPropertySpecs("", example.getProbe(), mappingContext.getRequiredPersistentEntity(example.getProbeType()),
+				matcherAccessor, example.getMatcher().getMatchMode(), chain);
+
+		return chain;
+	}
+
+	private void applyPropertySpecs(String path, @Nullable Object probe, RedisPersistentEntity<?> persistentEntity,
+			ExampleMatcherAccessor exampleSpecAccessor, MatchMode matchMode, RedisOperationChain chain) {
+
+		if (probe == null) {
+			return;
+		}
+
+		PersistentPropertyAccessor propertyAccessor = persistentEntity.getPropertyAccessor(probe);
+
+		Set<IndexedData> indexedData = getIndexedData(path, probe, persistentEntity);
+		Set<String> indexNames = indexedData.stream().map(IndexedData::getIndexName).distinct().collect(Collectors.toSet());
+
+		persistentEntity.forEach(property -> {
+
+			if (property.isIdProperty()) {
+				return;
+			}
+
+			String propertyPath = StringUtils.hasText(path) ? path + "." + property.getName() : property.getName();
+
+			if (exampleSpecAccessor.isIgnoredPath(propertyPath) || property.isCollectionLike() || property.isMap()) {
+				return;
+			}
+
+			applyPropertySpec(propertyPath, indexNames::contains, exampleSpecAccessor, propertyAccessor, property, matchMode,
+					chain);
+		});
+	}
+
+	private void applyPropertySpec(String path, Predicate<String> hasIndex, ExampleMatcherAccessor exampleSpecAccessor,
+			PersistentPropertyAccessor propertyAccessor, RedisPersistentProperty property, MatchMode matchMode,
+			RedisOperationChain chain) {
+
+		StringMatcher stringMatcher = exampleSpecAccessor.getDefaultStringMatcher();
+		boolean ignoreCase = exampleSpecAccessor.isIgnoreCaseEnabled();
+		Object value = propertyAccessor.getProperty(property);
+
+		if (exampleSpecAccessor.hasPropertySpecifiers()) {
+			stringMatcher = exampleSpecAccessor.getStringMatcherForPath(path);
+			ignoreCase = exampleSpecAccessor.isIgnoreCaseForPath(path);
+		}
+
+		if (ignoreCase) {
+			throw new InvalidDataAccessApiUsageException("Redis Query-by-Example supports only case-sensitive matching.");
+		}
+
+		if (!SUPPORTED_MATCHERS.contains(stringMatcher)) {
+			throw new InvalidDataAccessApiUsageException(
+					String.format("Redis Query-by-Example does not support string matcher %s. Supported matchers are: %s.",
+							stringMatcher, SUPPORTED_MATCHERS));
+		}
+
+		if (exampleSpecAccessor.hasPropertySpecifier(path)) {
+
+			PropertyValueTransformer valueTransformer = exampleSpecAccessor.getValueTransformerForPath(path);
+			value = valueTransformer.apply(Optional.ofNullable(value)).orElse(null);
+		}
+
+		if (value == null) {
+			return;
+		}
+
+		if (property.isEntity()) {
+			applyPropertySpecs(path, value, mappingContext.getRequiredPersistentEntity(property), exampleSpecAccessor,
+					matchMode, chain);
+		} else {
+
+			if (matchMode == MatchMode.ALL) {
+				if (hasIndex.test(path)) {
+					chain.sismember(path, value);
+				}
+			} else {
+				chain.orSismember(path, value);
+			}
+		}
+	}
+
+	private Set<IndexedData> getIndexedData(String path, Object probe, RedisPersistentEntity<?> persistentEntity) {
+
+		String keySpace = persistentEntity.getKeySpace();
+		return keySpace == null ? Collections.emptySet()
+				: indexResolver.resolveIndexesFor(persistentEntity.getKeySpace(), path, persistentEntity.getTypeInformation(),
+						probe);
+	}
+}

src/main/java/org/springframework/data/redis/repository/query/RedisOperationChain.java

@@ -33,6 +33,7 @@
  * Simple set of operations required to run queries against Redis.
  *
  * @author Christoph Strobl
+ * @author Mark Paluch
  * @since 1.7
  */
 public class RedisOperationChain {
@@ -42,6 +43,10 @@ public class RedisOperationChain {
 
 	private @Nullable NearPath near;
 
+	public boolean isEmpty() {
+		return near == null && sismember.isEmpty() && orSismember.isEmpty();
+	}
+
 	public void sismember(String path, Object value) {
 		sismember(new PathAndValue(path, value));
 	}