Quarkus JNoSQL Extension

This documentation provides instructions on how to integrate Eclipse JNoSQL, an implementation of the Jakarta NoSQL and Jakarta Data specifications, into a Quarkus project using the Quarkus JNoSQL Extension. This extension supports JNoSQL and facilitates using NoSQL databases in your Quarkus applications.

Introduction

The Quarkus NoSQL Extension facilitates seamless interaction between Quarkus and Eclipse JNoSQL, enabling easy integration with various NoSQL databases in Quarkus applications. By following the steps outlined in this documentation, Quarkus developers can effortlessly incorporate Eclipse JNoSQL into their projects, simplifying NoSQL database interactions and empowering the development of efficient and scalable applications. Eclipse JNoSQL adheres to two essential Jakarta EE specifications: Jakarta Data and Jakarta NoSQL.

Jakarta NoSQL is a Java framework designed to streamline the integration of Java applications with various NoSQL databases. It offers a consistent and easy-to-use API, allowing developers to interact with different NoSQL databases seamlessly.

On the other hand, the Jakarta Data specification provides an API for simplified data access to various database types, including relational and NoSQL databases. Java developers can access these repositories through multiple methods, such as composing custom queries on a Repository interface.

Integrating Eclipse JNoSQL into Quarkus projects ensures adherence to these Jakarta EE standards and leverages the benefits of standardized APIs for enhanced productivity and maintainability.

Why Use Quarkus JNoSQL Extension?

The Quarkus NoSQL Extension offers several advantages for developers:

  • Simplified NoSQL Integration: Abstracts the complexity of working with different NoSQL databases, providing a consistent API regardless of the underlying technology. Facilitates easy switching between databases or using multiple databases in a single application.

  • Type-Safe Queries: Empowers developers to write database queries using Java code rather than raw query strings, improving code readability and catching errors at compile-time.

  • Seamless Quarkus Integration: Utilizes Quarkus' fast startup times and efficient resource utilization while working with NoSQL databases, ensuring lightweight and responsive applications.

  • Database Agnosticism: Supports a wide range of NoSQL databases, including key-value stores, document databases, and column-family stores. Offers flexibility to choose the most suitable database for specific use cases without major code changes.

  • Rich Documentation and Ecosystem: Eclipse JNoSQL boasts a thriving community and comprehensive documentation, making it easy for developers to find support, tutorials, and examples. Integration with Quarkus allows tapping into the vibrant Quarkus ecosystem as well.

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>3.4.7</version>
</dependency>

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

Recommended Quarkus JNoSQL Extension version: 3.4.7 or higher

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.

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 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

MongoDB Project

MongoDB is a free and open-source cross-platform document-oriented database program.

This driver provides support for the Document NoSQL API and Jakarta Data.

To create a Quarkus project with this extension, you can use the Quarkus CLI:

quarkus create app --extensions=jnosql-mongodb

To add this extension with the Quarkus CLI to an existing project:

quarkus create app --extensions=jnosql-mongodb

Or add it manually to your pom.xml:

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

Set the database name in application.properties:

jnosql.document.database=my-database-name

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.

Do you want to get started to create your entities and repositories? See the section Using Jakarta NoSQL and Jakarta Data with Quarkus JNoSQL.

More details: JNoSQL MongoDB Database Driver.

Cassandra

Apache Cassandra Project

Apache Cassandra is a distributed database management system.

Supports the Column NoSQL API and Jakarta Data.

To create a Quarkus project with this extension, you can use the Quarkus CLI:

quarkus create app --extensions=jnosql-cassandra

To add this extension with the Quarkus CLI to an existing project:

quarkus create app --extensions=jnosql-cassandra

Or add it manually to your pom.xml:

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

Set the database name in application.properties:

jnosql.column.database=my-database-name

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.

Do you want to get started to create your entities and repositories? See the section Using Jakarta NoSQL and Jakarta Data with Quarkus JNoSQL.

More details: JNoSQL Cassandra Database Driver.

ArangoDB

ArangoDB Project

ArangoDB is a native multi-model database.

Supports Document and Key-Value types, and Jakarta Data for Document entities.

To create a Quarkus project with this extension, you can use the Quarkus CLI:

quarkus create app --extensions=jnosql-arangodb

To add this extension with the Quarkus CLI to an existing project:

quarkus create app --extensions=jnosql-arangodb

Or add it manually to your pom.xml:

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

Set the database name in application.properties:

For the Key-Value database:

jnosql.keyvalue.database=my-database-name

For the Document database name:

jnosql.document.database=my-database-name

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.

Do you want to get started to create your entities and repositories? See the section Using Jakarta NoSQL and Jakarta Data with Quarkus JNoSQL.

More details: Using ArangoDB JNoSQL driver.

DynamoDB

70553550 f033b980 1b40 11ea 9192 759b3b1053b3

Amazon DynamoDB is a fully managed, serverless, key-value and document NoSQL database.

Supports Key-Value.

To create a Quarkus project with this extension, you can use the Quarkus CLI:

