Warning: This document is for an old version of RDFox.

15. 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).

15.1. Starting the RDFox Process

The RDFox process can be started using the following command:

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

All variants of this command create a single RDFox 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 the documentation of the endpoint shell command (Section 15.2.2.14). Note that, when specified on the command line, endpoint option names must not include the prefix endpoint. that is used in the names of the corresponding shell variables. 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 15.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 and logs on to the shell with a temporary role (random name and password) which will be deleted when the shell closes. 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.

15.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.

The commands available within the shell fall into three broad categories: commands controlling behavior of the shell itself, commands addressing the process’s RDFox server and commands addressing one of the server’s data stores. To determine which data store is addressed by commands in the last category, the shell maintains the variable active which stores the name of the data store to be addressed. At startup, this variable is initialized to the name default after which it can be changed using the active command.

Note

The shell does not validate that the new value for the active variable matches the name of an existing data store. Commands that depend on this variable print a warning if at run-time the server does not contain a data store with the specified name.

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 (Section 15.2.3), 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 15.2.2.34).

15.2.1. 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.

15.2.2. Shell Commands

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

15.2.2.1. active

Syntax:

active [<name>]

Description: If <name> is omitted, this command prints the name of the active data store; otherwise, it sets the active data store name to <name>. Note that setting the active data store name does not create the data store with that name: the data store should still be initialized or loaded before it can be used.

15.2.2.2. answer

Syntax:

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

Description: This command evaluates one or more SELECT, ASK, or CONSTRUCT 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. 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 }

15.2.2.3. ask

Syntax:

ask <remaining_query_text>

Description: This command queries the current data store (against all IDB facts) 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 seq
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 }

15.2.2.4. begin

Syntax:

begin [interruptible-read | read | write]

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

15.2.2.5. 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 IDB fact domain into the EDB 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 par-complex-nn
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>]

15.2.2.6. commit

Syntax:

commit

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

15.2.2.7. 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.

15.2.2.8. construct

Syntax:

construct <remaining_query_text>

Description: This command queries the current data store (against all IDB facts) with the specified SPARQL CONSTRUCT query. The resulting triples are stored using the Turtle format.

15.2.2.9. daemon

Syntax:

daemon

Description: This command switches RDFox into daemon mode by first ensuring that the endpoint is listening and then closing the shell. Commands appearing after this command in an RDFox shell script will not be run.

15.2.2.10. delete

Syntax:

delete <remaining_query_text>

Description: This command can be used to remove EDB 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 }

15.2.2.11. dsource

Syntax:

dsource list | show <dsname> | register <type> <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 of type <type> and with name <dsname>. Information about the data source is specified by the key-value pairs in <parameters>.

  • 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>.

Section 10 describes in more detail on how data sources are imported and used in RDFox.

15.2.2.12. dstore

Syntax:

