Mentions légales du service

Skip to content

Changes

Page history
Update Storage authored by TORNIL Florent's avatar TORNIL Florent
Hide whitespace changes
Inline Side-by-side
User-Documentation/Storage.md
View page @ 0d7062a9
# InteGraal : Storage module
# InteGraal : Storage and Views modules
This document presents the storage module from InteGraal and describe how to use it.
This document presents the storage and views modules from InteGraal and describe how to use them.
## Utility
This module is used to both store atoms and query sources to retrieve data.
These modules are used to both store atoms and query sources to retrieve data.
## Module hierarchy
......@@ -94,7 +94,12 @@ You can either import this module using maven dependencies or adding the corresp
<dependency>
<groupId>integraal</groupId>
<artifactId>integraal-storage</artifactId>
<version>0.0.1-SNAPSHOT</version>
<version>${LAST_VERSION}</version>
</dependency>
<dependency>
<groupId>integraal</groupId>
<artifactId>integraal-views</artifactId>
<version>${LAST_VERSION}</version>
</dependency>
```
......@@ -102,7 +107,7 @@ You can either import this module using maven dependencies or adding the corresp
To use this module, you need to import it into your main application.
Then, you have access to the packages under `fr.boreal.storage` to get the needed interfaces or classes.
Then, you have access to the packages under `fr.boreal.storage` and `fr.boreal.views` to get the needed interfaces or classes.
The easier storage to setup is the `SimpleInMemoryGraphStore` which keeps atoms in memory and uses a graph representation using
......@@ -131,7 +136,7 @@ FactBase database = StorageBuilder.defaultBuilder()
## Modification
If you want to create your own implementations or approches, you can easily do so by implementing the `FactStorage` (or `FactBase`) interface.
If you want to create your own implementations or approches, you can easily do so by implementing the `FactBase` interface.
Once this is done, you can use your new implementation in the same way as presented in the configuration part of this document.
......@@ -139,20 +144,19 @@ Once this is done, you can use your new implementation in the same way as presen
We can describe the storages available in the two following kinds
### InteGraal Stores
### InteGraal Wrappers
A Store is an implementation of a factbase, which is based on an external system (ie, which is not InteGraal). For example, you can use as external system a DBMS (relational, triplestore, graph, noSQL, ...) or a Web Application.
A Wrapper is an implementation of a factbase, which is based on an external system (ie, which is not InteGraal). For example, you can use as external system a DBMS (relational, triplestore, graph, noSQL, ...) or a Web Application.
As a Wrapper is an implementation of a factbase, it must provide the facilities for:
As a Store is an implementation of a factbase, it must provide the facilities for:
1. answering queries
2. inserting data
3. deleting data
These facilities are defined in the `Factbase` interface, and indeed a Wrapper needs to implement the `Factbase` interface to work.
These facilities are defined in the `Factbase` interface, and indeed a Store needs to implement the `Factbase` interface to work.
When defining your own wrapper, we suggest to respect the following guidelines.
When defining your own store, we suggest to respect the following guidelines.
1. Create a driver.
......@@ -178,9 +182,9 @@ The evaluator evidently will use the driver.
This object is supposed to take the result of a native query and convert it into the corresponding InteGraal atoms or substitutions.
5. Create the wrapper itself.
5. Create the store itself.
A Wrapper is an implementation of a factbase supposed to implement methods for
A Store is an implementation of a factbase supposed to implement methods for
- `match(atom a)`
- `add(atom a)`
- `remove(atom a)`
......@@ -197,23 +201,23 @@ The implementation of `add(atom a)` and `remove(atom a)` is similar ; they simpl
6. Extend StorageBuilder.
Add your new wrapper to the StorageBuilder class
Add your new storage system to the StorageBuilder class
### Delegate more complex queries
Some algorithm exist to handle queries and even rules directly on the storage without retrieving data in memory. This is denoted by the `DatalogRuleDelegatable` interface.
Some algorithm exist to handle queries and even rules directly on the storage without retrieving data in memory. This is denoted by the `DatalogRuleDelegable` interface.
### External datasources (renommmer)
### View datasources
These storages are not handled entierly by InteGraal. They are accessible using user-defined queries.
For the moment, we do not have a textual format for declaring these types of storages, so you'll need to write some Java, but this is planned for the future.
You can refer to the [examples available in the project](https://gitlab.inria.fr/rules/integraal/-/blob/develop/integraal/integraal-app/src/main/java/O2SolubilityINRAEUseCase.java) for more information on how to setup this storage system.
You can refer to the [examples available in the example project](https://gitlab.inria.fr/rules/integraal-examples) for more information on how to setup this storage system.
To use this type of storages, represented by the `MappingDatasourceWrapper`, multiple elements are needed :
To use this type of storages, represented by the `AbstractViewWrapper`, multiple elements are needed :
* A native query to execute
* The connection to the datasource
* The object that will be used to execute the query at the lower level
......@@ -224,25 +228,23 @@ To use this type of storages, represented by the `MappingDatasourceWrapper`, mul
We provide some generic solutions for SQL and SPARQL as well as some potential solution for JSON data.
### InteGraal Relational View Definition (Mapping Wrapper)
### InteGraal Relational View Definition (View Wrapper)
A Mapping Wrapper is an implementation of a factbase, which allows to define a Relational View on any system (ie, it can be an external system or even InteGraal). For example, you can define a view over an external DBMS system (relational, triplestore, graph, noSQL, ...), a Web Application, or an existing InteGraal knowledge base.
A View Wrapper is an implementation of a readable, which allows to define a Relational View on any system (ie, it can be an external system or even InteGraal). For example, you can define a view over an external DBMS system (relational, triplestore, graph, noSQL, ...), a Web Application, or an existing InteGraal knowledge base.
As Mapping Wrapper is an implementation of a factbase, it must provide the facilities for:
As View Wrapper is an implementation of a readable, it must provide the facilities for:
1. answering queries
2. inserting data
3. deleting data
These facilities are defined in the `Factbase` interface, and indeed a Wrapper needs to implement the `Factbase` interface to work.
These facilities are defined in the `Readable` interface, and indeed a View Wrapper needs to implement the `Readable` interface to work.
Note that a Mapping Wrapper can operate in read-only mode, or in read-write mode. In the first case, data insertion and data deletion operations are supposed to raise an exception. For the time being, InteGraal implementations only supports Relational Views working in read-only mode. This means that the current implementation cannot update the a Relational View, by adding a new tuple or by removing an existing tuple. This feature can of course be added.
Note that a View Wrapper can operate in read-only mode, or in read-write mode. In the first case, data insertion and data deletion operations are supposed to raise an exception. For the time being, InteGraal implementations only supports Relational Views working in read-only mode. This means that the current implementation cannot update the a Relational View, by adding a new tuple or by removing an existing tuple. This feature can of course be added.
When defining your own mapping wrapper, we suggest to respect the following guidelines.
When defining your own View wrapper, we suggest to respect the following guidelines.
1. Create a driver.
This object is supposed to only connecti to the target system (DBMS, Web Application). Note that this is a major difference with the Wrapper defined above.
This object is supposed to only connect to the target system (DBMS, Web Application). Note that this is a major difference with the Store defined above.
2. Create a query specializer.
......@@ -258,9 +260,9 @@ The evaluator evidently will use the driver.
This object is supposed to take the result of a native query and convert it into the corresponding InteGraal atoms or substitutions.
5. Create the mapping wrapper itself.
5. Create the View wrapper itself.
To do so, the mapping wrapper will have to extend the abstract class `MappingDatasourceWrapper<NativeQueryType, NativeResultType>`.
To do so, the View wrapper will have to extend the abstract class `AbstractViewWrapper<NativeQueryType, NativeResultType>`.
It suffices to implement the constructor and pass as parameter
......@@ -268,8 +270,8 @@ It suffices to implement the constructor and pass as parameter
2. the evaluator
3. the transformer
6. Extend MappingBuilder.
6. Extend ViewBuilder.
Add your new mapping wrapper to the MappingBuilder class.
Add your new view wrapper to the ViewBuilder class.