Merge pull request #6 from FalkorDB/add-query-and-targetnode-annotations

Implement @query and @TargetNode annotations for Spring Data FalkorDB

Author: shahar-biron

ANNOTATIONS.md

@@ -0,0 +1,230 @@
+# Spring Data FalkorDB Annotations
+
+This document describes the annotations available in Spring Data FalkorDB for mapping entities and defining custom queries.
+
+## Query Annotations
+
+### @Query
+
+The `@Query` annotation allows you to define custom Cypher queries for repository methods that cannot be expressed as derived queries.
+
+**Location:** `org.springframework.data.falkordb.repository.query.Query`
+
+#### Basic Usage
+
+```java
+public interface UserRepository extends FalkorDBRepository<User, Long> {
+    
+    @Query("MATCH (u:User) WHERE u.age > $age RETURN u")
+    List<User> findUsersOlderThan(@Param("age") int age);
+}
+```
+
+#### Parameter Binding
+
+The `@Query` annotation supports multiple parameter binding techniques:
+
+1. **By parameter name using @Param:**
+   ```java
+   @Query("MATCH (u:User) WHERE u.name = $name RETURN u")
+   User findByName(@Param("name") String name);
+   ```
+
+2. **By parameter index:**
+   ```java
+   @Query("MATCH (u:User) WHERE u.age > $0 RETURN u")
+   List<User> findUsersOlderThan(int age);
+   ```
+
+3. **By entity property:**
+   ```java
+   @Query("MATCH (u:User {id: $user.__id__})-[:FOLLOWS]->(f) RETURN f")
+   List<User> findFollowing(@Param("user") User user);
+   ```
+
+#### Query Types
+
+**Count Queries:**
+```java
+@Query(value = "MATCH (u:User) WHERE u.age > $age RETURN count(u)", count = true)
+Long countUsersOlderThan(@Param("age") int age);
+```
+
+**Exists Queries:**
+```java
+@Query(value = "MATCH (u:User {name: $name}) RETURN count(u) > 0", exists = true)
+Boolean existsByName(@Param("name") String name);
+```
+
+**Write Operations:**
+```java
+@Query(value = "MATCH (u:User {id: $id}) SET u.lastLogin = timestamp() RETURN u", write = true)
+User updateLastLogin(@Param("id") Long id);
+```
+
+#### Complex Queries
+
+```java
+@Query("MATCH (m:Movie)-[r:ACTED_IN]-(p:Person {name: $actorName}) " +
+       "RETURN m, collect(r), collect(p)")
+List<Movie> findMoviesByActorName(@Param("actorName") String actorName);
+```
+
+## Relationship Mapping Annotations
+
+### @TargetNode
+
+The `@TargetNode` annotation marks a field in a relationship properties class as the target node of the relationship.
+
+**Location:** `org.springframework.data.falkordb.core.schema.TargetNode`
+
+#### Usage with @RelationshipProperties
+
+```java
+@RelationshipProperties
+public class ActedIn {
+    
+    @RelationshipId
+    private Long id;
+    
+    @TargetNode
+    private Person actor;  // The target node of the relationship
+    
+    private List<String> roles;  // Relationship properties
+    private Integer year;        // Relationship properties
+    
+    // constructors, getters, setters...
+}
+```
+
+#### Complete Example
+
+**Entity Classes:**
+```java
+@Node
+public class Movie {
+    @Id
+    private String title;
+    
+    @Relationship(type = "ACTED_IN", direction = Direction.INCOMING)
+    private List<ActedIn> actors = new ArrayList<>();
+    
+    // other fields...
+}
+
+@Node 
+public class Person {
+    @Id @GeneratedValue
+    private Long id;
+    
+    private String name;
+    private Integer born;
+    
+    // other fields...
+}
+```
+
+**Relationship Properties:**
+```java
+@RelationshipProperties
+public class ActedIn {
+    
+    @RelationshipId
+    private Long id;
+    
+    @TargetNode
+    private Person actor;
+    
+    private List<String> roles;
+    private Integer year;
+}
+```
+
+### @RelationshipId
+
+The `@RelationshipId` annotation marks a field as the relationship's internal ID.
+
+**Location:** `org.springframework.data.falkordb.core.schema.RelationshipId`
+
+```java
+@RelationshipProperties
+public class Friendship {
+    
+    @RelationshipId
+    private Long id;  // Relationship's internal ID
+    
+    @TargetNode
+    private Person friend;
+    
+    private LocalDate since;
+}
+```
+
+## Repository Examples
+
+### Complete Repository Interface
+
+```java
+public interface MovieRepository extends FalkorDBRepository<Movie, String> {
+
+    // Derived query methods
+    List<Movie> findByReleasedGreaterThan(Integer year);
+    
+    // Custom queries with different parameter binding styles
+    @Query("MATCH (m:Movie) WHERE m.released > $year RETURN m")
+    List<Movie> findMoviesReleasedAfter(@Param("year") Integer year);
+
+    @Query("MATCH (m:Movie) WHERE m.title CONTAINS $0 RETURN m")
+    List<Movie> findMoviesByTitleContaining(String titlePart);
+
+    // Complex relationship queries
+    @Query("MATCH (m:Movie {title: $title})-[r:ACTED_IN]-(p:Person) " +
+           "RETURN m, collect(r), collect(p)")
+    Optional<Movie> findMovieWithActors(@Param("title") String title);
+
+    // Entity parameter queries
+    @Query("MATCH (m:Movie {title: $movie.__id__})-[:ACTED_IN]-(p:Person) RETURN p")
+    List<Person> findActorsInMovie(@Param("movie") Movie movie);
+
+    // Count and exists queries
+    @Query(value = "MATCH (m:Movie) WHERE m.released > $year RETURN count(m)", count = true)
+    Long countMoviesReleasedAfter(@Param("year") Integer year);
+
+    @Query(value = "MATCH (m:Movie {title: $title}) RETURN count(m) > 0", exists = true)
+    Boolean existsByTitle(@Param("title") String title);
+
+    // Write operations
+    @Query(value = "MATCH (m:Movie {title: $title}) SET m.updated = timestamp() RETURN m", 
+           write = true)
+    Movie updateMovieTimestamp(@Param("title") String title);
+}
+```
+
+## Best Practices
+
+### Query Annotation Best Practices
+
+1. **Use meaningful parameter names** with `@Param` for better readability
+2. **Mark write operations** with `write = true` for proper transaction handling
+3. **Use count/exists flags** for performance optimization on aggregate queries
+4. **Avoid N+1 queries** by using `collect()` in Cypher for related data
+
+### Relationship Properties Best Practices
+
+1. **Always use @RelationshipId** for the relationship's internal ID field
+2. **Use @TargetNode** to clearly identify the target node field
+3. **Keep relationship properties simple** and avoid deep nesting
+4. **Consider performance implications** of relationship properties in queries
+
+## Migration from Spring Data Neo4j
+
+These annotations are designed to be compatible with Spring Data Neo4j patterns:
+
+- `@Query` works similarly to Neo4j's `@Query` annotation
+- `@TargetNode` replaces Neo4j's `@TargetNode` with the same semantics
+- `@RelationshipId` provides the same functionality as Neo4j's `@RelationshipId`
+
+The main differences are:
+- Package names use `falkordb` instead of `neo4j`
+- FalkorDB-specific optimizations and features
+- Integration with FalkorDB's graph query language

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

