= Jakarta NoSQL :toc: auto
ifndef::imagesdir[:imagesdir: spec/src/main/asciidoc/images] image::jakarta_ee_logo_schooner_color_stacked_default.png[Jakarta NoSQL logo,align=center, width=25%, height=25%]
== Introduction
Jakarta NoSQL is a comprehensive framework designed to simplify the integration of Java applications with various NoSQL databases. By providing a unified API and a set of powerful annotations, Jakarta NoSQL enables developers to seamlessly work with different NoSQL data stores while maintaining flexibility and productivity.
== Goals
- Increase productivity performing common NoSQL operations.
- Rich Object Mapping integrated.
- Java-based Query and Fluent-API.
- It is designed to work with various NoSQL databases and can quickly adapt to support new types and behaviors through extensions.
- Annotation-oriented using Jakarta Persistence-like naming when it makes sense.
== One Mapping API to Multiples NoSQL Databases
Jakarta NoSQL provides one API for each NoSQL database type. However, it incorporates the same annotations from the Jakarta Persistence specification and heritage Java Persistence Architecture (JPA) to map Java objects. Therefore, with just these annotations that look like Jakarta Persistence, there is support for more than twenty NoSQL databases.
[source,java]
@Entity public class Car {
@Id
private Long id;
@Column
private String name;
@Column
private CarType type;//... }
=== Annotations
The annotations from the Mapping API will look familiar to Jakarta Persistence developers:
[cols="2"]
|===
| Annotation | Description
| @Entity | Specifies that the class is an entity. This annotation is applied to the entity class.
| @Id | Specifies the primary key of an entity.
| @Column | Specifies the mapped column for a persistent property or field.
| @MappedSuperclass | Specifies a class whose mapping information is applied to entities that inherit from it.
| @Embeddable | Declares a class whose instances are stored as an intrinsic part of an owning entity, sharing the identity of the entity.
| @Inheritance | Specifies the inheritance mapping strategy for the entity class hierarchy.
| @DiscriminatorColumn | Specifies the discriminator column for the mapping strategy.
| @DiscriminatorValue | Specifies the value of the discriminator column for the annotated entity type.
| @Convert | Specifies how the values of a field or property are converted to a basic type or a type that can be persisted by a persistence provider.
| @Converter | Declares a converter class and specifies whether it is automatically applied to attributes of the target type.
| @Projection | Declares a Java record as a projection for query results. Enables mapping partial or flattened query results to a record without requiring explicit field selection in the query.
|===
These annotations serve as a familiar and powerful toolkit for Java developers, enabling them to map Java objects to NoSQL databases similarly to how Jakarta Persistence works with relational data.
=== Template
The Template interface is the central entry point for interacting with a NoSQL database in Jakarta NoSQL. It provides a consistent, high-level API for performing common persistence operations such as insert, update, delete, and query.
Jakarta NoSQL supports multiple interaction styles through the Template, including:
- Basic CRUD operations
- Fluent-style query builders
- String-based queries with support for projections
==== Basic Operations
Once you’ve annotated your entity, you can perform basic operations like insert, find, and delete using the Template instance.
[source,java]
@Inject Template template;
Car ferrari = Car.builder() .id(1L) .name("Ferrari") .type(CarType.SPORT) .build();
template.insert(ferrari);
Optional
template.delete(Car.class, 1L);
Jakarta NoSQL provides a unified API with specialized support for a wide range of NoSQL databases, including but not limited to document, key-value, column-oriented, graph, and emerging models.
==== Fluent API
Jakarta NoSQL provides a fluent API for dynamic query construction, enabling expressive selection, update, and deletion operations without relying on string-based queries.
This API is designed for scenarios where queries must be built programmatically, such as dynamic filters, reusable query logic, or conditional operations, while remaining database-agnostic.
Select example:
[source,java]
List sportsCars = template.select(Car.class)
.where("type").eq(CarType.SPORT)
.orderBy("name")
.result();
Update example:
[source,java]
template.update(Car.class) .set("available").to(false) .where("type").eq(CarType.CLASSIC) .execute();
Delete example:
[source,java]
template.delete(Car.class) .where("type").eq(CarType.CLASSIC) .execute();
This fluent style makes query intent explicit (select, update, delete),
reduces the risk of errors common in string-based queries, and adapts naturally
to the capabilities of different NoSQL databases.
==== Typed Queries and Projections
Jakarta NoSQL supports string-based queries using the Jakarta Common Query Language (JCQL). There are two main methods for executing these queries:
query(String)— executes a generic query that always returns entities and requires an explicitFROMclause.typedQuery(String, Class<T>)— maps results to either an entity or a projection class. Supports omitting theFROMclause when used with@Projection(from = ...).
===== Using query(String) – entity results only
The query(String) method is useful for selecting full entity instances, deleting, or updating data. It always returns entity types and requires a FROM clause in the query.
[source,java]
List
Optional car = template.query("FROM Car WHERE id = :id")
.bind("id", 42)
.singleResult();
IMPORTANT: You cannot use projections with query(String) — only entity classes are supported.
===== Using typedQuery(String, Class<T>) – entities and projections
Use typedQuery(...) when you want to:
- Retrieve data as a projection (using
recordand@Projection) - Omit the
FROMclause when using@Projection(from = ...)
This method supports the full query API — result(), stream(), and singleResult():
[source,java]
@Projection public record TechCarView(String name, CarType type) {}
List cars = template.typedQuery("FROM Car WHERE type = 'SPORT'", TechCarView.class).result();
You may also omit the FROM clause entirely if you annotate the projection with @Projection(from = Car.class):
[source,java]
@Projection(from = Car.class) public record BudgetCar(String name, double price) {}
List cheapCars = template.typedQuery("WHERE price < 100", BudgetCar.class).result();
===== Single result queries
Both query(...) and typedQuery(...) support retrieving a single result wrapped in an Optional:
[source,java]
Optional
Optional result = template.typedQuery("WHERE price < 100", BudgetCar.class).singleResult();
=== Maven dependency
[source,xml]
=== Communication API
The Communication API provides a low-level interface for interacting with NoSQL databases, allowing developers to perform operations directly on the underlying data structures. To get more information about the Communication API, please refer to the link:COMMUNICATION.adoc[Communication API] document.
=== More Information
To learn more, please refer to the https://www.jnosql.org/spec/[reference documentation], and https://www.jnosql.org/javadoc/[JavaDocs].
== Code of Conduct
This project is governed by the Eclipse Foundation of Conduct. By participating, you are expected to uphold this code of conduct. Please report unacceptable behavior to [email protected].
== Getting Help
Having trouble with Jakarta NoSQL? We’d love to help!
Please report any bugs, concerns, or questions with Jakarta NoSQL to https://github.com/jakartaee/nosql.
== Building from Source
You don't need to build from source to use the project, but should you be interested in doing so, you can build it using Maven and Java 21 or higher.