dstore list | create <name> [<type> [<parameterKey> <parameterValue>]*] | load <name> <filename> [<type> [<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 specify the data store type using the <type> parameter. See Section 8.2 for the list of supported types. The default is par-complex-nn. In addition to the type, one can also optionally specify various data store parameters as a list of key-value pairs; see Section 8.3 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.

15.2.2.13. 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.

15.2.2.14. endpoint

Syntax:

endpoint (start | stop)

Description: This command starts or stops the RDFox endpoint. The endpoint provides REST access to the process’s RDFox server and also serves the RDFox Console. Since the endpoint accesses the same server that is accessible through the command line, the results of any commands that affect the state of the server (e.g., dstore create) will be immediately visible on the endpoint. For a description of the RESTful API available when the endpoint is started, see Section 13.

The configuration of the endpoint is determined by the following shell variables.

  • endpoint.port determines the port at which the endpoint is started. The port be specified as a verbatim port number or as a TCP service name. The default is 12110. For legacy reasons, the port can also be specified using endpoint.service-name; moreover, if both options are present, then endpoint.port takes precedence.

  • endpoint.num-threads determines the number of threads that endpoint will use to process RESTful requests. The default value is one less than the number of logical processors of the machine on which RDFox is run.

  • endpoint.channel determines the connection type that the endpoint should use.

    • unsecure means the endpoint will use the unsecured HTTP connection. This is the default value.

    • ssl means the endpoint will use SSL/TLS using the platform’s native secure communication package. On macOS this is Secure Transport, and on Linux and Windows this is openSSL.

    • open-ssl means the endpoint will use SSL/TLS implemented using the openSSL package. This option is available on all platforms.

    • secure-transport means the endpoint will use SSL/TLS implemented using the Secure Transport library. This option is available only on macOS 10.8 or later.

  • The following parameters determine the configuration of the SSL/TLS connections, such as the server certificate and private key, as well as intermediate certificates.

    • endpoint.credentials specifies the server certificate and private key, and the intermediate certificates as a verbatim string in PEM format. The string must contain the server’s private key, the server’s certificate, and zero or more intermediate certificates. For example, this file could look as follows:

      -----BEGIN RSA PRIVATE KEY-----
... server key ...
-----END RSA PRIVATE KEY-----
-----BEGIN CERTIFICATE-----
... server certificate ...
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
... 1st intermediate certificate ...
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
... 2st intermediate certificate ...
-----END CERTIFICATE-----

    • endpoint.credentials-file specifies the name of the file whose content contains the credentials. The file content must have the same format as the endpoint.credentials parameters.

    • endpoint.credentials-name specifies the comma-separated list of names of items in the system’s keystore. The first name must identify a certificate and a private key, which are used as a main identity of the server. The remaining names identify intermediate certificates. This option is available only on macOS, where the keystore is the system’s keychain.

    • endpoint.credentials-passphrase provides the passphrase that can be used to unlock the credentials in case they are encrypted. This parameter is optional.

    • endpoint.min-secure-protocol determines the minimum protocol version that the server should use. The allowed values are ssl2, ssl3, tls1, tls11, tls12, and tls13. The default value is tls12.

  • endpoint.listening-backlog determines the TCP listening backlog for the socket accepting the connection. The default value is 10.

  • endpoint.receive-buffer and endpoint.send-buffer determine the sizes in bytes of the receive and send buffers for the sockets servicing the requests. The default values are zero, which means that the system will determine the buffer sizes depending on the properties of the connection. For more information, please refer to the SO_RCVBUF and SO_SNDBUF socket options.

  • endpoint.sweep-period and endpoint.sweeps-to-reclaim govern the reclamation of unused objects. During its operation, the endpoint retains certain objects between requests either for performance reasons (e.g., the endpoint may cache cursors of partially evaluated queries) or to ensure its operation (e.g., the endpoint will maintain objects associated with transactions). In order to prevent these objects from accumulating, every endpoint.sweep-period seconds the endpoint will sweep through all retained objects, and it will delete all objects (including transactions) that have not been used in the last endpoint.sweeps-to-reclaim sweeps. The default values for these parameters are 60 and 5, respectively.

  • endpoint.access-control-allow-origin configures the RDFox endpoint to include the Access-Control-Allow-Origin header in responses with the specified origin. If unset (the default), the header is omitted.

  • endpoint.protocol determines which network layer protocol the endpoint will use.

    • IPv4 means the endpoint will use Internet Protocol version 4.

    • IPv6 means the endpoint will use Internet Procotol version 6.

    • IPv6-v4 means the endpoint will use Internet Protocol version 6 if possible or Internet Protocol version 4 if not. This is the default value.

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

set endpoint.port "4567"
endpoint start

15.2.2.15. 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 seq
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

15.2.2.16. explain

Syntax:

explain [shortest] [<max_depth> [<max_rule_inst>]] <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, and by default all possible derivations will be printed. 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. Finally, <max_depth> can be specified to limit the maximal depth of a proof tree, and <max_rule_inst> 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 seq
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.

15.2.2.17. 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. At present, only the application/n-triples, text/turtle, application/n-quads, and application/trig formats support parameters; moreover, the only supported parameter is fact-domain, and its value is the fact domain determining which facts get exported. The default format is text/turtle with parameter fact-domain equal to EDB. 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.

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 these cases the supported parameter is axiom-domain or rule-domain, respectively, and the value is the domain that will be output, defaulting to the user axiom domain (4.5) or user rule domain (4.6).

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 IDB

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" axiom-domain triples

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"

15.2.2.18. 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

15.2.2.19. 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.

15.2.2.20. import

Syntax:

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

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 group the items to import in one or more files and simply pass the filename(s) as argument(s) here. RDFox supports importing triples and rules in N-Triple, Turtle, N-Quad, TriG, OWL 2 Functional-Style Syntax and Datalog formats. Note that, in addition to OWL 2 Functional-Style syntax documents, OWL 2 axioms may be imported from files in one of the four RDF triple formats if the owl-in-rdf-support option is set to relaxed or strict (See Section 8.3.10 ). 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 <filename> 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. <filename> may be quoted &mdash; that is, surrounded with single-quotes or double-quotes, if required, for example to support filenames containing spaces.

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 .

15.2.2.21. 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.

15.2.2.22. insert

Syntax:

insert <remaining_query_text>

Description: This command adds EDB 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 }

15.2.2.23. 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.

15.2.2.24. 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 commands starts a transaction, imports facts from the testData.ttl file, imports rules from the testProgram.dlog file, and them 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 seq
begin
import "testData.ttl"
import "testProgram.dlog"
mat
import - "factsToDelete.ttl"
mat
commit

15.2.2.25. password

Syntax:

password

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

15.2.2.26. 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 }