@@ -0,0 +1,73 @@
+/*
+ * Copyright 2011-2025 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
+ *
+ *      https://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.falkordb.core.schema;
+
+import java.lang.annotation.Documented;
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Inherited;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+import org.apiguardian.api.API;
+
+/**
+ * Annotation to mark a field in a {@link RelationshipProperties} annotated class as the
+ * relationship's internal ID.
+ * <p>
+ * This annotation is used to identify the field that holds the internal ID of a
+ * relationship in FalkorDB. The relationship ID is typically a {@code Long} value that is
+ * automatically generated by the database and represents the unique identifier of the
+ * relationship edge.
+ * <p>
+ * Example usage: <pre>
+ * &#64;RelationshipProperties
+ * public class ActedIn {
+ *
+ *     &#64;RelationshipId
+ *     private Long id;
+ *
+ *     &#64;TargetNode
+ *     private Person actor;
+ *
+ *     private List&lt;String&gt; roles;
+ *     private Integer year;
+ *
+ *     // constructors, getters, setters...
+ * }
+ * </pre>
+ * <p>
+ * In the above example, the {@code id} field marked with {@code @RelationshipId} will
+ * hold the internal ID of the relationship as assigned by FalkorDB.
+ * <p>
+ * This annotation is specifically designed for use with {@link RelationshipProperties}
+ * annotated classes and should not be used on regular node entities. For node entities,
+ * use {@link Id} or {@link org.springframework.data.annotation.Id} instead.
+ *
+ * @author Shahar Biron (FalkorDB adaptation)
+ * @since 1.0
+ * @see RelationshipProperties
+ * @see TargetNode
+ * @see Id
+ */
+@Retention(RetentionPolicy.RUNTIME)
+@Target(ElementType.FIELD)
+@Documented
+@Inherited
+@API(status = API.Status.STABLE, since = "1.0")
+public @interface RelationshipId {
+
+}

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

