Quarkus JNoSQL

This documentation provides instructions on how to integrate JNoSQL, an implementation of Jakarta NoSQL and Jakarta Data, into a Quarkus project using the Quarkus JNoSQL Extension.

This extension supports JNoSQL and facilitates using NoSQL databases in your Quarkus applications.

ℹ️ Recommended Quarkus version: 3.2.2.Final or higher

Getting Started

To use this extension, add the Quarkus JNoSQL Database extension that you need to your build file.For instance, with Maven, include the following dependency in your POM file:

<dependency>
    <groupId>io.quarkiverse.jnosql</groupId>
    <artifactId>quarkus-jnosql-[DATABASE]</artifactId>
    <version>{project-version}</version>
</dependency>

Replace [DATABASE] with the specific database you want to use. Let see the supported NoSQL databases in the next section.

And replace {project-version} with the latest stable version of the Quarkus JNoSQL Extension.

Supported NoSQL Databases

The Quarkus JNoSQL extension supports a variety of NoSQL databases, each with its own unique features and capabilities. Below is a table summarizing the supported NoSQL types, whether they support Jakarta Data, and if they support Native Compilation:

Database Vendor	Supported NoSQL Type	Supports Jakarta Data	Provides Codestart	Supports Native Compilation
MongoDB	Document	✅	✅	✅
Cassandra	Column	✅	✅	✅
CouchDB	Document	✅	✅	✅
ArangoDB	Document and Key-Value	✅	✅	✅
DynamoDB	Key-Value	❌	✅	✅
Elasticsearch	Document	✅	✅	❌
Hazelcast	Key-Value	❌	✅	✅
Solr	Document	✅	✅	✅
Neo4j	Graph	✅	✅	✅
Oracle NoSQL	Document and Key-Value	✅	✅	✅

Create your Quarkus JNoSQL Project using Extension Codestarts

The easiest way to get started with Quarkus JNoSQL Extension is by using the codestart provided by the extension. This codestart will generate a Quarkus project with the necessary dependencies and configurations for using JNoSQL with your chosen NoSQL database.

You can use the Quarkus CLI to create a new project passing the Quarkus JNoSQL Extension that you want. It'll create the project with all required dependencies and configurations automatically. For example, to create a project using Quarkus JNoSQL MongoDB Extension, you can run:

quarkus create app --extensions=jnosql-mongodb

Here is a table with the available Quarkus JNoSQL Extensions that you can use with the quarkus create app command:

Database Vendor	Command
MongoDB	quarkus create app --extensions=jnosql-mongodb
Cassandra	quarkus create app --extensions=jnosql-cassandra
CouchDB	quarkus create app --extensions=jnosql-couchdb
ArangoDB	quarkus create app --extensions=jnosql-arangodb
DynamoDB	quarkus create app --extensions=jnosql-dynamodb
Elasticsearch	quarkus create app --extensions=jnosql-elasticsearch
Hazelcast	quarkus create app --extensions=jnosql-hazelcast
Solr	quarkus create app --extensions=jnosql-solr
Neo4j	quarkus create app --extensions=jnosql-neo4j
Oracle NoSQL	quarkus create app --extensions=jnosql-oracle-nosql

Or you could create it on by downloading the scaffolding project from the code.quarkus.io and selecting the JNoSQL extension for your desired NoSQL database.

Manually adding Quarkus JNoSQL Extension to your project

There are a variety of NoSQL databases, each with its own unique features and capabilities. See the section Supported NoSQL Databases, select the one that fits your needs, and then follow the instructions below to manually add the Quarkus JNoSQL Extension to your project.

📝 IMPORTANT: If you are using Java 21 or above, make sure to enable the annotation processor execution. If you are using Java 17 or below, you can skip this step and go ahead to implement your entities and repositories.

Enabling the JNoSQL Mapping Lite Annotation Processor

The Quarkus JNoSQL Extensions are using the annotation processor provided by the org.eclipse.jnosql.lite:mapping-lite-processor:1.1.8 dependency. This dependency is automatically included when you add any Quarkus JNoSQL extension to your project.

This annotation processor is responsible to generate all the required implementation classes that will be used by the CDI during AOT compilation.

To ensure that the annotation processor is executed during the build process, you need to configure your build tool (Maven or Gradle) accordingly.

