16. Command-Line Interface¶

This section describes the command-line interface of RDFox including the syntax for launching RDFox processes and complete reference documentation for the RDFox shell.

Note

All command syntaxes are described using standard BNF notation: [x] means that x is optional, and <y> means that y is an argument (instead of a plain string).

16.1. Starting the RDFox Process¶

The RDFox executable may be used to launch processes that contain an RDFox Server instance, or to connect to an existing server whose endpoint is active.

16.1.1. Instantiating a Server¶

RDFox processes that instantiate the RDFox Server can be started using the following command syntax:

RDFox [-<option> <value> ...] [-temp-role | [-role <role>] [-password <password>]] {daemon [<endpointOption> <optionValue> ...] | {shell | sandbox} [<root> [<command> ...]]}

All variants of this command create a single server parameterized by the specifed -<option> <value> key pairs. See Section 7 for the list of parameters supported by RDFox Servers.

In daemon mode, RDFox starts its endpoint, parameterized using the specified key-value pairs, and listens until signalled to exit. For a description of the endpoint and its supported parameters, see Section 13. In daemon mode, both persist-ds and persist-roles are defaulted to file.

In shell and sandbox modes, RDFox creates an instance of the RDFox shell (see Section 16.2), sets the dir.root shell variable to <root>, runs all supplied commands, and then returns the command prompt. In shell mode both persist-ds and persist-roles are defaulted to file whereas in sandbox mode, both are set to off.

A role name and password are required at startup if access control has not been initialized, if an instance of the shell is being created, or if both of these conditions hold. If both conditions hold, the -temp-role option can be set. This initializes access control with a temporary role which will be deleted when the shell closes, and creates an initial connection to the local server authenticated as that role. The -temp-role option is intended to be used to restore a transcribed RDFox instance. See transcribe for more information.

If -temp-role is not specified, but a role name and password are required, RDFox will look for the arguments -role <role> and -password <password>. If one or both of these options is missing, RDFox will next inspect the RDFOX_ROLE and RDFOX_PASSWORD environment variables respectively. If after this one or both of these variables remains unset, the behavior will be as follows:

shell mode will prompt for the missing information
sandbox mode will use the value guest to fill in the blanks
daemon mode will terminate.

16.1.2. Connecting to a Server (EXPERIMENTAL)¶

The following command syntax can be used to connect using shell to an RDFox process running on a different server:

RDFox [-role <role> -password <password>] remote <server-url> [<command> ...]

The resulting process will call the remote shell API of the server at <server-url> to instantiate a remote shell instance, which will be used to run any commands supplied on the command line and then prompt for further commands to run.

A role name and password are required at startup. RDFox will first look for the arguments -role <role> and -password <password>. If one or both of these options is missing, RDFox will next inspect the RDFOX_ROLE and RDFOX_PASSWORD environment variables respectively. If after this one or both both variables remain unset, RDFox will prompt for the missing information.

When invoked from the remote shell, the majority of commands will operate in exactly the same way as if they were invoked from the local shell (shell and sandbox modes) save for the exceptions documented in Section 14.15.1.1. Interruptible operations may be interrupted with Ctrl-C.

Note that file paths embedded within commands are always interpreted with respect to the server’s file system. The remote shell client does not provide any way of using the client’s file system (unless the client is running on the same host as the server).

16.2. RDFox Shell Reference¶

The RDFox shell is a command-line interface for controlling the RDFox server within the same process. It can be used interactively or as a script execution environment and supports a range of variables and commands giving flexible access to RDFox’s features.

16.2.1. Connection Management¶

With the exception of commands that control the behaviour of the shell or endpoint, each shell command requires either a server or data store connection to do its work. To support this, the shell maintains a list of named connections of each type as well as variables to hold the names of the active connections.

When a command requiring a server connection is executed, the shell searches its list of server connections for a connection with the name held in the active-server-connection variable. If the search is successful, the idenfitied connection is used. If not, an error is printed. When an instance of the shell is created, an initial server connection named sc1 is created, using the role name and password provided by the user (see Section 16.1), and made active. Thereafter, command srvconn (described in Section 16.2.2.43) can be used to manage the shell’s server connections.

When a command requiring a data store connection is executed, the shell searches its list of data store connections for a connection with the name held in the active-data-store-connection variable. If the search is successful, the identified connection is used. If not, the shell looks for a data store whose name matches the active data store connection name and, if such a data store exists, opens a new connection to it using the active server connection. If no such data store exists, an error is printed. The command dsconn (described in Section 16.2.2.12) can be used to manage the shell’s data store connections.

16.2.2. Shell Commands¶

This section describes the commands that can be used in the shell.

16.2.2.1. active¶

Syntax:

active [<name>]

Description: If <name> is omitted, this command prints the name of the active data store connection; otherwise, it sets the active data store connection name to <name>. See Section 16.2.1 for details of how the shell manages connections.

16.2.2.2. answer¶

Syntax:

answer (! <query_text> | <filename>*)

Description: This command evaluates one or more SELECT, ASK, or CONSTRUCT queries. A single query can be given explicitly as text after the ! symbol, or one can specify zero or more file names that contain the queries to be evaluated. Each relative <filename> (e.g., it does not start with / on Unix-based platforms) is interpreted as relative to the content of the dir.queries shell variable.

