OntopCLI

juliencorman edited this page Aug 8, 2017 · 15 revisions
Clone this wiki locally

valid for Ontop Version 1

Ontop Command Line Interface

Ontop ships a shell script (ontop for *nix) and a bat file (ontop.bat for Windows) exposing the core functionality and several utilities through the command line interface. It is an easy way to get the system quickly set-up, tested for correct execution, and querying or materializing as needed.

Setup Ontop CLI

First, you have to download ontop latest distribution file from our download page. Unzip it in a folder. Open the command line terminal and cd to that folder. For Windows use the ontop.bat file, for Linux and OS X use the ontop file.

usage: ontop <command> [ <args> ]

Commands are:
    bootstrap     Bootstrap ontology and mapping from the database
    help          Display help information
    materialize   Materialize the RDF graph exposed by the mapping and the OWL ontology
    query         Query the RDF graph exposed by the mapping and the OWL ontology
    mapping       Manipulate mapping files

See 'ontop help <command>' for more information on a specific command.

jdbc configuratoin

For jdbc drivers, you will need to manually download them and put them into the jdbc directory.

PATH

Consider put the directory of ontop to your PATH.

ontop query

The ontop query command is designed for users to be able to test their system quickly using the command line utilities. You can use them if you already have a scenario test case including:

  • the ontology (owl) and the mappings (obda or RM2RML) files,
  • a working database to connect to,
  • a SPARQL query file

The ontop query command helps you to set up the system, run the query from the query string file over it, and get the results either in output file or terminal output. What the script actually does is to set up Quest using the owl and the mapping file, parses the query from the file and executes it over the created instance of Quest.

$ ./ontop help query
NAME
        ontop query - Query the RDF graph exposed by the mapping and the OWL
        ontology

SYNOPSIS
        ontop query [ {-d | --driver-class} <jdbcDriver> ] [ --disable-reasoning ]
                [ {-l | --url} <jdbcUrl> ] {-m | --mapping} <mappingFile>
                [ {-o | --output} <output> ] [ {-p | --password} <jdbcPassword> ]
                [ {-q | --query} <queryFile> ] [ {-t | --ontology} <ontologyFile> ]
                [ {-u | --username} <jdbcUserName> ]

OPTIONS
        -d <jdbcDriver>, --driver-class <jdbcDriver>
            class name of the jdbc Driver (only for R2RML mapping)

        --disable-reasoning
            disable OWL reasoning. Default: false

        -l <jdbcUrl>, --url <jdbcUrl>
            jdbcUrl for the jdbc connection (only for R2RML mapping)

        -m <mappingFile>, --mapping <mappingFile>
            Mapping file in R2RML (.ttl) or in Ontop native format (.obda)

        -o <output>, --output <output>
            output file (default) or directory (for --separate-files)

        -p <jdbcPassword>, --password <jdbcPassword>
            password for the jdbc connection (only for R2RML mapping)

        -q <queryFile>, --query <queryFile>
            SPARQL query file

        -t <ontologyFile>, --ontology <ontologyFile>
            OWL ontology file

        -u <jdbcUserName>, --username <jdbcUserName>
            user name for the jdbc connection (only for R2RML mapping)

Example 1.

Execute a SPARQL query using Ontop mapping.

$  ./ontop query -m /Users/xiao/Projects/iswc2014-benchmark/LUBM/univ-benchQL.obda \
  -t /Users/xiao/Projects/iswc2014-benchmark/LUBM/univ-benchQL.owl \
  -q /Users/xiao/Projects/iswc2014-benchmark/Ontop/q1.txt

x
<http://www.Department0.University0.edu/GraduateStudent44>
<http://www.Department0.University0.edu/GraduateStudent101>
<http://www.Department0.University0.edu/GraduateStudent124>
<http://www.Department0.University0.edu/GraduateStudent142>

Example 2.

Execute a SPARQL query using R2RML mapping and output the query result to a file.

$ ./ontop query -m /Users/xiao/Projects/iswc2014-benchmark/LUBM/univ-benchQL.ttl \
 -t /Users/xiao/Projects/iswc2014-benchmark/LUBM/univ-benchQL.owl \
 -o /tmp/q1.csv -l jdbc:mysql://10.7.20.39/lubm1 -u fish   -p fish  \
 -d com.mysql.jdbc.Driver -q /Users/xiao/Projects/iswc2014-benchmark/Ontop/q1.txt

$ cat /tmp/q1.csv
x
<http://www.Department0.University0.edu/GraduateStudent44>
<http://www.Department0.University0.edu/GraduateStudent101>
<http://www.Department0.University0.edu/GraduateStudent124>
<http://www.Department0.University0.edu/GraduateStudent142>

ontop materialize

The second option is the '''materialization utility''', it does not need any query file, but instead, needs the user to specify a format in which he/she wants the output (either to terminal or output file). Materialization is helpful when you want to generate RDF data out of your database, using the provided mappings. This utility will take all the triples that the mappings can produce from the data source, and write it to file or terminal surface. For large sets of data the result will be large and might take some seconds to produce. The user can choose between three different formats of output: Turtle, N3 or RDF/XML.

$ ./ontop help materialize
NAME
        ontop materialize - Materialize the RDF graph exposed by the mapping and
        the OWL ontology

SYNOPSIS
        ontop materialize [ {-d | --driver-class} <jdbcDriver> ]
                [ --disable-reasoning ] [ {-f | --format} <outputFormat> ]
                [ {-l | --url} <jdbcUrl> ] {-m | --mapping} <mappingFile>
                [ {-o | --output} <output> ] [ {-p | --password} <jdbcPassword> ]
                [ --separate-files ] [ {-t | --ontology} <ontologyFile> ]
                [ {-u | --username} <jdbcUserName> ]