Maven

If you're using Java 21 or above, you should explicitly make sure to activate the annotation processor execution by setting <proc>full</proc> on the maven-compiler plugin or via the maven.compiler.proc>full</maven.compiler.proc> property.For previous Java versions, e.g. Java 17, you can skip this step.For example:

Setting it in the pom.xml properties:

<project>
    <!-- skipping other elements -->
    <properties>
        <!-- skipping other properties -->
        <maven.compiler.proc>full</maven.compiler.proc>
        <!-- skipping other properties -->
    </properties>
    <!-- skipping other elements -->
</project>

Or setting it directly in the maven-compiler-plugin configuration:

<project>
<!-- skipping other elements -->
<build>
    <plugins>
        <!-- skipping other plugins -->
        <plugin>
            <artifactId>maven-compiler-plugin</artifactId>
            <version>${compiler-plugin.version}</version>
            <configuration>
                <proc>full</proc>
                <compilerArgs>
                    <arg>-parameters</arg>
                </compilerArgs>
            </configuration>
        </plugin>
        <!-- skipping other plugins -->
    </plugins>
</build>
<!-- skipping other elements -->
</project>

Gradle

The target build tool for the Quarkus JNoSQL Extension is Maven. However, if you are using Gradle, you may need to ensure that the annotation processor is executed during the build process.

To enable the annotation processors execution is necessary to pass the -proc:full to the compiler used by Gradle. For example like below:

Groovy DSL (build.gradle):

tasks.withType(JavaCompile).configureEach {
options.compilerArgs += ['-proc:full']
}

Kotlin DSL (build.gradle.kts):

tasks.withType<JavaCompile>().configureEach {
options.compilerArgs.add("-proc:full")
}

Using Jakarta NoSQL and Jakarta Data with Quarkus JNoSQL

Once you have added the Quarkus JNoSQL Extension to your project, you can start using it to interact with your NoSQL database. The following steps outline how to create entities and repositories in your Quarkus application:

Creating entities using JNoSQL annotations

import jakarta.nosql.Column;
import jakarta.nosql.Entity;
import jakarta.nosql.Id;

@Entity
public class TestEntity {

    @Id
    private String id;

    @Column
    private String testField;

    // omitted getters and setters
}

Using Jakarta NoSQL Template

Example using jakarta.nosql.Template:

@Inject
// If your NoSQL database supports multiple types,
// you can specify the type using the @Database annotation.

// @Database(DatabaseType.DOCUMENT) for Document databases
// @Database(DatabaseType.COLUMN) for Column databases
// @Database(DatabaseType.GRAPH) for Graph databases
// @Database(DatabaseType.KEY_VALUE) for Key-Value databases
protected Template template;

public void insert(TestEntity entity) {
    template.insert(entity);
}

Using Jakarta Data Repository

For implementations that offer Jakarta Data support, you may create and inject a Jakarta Data Repository:

@Repository
public interface TestEntityRepository extends NoSQLRepository<TestEntity, String> {
}

Jakarta Data repositories provide a powerful way to interact with your NoSQL database using a repository pattern.

The interface org.eclipse.jnosql.mapping.NoSQLRepository used above extends the jakarta.data.repository.BasicRepository, which is a Jakarta Data Repository interface that brings a specialization for NoSQL useful operations, allowing developers to use pre-defined methods. Also,you can define custom queries using method names or annotations, and the framework will handle the implementation for you. More information about Jakarta Data can be found in the Jakarta Data Specification.

Using the Jakarta Data Repositories or Jakarta NoSQL Templates in your service

@ApplicationScope
class TestEntityService {

    @Inject
    // If your NoSQL database supports multiple types,
    // you can specify the type using the @Database annotation.

    // @Database(DatabaseType.DOCUMENT) for Document databases
    // @Database(DatabaseType.COLUMN) for Column databases
    // @Database(DatabaseType.GRAPH) for Graph databases
    // @Database(DatabaseType.KEY_VALUE) for Key-Value databases
    Template template;

    @Inject
    // If your NoSQL database supports multiple types,
    // you can specify the type using the @Database annotation.

