# jnosql **Repository Path**: mirrors_eclipse/jnosql ## Basic Information - **Project Name**: jnosql - **Description**: Eclipse JNoSQL is a framework which has the goal to help Java developers to create Jakarta EE applications with NoSQL. - **Primary Language**: Unknown - **License**: Apache-2.0 - **Default Branch**: main - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2020-08-22 - **Last Updated**: 2026-10-22 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README = Eclipse JNoSQL :toc: auto == Introduction Eclipse JNoSQL is a compatible implementation of the https://jakarta.ee/specifications/nosql/[Jakarta NoSQL] and https://jakarta.ee/specifications/data/[Jakarta Data] specifications, a Java framework that streamlines the integration of Java applications with NoSQL databases. == Goals * Increase productivity performing common NoSQL operations * Rich Object Mapping integrated with Contexts and Dependency Injection (CDI) * Java-based Query and Fluent-API * Persistence lifecycle events * Low-level mapping using Standard NoSQL APIs * Specific template API to each NoSQL category * Annotation-oriented using JPA-like naming when it makes sense * Extensible to explore the particular behavior of a NoSQL database * Explore the popularity of Apache TinkerPop in Graph API * Jakarta NoSQL and Data implementations == Why Eclipse JNoSQL? Eclipse JNoSQL is a Java framework that unifies NoSQL access across different database types, including Key-Value, Column Family, Document, Graph, and Time Series. Built on top of the Jakarta NoSQL and Jakarta Data specifications, it simplifies development through standard annotations, fluent APIs, and full compatibility with Jakarta EE and MicroProfile runtimes. Use Eclipse JNoSQL to: * Increase productivity with annotation-based object mapping * Write expressive queries using a fluent or method-name DSL * Reduce boilerplate through CDI-managed components and lifecycle events * Switch NoSQL vendors with minimal code changes * Align with modern practices like Domain-Driven Design (DDD) * Rely on a standards-based solution compatible with Jakarta EE and MicroProfile servers == One Mapping API to Multiples NoSQL Databases Eclipse JNoSQL provides one API for each NoSQL database type. However, it incorporates the same annotations from the https://jakarta.ee/specifications/persistence/[Jakarta Persistence] specification and inherits from the Java Persistence Java Persistence API (JPA) to map Java objects. Therefore, with just these annotations that look like JPA, 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; //... } ---- These annotations from the Mapping API will look familiar to the Jakarta Persistence/JPA developer: [cols="Annotation description"] |=== |Annotation|Description |`@jakarta.nosql.Entity` |Specifies that the class is an entity. This annotation is applied to the entity class. |`@jakarta.nosql.Id` |Specifies the primary key of an entity. |`@jakarta.nosql.Column` |Specify the mapped column for a persistent property or field. |`@jakarta.nosql.Embeddable` |Specifies a class whose instances are stored as an intrinsic part of an owning entity and share the entity's identity. |`@jakarta.nosql.Convert` |Specifies the conversion of a Basic field or property. |`@org.eclipse.jnosql.mapping.MappedSuperclass` |Designates a class whose mapping information is applied to the entities that inherit from it. A mapped superclass has no separate table defined for it. |`@jakarta.nosql.Inheritance` |Specifies the inheritance strategy to be used for an entity class hierarchy. |`@jakarta.nosql.DiscriminatorColumn` |Specifies the discriminator column for the mapping strategy. |`@jakarta.nosql.DiscriminatorValue` |Specifies the value of the discriminator column for entities of the given type. |=== IMPORTANT: Although similar to JPA, Jakarta NoSQL defines persistable fields with either the ```@Id``` or ```@Column``` annotation. After mapping an entity, you can explore the advantage of using a ```Template``` interface, which can increase productivity on NoSQL operations. [source,java] ---- @Inject Template template; ... Car ferrari = Car.id(1L) .name("Ferrari") .type(CarType.SPORT); template.insert(ferrari); Optional car = template.find(Car.class, 1L); template.delete(Car.class, 1L); List cars = template.select(Car.class).where("name").eq("Ferrari").result(); template.delete(Car.class).execute(); ---- This template has specialization to take advantage of a particular NoSQL database type. A ``Repository`` interface is also provided for exploring the Domain-Driven Design (DDD) pattern for a higher abstraction. [source,java] ---- public interface CarRepository extends PageableRepository { Optional findByName(String name); } @Inject CarRepository repository; ... Car ferrari = Car.id(1L) .name("Ferrari") .type(CarType.SPORT); repository.save(ferrari); Optional idResult = repository.findById(1L); Optional nameResult = repository.findByName("Ferrari"); ---- == Getting Started Eclipse JNoSQL requires these minimum requirements: * Java 17 (or higher) * https://jakarta.ee/specifications/cdi/3.0/[Jakarta Contexts & Dependency Injection 3.0] (CDI) * https://jakarta.ee/specifications/jsonb/2.0/[Jakarta JSON Binding 2.0] (JSON-B) * https://jakarta.ee/specifications/jsonp/2.2/[Jakarta JSON Processing 2.0] (JSON-P) * https://microprofile.io/microprofile-config/[MicroProfile Config] === NoSQL Database Types Eclipse JNoSQL provides common annotations and interfaces. Thus, the same annotations and interfaces, ```Template``` and ```Repository```, will work across the supported NoSQL database types. As a reference implementation for Jakarta NoSQL, Eclipse JNoSQL provides particular behavior for each database type required by the specification and also supports Graph and Time Series databases: * Key-Value * Column Family * Document * Graph * Time Series === Key-Value Jakarta NoSQL provides a Key-Value template to explore the specific behavior of this NoSQL type. Eclipse JNoSQL offers a mapping implementation for Key-Value NoSQL types: [source,xml] ---- org.eclipse.jnosql.mapping jnosql-mapping-key-value 1.1.20 ---- Furthermore, check for a Key-Value databases. You can find some implementations in the https://github.com/eclipse/jnosql-databases[JNoSQL Databases]. [source,java] ---- @Inject KeyValueTemplate template; ... Car ferrari = Car.id(1L).name("ferrari").city("Rome").type(CarType.SPORT); template.put(ferrari); Optional car = template.get(1L, Car.class); template.delete(1L); ---- Key-Value is database agnostic. Thus, you can change the database in your application with no or minimal impact on source code. You can define the database settings using the https://microprofile.io/microprofile-config/[MicroProfile Config] specification, so you can add properties and overwrite it in the environment following the https://12factor.net/config[Twelve-Factor App]. [source,properties] ---- jnosql.keyvalue.database= jnosql.keyvalue.provider= jnosql.provider.host= jnosql.provider.user= jnosql.provider.password= ---- TIP: The ```jnosql.keyvalue.provider``` property is necessary when you have more than one driver in the classpath. Otherwise, it will take the first one. These configuration settings are the default behavior. Nevertheless, there is an option to programmatically configure these settings. Create a class that implements the ```Supplier``` interface and then define it using the ```@Alternative``` and ```@Priority``` annotations. [source,java] ---- @Alternative @Priority(Interceptor.Priority.APPLICATION) @ApplicationScoped public class ManagerSupplier implements Supplier { @Produces public BucketManager get() { Settings settings = Settings.builder() .put("credential", "value") .build(); KeyValueConfiguration configuration = new NoSQLKeyValueProvider(); BucketManagerFactory factory = configuration.apply(settings); return factory.apply("database"); } } ---- You can work with several Key-Value database instances through the CDI qualifier. To identify each database instance, make a ```BucketManager``` visible for CDI by adding the ```@Produces``` and the ```@Database``` annotations in the method. [source,java] ---- @Inject @Database(value = DatabaseType.KEY_VALUE, provider = "databaseA") private KeyValueTemplate templateA; @Inject @Database(value = DatabaseType.KEY_VALUE, provider = "databaseB") private KeyValueTemplate templateB; // producers methods @Produces @Database(value = DatabaseType.KEY_VALUE, provider = "databaseA") public BucketManager getManagerA() { BucketManager manager = // instance; return manager; } @Produces @Database(value = DatabaseType.KEY_VALUE, provider = "databaseB") public BucketManager getManagerB() { BucketManager manager = // instance; return manager; } ---- The KeyValue Database module provides a simple way to integrate the `KeyValueDatabase` annotation with CDI, allowing you to inject collections managed by the key-value database. This annotation works seamlessly with various collections, such as List, Set, Queue, and Map. To inject collections managed by the key-value database, use the `@KeyValueDatabase` annotation in combination with CDI's `@Inject` annotation. Here's how you can use it: [source,java] ---- import javax.inject.Inject; // Inject a List instance from the "names" bucket in the key-value database. @Inject @KeyValueDatabase("names") private List names; // Inject a Set instance from the "fruits" bucket in the key-value database. @Inject @KeyValueDatabase("fruits") private Set fruits; // Inject a Queue instance from the "orders" bucket in the key-value database. @Inject @KeyValueDatabase("orders") private Queue orders; // Inject a Map instance from the "orders" bucket in the key-value database. @Inject @KeyValueDatabase("orders") private Map map; ---- === Column Family Jakarta NoSQL provides a Column Family template to explore the specific behavior of this NoSQL type. Eclipse JNoSQL offers a mapping implementation for Column NoSQL types: [source,xml] ---- org.eclipse.jnosql.mapping jnosql-mapping-column 1.1.20 ---- Furthermore, check for a Column Family databases. You can find some implementations in the https://github.com/eclipse/jnosql-databases[JNoSQL Databases]. [source,java] ---- @Inject ColumnTemplate template; ... Car ferrari = Car.id(1L) .name("ferrari").city("Rome") .type(CarType.SPORT); template.insert(ferrari); Optional car = template.find(Car.class, 1L); template.delete(Car.class).where("id").eq(1L).execute(); Optional result = template.singleResult("FROM Car WHERE _id = 1"); ---- Column Family is database agnostic. Thus, you can change the database in your application with no or minimal impact on source code. You can define the database settings using the https://microprofile.io/microprofile-config/[MicroProfile Config] specification, so you can add properties and overwrite it in the environment following the https://12factor.net/config[Twelve-Factor App]. [source,properties] ---- jnosql.column.database= jnosql.column.provider= jnosql.provider.host= jnosql.provider.user= jnosql.provider.password= ---- TIP: The ```jnosql.column.provider``` property is necessary when you have more than one driver in the classpath. Otherwise, it will take the first one. These configuration settings are the default behavior. Nevertheless, there is an option to programmatically configure these settings. Create a class that implements the ```Supplier``` interface, then define it using the ```@Alternative``` and ```@Priority``` annotations. [source,java] ---- @Alternative @Priority(Interceptor.Priority.APPLICrATION) @ApplicationScoped public class ManagerSupplier implements Supplier { @Produces @Database(DatabaseType.COLUMN) public DatabaseManager get() { Settings settings = Settings.builder() .put("credential", "value") .build(); DatabaseConfiguration configuration = new NoSQLColumnProvider(); DatabaseManagerFactory factory = configuration.apply(settings); return factory.apply("database"); } } ---- You can work with several column database instances through CDI qualifier. To identify each database instance, make a ``ColumnManager`` visible for CDI by putting the ```@Produces``` and the ```@Database``` annotations in the method. [source,java] ---- @Inject @Database(value = DatabaseType.COLUMN, provider = "databaseA") private ColumnTemplate templateA; @Inject @Database(value = DatabaseType.COLUMN, provider = "databaseB") private ColumnTemplate templateB; // producers methods @Produces @Database(value = DatabaseType.COLUMN, provider = "databaseA") public ColumnManager getManagerA() { return manager; } @Produces @Database(value = DatabaseType.COLUMN, provider = "databaseB") public ColumnManager getManagerB() { return manager; } ---- === Document Jakarta NoSQL provides a Document template to explore the specific behavior of this NoSQL type. Eclipse JNoSQL offers a mapping implementation for Document NoSQL types: [source,xml] ---- org.eclipse.jnosql.mapping jnosql-mapping-document 1.1.20 ---- Furthermore, check for a Document databases. You can find some implementations in the https://github.com/eclipse/jnosql-databases[JNoSQL Databases]. [source,java] ---- @Inject DocumentTemplate template; ... Car ferrari = Car.id(1L) .name("ferrari") .city("Rome") .type(CarType.SPORT); template.insert(ferrari); Optional car = template.find(Car.class, 1L); template.delete(Car.class).where("id").eq(1L).execute(); Optional result = template.singleResult("FROM Car WHERE _id = 1"); ---- Document is database agnostic. Thus, you can change the database in your application with no or minimal impact on source code. You can define the database settings using the https://microprofile.io/microprofile-config/[MicroProfile Config] specification, so you can add properties and overwrite it in the environment following the https://12factor.net/config[Twelve-Factor App]. [source,properties] ---- jnosql.document.database= jnosql.document.provider= jnosql.provider.host= jnosql.provider.user= jnosql.provider.password= ---- TIP: The ```jnosql.document.provider``` property is necessary when you have more than one driver in the classpath. Otherwise, it will take the first one. These configuration settings are the default behavior. Nevertheless, there is an option to programmatically configure these settings. Create a class that implements the ```Supplier```, then define it using the ```@Alternative``` and ```@Priority``` annotations. [source,java] ---- @Alternative @Priority(Interceptor.Priority.APPLICATION) @ApplicationScoped public class ManagerSupplier implements Supplier { @Produces @Database(DatabaseType.DOCUMENT) public DatabaseManager get() { Settings settings = Settings.builder() .put("credential", "value") .build(); DatabaseConfiguration configuration = new NoSQLDocumentProvider(); DatabaseManagerFactory factory = configuration.apply(settings); return factory.apply("database"); } } ---- You can work with several document database instances through CDI qualifier. To identify each database instance, make a ```DocumentManager``` visible for CDI by putting the ```@Produces``` and the ```@Database``` annotations in the method. [source,java] ---- @Inject @Database(value = DatabaseType.DOCUMENT, provider = "databaseA") private DocumentTemplate templateA; @Inject @Database(value = DatabaseType.DOCUMENT, provider = "databaseB") private DocumentTemplate templateB; // producers methods @Produces @Database(value = DatabaseType.DOCUMENT, provider = "databaseA") public DocumentManager getManagerA() { return manager; } @Produces @Database(value = DatabaseType.DOCUMENT, provider = "databaseB") public DocumentManager getManagerB() { return manager; } ---- === Time Series Use the Time Series Mapping module to store, query, and manage Java entities in a time-series database. Add the module to your project: [source,xml] ---- org.eclipse.jnosql.mapping jnosql-mapping-timeseries 1.1.20 ---- Map a time-series record as a Jakarta NoSQL entity: [source,java] ---- @Entity public class SensorReading { @Id private Instant timestamp; @Column private String sensor; @Column private double value; // constructors, getters, and setters } ---- Inject `TimeSeriesTemplate` to perform persistence and query operations: [source,java] ---- @Inject private TimeSeriesTemplate template; SensorReading reading = new SensorReading( Instant.now(), "sensor-1", 21.5); template.insert(reading); Optional result = template.find(SensorReading.class, reading.getTimestamp()); List readings = template.select(SensorReading.class) .where("sensor").eq("sensor-1") .result(); ---- You can also use Jakarta Data repositories: [source,java] ---- @Repository public interface SensorReadingRepository extends BasicRepository { List findBySensor(String sensor); } @Inject @Database(DatabaseType.TIME_SERIES) private SensorReadingRepository repository; ---- Configure the database name and provider using MicroProfile Config: [source,properties] ---- jnosql.timeseries.database= jnosql.timeseries.provider= jnosql.provider.host= jnosql.provider.user= jnosql.provider.****** ---- TIP: The `jnosql.timeseries.provider` property is necessary when more than one time-series database provider is available in the classpath. Applications that create the database manager programmatically can expose it through CDI: [source,java] ---- @Produces @Database(DatabaseType.TIME_SERIES) public DatabaseManager getTimeSeriesManager() { return manager; } ---- Use named providers when the application connects to multiple time-series databases: [source,java] ---- @Inject @Database(value = DatabaseType.TIME_SERIES, provider = "metrics") private TimeSeriesTemplate metrics; @Inject @Database(value = DatabaseType.TIME_SERIES, provider = "audit") private TimeSeriesTemplate audit; ---- === Vector Database Use the Vector Mapping module to store and query Java entities in a vector database. Add the module to your project: [source,xml] ---- org.eclipse.jnosql.mapping jnosql-mapping-vector 1.1.20 ---- A regular Jakarta NoSQL entity can include a vector attribute by declaring one persisted field whose type implements `Vector`. [source,java] ---- @Entity public class Article { @Id private String id; @Column private String content; @Column private String author; @Column private int year; @Column private Vector embedding; // constructors, getters, and setters } ---- For a vector database, the entity is interpreted conceptually as: [source,text] ---- Article ├── id -> identifier ├── embedding -> vector └── payload ├── content ├── author └── year ---- The vector attribute does not require a predefined name such as `embedding`. It is identified by the `Vector` type hierarchy. Eclipse JNoSQL provides three vector representations: `DenseVector`, `SparseVector`, and `MultiVector`. [source,mermaid] ---- classDiagram direction TB class Vector { } class DenseVector { +int dimensions() +float[] values() } class SparseVector { +int dimensions() +int[] indices() +float[] values() } class MultiVector { +int size() +int dimensions() +List~DenseVector~ vectors() } Vector <|-- DenseVector Vector <|-- SparseVector Vector <|-- MultiVector style Vector fill:#1D5183,stroke:#1D5183,color:#F8F7F7,stroke-width:2px style DenseVector fill:#F8F7F7,stroke:#019DDC,color:#1D5183,stroke-width:2px style SparseVector fill:#F8F7F7,stroke:#019DDC,color:#1D5183,stroke-width:2px style MultiVector fill:#F8F7F7,stroke:#019DDC,color:#1D5183,stroke-width:2px ---- ==== Dense Vector A `DenseVector` stores a value for every dimension. [source,java] ---- DenseVector vector = DenseVector.of( 0.12F, 0.45F, 0.78F ); ---- Conceptually: [source,text] ---- [0.12, 0.45, 0.78] ---- Dense vectors are commonly used for embeddings generated by language, image, audio, recommendation, and other machine learning models. ==== Sparse Vector A `SparseVector` stores only the non-zero values and their positions. A vector such as: [source,text] ---- [0, 0, 7, 0, 0, 0, 0, 0, 3, 0] ---- can be represented as: [source,text] ---- dimensions: 10 indices: [2, 8] values: [7, 3] ---- In Java: [source,java] ---- SparseVector vector = SparseVector.of( 10, SparseVector.element(2, 7.0F), SparseVector.element(8, 3.0F) ); ---- Sparse vectors are useful when the vector has many dimensions but only a small number of them contain explicit values, such as lexical or sparse embedding representations. ==== Multi-Vector A `MultiVector` represents one logical value using multiple dense vectors. Conceptually: [source,text] ---- [ [0.2, 0.8, 0.1], [0.7, 0.1, 0.4], [0.3, 0.6, 0.9] ] ---- In Java: [source,java] ---- MultiVector vector = MultiVector.of( DenseVector.of(0.2F, 0.8F, 0.1F), DenseVector.of(0.7F, 0.1F, 0.4F), DenseVector.of(0.3F, 0.6F, 0.9F) ); ---- A multi-vector is useful when one logical value needs multiple embeddings, such as different regions of media content, sections of a document, or multiple representations produced by a model. Vector generation is outside the scope of Eclipse JNoSQL. The application can obtain a vector from an embedding model, recommendation model, image or audio encoder, feature extractor, or another mechanism. Inject `VectorTemplate` to use the regular Jakarta NoSQL capabilities together with vector-native operations: [source,java] ---- @Inject private VectorTemplate template; Article article = Article.id("article-123") .content("Jakarta NoSQL and vector databases") .author("Otavio Santana") .year(2026) .embedding(vector); template.insert(article); Optional
result = template.find(Article.class, "article-123"); ---- `VectorTemplate` extends the Jakarta NoSQL `Template` interface, preserving the regular mapping and query capabilities while adding vector similarity search through `search(Class)`. ==== Vector Search A vector search starts with the entity type and the vector used as the search reference: [source,java] ---- Vector queryVector = DenseVector.of( 0.10F, 0.42F, 0.80F ); List
articles = template.search(Article.class) .vector(queryVector) .limit(Limit.of(10)) .result(); ---- IMPORTANT: Vector search extends the regular Jakarta NoSQL query capabilities with two vector-specific concepts: the query `Vector` and an optional similarity or distance `threshold`. The supported fluent flows can be summarized as: [source,mermaid] ---- flowchart LR V["vector(...)"] L1["limit(...)"] R1["result()"] W["where(...)"] C["condition"] L2["limit(...)"] R2["result()"] T1["threshold(...)"] L3["limit(...)"] R3["result()"] WT["where(...)"] CT["condition"] T2["threshold(...)"] L4["limit(...)"] R4["result()"] V --> L1 --> R1 V --> W --> C --> L2 --> R2 V --> T1 --> L3 --> R3 V --> WT --> CT --> T2 --> L4 --> R4 style V fill:#1D5183,stroke:#1D5183,color:#F8F7F7,stroke-width:2px style W fill:#F8F7F7,stroke:#019DDC,color:#1D5183,stroke-width:2px style C fill:#F8F7F7,stroke:#019DDC,color:#1D5183,stroke-width:2px style T1 fill:#F8F7F7,stroke:#019DDC,color:#1D5183,stroke-width:2px style WT fill:#F8F7F7,stroke:#019DDC,color:#1D5183,stroke-width:2px style CT fill:#F8F7F7,stroke:#019DDC,color:#1D5183,stroke-width:2px style T2 fill:#F8F7F7,stroke:#019DDC,color:#1D5183,stroke-width:2px style L1 fill:#019DDC,stroke:#019DDC,color:#F8F7F7,stroke-width:2px style L2 fill:#019DDC,stroke:#019DDC,color:#F8F7F7,stroke-width:2px style L3 fill:#019DDC,stroke:#019DDC,color:#F8F7F7,stroke-width:2px style L4 fill:#019DDC,stroke:#019DDC,color:#F8F7F7,stroke-width:2px style R1 fill:#F8F7F7,stroke:#1D5183,color:#1D5183,stroke-width:2px style R2 fill:#F8F7F7,stroke:#1D5183,color:#1D5183,stroke-width:2px style R3 fill:#F8F7F7,stroke:#1D5183,color:#1D5183,stroke-width:2px style R4 fill:#F8F7F7,stroke:#1D5183,color:#1D5183,stroke-width:2px linkStyle 0 stroke:#1D5183,stroke-width:2px linkStyle 1 stroke:#1D5183,stroke-width:2px linkStyle 2 stroke:#1D5183,stroke-width:2px linkStyle 3 stroke:#1D5183,stroke-width:2px linkStyle 4 stroke:#1D5183,stroke-width:2px linkStyle 5 stroke:#1D5183,stroke-width:2px linkStyle 6 stroke:#1D5183,stroke-width:2px linkStyle 7 stroke:#1D5183,stroke-width:2px ---- ==== Filtering Vector Searches The same Jakarta NoSQL conditions can be combined with vector similarity search: [source,java] ---- List
articles = template.search(Article.class) .vector(queryVector) .where("author").eq("Otavio Santana") .and("year").gte(2024) .limit(Limit.of(10)) .result(); ---- This keeps the regular Jakarta NoSQL filtering model while applying it to the vector search operation. ==== Threshold-Based Search A threshold can restrict the results according to the similarity or distance metric configured by the underlying vector database: [source,java] ---- List
articles = template.search(Article.class) .vector(queryVector) .threshold(0.85F) .limit(Limit.of(10)) .result(); ---- The meaning and valid range of the threshold depend on the configured similarity or distance metric. Payload conditions and thresholds can also be combined: [source,java] ---- List
articles = template.search(Article.class) .vector(queryVector) .where("author").eq("Otavio Santana") .and("year").gte(2024) .threshold(0.85F) .limit(Limit.of(10)) .result(); ---- The fluent API keeps the Jakarta NoSQL query model and adds the vector and threshold steps required for vector-native search. === Graph Eclipse JNoSQL provides a Graph API that simplifies working with graph databases such as Neo4j and Apache TinkerPop. This API enables seamless integration with graph databases while following the Jakarta NoSQL specifications. To start using graph databases with Eclipse JNoSQL, add the required dependency: [source,xml] ---- org.eclipse.jnosql.mapping jnosql-mapping-graph 1.1.20 ---- ==== Using the Relationship on Graph (Edge) The `EdgeBuilder` provides a fluent API to define edges between entities, including properties. [source,java] ---- private GraphTemplate template; Person person = new Person(); Book book = new Book(); Edge edge = Edge.source(person) .label("READS") .target(book) .property("since", 2019) .property("format", "digital") .build(); template.edge(edge); ---- ==== Configuring a Graph Database You can configure your graph database using MicroProfile Config properties. [source,properties] ---- jnosql.graph.database= jnosql.graph.provider= ---- You can also configure the database programmatically by providing a `GraphDatabaseManager` implementation. [source,java] ---- @Alternative @Priority(Interceptor.Priority.APPLICATION) @ApplicationScoped public class GraphManagerSupplier implements Supplier { @Produces @Database(DatabaseType.GRAPH) @Default public GraphDatabaseManager get() { Settings settings = Settings.builder() .put("credential", "value") .build(); GraphConfiguration configuration = new NoSQLGraphProvider(); GraphDatabaseManagerFactory factory = configuration.apply(settings); return factory.apply("database"); } } ---- By using the `@Database` annotation, multiple graph database instances can be configured for CDI injection. [source,java] ---- @Inject @Database(value = DatabaseType.GRAPH, provider = "graphA") private GraphTemplate graphA; @Inject @Database(value = DatabaseType.GRAPH, provider = "graphB") private GraphTemplate graphB; ---- === Jakarta Data Eclipse JNoSQL as a https://jakarta.ee/specifications/data/1.0/jakarta-data-1.0[Jakarta Data] exploring more the NoSQL capabilities, provides a mapping API that allows you to map Java objects to NoSQL databases. === Jakarta NoSQL Eclipse JNoSQL is a https://jakarta.ee/specifications/nosql/1.0/jakarta-nosql-1.0[Jakarta NoSQL] implementation that provides a standard way to access NoSQL databases in Java applications. It offers a set of annotations and APIs to interact with various NoSQL database types, including Key-Value, Column Family, Document, Graph, and Time Series. === More Information Check the https://www.jnosql.org/spec/[reference documentation] and https://www.jnosql.org/javadoc/[JavaDocs] to learn more. == Code of Conduct This project is governed by the Eclipse Foundation Code of Conduct. By participating, you are expected to uphold this code of conduct. Please report unacceptable behavior to mailto:codeofconduct@eclipse.org[codeofconduct@eclipse.org]. == Getting Help Having trouble with Eclipse JNoSQL? We’d love to help! Please report any bugs, concerns or questions with Eclipse JNoSQL to https://github.com/eclipse/jnosql[https://github.com/eclipse/jnosql]. If your issue refers to the https://github.com/eclipse/jnosql-databases[JNoSQL databases project] or the https://github.com/eclipse/jnosql-extensions[JNoSQL extensions project], please, open the issue in this repository following the instructions in the templates. == 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. [source, Bash] ---- mvn clean install ---- == Contributing We are very happy you are interested in helping us and there are plenty ways you can do so. - https://github.com/eclipse/jnosql/issues[**Open an Issue:**] Recommend improvements, changes and report bugs - **Open a Pull Request:** If you feel like you can even make changes to our source code and suggest them, just check out our link:CONTRIBUTING.adoc[contributing guide] to learn about the development process, how to suggest bugfixes and improvements. Here are the badges of this project: [%autowidth,cols="a,a,a,a", frame=none, grid=none, role=stretch ] |=== | image::https://sonarcloud.io/api/project_badges/measure?project=org.eclipse.jnosql%3Ajakarta-nosql-parent&metric=sqale_rating[ link=https://sonarcloud.io/summary/new_code?id=org.eclipse.jnosql%3Ajakarta-nosql-parent, window=_blank, target=_blank] | image::https://sonarcloud.io/api/project_badges/measure?project=org.eclipse.jnosql%3Ajakarta-nosql-parent&metric=code_smells[window=_blank, link=https://sonarcloud.io/summary/new_code?id=org.eclipse.jnosql%3Ajakarta-nosql-parent] | image::https://sonarcloud.io/api/project_badges/measure?project=org.eclipse.jnosql%3Ajakarta-nosql-parent&metric=ncloc[window=_blank, link=https://sonarcloud.io/summary/new_code?id=org.eclipse.jnosql%3Ajakarta-nosql-parent] | image::https://sonarcloud.io/api/project_badges/measure?project=org.eclipse.jnosql%3Ajakarta-nosql-parent&metric=coverage[window=_blank, link=https://sonarcloud.io/summary/new_code?id=org.eclipse.jnosql%3Ajakarta-nosql-parent] | image::https://sonarcloud.io/api/project_badges/measure?project=org.eclipse.jnosql%3Ajakarta-nosql-parent&metric=sqale_index[window=_blank, link=https://sonarcloud.io/summary/new_code?id=org.eclipse.jnosql%3Ajakarta-nosql-parent] | image::https://sonarcloud.io/api/project_badges/measure?project=org.eclipse.jnosql%3Ajakarta-nosql-parent&metric=alert_status[window=_blank, link=https://sonarcloud.io/summary/new_code?id=org.eclipse.jnosql%3Ajakarta-nosql-parent] | image::https://sonarcloud.io/api/project_badges/measure?project=org.eclipse.jnosql%3Ajakarta-nosql-parent&metric=reliability_rating[window=_blank, link=https://sonarcloud.io/summary/new_code?id=org.eclipse.jnosql%3Ajakarta-nosql-parent] | image::https://sonarcloud.io/api/project_badges/measure?project=org.eclipse.jnosql%3Ajakarta-nosql-parent&metric=duplicated_lines_density[window=_blank, link=https://sonarcloud.io/summary/new_code?id=org.eclipse.jnosql%3Ajakarta-nosql-parent] | image::https://sonarcloud.io/api/project_badges/measure?project=org.eclipse.jnosql%3Ajakarta-nosql-parent&metric=vulnerabilities[window=_blank, link=https://sonarcloud.io/summary/new_code?id=org.eclipse.jnosql%3Ajakarta-nosql-parent] | image::https://sonarcloud.io/api/project_badges/measure?project=org.eclipse.jnosql%3Ajakarta-nosql-parent&metric=bugs[window=_blank, link=https://sonarcloud.io/summary/new_code?id=org.eclipse.jnosql%3Ajakarta-nosql-parent] | image::https://sonarcloud.io/api/project_badges/measure?project=org.eclipse.jnosql%3Ajakarta-nosql-parent&metric=security_rating[window=_blank, link=https://sonarcloud.io/summary/new_code?id=org.eclipse.jnosql%3Ajakarta-nosql-parent] |=== == Testing Guideline This project's testing guideline will help you understand Jakarta Data's testing practices. Please take a look link:TESTING-GUIDELINE.adoc[at the file]. == Migration This migration guide explains how to upgrade from Eclipse JNoSQL version 1.0.0-b6 to the latest version, considering two significant changes: upgrading to Jakarta EE 9 and reducing the scope of the Jakarta NoSQL specification to only run on the Mapping. The guide provides instructions on updating package names and annotations to migrate your Eclipse JNoSQL project successfully. link:MIGRATION.adoc[Migration Guide] == Compatibility and Innovation Strategy Eclipse JNoSQL preserves stability and drives innovation by using a versioning strategy based on https://semver.org/[Semantic Versioning] and Jakarta EE platform generations. The Eclipse JNoSQL version follows the `MAJOR.MINOR.PATCH` format: [source,text] ---- MAJOR.MINOR.PATCH ---- Where: * *MAJOR* reflects the Jakarta EE generation supported by the Eclipse JNoSQL release line. Upgrading to a new Jakarta EE generation requires a new major version. Because each Jakarta EE platform version may require a different minimum Java version, applications must verify and adopt the necessary Java version when migrating between major versions. * *MINOR* introduces backward-compatible features, APIs, and improvements while remaining within the same Jakarta EE generation. * *PATCH* delivers backward-compatible bug fixes and maintenance updates without adding new features. For example: [source,text] ---- 1.x.x -> Jakarta EE 11 2.x.x -> Jakarta EE 12 3.x.x -> next Jakarta EE generation ---- A new Jakarta EE generation requires a new Eclipse JNoSQL major version. Within each major version, minor and patch releases follow Semantic Versioning. The `1.x.x` release line of Eclipse JNoSQL targets Jakarta EE 11. Within this release line: * A *patch release*, such as `1.1.19` to `1.1.20`, contains backward-compatible bug fixes, maintenance updates, and compatible corrections. * A *minor release*, such as `1.1.x` to `1.2.0`, may add new backward-compatible features, APIs, and improvements while remaining compatible with Jakarta EE 11. * A *major release*, such as moving from `1.x.x` to `2.0.0`, upgrades Eclipse JNoSQL to the next Jakarta EE generation and establishes a new compatibility baseline. This migration may also require adopting a newer Java version, as specified by the target Jakarta EE platform. For example: [source,text] ---- 1.1.19 -> Jakarta EE 11, maintenance release 1.1.20 -> Jakarta EE 11, maintenance release 1.2.0 -> Jakarta EE 11, new backward-compatible features 1.3.0 -> Jakarta EE 11, additional backward-compatible features 2.0.0 -> Jakarta EE 12 ---- Applications can upgrade within the same major version to stay on the same Jakarta EE generation. Minor releases add new capabilities without changing the Jakarta EE compatibility baseline. Patch releases provide bug fixes and maintenance updates only. A new major version adopts a new Jakarta EE generation. For example, Eclipse JNoSQL `2.x.x` targets Jakarta EE 12. Applications upgrading from `1.x.x` to `2.x.x` must manage the Jakarta EE platform transition, verify the required Java version, and deal with any incompatible API changes. The versioning contract can be summarized as follows: * *PATCH* releases provide backward-compatible bug fixes and maintenance updates. * *MINOR* releases introduce backward-compatible features and improvements within the same Jakarta EE generation. * *MAJOR* releases align Eclipse JNoSQL with a new Jakarta EE generation and may introduce backward-incompatible API changes. Migrating to a major version also requires checking the minimum Java version the target Jakarta EE platform supports. This strategy combines Semantic Versioning with an explicit Jakarta EE compatibility model: [source,text] ---- Eclipse JNoSQL 1.x.x -> Jakarta EE 11 Eclipse JNoSQL 2.x.x -> Jakarta EE 12 Eclipse JNoSQL 3.x.x -> next Jakarta EE generation ---- The major version indicates the Jakarta EE compatibility baseline. Minor and patch versions allow Eclipse JNoSQL to evolve within that baseline according to Semantic Versioning. When upgrading between major versions, developers should consider both the Jakarta EE platform version and its minimum Java requirement as part of the compatibility boundary. == Learn More If you want to know more about both the communication and mapping layer, there are two complementary files for it each specific topic: * link:MAPPING.adoc[Mapping API]