OPTIONS
        -d <jdbcDriver>, --driver-class <jdbcDriver>
            class name of the jdbc Driver (only for R2RML mapping)

        --disable-reasoning
            disable OWL reasoning. Default: false

        -f <outputFormat>, --format <outputFormat>
            The format of the materialized ontology. Default: rdfxml

            This options value is restricted to the following value(s):
                rdfxml
                owlxml
                turtle

        -l <jdbcUrl>, --url <jdbcUrl>
            jdbcUrl for the jdbc connection (only for R2RML mapping)

        -m <mappingFile>, --mapping <mappingFile>
            Mapping file in R2RML (.ttl) or in Ontop native format (.obda)

        -o <output>, --output <output>
            output file (default) or directory (for --separate-files)

        -p <jdbcPassword>, --password <jdbcPassword>
            password for the jdbc connection (only for R2RML mapping)

        --separate-files
            generating separate files for different classes/properties. This is
            useful for materializing large OBDA setting. Default: false.

        -t <ontologyFile>, --ontology <ontologyFile>
            OWL ontology file

        -u <jdbcUserName>, --username <jdbcUserName>
            user name for the jdbc connection (only for R2RML mapping)

Example:

$ ~/opt/ontop-1.15/ontop materialize -l jdbc:h2:tcp://localhost/./../data/books \
 -d org.h2.Driver -m exampleBooks.ttl -u sa -p passowrd \
 -f turtle -o materializedBooks.ttl

ontop mapping

$ ./ontop help mapping
NAME
        ontop mapping - Manipulate mapping files

SYNOPSIS
        ontop mapping { pretty-r2rml | to-obda | to-r2rml } [--] [cmd-options]

        Where command-specific options [cmd-options] are:
            pretty-r2rml: {-i | --input} <input.ttl> {-o | --output}
                    <pretty.ttl>
            to-obda: {-i | --input} <mapping.ttl> [ {-o | --output} <mapping.obda> ]
            to-r2rml: [ {-t | --ontology} <ontology.owl> ] {-i | --input}
                    <mapping.obda> [ {-o | --output} <mapping.ttl> ]

        See 'ontop help mapping <command>' for more information on a specific command.

ontop mapping to-r2rml

$ ./ontop help mapping to-r2rml
NAME
        ontop mapping to-r2rml - Convert ontop native mapping format (.obda) to
        R2RML format

SYNOPSIS
        ontop mapping to-r2rml {-i | --input} <mapping.obda>
                [ {-o | --output} <mapping.ttl> ] [ {-t | --ontology} <ontology.owl> ]

OPTIONS
        -i <mapping.obda>, --input <mapping.obda>
            Input mapping file in Ontop native format (.obda)

        -o <mapping.ttl>, --output <mapping.ttl>
            Output mapping file in R2RML format (.ttl)

        -t <ontology.owl>, --ontology <ontology.owl>
            OWL ontology file

ontop mapping to-obda

$ ./ontop help mapping to-obda
NAME
        ontop mapping to-obda - Convert R2RML format to ontop native mapping
        format (.obda)

SYNOPSIS
        ontop mapping to-obda {-i | --input} <mapping.ttl>
                [ {-o | --output} <mapping.obda> ]

OPTIONS
        -i <mapping.ttl>, --input <mapping.ttl>
            Input mapping file in R2RML format (.ttl)

        -o <mapping.obda>, --output <mapping.obda>
            Output mapping file in Ontop native format (.obda)

ontop mapping pretty-r2rml

$ ./ontop help mapping pretty-r2rml
NAME
        ontop mapping pretty-r2rml - prettify R2RML file using Jena

SYNOPSIS
        ontop mapping pretty-r2rml {-i | --input} <input.ttl>
                {-o | --output} <pretty.ttl>

OPTIONS
        -i <input.ttl>, --input <input.ttl>
            Input mapping file in Ontop native format (.obda)

        -o <pretty.ttl>, --output <pretty.ttl>
            Input mapping file in Ontop native format (.obda)

ontop bootstrap

$ ./ontop help bootstrap
NAME
        ontop bootstrap - Bootstrap ontology and mapping from the database

SYNOPSIS
        ontop bootstrap [ {-b | --base-uri} <baseURI> ]
                [ {-d | --driver-class} <jdbcDriver> ] [ {-l | --url} <jdbcUrl> ]
                {-m | --mapping} <mappingFile> [ {-p | --password} <jdbcPassword> ]
                [ {-t | --ontology} <ontologyFile> ]
                [ {-u | --username} <jdbcUserName> ]

OPTIONS
        -b <baseURI>, --base-uri <baseURI>
            base uri of the generated mapping

        -d <jdbcDriver>, --driver-class <jdbcDriver>
            class name of the jdbc Driver (only for R2RML mapping)

        -l <jdbcUrl>, --url <jdbcUrl>
            jdbcUrl for the jdbc connection (only for R2RML mapping)

        -m <mappingFile>, --mapping <mappingFile>
            Mapping file in R2RML (.ttl) or in Ontop native format (.obda)

        -p <jdbcPassword>, --password <jdbcPassword>
            password for the jdbc connection (only for R2RML mapping)

        -t <ontologyFile>, --ontology <ontologyFile>
            OWL ontology file

        -u <jdbcUserName>, --username <jdbcUserName>
            user name for the jdbc connection (only for R2RML mapping)

Ontop preferences

See here how to set other Ontop preferences if necessary.