Add @Interned annotation for low-cardinality string optimization (#16)

* Add @Interned annotation for low-cardinality string optimization

- Add @Interned annotation to mark string properties that should use FalkorDB's intern() function
- Update FalkorDBPersistentProperty interface with isInterned() method
- Implement @Interned support in DefaultFalkorDBEntityConverter with InternedValue marker class
- Update FalkorDBTemplate and DefaultFalkorDBEntityConverter to generate Cypher with inline intern() calls
- Add comprehensive tests for @Interned functionality
- Add README documentation explaining when and how to use @Interned
- Add InternedUsageExample demonstrating best practices for using @Interned annotation

This feature optimizes storage for properties with limited value sets (status codes, categories, country codes, etc.) by ensuring FalkorDB keeps only a single copy of frequently repeated string values.

* Remove ineffective @inherited meta-annotation from @Interned

@inherited only affects class-level annotations, not field-level ones.
Since @Interned targets ElementType.FIELD, the @inherited annotation
has no effect and should be removed.

Addresses CodeRabbitAI review comment.

* Fix escape sequence in @Interned annotation to properly handle backslashes

- Escape backslashes before single quotes to prevent injection issues
- Add comprehensive tests for backslash and quote escaping
- Addresses CodeRabbitAI security review comment on PR #16

The previous implementation only escaped single quotes, which could lead
to incorrect Cypher generation or potential injection issues when values
contained backslashes. Now backslashes are escaped first (doubled), then
single quotes are escaped with backslash-quote.

* Add repositoryFactoryBeanClass attribute to @EnableFalkorDBRepositories

- Add repositoryFactoryBeanClass attribute that specifies FalkorDBRepositoryFactoryBean
- This attribute is required for Spring Data to correctly instantiate repository proxies
- Ensures proper integration with Spring Data infrastructure

* Fix parameter binding in StringBasedFalkorDBQuery to prevent collisions

- Only use indexed parameter binding (-zsh, , etc.) for parameters without @param
- Use named parameter binding exclusively for parameters with @param annotation
- Prevents parameter collision when mixing indexed and named parameters
- Improves predictability and correctness of query parameter binding

Previously, all parameters were first added as indexed, then named parameters
were added, which could cause unexpected behavior if parameter names matched
index values.

* Add support for scalar and Map return types in repository queries

- Add flexible query method with result mapper to FalkorDBOperations/Template
- Support scalar return types (String, Integer, Long, Boolean, etc.) in @query methods
- Support Map and List<Map> return types for raw result handling
- Add queryForScalar() to extract single column values
- Add queryForMaps() to return raw Map results without entity mapping
- Add proper type conversion for Number types
- Fix FalkorDBQueryLookupStrategy initialization with proper constructor

This allows repository methods to return:
- Single scalar values: @query("RETURN count(*)") Long count();
- Collections of scalars: @query("RETURN n.name") List<String> names();
- Single Map: @query("RETURN n{.*}") Map<String, Object> getMap();
- Collections of Maps: @query("RETURN n{.*}") List<Map<String, Object>> getMaps();

Previously, only entity types were supported as return values.

* Add support for Number to String conversion in entity converter

- Allow automatic conversion of numeric values to String type
- Useful for cases where IDs are Long in database but String in entity
- Handles scenarios like internal FalkorDB IDs being mapped to String properties

This enables flexibility in entity ID type declarations while maintaining
compatibility with FalkorDB's internal numeric ID system.

Author: shahar-biron

README.md

@@ -225,6 +225,29 @@ private String name;  // Maps to "full_name" property
 private String email;  // Maps to "email" property (default)
 ```
 
+### @Interned
+Marks string properties as low-cardinality, applying FalkorDB's `intern()` function to optimize storage:
+
+```java
+@Interned
+private String status;  // Uses intern() - ideal for limited values like "ACTIVE", "INACTIVE"
+
+@Interned
+private String country;  // Uses intern() - ideal for country codes "US", "UK", "CA"
+
+@Interned
+private String category;  // Uses intern() - ideal for categories like "SPORTS", "NEWS"
+```
+
+The `@Interned` annotation is useful for string properties that have a limited set of possible values (low cardinality). When a property is marked with `@Interned`, FalkorDB's `intern()` function is automatically applied when writing to the database, which keeps only a single copy of frequently repeated string values, optimizing storage and query performance.
+
+**Use cases:**
+- Status codes (ACTIVE, INACTIVE, PENDING)
+- Country/region codes
+- Categories and types
+- Enum-like string values
+- Any string with a limited vocabulary
+
 ### @Relationship
 Maps relationships between entities:
 

src/main/java/org/springframework/data/falkordb/core/FalkorDBOperations.java

@@ -151,4 +151,15 @@ public interface FalkorDBOperations {
 	 */
 	<T> Optional<T> queryForObject(String cypher, java.util.Map<String, Object> parameters, Class<T> clazz);
 
+	/**
+	 * Executes a custom Cypher query with a result mapper function.
+	 * @param <T> the type of the result
+	 * @param cypher the Cypher query
+	 * @param parameters the query parameters
+	 * @param resultMapper function to map the query result
+	 * @return the mapped result
+	 */
+	<T> T query(String cypher, java.util.Map<String, Object> parameters,
+				java.util.function.Function<FalkorDBClient.QueryResult, T> resultMapper);
+
 }

src/main/java/org/springframework/data/falkordb/core/FalkorDBTemplate.java

@@ -98,20 +98,36 @@ public <T> T save(T instance) {
 		cypher.append(primaryLabel);
 		cypher.append(" ");
 
+		// Separate regular properties from interned properties
+		Map<String, Object> regularParams = new HashMap<>();
+		List<String> propertyAssignments = new ArrayList<>();
+		
+		for (Map.Entry<String, Object> entry : properties.entrySet()) {
+			String key = entry.getKey();
+			Object value = entry.getValue();
+			
+			if (value instanceof DefaultFalkorDBEntityConverter.InternedValue) {
+				// For interned values, inline the intern() function call
+				DefaultFalkorDBEntityConverter.InternedValue internedValue = 
+					(DefaultFalkorDBEntityConverter.InternedValue) value;
+				propertyAssignments.add(key + ": intern('" + internedValue.getValue() + "')");
+			} else {
+				// For regular values, use parameters
+				propertyAssignments.add(key + ": $" + key);
+				regularParams.put(key, value);
+			}
+		}
+
 		// Add properties
-		if (!properties.isEmpty()) {
+		if (!propertyAssignments.isEmpty()) {
 			cypher.append("{ ");
-			String propertiesStr = properties.keySet()
-				.stream()
-				.map(key -> key + ": $" + key)
-				.collect(Collectors.joining(", "));
-			cypher.append(propertiesStr);
+			cypher.append(String.join(", ", propertyAssignments));
 			cypher.append(" }");
 		}
 
 		cypher.append(") RETURN n, id(n) as nodeId");
 
-		return this.falkorDBClient.query(cypher.toString(), properties, result -> {
+		return this.falkorDBClient.query(cypher.toString(), regularParams, result -> {
 			// Convert back to entity
 			for (FalkorDBClient.Record record : result.records()) {
 				T savedEntity = (T) this.entityConverter.read(entityType, record);
@@ -345,6 +361,16 @@ public <T> Optional<T> queryForObject(String cypher, Map<String, Object> paramet
 		});
 	}
 
+	@Override
+	public <T> T query(String cypher, Map<String, Object> parameters,
+					   java.util.function.Function<FalkorDBClient.QueryResult, T> resultMapper) {
+		Assert.hasText(cypher, "Cypher query must not be null or empty");
+		Assert.notNull(parameters, "Parameters must not be null");
+		Assert.notNull(resultMapper, "Result mapper must not be null");
+
+		return this.falkorDBClient.query(cypher, parameters, resultMapper);
+	}
+
 	/**
 	 * Returns the {@link FalkorDBEntityConverter} used by this template.
 	 *

src/main/java/org/springframework/data/falkordb/core/mapping/DefaultFalkorDBEntityConverter.java

@@ -188,28 +188,54 @@ public final void write(final Object source, final Map<String, Object> sink) {
 			Object value = accessor.getProperty(property);
 			if (value != null) {
 				// Convert value to FalkorDB-compatible format
-				Object convertedValue = convertValueForFalkorDB(value);
+				Object convertedValue = convertValueForFalkorDB(value, property);
 				sink.put(property.getGraphPropertyName(), convertedValue);
 			}
 		});
 	}
 
 	/**
 	 * Convert a value to a format compatible with FalkorDB. This handles special types
-	 * like LocalDateTime that need formatting.
+	 * like LocalDateTime that need formatting and applies intern() for low-cardinality strings.
 	 * @param value the value to convert
+	 * @param property the property metadata (optional, can be null)
 	 * @return the converted value compatible with FalkorDB
 	 */
-	private Object convertValueForFalkorDB(final Object value) {
+	private Object convertValueForFalkorDB(final Object value, final FalkorDBPersistentProperty property) {
 		if (value instanceof LocalDateTime) {
 			// Convert LocalDateTime to ISO string format that FalkorDB
 			// can handle. Using ISO_LOCAL_DATE_TIME format.
 			return ((LocalDateTime) value).format(DateTimeFormatter.ISO_LOCAL_DATE_TIME);
 		}
+		
+		// Apply intern() function for low-cardinality string properties
+		if (property != null && property.isInterned() && value instanceof String) {
+			String strValue = (String) value;
+			// Escape backslashes first, then single quotes
+			String escapedValue = strValue.replace("\\", "\\\\").replace("'", "\\'");
+			// Return as a special marker object that will be handled during Cypher generation
+			return new InternedValue(escapedValue);
+		}
+		
 		// Add more type conversions as needed
 		return value;
 	}
 
+	/**
+	 * Marker class to indicate that a value should use FalkorDB's intern() function.
+	 */
+	public static class InternedValue {
+		private final String value;
+
+		public InternedValue(final String value) {
+			this.value = value;
+		}
+
+		public String getValue() {
+			return value;
+		}
+	}
+
 	/**
 	 * Check if the given type is a primitive type or its wrapper.
 	 * @param type the type to check
@@ -312,6 +338,10 @@ else if (targetType == Short.class || targetType == short.class) {
 			else if (targetType == Byte.class || targetType == byte.class) {
 				return numValue.byteValue();
 			}
+			else if (targetType == String.class) {
+				// Convert number to string (e.g., Long ID to String)
+				return numValue.toString();
+			}
 		}
 
 		// Handle String conversions
@@ -612,7 +642,7 @@ private Object saveEntityAndGetId(Object entity, FalkorDBPersistentEntity<?> per
 
 			Object value = accessor.getProperty(property);
 			if (value != null) {
-				Object convertedValue = convertValueForFalkorDB(value);
+				Object convertedValue = convertValueForFalkorDB(value, property);
 				properties.put(property.getGraphPropertyName(), convertedValue);
 			}
 		});
@@ -630,24 +660,39 @@ private Object saveEntityAndGetId(Object entity, FalkorDBPersistentEntity<?> per
 			}
 		}
 
-		StringBuilder cypher = new StringBuilder("CREATE (n:");
-		cypher.append(String.join(":", labels));
-		cypher.append(" ");
-
-		if (!properties.isEmpty()) {
-			cypher.append("{ ");
-			String propertiesStr = properties.keySet()
-				.stream()
-				.map(key -> key + ": $" + key)
-				.collect(java.util.stream.Collectors.joining(", "));
-			cypher.append(propertiesStr);
-			cypher.append(" }");
+	StringBuilder cypher = new StringBuilder("CREATE (n:");
+	cypher.append(String.join(":", labels));
+	cypher.append(" ");
+
+	// Separate regular properties from interned properties
+	Map<String, Object> regularParams = new HashMap<>();
+	List<String> propertyAssignments = new ArrayList<>();
+	
+	for (Map.Entry<String, Object> entry : properties.entrySet()) {
+		String key = entry.getKey();
+		Object value = entry.getValue();
+		
+		if (value instanceof InternedValue) {
+			// For interned values, inline the intern() function call
+			InternedValue internedValue = (InternedValue) value;
+			propertyAssignments.add(key + ": intern('" + internedValue.getValue() + "')");
+		} else {
+			// For regular values, use parameters
+			propertyAssignments.add(key + ": $" + key);
+			regularParams.put(key, value);
 		}
+	}
+
+	if (!propertyAssignments.isEmpty()) {
+		cypher.append("{ ");
+		cypher.append(String.join(", ", propertyAssignments));
+		cypher.append(" }");
+	}
 
-		cypher.append(") RETURN id(n) as nodeId");
+	cypher.append(") RETURN id(n) as nodeId");
 
-		// Execute save and get the ID
-		Object nodeId = this.falkorDBClient.query(cypher.toString(), properties, result -> {
+	// Execute save and get the ID
+	Object nodeId = this.falkorDBClient.query(cypher.toString(), regularParams, result -> {
 			for (FalkorDBClient.Record record : result.records()) {
 				return record.get("nodeId");
 			}

src/main/java/org/springframework/data/falkordb/core/mapping/DefaultFalkorDBPersistentProperty.java

@@ -23,6 +23,7 @@
 package org.springframework.data.falkordb.core.mapping;
 
 import org.springframework.data.falkordb.core.schema.GeneratedValue;
+import org.springframework.data.falkordb.core.schema.Interned;
 import org.springframework.data.falkordb.core.schema.Property;
 import org.springframework.data.falkordb.core.schema.Relationship;
 import org.springframework.data.mapping.Association;
@@ -114,6 +115,15 @@ else if (StringUtils.hasText(relationshipAnnotation.value())) {
 		return null;
 	}
 
+	/**
+	 * Checks if this property should use FalkorDB's intern() function.
+	 * @return true if this property is marked with @Interned
+	 */
+	@Override
+	public final boolean isInterned() {
+		return isAnnotationPresent(Interned.class);
+	}
+
 	/**
 	 * Creates an association for this property.
 	 * @return the association

src/main/java/org/springframework/data/falkordb/core/mapping/FalkorDBPersistentProperty.java

@@ -64,4 +64,11 @@ public interface FalkorDBPersistentProperty extends PersistentProperty<FalkorDBP
 	 */
 	String getRelationshipType();
 
+	/**
+	 * Returns whether this property should use FalkorDB's intern() function for
+	 * low-cardinality string values.
+	 * @return true if this property is marked with @Interned
+	 */
+	boolean isInterned();
+
 }

src/main/java/org/springframework/data/falkordb/core/schema/Interned.java

@@ -0,0 +1,68 @@
+/*
+ * Copyright (c) 2023-2025 FalkorDB Ltd.
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+package org.springframework.data.falkordb.core.schema;
+
+import java.lang.annotation.Documented;
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+import org.apiguardian.api.API;
+
+/**
+ * Annotation to mark a string property as low-cardinality, which will cause
+ * FalkorDB's {@code intern()} function to be applied when writing the value
+ * to the database. This helps FalkorDB optimize storage by keeping only a
+ * single copy of frequently repeated string values.
+ * <p>
+ * This annotation is useful for properties like categories, status codes,
+ * country codes, or any other string field with a limited set of possible values.
+ * <p>
+ * Example usage:
+ * <pre>
+ * {@code
+ * @Node("User")
+ * public class User {
+ *     @Id
+ *     private String id;
+ *     
+ *     @Interned
+ *     private String status; // e.g., "ACTIVE", "INACTIVE", "PENDING"
+ *     
+ *     @Interned
+ *     private String country; // e.g., "US", "UK", "CA"
+ * }
+ * }
+ * </pre>
+ *
+ * @author Shahar Biron (FalkorDB)
+ * @since 1.0
+ */
+@Retention(RetentionPolicy.RUNTIME)
+@Target({ ElementType.FIELD, ElementType.ANNOTATION_TYPE })
+@Documented
+@API(status = API.Status.STABLE, since = "1.0")
+public @interface Interned {
+
+}

src/main/java/org/springframework/data/falkordb/repository/config/EnableFalkorDBRepositories.java

@@ -131,4 +131,10 @@
 	 */
 	boolean considerNestedRepositories() default false;
 
+	/**
+	 * Configures the repository factory bean class to be used.
+	 * @return repository factory bean class
+	 */
+	Class<?> repositoryFactoryBeanClass() default org.springframework.data.falkordb.repository.support.FalkorDBRepositoryFactoryBean.class;
+
 }