15.2.2.27. quit

Syntax:

quit

Description: This command terminates the RDFox instance.

15.2.2.28. 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.

15.2.2.29. 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

15.2.2.30. role

Syntax:

role [list | show <role> | switch <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 switch switches the currently active role to <role> subject to successful authentication.

  • 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 13.12.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.

15.2.2.31. rollback

Syntax:

rollback

Description: This command rolls back the currently running transaction.

15.2.2.32. 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.

15.2.2.33. select

Syntax:

select <remaining_query_text>

Description: This command queries the current data store (against all IDB facts) with the specified SPARQL query.

Example: The following commands load a data and 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 seq
import "LUBM.ttl" "LUBM.dlog"
set output "results.txt"
SELECT ?X WHERE { ?X rdf:type <http://lehigh.edu/onto/univ-bench.owl#Org> }

15.2.2.34. 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 15.2.3 for details of the available variables.

15.2.2.35. sleep

Syntax:

sleep <milliseconds>

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

15.2.2.36. 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-stats option is set to true, then statistics will be updated automatically whenever the number of facts in the system changes by more than 10%.

15.2.2.37. 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.

15.2.2.38. 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

15.2.2.39. 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.

15.2.2.40. 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"

15.2.2.41. 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' }

15.2.3. Shell Variables

Shell variables are set by invoking the set command (see Section 15.2.2.34). Variables that are initially set after starting RDFox, their default values, and a summary of each is 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

default

Contains the name of the active data store.

dir.dlog

./

Determines the directory for resolving relative file names of datalog programs.

dir.facts

./

Determines the directory for resolving relative file names of RDF files.

dir.output

./

Determines the directory for resolving relative file names of output files (as specified by the output variable).

dir.queries

./

Determines the directory for resolving relative file names of query files.

dir.root

./

Determines the root directory of the current data set.

dir.scripts

./

Determines the directory for resolving relative file names of script files.

dir.stores

./

Determines the directory for resolving relative file names of binary store files.

import.format

""

Determines the format that will be parsed by the import command.

log-frequency

0

Determines the time in seconds during which various logs are produced (see note below table).

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

IDB

Determines the fact domain of the matched tuples: EDB matches the explicitly stated tuples; IDB matches all tuples; IDBrep matches the nonmerged tuples; IDBrepNoEDB matches the nonmerged tuples that are not EDBs.

query.monitor

off

Determines whether and how query evaluation is monitored: off (no monitoring), stats (gather 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), and trace (print reasoning trace).

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 15.2.2.14.

  • 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 13.9.2, and text/turtle in the case of queries over exactly three variables called ?S, ?P, and ?O.