-
Notifications
You must be signed in to change notification settings - Fork 13
Standalone client
Irina Dragoste edited this page Sep 4, 2020
·
11 revisions
Rulewerk standalone client jar allows interacting with Rulewerk via the command line, using our rule syntax. It provides:
- an interactive shell for interacting with a knowledge base and a reasoner
- a command-line client for knowledge base materialization and querying
After cloning or downloading the repository, the standalone client jar may be build by invoking mvn package with the client profile:
$ git clone https://github.com/knowsys/rulewerk.git
$ cd rulewerk
$ mvn package -Pclient
This generates the standalone clinet jar file rulewerk-client/target/standalone-rulewerk-client-0.8.0-SNAPSHOT.jar.
The shell is used for interacting with Rulewerk via a series of commands. This way, a user can iteratively load statements into a knowledge base, materialize, query, etc.
Running the standalone client jar without arguments (or with argument shell) launches the interactive shell.
$ java -jar standalone-rulewerk-client-0.7.0.jar
Welcome to the Rulewerk interactive shell.
For further information, type @help. To quit, type @exit.
rulewerk> help
Available commands:
@help : print help on available commands
@load : load a knowledge base from file (in Rulewerk format, OWL, or RDF)
@assert : add facts and rules to the knowledge base
@retract : remove facts and rules to the knowledge base
@addsource : define a new external data source for a predicate
@delsource : remove one or all external data sources for a predicate
@setprefix : set a prefix to abbreviate long IRIs (only affects future inputs)
@clear : discards (parts of) the knowledge base or computed inferences
@reason : load data and compute conclusions from knowledge base
@query : print or export query results
@export : export knowledgebase or inferences to a Rulewerk file
@showkb : displays the content of the knowledge base
@exit : exit Rulewerk shell
For more information on any command, use @help [command name].
rulewerk>
rulewerk> @help help
@help: print help on available commands
Usage: @help [command name] .
command name: command to get detailed help for
rulewerk> @help load
@load: load a knowledge base from file (in Rulewerk format, OWL, or RDF)
Usage: @load [TASK] "file" [RDF predicate] .
TASK: optional; one of RULES (default), OWL, RDF:
RULES to load a knowledge base in Rulewerk rls format
OWL to load an OWL ontology and convert it to facts and rules
RDF to load an RDF document and convert it to facts
"file": path to the file to load, enclosed in quotes
RDF predicate: optional name of the predicate used for loading RDF
triples (default: TRIPLE); use ABOX to load triples
like OWL assertions, using unary and binary predicates
rulewerk> @help assert
@assert: add facts and rules to the knowledge base
Usage: @assert (<fact or rule>)+ .
fact or rule: statement(s) to be added to the knowledge base
Reasoning needs to be invoked after finishing addition of statements.
@retract: remove facts and rules to the knowledge base
Usage: @retract (<fact or rule>)+ .
fact or rule: statement(s) to be removed from the knowledge base, or a predicate declaration
of the form name[arity] to remove all facts for that predicate.
Reasoning needs to be invoked after finishing the removal of statements.
rulewerk> @help addsource
@addsource: define a new external data source for a predicate
Usage: @addsource <predicateName>[<arity>]: <source declaration> .
<predicateName>[<arity>] : the name of the predicate and its arity
<source declaration> : a fact specifying a source declaration
Note that every predicate can have multiple sources
rulewerk> @help delsource
@delsource: remove one or all external data sources for a predicate
Usage: @delsource <predicateName>[<arity>]: <source declartion> .
<predicateName>[<arity>] : the name of the predicate and its arity
<source declaration> (optional): a fact specifying a source declaration
Note that every predicate can have multiple sources.
rulewerk> @help setprefix
@setprefix: set a prefix to abbreviate long IRIs (only affects future inputs)
Usage: @setprefix <prefix>: <IRI> .
rulewerk> @help clear
@clear: discards (parts of) the knowledge base or computed inferences
Usage: @clear TASK .
TASK: what to reset, possuble values:
ALL: empty knowledge base and completely reset reasoner
INF: reset reasoner to clear all loaded data and inferences
FACTS: remove all facts from knowledge base
RULES: remove all rules from knowledge base
DATASOURCES: remove all data source declarations from knowledge base
PREFIXES: undeclare all prefixes and base namespace
rulewerk> @help reason
@reason: load data and compute conclusions from knowledge base
Usage: @reason .
rulewerk> @help query
@query: print or export query results
Usage: @query [COUNT] <query literal> [LIMIT <limit>] [EXPORTCSV <"file">] .
query literal: positive literal, possibly with ?queryVariables
limit: maximal number of results to be shown
"file": path to CSV file for exporting query results, enclosed in quotes
rulewerk> @help export
@export: export knowledgebase or inferences to a Rulewerk file
Usage: @export TASK "file" .
TASK: what to export; can be KB or INFERENCES
"file": path to export file (suggested extension: .rls), enclosed in quotes
rulewerk> @help showkb
@showkb: displays the content of the knowledge base
Usage: @showkb .
rulewerk> @help exit
@exit: exit Rulewerk shell
Usage: @exit .
Given a program and one or more queries, Rulewerk Command-Line Client can:
- print the query result (or only its size) in the standard output.
- save the query results into a directory.
Required parameters:
-
--rule-file=<ruleFiles>: a rule program -
--query=<queryStrings>: a query, or set of queries specified one by one (examples)
Optional parameters:
-
--chase-algorithm=<chaseAlgorithm>: Chase algorithm. RESTRICTED_CHASE (default) or SKOLEM_CHASE. -
--log-file=<logFile>: Log file of VLog (c++ library). VLog will log to the default system output by default. -
--log-level=<logLevel>: Log level of VLog (c++ library). One of: DEBUG, INFO, WARNING (default), ERROR. -
--output-query-result-directory=<outputQueryResultDirectory>: Directory to store the model. Used only if--save-query-resultsis true. "query-results" by default. -
--print-complete-query-result: Boolean. If true, RulewerkClient will print the query results in stdout. False by default. -
--print-query-result-size: Boolean. If true, RulewerkClient will print the size of the query result. True by default. -
--query=<queryStrings>: Positive not-ground Literals to query after materialization in RLS syntax -
--rule-file=<ruleFiles>: Rule file(s) in rls syntax -
--save-query-results: Boolean. If true, RulewerkClient will save the query result into--output-query-result-directory. False by default -
--timeout=<timeout>: Timeout in seconds. Infinite by default
Let's assume that we have a directory called doid-example where we store (1) our Rulewerk command line tool renamed to rulewerk.jar, (2) an RDF file, and a rule file in our syntax.
$ mkdir doid-example
$ cd doid-example
$ wget https://raw.githubusercontent.com/knowsys/rulewerk/master/rulewerk-examples/src/main/data/input/doid.nt.gz
$ wget https://raw.githubusercontent.com/knowsys/rulewerk/master/rulewerk-examples/src/main/data/input/doid.rls
$ cp your-rulewerk-path/rulewerk-client/target/standalone-rulewerk-client-0.6.0-SNAPSHOT.jar ~/doid-example/rulewerk.jar
Please note that your-rulewerk-path needs to be replaced with the correct path
After executing the previous commands, the doid-example folder should looks like:
.
├── doid.nt.gz
├── doid.rls
└── rulewerk.jar
0 directories, 3 files
The following code executes the Doid example, but it ends with an error that is solved bellow
java -jar rulewerk.jar materialize --rule-file=doid.rls --query=humansWhoDiedOfCancer\(?X\) --query=humansWhoDiedOfNoncancer\(?X\)
Configuration:
--rule-file: doid.rls
--query: humansWhoDiedOfCancer(?X)
--query: humansWhoDiedOfNoncancer(?X)
--log-file: null
--log-level: WARNING
--chase-algorithm: RESTRICTED_CHASE
--timeout: none
--print-query-result-size: true
--print-complete-query-result: false
Executing the chase ...
2019-10-28 22:17:51 INFO - Started loading knowledge base ...
[0x1a626ee50f25a99a 2019-10-28 22:17:51] ERROR Could not find doid
Something went wrong. Please check the log file.Could not find doid
This error is produced because the line 4 in file doid.rls contains a wrong relative path. To fix this issue, we need to replace the line
@source doidTriple[3]: load-rdf("src/main/data/input/doid.nt.gz") .
with the line
@source doidTriple[3]: load-rdf("doid.nt.gz") .
After fixing the error, we can lunch the process again and see the results
$ java -jar rulewerk.jar materialize --rule-file=doid.rls --query=humansWhoDiedOfCancer\(?X\) --query=humansWhoDiedOfNoncancer\(?X\)
Configuration:
--rule-file: doid.rls
--query: humansWhoDiedOfCancer(?X)
--query: humansWhoDiedOfNoncancer(?X)
--log-file: null
--log-level: WARNING
--chase-algorithm: RESTRICTED_CHASE
--timeout: none
--print-query-result-size: true
--print-complete-query-result: false
Executing the chase ...
2019-10-28 22:23:46 INFO - Started loading knowledge base ...
2019-10-28 22:23:46 INFO - Finished loading knowledge base.
2019-10-28 22:23:46 INFO - Started materialisation of inferences ...
2019-10-28 22:24:40 INFO - Completed materialisation of inferences.
Answering queries ...
Number of query answers in humansWhoDiedOfCancer(?X): 586
Number of query answers in humansWhoDiedOfNoncancer(?X): 18009
2019-10-28 22:24:40 INFO - Reasoner closed.
Process completed.
Where we can see that according to Wikidata, 586 humans died of cancer related issues during 2018.
To see all the options available in the command line tool, just execute java -jar rulewerk.jar materialize
$ java -jar rulewerk.jar materialize
Missing required options [--rule-file=<ruleFiles>, --query=<queryStrings>]
Usage: java -jar RulewerkClient.jar materialize [[--print-query-result-size]
[--print-complete-query-result]] [[--save-query-results]
[--output-query-result-directory=<outputQueryResultDirectory>]]
[--chase-algorithm=<chaseAlgorithm>] [--log-file=<logFile>]
[--log-level=<logLevel>] [--timeout=<timeout>] --query=<queryStrings>
[--query=<queryStrings>]... --rule-file=<ruleFiles>
[--rule-file=<ruleFiles>]...
Execute the chase and store the literal's extensions
--chase-algorithm=<chaseAlgorithm>
Chase algorithm. RESTRICTED_CHASE (default) or
SKOLEM_CHASE.
--log-file=<logFile> Log file of VLog (c++ library). VLog will log to
the default system output by default
--log-level=<logLevel> Log level of VLog (c++ library). One of: DEBUG,
INFO, WARNING (default), ERROR.
--output-query-result-directory=<outputQueryResultDirectory>
Directory to store the model. Used only if
--save-query-results is true. "query-results" by
default.
--print-complete-query-result
Boolean. If true, RulewerkClient will print the
query result in stdout. False by default.
--print-query-result-size
Boolean. If true, RulewerkClient will print the size
of the query result. True by default.
--query=<queryStrings> Positive not-ground Literals to query after
materialization in rls syntax. RulewerkClient will
print the size of its extension
--rule-file=<ruleFiles>
Rule file(s) in rls syntax
--save-query-results Boolean. If true, RulewerkClient will save the query
result into --output-query-result-directory.
False by default.
--timeout=<timeout> Timeout in seconds. Infinite by default