    // @Database(DatabaseType.DOCUMENT) for Document databases
    // @Database(DatabaseType.COLUMN) for Column databases
    // @Database(DatabaseType.GRAPH) for Graph databases
    // @Database(DatabaseType.KEY_VALUE) for Key-Value databases
    TestEntityRepository repository;

    public void insertViaRepository(TestEntity entity) {
        repository.save(entity);
    }

    public void insertViaTemplate(TestEntity entity) {
        template.insert(entity);
    }

}

Now, you can use the TestEntityService to perform CRUD operations on your TestEntity objects using the repository.

That's it! You have successfully set up a Quarkus application with the Quarkus JNoSQL Extension, allowing you to interact with your NoSQL database using Jakarta NoSQL and Jakarta Data.

Next, we provide more instructions for each supported database.

MongoDB

https://www.mongodb.com/[MongoDB] is a free and open-source cross-platform document-oriented database program. Classified as a NoSQL database program, MongoDB uses JSON-like documents with schemas.

This driver provides support for the Document NoSQL API.

It supports Jakarta Data.

Add the MongoDB dependency to your project's pom.xml:

<dependency>
    <groupId>io.quarkiverse.jnosql</groupId>
    <artifactId>quarkus-jnosql-mongodb</artifactId>
</dependency>

To define the Document database's name, you need to add the following info in your application.properties:

jnosql.document.database=my-database-name

For specific configuration details, please refer to the MongoDB Quarkus extension.

Cassandra

Apache Cassandra is a free and open-source distributed database management system designed to handle large amounts of data across many commodity servers, providing high availability with no single point of failure.

This driver provides support for the Column NoSQL API.

It supports Jakarta Data.

Add the Cassandra dependency to your project's pom.xml:

<dependency>
    <groupId>io.quarkiverse.jnosql</groupId>
    <artifactId>quarkus-jnosql-cassandra</artifactId>
</dependency>

To define the Column database's name, you need to add the following info in your application.properties:

jnosql.column.database=my-database-name

Please refer to the Cassandra Quarkus extension for specific configuration details.

ArangoDB

ArangoDB is a native multi-model database with flexible data models for documents, graphs, and key-values. Build high performance applications using a convenient SQL-like query language or JavaScript extensions.

This extension offers support for Document and Key-Value types. Also, it provides support for Jakarta Data for Document NoSQL Entities.

Add the ArangoDB dependency to your project's pom.xml:

<dependency>
    <groupId>io.quarkiverse.jnosql</groupId>
    <artifactId>quarkus-jnosql-arangodb</artifactId>
    <version>${quarkus-jnosql.version}</version>
</dependency>

To define the Key-Value database's name, you need to add the following info in your application.properties:

jnosql.keyvalue.database=my-database-name

To define the Document database's name, you need to add the following info in your application.properties:

jnosql.document.database=my-database-name

For specific configuration details, please refer to the ArangoDB JNoSQL driver.

DynamoDB

Amazon DynamoDB is a fully managed, serverless, key-value and document NoSQL database designed to run high-performance applications at any scale. DynamoDB offers built-in security, continuous backups, automated multi-Region replication, in-memory caching, and data import and export tools.

This driver has support for two NoSQL API types: Key-Value.

Add the DynamoDB dependency to your project's pom.xml:

<dependency>
    <groupId>io.quarkiverse.jnosql</groupId>
    <artifactId>quarkus-jnosql-dynamodb</artifactId>
</dependency>

To define the Key-Value database's name, you need to add the following info in your application.properties:

jnosql.keyvalue.database=my-database-name

Please refer to the DynamoDB Quarkiverse extension for specific configuration details.

Hazelcast

Hazelcast is an open source in-memory data grid based on Java.

This driver provides support for the Key-Value NoSQL API.

Add the Hazelcast dependency to your project's pom.xml:

<dependency>
    <groupId>io.quarkiverse.jnosql</groupId>
    <artifactId>quarkus-jnosql-hazelcast</artifactId>
</dependency>

To define the Key-Value database's name, you need to add the following info in your application.properties:

jnosql.keyvalue.database=my-database-name

Please refer to the Quarkus Hazelcast extension for specific configuration details.

CouchDB

The CouchDB driver provides an API integration between Java and the database through a standard communication level.

This driver provides support for the Document NoSQL API.