@@ -0,0 +1,86 @@
+/*
+ * Copyright 2011-2025 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
+ *
+ *      https://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.falkordb.core.schema;
+
+import java.lang.annotation.Documented;
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Inherited;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+import org.apiguardian.api.API;
+
+/**
+ * Annotation to mark a field in a {@link RelationshipProperties} annotated class as the
+ * target node of the relationship.
+ * <p>
+ * This annotation is used in conjunction with {@link RelationshipProperties} to define
+ * relationship entities that have properties. The field annotated with
+ * {@code @TargetNode} represents the target node of the relationship from the perspective
+ * of the source node.
+ * <p>
+ * Example usage: <pre>
+ * &#64;RelationshipProperties
+ * public class ActedIn {
+ *
+ *     &#64;RelationshipId
+ *     private Long id;
+ *
+ *     &#64;TargetNode
+ *     private Person actor;
+ *
+ *     private List&lt;String&gt; roles;
+ *     private Integer year;
+ *
+ *     // constructors, getters, setters...
+ * }
+ *
+ * &#64;Node
+ * public class Movie {
+ *
+ *     &#64;Id
+ *     private String title;
+ *
+ *     &#64;Relationship(type = "ACTED_IN", direction = Direction.INCOMING)
+ *     private List&lt;ActedIn&gt; actors = new ArrayList&lt;&gt;();
+ *
+ *     // other fields...
+ * }
+ * </pre>
+ * <p>
+ * In the above example, the {@code ActedIn} class represents a relationship with
+ * properties between a {@code Movie} and a {@code Person}. The {@code actor} field marked
+ * with {@code @TargetNode} represents the Person node that is the target of the ACTED_IN
+ * relationship.
+ * <p>
+ * The {@code @TargetNode} annotation helps Spring Data FalkorDB understand the structure
+ * of the relationship and properly map the relationship properties and target node when
+ * loading and saving entities.
+ *
+ * @author Shahar Biron (FalkorDB adaptation)
+ * @since 1.0
+ * @see RelationshipProperties
+ * @see Relationship
+ */
+@Retention(RetentionPolicy.RUNTIME)
+@Target(ElementType.FIELD)
+@Documented
+@Inherited
+@API(status = API.Status.STABLE, since = "1.0")
+public @interface TargetNode {
+
+}