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 begin using JNoSQL with Quarkus, follow these steps:

1. Add the Quarkus JNoSQL Extension to your project's dependencies that fits with your necessities. Here are the supported databases by now and their respective NoSQL types:

   Database Vendor	Supported NoSQL Type	Supports Jakarta Data	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	✅	✅

2. If you're using Java 21 or above you should activate explicitly the annotation processor execution by setting <proc>full</proc> on the maven-compiler plugin. If you're using any previous Java version, e.g. Java 17, you can skip this step.

   This is necessary for the JNoSQL Lite Extension to work properly. An pom.xml configuration example below:

   <plugin>
        <artifactId>maven-compiler-plugin</artifactId>
        <version>${compiler-plugin.version}</version>
        <configuration>
            <proc>full</proc>
            <compilerArgs>
                <arg>-parameters</arg>
            </compilerArgs>
        </configuration>
    </plugin>

3. Define your entities using JNoSQL annotations. Here's an example entity class:

   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
   }

4. Use the JNoSQL template to perform CRUD operations on your entities.

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

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

   • For implementation that offers Jakarta Data support you may create and inject a Jakarta Data Repository. Here's an usage example:

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

   • With that, you can inject and use the TestEntityRepository in your service classes as the example below:

   @ApplicationScope
   class TestEntityService {
   
       @Inject
       @Database(DatabaseType.COLUMN)
       TestEntityRepository repository;
   
       public void insert(TestEntity entity) {
          repository.save(entity);
       }
   }

Next, we will provide specific 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!