quarkus create app --extensions=jnosql-dynamodb

To add this extension with the Quarkus CLI to an existing project:

quarkus create app --extensions=jnosql-dynamodb

Or add it manually to your pom.xml:

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

Set the database name in application.properties:

jnosql.keyvalue.database=my-database-name

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.

Do you want to get started to create your entities and repositories? See the section Using Jakarta NoSQL and Jakarta Data with Quarkus JNoSQL.

See more details about DynamoDB Quarkiverse extension.

More details about JNoSQL DynamoDB Database driver.

Hazelcast

Hazelcast Project

Hazelcast is an open source in-memory data grid.

Supports Key-Value.

To create a Quarkus project with this extension, you can use the Quarkus CLI:

quarkus create app --extensions=jnosql-hazelcast

To add this extension with the Quarkus CLI to an existing project:

quarkus create app --extensions=jnosql-hazelcast

Or add it manually to your pom.xml:

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

Set the database name in application.properties:

jnosql.keyvalue.database=my-database-name

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.

Do you want to get started to create your entities and repositories? See the section Using Jakarta NoSQL and Jakarta Data with Quarkus JNoSQL.

More details about Quarkus Hazelcast extension.

More details about JNoSQL Hazelcast Database driver.

CouchDB

CouchDB

CouchDB provides an API integration between Java and the database.

Supports the Document NoSQL API and Jakarta Data.

To create a Quarkus project with this extension, you can use the Quarkus CLI:

quarkus create app --extensions=jnosql-couchdb

To add this extension with the Quarkus CLI to an existing project:

quarkus create app --extensions=jnosql-couchdb

Or add it manually to your pom.xml:

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

Set the database name in application.properties:

jnosql.document.database=my-database-name

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.

Do you want to get started to create your entities and repositories? See the section Using Jakarta NoSQL and Jakarta Data with Quarkus JNoSQL.

More details about JNoSQL CouchDB Database driver.

Elasticsearch

Elasticsearch Project

Elasticsearch is a search engine based on Lucene.

Supports the Document NoSQL API and Jakarta Data.

Does not support native compilation.

To create a Quarkus project with this extension, you can use the Quarkus CLI:

quarkus create app --extensions=jnosql-elasticsearch

To add this extension with the Quarkus CLI to an existing project:

quarkus create app --extensions=jnosql-elasticsearch

Or add it manually to your pom.xml:

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

Set the database name in application.properties:

jnosql.document.database=my-database-name

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.

Do you want to get started to create your entities and repositories? See the section Using Jakarta NoSQL and Jakarta Data with Quarkus JNoSQL.

More details about the Elasticsearch Client Quarkus extension.

More details about JNoSQL Elasticsearch Database driver.

Solr

Apache Solr Project

Solr is an open-source enterprise-search platform.

Supports the Document NoSQL API and Jakarta Data.

To create a Quarkus project with this extension, you can use the Quarkus CLI:

quarkus create app --extensions=jnosql-solr

To add this extension with the Quarkus CLI to an existing project:

quarkus create app --extensions=jnosql-solr

Or add it manually to your pom.xml:

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

Set the database name in application.properties:

jnosql.document.database=my-database-name

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.

Do you want to get started to create your entities and repositories? See the section Using Jakarta NoSQL and Jakarta Data with Quarkus JNoSQL.

More details about JNoSQL Solr Database driver.

Neo4j

Neo4J Project

Neo4J is a highly scalable, native graph database.

Supports Graph operations and Jakarta Data.

To create a Quarkus project with this extension, you can use the Quarkus CLI:

quarkus create app --extensions=jnosql-neo4j

To add this extension with the Quarkus CLI to an existing project:

quarkus create app --extensions=jnosql-neo4j

Or add it manually to your pom.xml:

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

Set the database name in application.properties:

jnosql.graph.database=my-database-name

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.

Example using GraphTemplate:

@Inject
@Database(DatabaseType.GRAPH)
protected GraphTemplate template;

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

Do you want to get started to create your entities and repositories? See the section Using Jakarta NoSQL and Jakarta Data with Quarkus JNoSQL.

More details about the Quarkus Neo4j extension.

More details about JNoSQL Neo4j Database driver.

Oracle NoSQL

Oracle NoSQL Project

Oracle NoSQL Database is a multi-model database.

Supports Document and Key-Value types and Jakarta Data.

To create a Quarkus project with this extension, you can use the Quarkus CLI:

quarkus create app --extensions=jnosql-oracle-nosql

To add this extension with the Quarkus CLI to an existing project:

quarkus create app --extensions=jnosql-oracle-nosql

Or add it manually to your pom.xml:

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

Set the database name in application.properties:

  • For Document database:

    jnosql.document.database=my-database-name

  • For Key-Value database:

    jnosql.keyvalue.database=my-database-name

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.

Do you want to get started to create your entities and repositories? See the section Using Jakarta NoSQL and Jakarta Data with Quarkus JNoSQL.

More details about JNoSQL Oracle NoSQL Database driver.