Usage

This page provides the necessary information to run morph-RDB. First with some predefined examples with datasets in different formats, such as Oracle, MySQL and H2; then with the testcases, and finally how to run it on your own.

Predefined R2RML mapping examples from the command line

The examples are based on the paper: http://users.dcc.uchile.cl/~cgutierr/papers/tods09.pdf (page 16.7).

With H2

Go to the H2 example directory

cd morph-examples/examples-h2

Run the example

In Linux/MacOS:

./example1-batch-h2.sh
./example1-query01-h2.sh
./example1-query02-h2.sh
./example1-query03-h2.sh
./example1-query04-h2.sh
./example1-query05-h2.sh

In Windows:

example1-batch-h2.bat
example1-query01-h2.bat
example1-query02-h2.bat
example1-query03-h2.bat
example1-query04-h2.bat
example1-query05-h2.bat

With MySQL (Recommended v5.5, Experiment v8.0)

We expect you to have also a MySQL database installed on your computer or available for your use.

Download the SQL example file

wget https://raw.githubusercontent.com/oeg-upm/morph-rdb/master/morph-examples/examples-mysql/morph_example.sql
Import the SQL file into your MySQL database

/opt/lampp/bin/mysql -uroot < morph_example.sql

Note that "/opt/lampp/bin/mysql" must be replaced with the path to your mysql binary and "-uroot" must be replaced with your credentials (e.g., "-umyuser -p" or "-umyuser -pmypassword")
Download example files

wget https://github.com/oeg-upm/morph-rdb/releases/download/morph-RDB_v3.9.17/examples-mysql.zip
unzip the example files

unzip examples-mysql.zip
Go to the mysql example directory

cd examples-mysql
Edit the *.r2rml.properties files according to your database configuration (explained below, in how to run it on your own)

Run the example

In Linux/MacOS:

sh mysql-example1-batch.sh
sh mysql-example1-query01.sh
sh mysql-example1-query02.sh
sh mysql-example1-query03.sh
sh mysql-example1-query04.sh
sh mysql-example1-query05.sh

In Windows:

example1-batch-mysql.bat
example1-query01-mysql.bat
example1-query02-mysql.bat
example1-query03-mysql.bat
example1-query04-mysql.bat
example1-query05-mysql.bat

Set of W3C Direct Mapping Test Cases using the morph-RDB automatic mappings generator from a command line

The test cases that we are using in this case are the ones defined at: http://www.w3.org/TR/rdb2rdf-test-cases/. The results can be found in the [RDB2RDF Implementation Report] (https://www.w3.org/TR/rdb2rdf-implementations/).

Download the latest morph-RDB R2RML mappings generator jar file and copy it to the lib folder. Make sure you remove all the older mapping generator jars

wget https://github.com/oeg-upm/morph-rdb/releases/download/v3.5.15/r2rml-mappings-generator-v1.1.6.jar
mv r2rml-mappings-generator-*.jar morph-examples/lib/

Go to the testcases directory

cd morph-examples/testcases-mysql or cd morph-examples/testcases-postgresql or cd morph-examples/testcases-oracle
Import the database dump files (testcases/DXXX/dXXX.sql)
Run morph-RDB

In Linux/MacOS:

./DirectGraphTC0000.sh

In Windows:

DirectGraphTC0000.bat

On your own

In order to run morph-RDB with your own datasets, you need to create some files that must be in the same directory as the dataset(s):

The R2RML mapping file, which contains the mappings from the relational database (in Oracle, MySQL or H2 format) to RDF datasets.
The 'properties' file, that specifies the paths to the necessary files to run (the mapping file, the database), the output and its format, optionally the file with a SQL query, and some other settings.
There can also be a SH/BAT file to run morph-RDB, with the java command to run the program depending on the type of dataset you're using.
And optionally, a SPARQL query can be included.

Mapping file

