clotho/docs/ANNOTATIONS.md

Annotation Reference

Class-Level Annotations

---

@VertexType

Declares a class as a Clotho-managed vertex type. The class must extend ClothoVertex.

@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
public @interface VertexType {
    String value();                  // ArcadeDB vertex type name (required)
    String[] additionalParents()     // ArcadeDB parent type names beyond Java hierarchy
        default {};                  // Use for diamond inheritance
    String parentLabel()             // Explicit ArcadeDB parent when Java hierarchy diverges
        default "";
}

Examples:

// Simple
@VertexType("Employee")
public class Employee extends ClothoVertex { }

// Abstract type
@VertexType("Person")
public abstract class Person extends ClothoVertex { }

// Diamond inheritance
@VertexType(value = "ContractEmployee", additionalParents = {"Contractor"})
public class ContractEmployee extends Employee { }

// Divergent Java/ArcadeDB hierarchy
@VertexType(value = "ExternalWorker", parentLabel = "Employee")
public class ExternalWorker extends ClothoVertex { }

---

@EdgeType

Declares a class as a Clotho-managed edge type. The class must extend ClothoEdge.

@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
public @interface EdgeType {
    String value();   // ArcadeDB edge type name (required)
}

Example:

@EdgeType("WORKS_AT")
public class WorksAt extends ClothoEdge {
    public static final String LABEL = "WORKS_AT";
    // ...
}

Convention: define LABEL as a constant on the edge class to avoid magic strings at call sites when referencing the label in @Via.

---

@SubgraphType

Declares a composite type assembled from a Gremlin select() traversal. Must NOT extend ClothoVertex or ClothoEdge. Has no ARID.

@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
public @interface SubgraphType {
}

Example:

@SubgraphType
public class EmployeeProfile {
    Employee employee;
    Manager manager;
    @Alias("dept") Department department;
    List<WorksAt> workHistory;
}

---

Field-Level Annotations

---

@RID

Marks the field that holds the element's ARID. Inherited from ClothoEntity; generally not needed unless overriding the base class field.

@Target(ElementType.FIELD)
@Retention(RetentionPolicy.RUNTIME)
public @interface RID {
}

---

@Property

Maps a field to an ArcadeDB vertex or edge property. Optional when the field name exactly matches the property name.

@Target(ElementType.FIELD)
@Retention(RetentionPolicy.RUNTIME)
public @interface Property {
    String value();   // ArcadeDB property name
}

Example:

@Property("startDate") LocalDate start;   // field name differs from property name
LocalDate endDate;                         // no annotation needed; names match

---

@Include

Marks a field as part of this object's eager-load boundary. Always paired with @Via. The field type must be a @VertexType class, an @EdgeType class, or a List<> of either.

@Target(ElementType.FIELD)
@Retention(RetentionPolicy.RUNTIME)
public @interface Include {
}

---

@Via

Specifies the ArcadeDB edge label to traverse for an @Include field.

@Target(ElementType.FIELD)
@Retention(RetentionPolicy.RUNTIME)
public @interface Via {
    String value();   // Edge label (required)
}

Strongly preferred pattern — use the edge class's LABEL constant:

@Include @Via(WorksAt.LABEL)
List<WorksAt> workHistory;

---

@Direction

Specifies which edge direction to follow for an @Include + @Via traversal. Defaults to OUT (or the global configured default).

@Target(ElementType.FIELD)
@Retention(RetentionPolicy.RUNTIME)
public @interface Direction {
    Direction value() default Direction.OUT;
}

public enum Direction { OUT, IN, BOTH }

Example:

@Include @Via("ASSIGNED_TO") @Direction(Direction.IN)
List<Task> assignedTasks;

---

@OutVertex

On an @EdgeType class: marks the field holding the out-vertex (source) of the edge. The field type must be a @VertexType class.

@Target(ElementType.FIELD)
@Retention(RetentionPolicy.RUNTIME)
public @interface OutVertex {
}

---

@InVertex

On an @EdgeType class: marks the field holding the in-vertex (target) of the edge. The field type must be a @VertexType class. Omitting @InVertex entirely = edge-only inclusion; the target vertex is not loaded.

@Target(ElementType.FIELD)
@Retention(RetentionPolicy.RUNTIME)
public @interface InVertex {
}

---

@Alias

On a @SubgraphType field: specifies the Gremlin as() alias that this field is bound to. Defaults to the field name when omitted.

@Target(ElementType.FIELD)
@Retention(RetentionPolicy.RUNTIME)
public @interface Alias {
    String value();
}

Example:

@Alias("dept")
Department department;   // binds to .as("dept") in the Gremlin query

---

Query Annotations

---

@Query

Declares a Gremlin traversal. Used on @ClothoRepository interface methods (primary use) or on @VertexType classes as named queries (secondary use).

@Target({ElementType.METHOD, ElementType.TYPE})
@Retention(RetentionPolicy.RUNTIME)
@Repeatable(Queries.class)   // allows multiple @Query on a class (different names)
public @interface Query {
    String value() default "";   // Gremlin string (for method use)
    String name() default "";    // Named query identifier (for class-level use)
    String gremlin() default ""; // Gremlin string (for class-level use; alias for clarity)
    boolean mapResult() default true;  // false = return raw Gremlin result
}

Examples:

// On a repository method
@Query("g.V().hasLabel('Employee').has('dept',:dept)")
List<Employee> findByDepartment(@Param("dept") String dept);

// Raw result — no Clotho mapping
@Query(value = "g.V().hasLabel('Employee').count()", mapResult = false)
long countAll();

// Named query on a class
@VertexType("Order")
@Query(name = "openForCustomer",
       gremlin = "g.V().has('Customer','id',:custId).out('PLACED').has('status','OPEN')")
public class Order extends ClothoVertex { ... }

---

@Param

Binds a method parameter to a named placeholder in a @Query Gremlin string.

@Target(ElementType.PARAMETER)
@Retention(RetentionPolicy.RUNTIME)
public @interface Param {
    String value();   // placeholder name (without the colon)
}

Example:

@Query("g.V().has('Employee','dept',:dept).has('level',:level)")
List<Employee> findByDeptAndLevel(
    @Param("dept") String department,
    @Param("level") int level);

---

Spring Annotation

---

@ClothoRepository

Marks an interface as a Clotho query interface. The clotho-spring-boot-starter scans for these interfaces and registers a dynamic proxy as a Spring bean.

@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
public @interface ClothoRepository {
}

Example:

@ClothoRepository
public interface OrderQueries {
    @Query("g.V().has('Order','status','OPEN')")
    List<Order> findOpenOrders();
}

Inject via Spring as you would any repository:

@Autowired OrderQueries orderQueries;