Example: The following command checks whether the a1:Org class contains any instances.:

answer ! ask { ?X rdf:type a1:Org }

16.2.2.3. ask¶

Syntax:

ask <remaining_query_text>

Description: This command queries the current data store with the specified SPARQL query. An ask query tests whether or not a query pattern has a solution.

Example: The last command of the following scripts tests whether the specified pattern can be matched in the materialization, and prints out the total number of matched tuples.

dstore create default
import "LUBM.ttl"
import "LUBM.dlog"
mat
prefix a1: <http://lehigh.edu/onto/univ-bench.owl#>
set output out
ask { ?X rdf:type a1:Org }

16.2.2.4. base¶

Syntax:

base [<baseIRI>]

Description: This command set the base IRI for the shell if an argument is given or prints the value otherwise. The base IRI for the shell is used to expand relative IRIs entered into the shell. The baseIRI argument, when provided, must be an absolute IRI enclosed in angle brackets.

16.2.2.5. begin¶

Syntax:

begin [read | write]

Description: This command starts a transaction on the current data store. The transaction is read-only (if read parameter is specified), or read/write (if write parameter is specified). The read/write mode is the default.

16.2.2.6. clear¶

Syntax:

clear [rules-explicate-facts | facts-keep-rules] [force]

Description: This command clears various parts of the data store.

With no arguments, it removes all facts, axioms, and rules.
With rules-explicate-facts, it clears all rules and makes all facts explicit – that is, it adds all facts from the derived fact domain into the explicit domain. This operation can be used when the facts derived by one set of rules should be fed as input to another set of rules.
With facts-keep-rules, it clears all facts but keeps all rules currently loaded into the data store. This operation can be useful when the same set of rules needs to be applied to different data.

All variants of the command will prompt for confirmation unless force is specified.