Morph-rdb is designed to use R2RML, a W3C recommended RDB2RDF mapping language which creates RDF triples from a relational database. All the information to create the R2RML mappings is carefully explained in the [R2RML specification] (https://www.w3.org/TR/r2rml/). The file should end with the extension ".ttl", since it's a TURTLE format file.

Properties file

This file contains the information about the settings and files needed for running the program, and should end with the extension ".morph.properties". It will have the following content for MySQL and Oracle databases:

mappingdocument.file.path=example-mysql.r2rml.ttl
output.file.path=example-mysql-result.nt


# RDF/XML|RDF/XML-ABBREV|N-TRIPLE|TURTLE|N3
output.rdflanguage=N-TRIPLE
	
no_of_database=1 
database.name[0]=morph_example
database.driver[0]=com.mysql.jdbc.Driver
database.url[0]=jdbc:mysql://127.0.0.1:3306/morph_example
database.user[0]=root
database.pwd[0]=password

# CSV|mysql|h2
database.type[0]=mysql

uri.encode=(" "->"%20"),,(","->""),,("á"->"a"),,("é"->"e"),,("í"->"i"),,("ó"->"o"),,("ú"->"u"),,("ü"->"u"),,("ñ"->"n"),,("\u00B4"->"%C2%B4")

The fields that must be changed for different data are mappingdocument.file.path (which will lead to the mapping file), output.file.path (output file to be created) and others involving the settings in MySQL, database.url and database.name for the database, and database.user and database.pwd for the user and password.

Depending on what the user wants, the output format can be changed in output.rdflanguage, and can be RDF/XML, RDF/XML-ABBREV, N-TRIPPLE, TURTLE and N3. There is also an option to encode uris in uri.encode. Finally, the format of the data must be specified in the field database.type

The file for H2 databases is similar to that of MySQL and Oracle:

mappingdocument.file.path=example1-mapping-h2.ttl
output.file.path=example1-batch-result-h2.nt

#RDF/XML|RDF/XML-ABBREV|N-TRIPLE|TURTLE|N3
output.rdflanguage=N-TRIPLE

no_of_database=1
database.name[0]=morph-example
database.driver[0]=org.h2.Driver
database.url[0]=jdbc:h2:./examples-h2/morph-example
database.user[0]=sa
database.pwd[0]=

# CSV|mysql|h2
database.type[0]=h2

uri.encode=(" "->"%20"),,(","->""),,("·"->"a"),,("È"->"e"),,("Ì"->"i"),,("Û"->"o"),,("˙"->"u"),,("¸"->"u"),,("Ò"->"n"),,("¥"->"%C2%B4")

Just as the example above, the fields mappingdocument.file.path and output.file.path must be changed for other data, and the format of the database in database.type. The database is specified in database.url and database.name.

These examples show with different databases the transformation of the whole RDB to RDF in n-triple format. But there also an option to make SPARQL queries to the dataset. To do this, a file containing the SPARQL query is required, which will be explained later on. It must be specified in the properties file, so there will be a few changes. The example shown here is for CSV files, but can be applied to the other formats (changing the corresponding fields).

mappingdocument.file.path=example1-mapping-mysql.ttl
query.file.path=example-query.rq
output.file.path=example-query-result-mysql.xml

no_of_database=1 
database.name[0]=morph_example
database.driver[0]=com.mysql.jdbc.Driver
database.url[0]=jdbc:mysql://127.0.0.1:3306/morph_example
database.user[0]=root
database.pwd[0]=password
database.type[0]=mysql

As we can see, now there's another required field for the query file, query.file.path, and the output.rdflanguage is not necessary any more, since the output format is going to be XML.

SH/BAT file

This file contains the necessary commands to run morph-rdb, so it must be an executable. It changes a little depending on the operative system.

For Linux and MacOS systems, it should look like this:

cd ..
java -cp .:morph-rdb-dist-3.8.1.jar:dependency/* es.upm.fi.dia.oeg.morph.r2rml.rdb.engine.MorphRDBRunner examples-mysql example-batch-mysql.morph.properties
cd examples-mysql

For Windows:

cd ..
java -cp morph-rdb.jar;lib/* es.upm.fi.dia.oeg.morph.r2rml.rdb.engine.MorphRDBRunner examples-mysql example-batch-mysql.morph.properties
cd examples-mysql

It just contains the command to run the program with Java, and changes of directories. The names of the directory where the data is must be changed in each case (here it's named examples-csv) and the properties file (here named example-batch-csv.morph.properties).

For the program to work this way, the datasets and required files explained above must be in a directory. Both this directory with the data and the program jar file, morph-rdb.jar must be in the same directory, together with another two directories (dependency and src) and the files log4j2.xml and pom.xml. This is how is set in the morph-examples directory that comes with the installation of the program. You can either run you data inside this folder or copy all the necessary files and run it somewhere else.

Query file (optional)

This file is required only when the user wants to translate a SPARQL query to SQL and do it to the RDB. It only contains the query, and the file should end with the extension ".rq".

PREFIX rdfs: <http://www.w3.org/2000/01/rdf-schema#>
PREFIX rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#>
PREFIX mpv: <http://mappingpedia.linkeddata.es/vocabulary#>

SELECT ?a ?n ?e 
WHERE { 
	?a mpv:name ?n .
	OPTIONAL {?a mpv:email ?e .}
}

The output of this operation is an XML file with the result of the query, like the example below.

<?xml version="1.0" encoding="UTF-8"?>
<sparql>
    <head>
        <variable name="a"/>
        <variable name="n"/>
        <variable name="e"/>
    </head>
    <results>
        <result>
            <binding name="a">
                <uri>http://mappingpedia.linkeddata.es/resources/Person/B3</uri>
            </binding>
            <binding name="n">
                <literal>George</literal>
            </binding>
            <binding name="e">
                <literal>NULL</literal>
            </binding>
        </result>
        <result>
            <binding name="a">
                <uri>http://mappingpedia.linkeddata.es/resources/Person/B4</uri>
            </binding>
            <binding name="n">
                <literal>Ringo</literal>
            </binding>
            <binding name="e">
                <literal>ringo@acd.edu</literal>
            </binding>
        </result>
    </results>
</sparql>

Many more examples of all the cases can be found in the morph-examples folder, for the different types of datasets and operative systems.

CSV files

There's also an option to run the program with CSV files instead of relational databases. However, this is being developed now, and it can only work with clean data (no blank fields, with column names, etc). As the cases above, you can run some predefined examples, or do it on you own.

Predefined examples

Go to the CSV example directory

cd morph-examples/examples-csv/

Run the example

In Linux/MacOS:

./example1-batch-csv.sh
./example1-query01-csv.sh
./example1-query02-csv.sh
./example1-query03-csv.sh
./example1-query04-csv.sh
./example1-query05-csv.sh

In Windows:

example1-batch-csv.bat
example1-query01-csv.bat
example1-query02-csv.bat
example1-query03-csv.bat
example1-query04-csv.bat
example1-query05-csv.bat

On your own

Just as with the other kinds of databases, the needed files are the mapping R2RML file, the 'properties' file, the SH/BAT file and optionally a file with a SPARQL query. All the files are just as we have just seen except for the 'properties' file and the SH/BAT file. An example of the 'properties' file is shown below:

mappingdocument.file.path=example-csv.r2rml.ttl
output.file.path=example-csv-result.nt

# RDF/XML|RDF/XML-ABBREV|N-TRIPLE|TURTLE|N3
output.rdflanguage=N-TRIPLE

csv.file.path = example.csv
no_of_database=1
database.name[0]=morphcsv
database.driver[0]=org.h2.Driver
database.url[0]=jdbc:h2:mem:morphcsv
database.user[0]=sa
database.pwd[0]=

# CSV|mysql|h2
database.type[0]=CSV
	
uri.encode=(" "->"%20"),,("ó"->"o"),,("í"->"i")

The fields that must be changed for different data are mappingdocument.file.path, output.file.path and csv.file.path (which will lead to the CSV file). Depending on what the user wants, the output format can be changed in output.rdflanguage, and can be RDF/XML, RDF/XML-ABBREV, N-TRIPPLE, TURTLE and N3. There is also the option to encode uris in uri.encode. The rest of the fields can remain as they are in the example, since they refer to a RDB, and here the path to the CSV file is specified in csv.file.path.

Regarding the SH/BAT file, there's a minor change. Instead of calling es.upm.fi.dia.oeg.morph.r2rml.rdb.engine.MorphRDBRunner, for CSV files another program must called, es.upm.fi.dia.oeg.morph.r2rml.rdb.engine.MorphCSVRunner. An example is shown below:

cd ..
java -cp .:morph-rdb-dist-3.8.1.jar:dependency/* es.upm.fi.dia.oeg.morph.r2rml.rdb.engine.MorphCSVRunner examples-csv example1-csv.morph.properties
cd examples-csv

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Usage

Table of Contents

Predefined R2RML mapping examples from the command line

With H2

With MySQL (Recommended v5.5, Experiment v8.0)

Set of W3C Direct Mapping Test Cases using the morph-RDB automatic mappings generator from a command line

On your own

Mapping file

Properties file

SH/BAT file

Query file (optional)

CSV files

Predefined examples

On your own

Clone this wiki locally