Module jakarta.nosql.core
Package jakarta.nosql

Annotation Interface Entity

@Retention(RUNTIME) @Target(TYPE) public @interface Entity
Annotates a class as an entity, representing a persistent domain object stored in a NoSQL database.

Entity classes are associated with a database structure, such as a collection, bucket, column family, or edge label, depending on the type of NoSQL database. By default, the entity structure name is inferred from the class name, but you can customize it using value().

When writing queries using Jakarta Common Query Language (JCQL), the name used in the `FROM` clause is inferred from the class name or explicitly defined using the name() attribute. This is useful when multiple classes share the same simple name or when you want a more semantic alias for the query layer.

Entity classes must follow these rules:

  • Must include at least one field annotated with Id or Column.
  • Can use either fields or constructors to define persistence mappings.
  • If a constructor is annotated with Column or Id, it will be used to instantiate the entity.
  • If both a no-arg constructor and an annotated constructor are present, the annotated one is preferred.
  • Parameters without annotations in constructors are ignored.
  • Only one constructor should contain mapping annotations.
  • Records may also be annotated as entities.

Interfaces and enums cannot be used as entities.

Example using class and embedded entity:


 @Entity("people")
 public class Person {

     @Id
     private Long id;

     @Column
     private String name;

     @Column
     private Address address;
 }

 @Embeddable
 public class Address {

     @Column
     private String street;

     @Column
     private String city;
 }

Example using records and a custom query name:


 @Entity("Contacts")
 public record Person(@Id Long id, @Column String name, @Column Address address) {
 }

 // Query usage
 List<Person> people = template.query("FROM Contacts WHERE name = 'Ada'").result();

Note: NoSQL providers may serialize entities differently based on the underlying database engine.

Since:
1.0
See Also:

  • Optional Element Summary

    Optional Elements
    Modifier and Type
    Optional Element
    Description
    String
    name
    Defines the logical name used to reference this entity in Jakarta Common Query Language (JCQL).
    String
    value
    Defines the name of the NoSQL structure used to persist this entity.

  • Element Details

    • value

      String value
      Defines the name of the NoSQL structure used to persist this entity.

      If not specified, it defaults to the simple (unqualified) class name.

      The actual structure name depends on the NoSQL database type, for example:

      • Document: collection
      • Key-Value: bucket
      • Wide-column: column family
      • Graph: vertex label or edge label

      Example:

      
 @Entity("product_bucket")
 public class Product {
     @Id
     private String id;

     @Column
     private String name;
 }
      Returns:
      the NoSQL structure name
      Default:
      ""

    • name

      String name
      Defines the logical name used to reference this entity in Jakarta Common Query Language (JCQL).

      This is useful when multiple entity classes share the same simple name in different packages, or when you want a custom name for use in queries.

      If not specified, it defaults to the simple class name.

      Example:

      
 @Entity(name = "CatalogItem")
 public class Product {
     @Id
     private String id;

     @Column
     private String category;
 }

 // Usage in query:
 List<Product> items = template.query("FROM CatalogItem WHERE category = 'TECH'").result();
      Returns:
      the entity name used in query language
      Since:
      1.1.0
      Default:
      ""