Example: After the clear rules-explicate-facts command of the following script is issued, all facts will become explicit and all rules will be deleted. Therefore, if a1:Org[http://www.University389.edu] is derived during the materialization, then the first “explain” command will print information about how this fact is derived, whereas the second “explain” command will simply tell the user that the fact is an explicit fact.

dstore create default
import "LUBM.ttl"
import "LUBM.dlog"
prefix a1: <http://lehigh.edu/onto/univ-bench.owl#>
explain shortest a1:Org[<http://www.University389.edu>]
clear rules-explicate-facts
explain shortest a1:Org[<http://www.University389.edu>]

16.2.2.7. commit¶

Syntax:

commit

Description: This command commits the transaction on the current data store.

16.2.2.8. compact¶

Syntax:

compact

Description: This command compacts all facts in the data store, reclaiming the space used by the deleted facts in the process and persistent storage. This operation may take a long time to complete, the time taken is roughly proportional to the number of triples in the data store.

16.2.2.9. construct¶

Syntax:

construct <remaining_query_text>

Description: This command queries the current data store with the specified SPARQL CONSTRUCT query. The resulting triples are stored using the Turtle format.

16.2.2.10. daemon¶

Syntax:

daemon

Description: This command switches RDFox into daemon mode by first ensuring that the endpoint is listening and then closing the shell. Endpoint configuation parameters must be set as shell variables before running this command in the same way as for the endpoint command. Commands appearing after this command in an RDFox shell script will not be run.

This command cannot be executed in a remote shell instance.

16.2.2.11. delete¶

Syntax:

delete <remaining_query_text>

Description: This command can be used to remove explicit facts from the data store based on bindings for a query pattern specified in a where clause.

Example: The following command removes all facts matching the specified query pattern ?X a1:headOf ?Y from the data store.

delete { ?X a1:headOf ?Y } where{ ?X a1:headOf ?Y }

16.2.2.12. dsconn¶

Syntax:

dsconn list | active [<name>] | open [name] to <data-store-name> [as <role>] | close [<name>|to <data-store-name>]

Description: Manages data store connections belonging to the current shell. See also Section 16.2.1.

Option list prints the currently open data store connections.
Option active sets <name> as the name of the active data store connection if a parameter is provided or prints the name of the active data store connection if not.
Option open opens a new connection to the data store with name <data-store-name>. If the optional <name> parameter is provided, it is used as the name of the connection, otherwise a name is assigned automatically. If the optional <role> parameter is supplied, the command will attempt to create the connection as <role>. If no role is specified, the the command will attempt to create the new data store connection from the active server connection.
Option close closes the active data store connection if no argument is given, the data store connection with name <name> if a single argument is given, or all connections to the data store with name <data-store-name> if the arguments to and <data-store-name> are given in that order.

16.2.2.13. dsource¶

Syntax:

dsource list | show <dsname> | register <dsname> <parameters> | sample <dsname> <table> [<size>] | deregister <dsname>

Description: This command manages the data sources of the current store. The command is useful when the user wishes to import and manage data of non-RDF formats in RDFox. For an overview of how RDFox manages data sources, see Section 10.

Option list prints the currently available data sources.
Option show shows information about the data source with name <dsname>.
Option register registers a new data source with name <dsname>. Information about the data source is specified by the key-value pairs in <parameters>. See Section 10.1 for details of the parameter names and values that can be supplied.
Option sample shows a preview of up to <size>; rows from table <table> of data source <dsname>.
Option deregister deregisters a data source with name <dsname>.

16.2.2.14. dstore¶

Syntax:

dstore list | create <name> [<parameterKey> <parameterValue>]* | load <name> <filename> [<parameterKey> <parameterValue>]* | save <name> <filename> [raw] | delete <name> [force]

Description: This command manages the data stores of the server.

Option list prints the currently available data stores.
Option create adds a new data store with name <name>. One can optionally specify various data store parameters as a list of key-value pairs; see Section 8.2 for the list of supported parameters.
Option load creates a new data store with name <name> using the content of the specified file. If <filename> is relative (e.g., it does not start with / on Unix-based platforms), it is interpreted as relative to the content of the dir.stores shell variable. This command can load binary files in both standard and raw formats. In case of the former, one can override the data store parameters by specifying various data store options in the same way as for the dstore create command (but one cannot change the equality mode of the data store).
Option save saves the contents of the data store with name <name> to a binary file. The standard format is used for the output, unless the raw option is specified in which case the raw format is used. If <filename> is relative (e.g., it does not start with / on Unix-based platforms), it is interpreted as relative to the content of the dir.stores shell variable.
Option delete deletes the data store with name <name> from the server. This option will prompt for confirmation unless force is specified.

16.2.2.15. echo¶

Syntax:

echo <tok>*

Description: This command prints all tokens given after the command, separating them by a single space. All variables occurring in the tokens are expanded as usual, which can be used to print useful information.

16.2.2.16. endpoint¶

Syntax:

endpoint (start | stop)

Description: This command starts or stops the RDFox Endpoint. To override the default value for an endpoint parameter <parameter>, set the desired value into shell parameter endpoint.<parameter> before starting the endpoint. See Section 13.2 for details of the supported parameters.

Example: The following commands start the RESTful endpoint on port 4567.

set endpoint.port "4567"
endpoint start

This command cannot be executed in a remote shell instance.

16.2.2.17. evaluate¶

Syntax:

evaluate (! <statement_text> | <filename>*)

Description: This command evaluates one or more SPARQL statements. A statement is either a SPARQL query or a SPARQL update. The statement to evaluate can be given explicitly as text after the ! symbol, or one can specify zero or more file names that contain the statements to be evaluated. Each relative <filename> (e.g., it does not start with / on Unix-based platforms) is interpreted as relative to the content of the dir.queries shell variable.

Example: The following command checks whether the a1:Org class contains any instances.:

evaluate ! ask { ?X rdf:type a1:Org }

Example: The following command inserts a triple and then, in a separate update, derives a second triple from it. Both updates are applied in a single transaction.:

evaluate ! insert data { <a> a <A> } ; insert { ?a a <B> } where { ?a a <A> }

16.2.2.18. exec¶

Syntax:

exec [<repeat_num>] <filename> [<argument>]*

Description: This command executes the contents of the specified script repeatedly for the specified number of times. If <repeat_num> is not specified, then the script is executed once. All <argument> tokens are passed as variables $(1), $(2), and so on. If <filename> is relative (e.g., it does not start with / on Unix-based platforms), it is interpreted as relative to the content of the dir.scripts shell variable.

Example: The following command executes the script stored in file testMat.rdfox.

exec "testMat.rdfox"

Example: The following scripts accesses arguments passed to it.

dstore create default
import "$(1)"
import "$(2)"
mat
import - "$(3)"
mat
quit

Assuming that the script is stored in file testMat.rdfox, it can be invoked as follows.

exec "testMat.rdfox" data.ttl program.dlog delta.ttl

If a script file has suffix “.rdfox” and is in the directory that the dir.scripts shell variable points to, then both exec and the suffix .rdfox can be omitted. Together with the support for argument passing, one to group arbitrary commands together in a script and use the latter as if it were a new command.

Example: The following command does the same as the exec command in the previous example, provided that the script file testMat.rdfox can be found in the directory specified by the dir.scripts shell variable.

testMat data.ttl program.dlog delta.ttl

16.2.2.19. explain¶

Syntax:

explain [shortest | to-explicit | exhaustive] [<max_depth> [<max_rule_instances>]] <fact>

Description: This command explains how a fact has been derived. The fact is specified using the Datalog syntax — that is, a triple can be written as [s, p, o] or p[s, o], a triple [s, rdf:type, C] can be written as C[s], and so on. A fact can be derived in more than one way. If shortest is specified, then just one shortest derivation (in terms of height) is printed; if there are several derivations of the same height, one is arbitrarily chosen. If to-explicit is specified, then all explanations up to explicit facts are printed. Finally, if exhaustive is specified, then all facts are maximally explained, including the explicitfacts. Finally, <max_depth> can be specified to limit the maximal depth of a proof tree, and <max_rule_instances> can be specified to limit the maximal number of rule instances in each node of the proof tree.

Example: The last command of the following script explains how the specified fact was derived (in the shortest way) during the materialization.

dstore create default
import "LUBM.ttl"
import "LUBM.dlog"
mat
prefix a1: <http://lehigh.edu/onto/univ-bench.owl#>
explain shortest a1:Org[<http://www.University389.edu>]

Note

Facts in data stores where equality is set to anything other than off cannot currently be explained using this command.

16.2.2.20. export¶

Syntax:

export <filename> [<format_name>  [<parameterKey> <parameterValue>]*]

Description: This command exports the data in the current store to the specified file in the specified format. One can optionally specify a number of key-value pairs that customize the export process. The available key-value pairs are specific to the answer format. The supported formats are described in Section 14.3.1. When exporting to a format that stores facts, the only supported parameter is fact-domain, and its value is the fact domain determining which facts get exported. This command can also be be used to export the OWL axioms and rules in current store, by specifying supported output formats text/owl-functional and application/x.datalog respectively. In the latter case, the rule-domain parameter specifies from which domains should the rules be exported, with the default being the user rule domain (4.6). The default format is text/turtle with parameter fact-domain equal to explicit.

If <filename> is relative (e.g., it does not start with / on Unix-based platforms), then it is interpreted as relative to the content of the dir.facts shell variable if the selected format can store facts, or as relative to the content of the dir.dlog shell variable if the selected format cannot store facts.

Example: The following command exports the derived facts from the data store in the application/n-triples format.

export "output.ttl" "application/n-triples" fact-domain all

Example: The following command exports the OWL 2 axioms that have been translated from the data in the current store.

export "output.fss" "text/owl-functional"

Example: The following command exports the rules that have been imported by the user i.e. imported into the default “user” rule domain.

export "output.dlog" "application/x.datalog"

16.2.2.21. grant¶

Syntax:

grant privileges <actions> <resource-specifier> to <role> | role <super-role> to <role>

Description: This command grants privileges and role memberships to roles in a server’s role database. The counterpart to this command is revoke.

Option privileges grants the privileges to perform <actions> on the resource(s) matched by <resource-specifier> to the role <role>, where <actions> is a comma-separated list of the elements read, write, grant and full and <resource-specifier> is a string meeting the requirements of a resource specifier described in Section 11.1.2.1.
Option role grants membership of the role with name <super-role> to the role with name <role>. See Section 11.2.5 for more information about role membership.

Section 11 describes RDFox’s access control model in more detail.

Example: The following command grants read and write access over the family data store to the role graphuser.

grant privileges read,write >datastores|family to graphuser

16.2.2.22. help¶

Syntax:

help [<command_name>]

Description: When executed without arguments, this command prints the list of all available commands. It also prints a reference list of supported formats for data store content. When executed with one or more commands, help information about each of the specified commands will be printed.

16.2.2.23. import¶

Syntax:

import [> <default graph name>] [+|-] (! <text> | ( <file name> | <iri> )* )

Description: This command adds the specified items (i.e., facts and/or axioms/rules) into the current store (if nothing or + is specified), or removes the specified items from the current store (if − is specified). The user may choose to specify items in plain text, in which case the text follows the ! symbol. Alternatively, the user can specify a list of local paths and IRIs from which content should be loaded.

RDFox supports importing triples and rules in N-Triple, Turtle, N-Quad, TriG, OWL 2 Functional-Style Syntax and Datalog formats. Option > can be used to specify the name of a graph that should be used as the default graph. The format of the file to import may be specified by setting the import.format variable to the desired format in the shell. The list of available formats is printed when typing help into the shell.

If <file name> is relative (e.g., it does not start with / on Unix-based platforms), it is first interpreted as relative to the content of the dir.facts shell variable, and if no file is found then it is interpreted as relative to the content of the dir.dlog shell variable. <file name> may be quoted — that is, surrounded with single-quotes or double-quotes, if required, for example to support filenames containing spaces. IRIs appearing in this list must be enclosed in angle brackets.

Example: The following command adds a rule to the current data store; informally, the rule says that if ?X is a person and ?X likes something, then ?X is a person with hobby.

import ! a1:PHobby[?X]:- a1:Person[?X], a1:like[?X,?Y] .

Example: The following command adds a fact to the default graph of the current data store.

import ! a1:Person[a1:john] .

Example: The following command adds a fact to the graph named a1:G in the current data store. Note that the named graph is not specified in the input text; rather, the command itself specifies that a1:G should be used as the default graph.

import > a1:G ! a1:john a a1:Person .

Example: The following command adds the data from two local files (./data.ttl and ./rules.dlog) and one URL in parallel.

import ./data.ttl <https://www.w3.org/1999/02/22-rdf-syntax-ns> ./rules.dlog

16.2.2.24. importaxioms¶

Syntax:

importaxioms [<source graph name>] [> <target graph name>] [+|-] [assertions]

Description: This command parses the triples in the source named graph and adds them as OWL axioms in the target named graph. rdfox:DefaultTriples is used as source and target when the respective name is missing. The axioms can be added (if nothing or + is specified) or removed (if - is specified). Unless assertions is specified, the ABox assertions are not parsed.

16.2.2.25. info¶

Syntax:

info [extended | axioms | rulestats [print-rules] [by-body-size] | ruleplans]

Description: This command prints various information about a data store. The exact information printed is determined by the command options.

If no argument is specified, only a short breakdown of memory use and the state of the data store is shown.
If extended is specified, the summary from the previous item is extended with detailed information about the memory use and the state of various subcomponents of RDFox. This diagnostic information depends on the internal structure of RDFox and is thus not meant to be used by users, it is moreover likely to change in future, and is mainly intended to aid Oxford Semantic Technologies in providing client support.
If axioms is specified, then the OWL axioms currently loaded in the data store are printed.
If rulestats is specified, then statistics (i.e., the numbers of recursive, nonrecursive, and all rules) is printed for each component of the currently loaded datalog program. The optional argument print-rules determines whether the rules will be printed, and the argument by-body-size determines whether the rules will be grouped by rule body size (i.e., the number of atoms in the rule body) inside each component.
If ruleplans is specified, then the query plans of the compiled rules are printed. This is mainly used for troubleshooting.

16.2.2.26. insert¶

Syntax:

insert <remaining_query_text>

Description: This command adds the explicit facts to the data store based on bindings for a query pattern specified in a where clause.

Example: The following command evaluates ?X a1:headOf ?Y in the data store, and for each value of ?X and ?Y it creates a triple ?Y a1:hasHead ?X.

insert { ?Y a1:hasHead ?X } where { ?X a1:headOf ?Y }

16.2.2.27. lookup¶

Syntax:

lookup <ResourceID>*

Description: The system assigns each IRI resource a unique ID, and this command returns the corresponding resources for the specified IDs.

16.2.2.28. mat¶

Syntax:

mat

Description: This command explicitly updates the set of materialized facts in the data store. In normal operation, RDFox will invoke this operation internally as needed so that, when queries are issued, query results correctly reflect all additions/deletions of facts/rules to the data store. Hence, this command is useful mostly when one must know exactly materialization is to be updated. For example, this can be the case when benchmarking reasoning algorithms, or when debugging the reasoning process. Since materialization is updated automatically when a transaction is committed, this command should be used only inside transactions.

Example: The following sequence of commands starts a transaction, imports facts from the testData.ttl file, imports rules from the testProgram.dlog file, and then updates the Materialization. Next, it deletes facts from the factsToDelete.ttl file, again updates the materialization, and commits the transaction. When mat is first invoked, the system performs‘reasoning from scratch’, whereas in the second case it updates the materialization incrementally.

dstore create default
begin
import "testData.ttl"
import "testProgram.dlog"
mat
import - "factsToDelete.ttl"
mat
commit

16.2.2.29. password¶

Syntax:

password

Description: This command initiates an interactive process to change the password of the logged-in role.

16.2.2.30. prefix¶

Syntax:

prefix <prefixname> <prefixIRI>

Description: This command associates a prefix name with the given IRI. Such prefix names are used to abbreviate IRIs on the command line.

Example: The following command declares prefix a1: and then uses it in a SELECT query.

prefix a1: <http://www.a1.org/a1#>
SELECT ?X ?Y WHERE { ?X a1:hasName ?Y }

16.2.2.31. prefixes¶

Syntax:

prefixes list | clear | restore-defaults

Description: This command manages the shell’s prefixes

Option list prints the shell’s prefixes.
Option clear clears the shell’s prefixes.
Option restore-defaults restores the default prefixes for the shell. Prefix definitions that do not conflict with the defaults are preserved.

16.2.2.32. quit¶

Syntax:

quit

Description: This command terminates the shell.

When run in a local shell (created by starting the executable in shell or sandbox mode) this command will also cause the process to exit. To instead transition the process into a daemon, use the daemon command (see Section 16.2.2.10).

Note that it is not possible to cause the server process to exit from a remote shell instance.

16.2.2.33. recompilerules¶

Syntax:

recompilerules

Description: This command recompiles the rules in the current data store according to the current statistics. This can be used after the stats update command so that the rule compilation takes advantage of up-to-date statistics.

16.2.2.34. remat¶

Syntax

remat

Description: This command performs a full, from-scratch materialization within the data store. This can be useful to ensure that all derived facts in the data store are up-to-date with respect to the data store’s data sources.

16.2.2.35. revoke¶

Syntax:

revoke privileges <actions> <resource-specifier> from <role> | role <super-role> from <role>

Description: This command revokes privileges and role memberships from roles in a server’s role database. The counterpart to this command is grant.

Option privileges revokes the privileges to perform <actions> on the resource(s) matched by <resource-specifier> from the role <role>, where <actions> is a comma-separated list of the elements read, write, grant and full and <resource-specifier> is a string meeting the requirements of a resource specifier described in Section 11.1.2.1.
Option role revokes membership of the role with name <super-role> from the role <role>. See Section 11.2.5 for more information about role membership.

Section 11 describes RDFox’s access control model in more detail.

Example: The following command revokes write access over the family data store from the role graphuser.

revoke privileges write >datastores|family from graphuser

16.2.2.36. role¶

Syntax:

role list | show <role> | create <role> [hash <password_hash>] | delete <role> [force]

Description: This command manages the set of Roles defined within the system.

If no argument is specified, the name of the currently active role is shown.
Option list lists the roles defined within the system.
Option show shows the privileges, memberships and members of role <role>.
Option create creates a new role with name <role>. If the hash option is used then the role is created using the given <password_hash>, otherwise the user is prompted to enter a new password for the role. A password hash of an existing role can obtained by listing role information using the role show shell command or programmatically as described in Section 14.13.4.
Option delete deletes role <role>. This option will prompt for confirmation unless force is specified.

Section 11 describes RDFox’s access control model in more detail.

16.2.2.37. rollback¶

Syntax:

rollback

Description: This command rolls back the currently running transaction.

16.2.2.38. root¶

Syntax:

root <directory>

Description: This command sets the dir.root shell variable (which determines the root directory) to the specified string. Many other shell variables are updated as well, as specified at the beginning of this section.

16.2.2.39. rwtest¶

Syntax:

rwtest <min-sleep> <max-sleep> [read-only]

Description: This command runs a test of reading from and, optionally, writing to the active data store.

The test works by repeatedly adding and deleting a fixed sequence of RDF graphs to/from the data store. When the read-only flag is omitted each iteration of the test loop begins a read-write transaction, deletes the RDF graph added in the previous iteration, runs a query to ensure that the deletion has fully emptied the store, adds the next RDF graph in the sequence, and attempts to commit the transaction. If committing the transaction fails due to unapplied transactions from other replicas the transaction is rolled back and the next loop iteration begins immediately. When the read-only flag is included the begin, deletion, and query steps are performed in each iteration but the addition step is skipped and no attempt to commit the transaction is made (the transaction is always rolled back). After the end of each successful iteration the test sleeps for a random duration between <min-sleep> and <max-sleep> milliseconds. These parameters can be varied to simulate different transaction rates.

Every 60 s the test produces a report summarising various statistics. The report may be printed to the terminal, redirected to a file, or disabled by setting the shell’s output variable to out, the name of the desired file, or null respectively.

The test stops when an error is encountered or it is interrupted (for example with Ctrl-C). A final report is produced at this point.

16.2.2.40. select¶

Syntax:

select <remaining_query_text>

Description: This command queries the current data store with the specified SPARQL query.

Example: The following commands load data and run a query. The output of the command will be written into file $(dir.output)/results.txt; note that directory $(dir.output) must exist for query evaluation to succeed.

dstore create default
import "LUBM.ttl" "LUBM.dlog"
set output "results.txt"
SELECT ?X WHERE { ?X rdf:type <http://lehigh.edu/onto/univ-bench.owl#Org> }

16.2.2.41. set¶

Syntax:

set [<variable> [<value>]]

Description: This command assigns the specified value to the specified variable. If no argument is given at all, then all variable-value pairs are printed; if the variable is given but the value is not, then the current value for the given variable is printed. Issue the set command with no arguments or see Section 16.2.3 for details of the available variables.

16.2.2.42. sleep¶

Syntax:

sleep <milliseconds>

Description: This command makes the system sleep for the specified number of milliseconds.

16.2.2.43. srvconn¶

Syntax:

srvconn list | active [<name>] | open [<name>] [as <role>] | close [<name>]

Description: Manages server connections belonging to the current shell. See also Section 16.2.1.

Option list prints the currently open server connections.
Option active sets <name> as the name of the active server connection if a parameter is provided or prints the name of the active server connection if not.
Option open opens a new connection to the local server. If the optional <name> parameter is provided, it is used as the name of the connection, otherwise a name is assigned automatically. If the optional <role> parameter is provided, the command will attempt to create the connection as <role>. If no role is provided, the command will duplicate the active server connection.
Option close closes the active server connection if no argument is given or the server connection with name <name> if a single argument is given.

16.2.2.44. stats¶

Syntax:

stats list | show <name> | create <name> <parameters> | delete <name> | update [<name>]

Description: This command maintains the statistics that RDFox uses internally for tasks such as query planning.

Option list prints the currently available statistics.
Option show shows information about the statistics with name <name>.
Option create creates the statistics with name <name>. Information that governs how the statistics are created is specified by the key-value pairs in <parameters>.
Option delete deletes the statistics with name <name>.
Option update updates all statistics if <name> is not specified, or it updates the statistics with name <name>. Note that, if auto-update-statistics option is set to true, then statistics will be updated automatically whenever the number of facts in the system changes by more than 10%.

16.2.2.45. threads¶

Syntax:

threads [<number_of_threads>]

Description: This command sets the number of threads that the server will use for tasks such as reasoning or importation of data. The initial value of this parameter can be specified using the -num-threads server option at the command line. The default is the number of logical processors on the machine.

16.2.2.46. transcribe¶

Syntax:

transcribe [force] <directory_name> [<datastore_name>*]

Description: This command saves the RDFox server state to a collection of files under a directory named <directory_name>. A file name main_restore.txt will be created under the directory <directory_name> that can be executed in another instance of RDFox to restore all transcribed content.

By default transcribe will save the content of all data stores that have persistence enabled. It is possible to transcribe only certain data stores, regardless of whether persistence is enabled or not, by specifying one or more data stores names as <datastore_name> parameters.

transcribe is intended to be used to transfer the entire server state to another RDFox instance. To prevent changes occurring while the transcribe command is running, the normal behavior is to raise an error if the endpoint is running. This check can be disabled by using the force option.

Example

To transcribe the content of an existing RDFox instance to a directory named save_directory. Log into the existing RDFox shell and execute the following

transcribe save_directory
quit

Then invoke another instance of RDFox, typically a newer version, and restore the settings into into a new server directory (in example new_server_dir) as follows.

./RDFox -server-directory new_server_dir -temp-role shell save_directory main_restore.txt

16.2.2.47. tstamp¶

Syntax:

tstamp [<variable_name>]

Description: This command saves the current time stamp into the variable with the specified name. If no variable is specified, the system prints the current time stamp.

16.2.2.48. tupletable¶

Syntax:

tupletable list | show <IRI> | create <IRI> <parameters> | delete <IRI> [force]

Description: This command manages the tuple tables of the current store.

Option list prints the currently available tuple tables.
Option show shows information about the tuple table with name <IRI>.
Option create creates a new tuple table with name <IRI>. Information about the tuple table is specified by the key-value pairs in <parameters>.
Option delete deletes the tuple table with name <IRI>. This option will prompt for confirmation unless force is specified.

Example: The following command creates a tupletable from a delimitedFile datasource.

tupletable create :myTupletable dataSourceName myDataSource columns 3 "1" "http://oxfordsemantic.tech/data/entity#{id}" "1.datatype" "iri" "2" "{name}" "3" "{dob}" "3.datatype" "xsd:dateTime" "3.if-empty" "absent"

Example: The following command creates a tupletable from a table in a SQL datasource (either PostgreSQL or ODBC).

tupletable create :myTupletable dataSourceName mySQLdsource table.name salaries columns 2 "1" "http://oxfordsemantic.tech/data/entity#{employee_id}" "1.datatype" "iri" "2" "{salary}" "2.datatype" "xsd:decimal" "2.if-empty" "absent"

Example: The following command creates a tupletable from a query in a SQL datasource.

tupletable create :myTupletable dataSourceName mySQLdsource query "SELECT ssn.social_security_number AS col1, salaries.salary AS col2 FROM ssn JOIN salaries ON ssn.employee_id = salaries.employee_id" columns 2 "1" "http://oxfordsemantic.tech/data/ssn#{col1}" "1.datatype" "iri" "2" "{col2}" "2.datatype" "xsd:decimal" "2.if-empty" "absent"

16.2.2.49. unset¶

Syntax:

unset <variable_name>

Description: This command unsets the variable with name variable_name.

16.2.2.50. update¶

Syntax:

update (! <query_text> | <filename>*)

Description: This command evaluates one or more update queries. The query can be either given explicitly as text after the ! symbol, or one can specify zero or more file names that contain the queries to be evaluated. If <filename> is relative (e.g., it does not start with / on Unix-based platforms), it is interpreted as relative to the content of the dir.queries shell variable.

Example: The following command evaluates an update query.

update ! delete { ?p :givenName 'Bill' } insert { ?p :givenName 'William' } where { ?p :givenName 'Bill' }

16.2.3. Shell Variables¶

Shell variables can hold string, signed integer, or Boolean values. As well as a predefined set of variables that control the behavior of the shell or individual commands (see below), users can define their own variables. A shell variable called var can be used in commands in the form $(var). Shell variables can be set using the set command (Section 16.2.2.41).

Variables that are initially set after starting RDFox, their default values, and a summary of each are given in the table below. Similar information for all currently set variables may be obtained in the RDFox shell by running the set command with no arguments.

Variable Name	Default Value	Description
`active-data-store-connection`	`default`	Contains the name of the active data store connection.
`active-server-connection`	`sc1`	Contains the name of the active server connection.
`base-iri`	`http://oxfordsemantic.tech/RDFox/`	Contains the base IRI for the shell.
`dir.executing-script`	(none)	When executing a script, RDFox sets this variable to the path of the directory that contains the script. This can be used to set the shell root directory so that the script can then use relative file paths. This variable cannot be set directly.
`dir.dlog`	`./`	Determines the directory for resolving relative file names of datalog programs. For details on path resolution, see note below table.
`dir.facts`	`./`	Determines the directory for resolving relative file names of RDF files. For details on path resolution, see note below table.
`dir.output`	`./`	Determines the directory for resolving relative file names of output files (as specified by the `output` variable). For details on path resolution, see note below table.
`dir.queries`	`./`	Determines the directory for resolving relative file names of query files. For details on path resolution, see note below table.
`dir.root`	`./`	Determines the root directory of the current data set. For details on path resolution, see note below table.
`dir.scripts`	`./`	Determines the directory for resolving relative file names of script files. For details on path resolution, see note below table.
`dir.stores`	`./`	Determines the directory for resolving relative file names of binary store files. For details on path resolution, see note below table.
`import.format`	`""`	Determines the format that will be parsed by the import command.
`import.monitor`	`off`	Determines whether and how import operations are monitored: `off` (no monitoring) and `progress` (report progress during import).
`log-frequency`	`0`	Determines the time in seconds during which various logs are produced (see note below table).
`on-error`	`continue`	Determines how the shell behaves when a command results in an error: `continue` continues to the next command; `continue-if-exists` continues to the next command if the error is due to an attempt to create a resource (for example a data store or role) that already exists, otherwise stops processing commands; `stop` stops processing commands. See also Section 16.2.5.
`output`	`null`	Determines how command results (including queries) are printed: `null` (nothing is printed); `out`, (to stdout); or a file name.
`query.answer-format`	`application/x.sparql-results+turtle-abbrev`	Determines the name of the format used to serialize query answers (see note below table).
`query.cardinality`	`true`	If true, then queries return the correct cardinality.
`query.delete-output-if-answer-empty`	`false`	If true, then the output file is deleted when the query answer is empty.
`query.explain`	`false`	If true, the query plan is printed after compilation.
`query.fact-domain`	`all`	Determines the fact domain of the matched tuples: `explicit` matches the explicitly stated facts; `derived` matches facts that are not explicitly stated, but are derived by a rule; `all` matches all facts.
`query.monitor`	`off`	Determines whether and how query evaluation is monitored: `off` (no monitoring); `profile` (periodically print query evaluation statistics); and `trace` (print query evaluation trace).
`query.planning-algorithms`	`rewriting greedy`	Determines the sequence of planning algorithms that will be used when evaluating queries.
`query.print-options`	`false`	If true, then query compilation options are printed before queries are evaluated.
`query.print-statistics`	`false`	If true, the statistics about query evaluation is printed after query is evaluated.
`query.print-summary`	`true`	If true, then a summary of query evaluation (number of returned tuples and query evaluation time) is printed after a query is evaluated.
`reason.monitor`	`off`	Determines whether and how reasoning is monitored: `off` (no monitoring); `stats` (gather statistics); `progress` (report progress during reasoning); `profile` (periodically print rule evaluation statistics); and `trace` (print reasoning trace).
`reason.profiler-entries`	`20`	Specifies the number of entries reported by the reasoning profiler.
`reason.profiler-logPlans`	`false`	Determines wether the rule profiler will report statistics about rule plans.
`run`	`true`	The shell is running while this variable is true.
`version`	e.g., `3.0.0 (96b08d35d74e54c8763c9ef5d6face6800e44397)`	Contains the current version of RDFox.

Note:

Additional variables are available to control the RDFox endpoint. See Section 16.2.2.16 for details.
If a path variable (e.g. dir.dlog, dir.facts, etc.) contains a relative path, then it is resolved against the sandbox directory of the server (see Section 7.2) when sandboxing is enabled, and against the working directory of the RDFox process otherwise.
It can be useful to set the log-frequency variable to a nonzero value n when large amounts of data are being imported. This will cause progress to be reported every n seconds.
The query.answer-format variable may be set to any of the values detailed in Section 14.3.2, and text/turtle in the case of queries over exactly three variables called ?S, ?P, and ?O.

16.2.4. Script Execution¶

When RDFox encounters an unrecognized command name, it checks the directories identified by the dir.scripts and dir.root shell variables (in that order) for a file whose name matches the given command or the given command with the file extension .rdfox. If a file is found, RDFox will attempt to interpret it as a shell script.

Shell scripts may use any of the commands available when the shell is running interactively and may themselves call other scripts. RDFox will treat anything between a # character and the end of the containing line as a comment.

16.2.5. Error Handling¶

It is possible to control how the shell behaves when errors are encountered. When a command results in an error, the details of the error are printed and execution of the command is aborted. The on-error variable controls what happens next. If the on-error policy says that shell execution should continue, then control moves to the next line if a script is being executed or returns to the command prompt if not. If the on-error policy says that execution should stop, then the remaining commands in the script are skipped if a script is being executed or the process exits with a non-zero return code if not.

When several levels of script execution are used, with one script invoking another and so on, it may be desirable for errors at the lowest level to cause the entire process to exit or for the effect of the error to be limited to just the level in which it occurs or to one of the intermediate levels. The RDFox shell supports this by creating a new scope for the on-error variable at each level of script execution. This ensures that modifications to the on-error variable last only for the duration of the given script execution. When a subordinate level of execution is aborted due its on-error policy, the on-error policy of the calling level is consulted to determine whether the error should stop execution there too. This continues right up to the top level where, as always, an error that stops execution causes the process to exit with a non-zero return code.

RDFox recognises three distinct on-error policies:

setting value continue ensures that execution continues on any error
setting value continue-if-exists ensures that execution stops on any error other than those which are due to attempts to create resources that already exist
setting value stop ensures that execution stops on any error.

The continue-if-exists policy is useful in scripts for initializing servers in automated deployments. In these cases it is important that the process should terminate with an error code if any of the commands in the script fails so that the calling process knows not to proceed with the subsequent steps of the deployment. For this reason the policy continue is unsuitable. At the same time, it is often the case that the script may be executed several times on the same server even if it has run successfully in the past. This means that the policy stop is also unsuitable since RDFox treats attempts to create resources that already exist as an error. The continue-if-exists policy achieves the desired behaviour of continuing if an error occurs because an attempt was made to create a resource with a name that is already in use, but stopping on any other error.

Note

The class of error tolerated by the continue-if-exists policy indicates only that an attempt to create an instance of a resource that must have a unique name failed because the chosen name was already in use. It is important to be aware that RDFox does not check that the other properties of the existing resource are the same as those of the instance that would have been created.

For example, imagine a script for initializing a server which contains the following command.

dstore create recipes type par-complex-nn

The script may safely be re-run in continue-if-exists mode since the error raised by RDFox when the above command is re-executed will not cause execution to stop. If at a later date, the number of resources that the data store needs to accommodate grows beyond the capacity of a par-complex-nn store (see Section 8.2.12), the above line may be replaced with the following.

dstore create recipes type par-complex-wn

Simply re-running the script against the server after this change would not be sufficient to change the type of the data store irrespective of the on-error setting but doing so under continue-if-exists will now mask a real problem — the data store not being of the intended type — instead of simply allowing execution to continue after an expected name clash. The shell does not provide a way to execute commands conditionally so, in situations such as these, additional manual intervention will be needed.