It supports Jakarta Data.

Add the CouchDB dependency to your project's pom.xml:

<dependency>
    <groupId>io.quarkiverse.jnosql</groupId>
    <artifactId>quarkus-jnosql-couchdb</artifactId>
</dependency>

To define the Document database's name, you need to add the following info in your application.properties:

jnosql.document.database=my-database-name

For specific configuration details, please refer to the CouchDB JNoSQL driver.

Elasticsearch

Elasticsearch is a search engine based on Lucene.
It provides a distributed, multitenant-capable full-text search engine with an HTTP web interface and schema-free JSON documents.
Elasticsearch is developed in Java and is released as open source under the terms of the Apache License. Elasticsearch is the most popular enterprise search engine followed by Apache Solr, also based on Lucene.

This driver provides support for the Document NoSQL API.

It supports Jakarta Data.

ℹ️ It does not support native compilation, unfortunately.

Add the Elasticsearch dependency to your project's pom.xml:

<dependency>
    <groupId>io.quarkiverse.jnosql</groupId>
    <artifactId>quarkus-jnosql-elasticsearch</artifactId>
</dependency>

To define the Document database's name, you need to add the following info in your application.properties:

jnosql.document.database=my-database-name

Please refer to the Elasticsearch Quarkus extension for specific configuration details.

Solr

Solr is an open-source enterprise-search platform, written in Java, from the Apache Lucene project. Its major features include full-text search, hit highlighting, faceted search, real-time indexing, dynamic clustering, database integration, NoSQL features and rich document (e.g., Word, PDF) handling. Providing distributed search and index replication, Solr is designed for scalability and fault tolerance. Solr is widely used for enterprise search and analytics use cases and has an active development community and regular releases.

This driver provides support for the Document NoSQL API.

It supports Jakarta Data.

Add the Quarkus JNoSQL Solr dependency to your project's pom.xml:

<dependency>
    <groupId>io.quarkiverse.jnosql</groupId>
    <artifactId>quarkus-jnosql-solr</artifactId>
</dependency>

For specific configuration details, please refer to the Solr JNoSQL driver.

Neo4j

Neo4J is a highly scalable, native graph database designed to manage complex relationships in data. It enables developers to build applications that leverage the power of graph traversal, pattern matching, and high-performance querying using the Cypher query language.

This API provides support for Graph database operations, including entity persistence, query execution via Cypher, and relationship traversal.

ℹ️ This extension is using the org.eclipse.jnosql.databases:jnosql-neo4j:1.1.7-SNAPSHOT

Add the Quarkus JNoSQL Neo4j dependency to your project's pom.xml:

<dependency>
    <groupId>io.quarkiverse.jnosql</groupId>
    <artifactId>quarkus-jnosql-neo4j</artifactId>
</dependency>

Now, you can use the org.eclipse.jnosql.mapping.graph.GraphTemplate, a jakarta.nosql.Template specialized interface, to perform CRUD operations on your entities.

• Here's an example of how to use the jakarta.nosql.Template:

  @Inject
  @Database(DatabaseType.GRAPH)
  protected GraphTemplate template;
  
  public void insert(TestEntity entity) {
   template.insert(entity);
  }

For specific configuration details, please refer to the Quarkus Neo4j extension.

Oracle NoSQL

Oracle NoSQL Database is a versatile multi-model database offering flexible data models for documents, graphs, and key-value pairs. It empowers developers to build high-performance applications using a user-friendly SQL-like query language or JavaScript extensions.

This API provides support for Document and Key-Value data types.

It supports Jakarta Data.

Add the Quarkus JNoSQL Oracle NoSQL dependency to your project's pom.xml:

<dependency>
    <groupId>io.quarkiverse.jnosql</groupId>
    <artifactId>quarkus-jnosql-oracle-nosql</artifactId>
</dependency>

For specific configuration details, please refer to the Oracle NoSQL JNoSQL driver.

Contributors ✨

Thanks to these wonderful people (emoji key) for their contributions:

amoscatelli 💻 🚧 📖

Otávio Santana 💻 🚧 📖

Maximillian Arruda 💻 🚧 📖

George Gastaldi 🚇 🚧 📖

This project follows the all-contributors specification. Contributions of any kind are welcome!