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

10. Shell Commands and Variables

This section describes the shell interface of RDFox.

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

The shell of RDFox maintains a number of shell variables that can have string, signed integer, or Boolean values. A shell variable called var can be used in commands in the form $(var). Shell variables can be set using the set command.

In the following sections, we describe each of the commands and variables available in the RDFox shell.

10.1. Shell Commands

The RDFox process can be started using the following command:

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

The command daemon starts the REST endpoint parameterized using the the specified key-value pairs. Commands shell and sandbox both start an RDFox instance, set the dir.root shell variable to <root>, run all supplied commands, and launch the shell that allows executing further commands.

By default sandbox sets all persistence-related options (see below) to off, whereas shell and daemon set them to file. These defaults may be overridden by explicitly specifying the appropriate option on the command line.

If a role name and password are required, either to initialize access control or to log into the shell, RDFox will first look for the arguments -role <role> and -password <password>. If one or both of these options are missing, RDFox will next inspect the RDFOX_ROLE and RDFOX_PASSWORD environment variables. If after this one or both of these variables remains unset, the behavior will be as follows: - command shell will prompt for the missing information - command sandbox will use the value guest to fill in the blanks - command daemon will terminate.

The RDFox instance can additionally be configured using zero or more server options, each of which is specified as a key-value pair of the form -<option> <value>. The following options are currently supported

Option

Value

Description

-log-calls

true or false

If the value is true, all API calls are recorded in a script called ‘RDFox-Log.txt’ that the shell can replay later. This is can be useful for trouble-shooting.

-max-memory

an integer

Specifies the maximum of memory (in MB) that the RDFox instance is allowed to use.

-num-threads

an integer

Specifies the number of threads that the system will use for tasks such as reasoning and importation. The default is the number of logical processors available on the machine.

-license-content

a string

Specifies the license content verbatim as the parameter to the system.

-license-file

a string

Specifies the path to the license file to use.

-server-directory

a string

Specifies the path where server configuration files are stored.

-persist-roles

file or off

If the value is file, RDFox will persist roles, their privileges, and their memberships to a file in the server directory.

-persist-ds

file or off

If the value is file, data stores and their content with be incrementally saved (persisted) to files in the server directory. Must be off if -persist-roles is off.

Many RDFox commands accept a file name as input. Absolute file names (e.g.., file names starting with / on Unix-based platforms) are interpreted as they are. In contrast, relative file names are resolved using the following RDFox shell variables:

  • dir.root is the value of <root directory>,

  • dir.dlog is used for files containing datalog programs,

  • dir.facts is used for files containing RDF files,

  • dir.output is used for output files,

  • dir.queries is used for query files,

  • dir.scripts is used for script files, and

  • dir.stores is used for binary store files.

The simplest way to change the root is using the root command (see Section 10.1.32), which sets all of the above variables to the supplied value. Individual variables can be set using the set command (see Section 10.1.35).

Example: The following commands set the root and then ensure that Datalog and RDF files are found in dlog and facts subdirectories of the root, respectively.

root MyRoot
set dir.dlog "$(dir.root)/dlog/"
set dir.facts "$(dir.root)/facts/"

When an RDFox instance is started, it creates an empty server that is not exposed via a RESTful endpoint. All commands operate on a single data store of this server. It is common to apply a sequence of commands to one data store, so specifying a data store name in each command would be very inconvenient. Therefore, the shell maintains the name of an active data store, to which all commands are applied. The default data store is called default, and it can be changed using the active command. As an example, the following sequence of commands initialize two data stores, one with name default and one with name store1.

dstore create par-complex-nn
active store1
dstore create par-complex-ww

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

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

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

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

10.1.5. clear

Syntax:

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

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.

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>]

10.1.6. commit

Syntax:

commit

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

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

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

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

10.1.10. dsource

Syntax:

dsource list | show <dsname> | add <type> <dsname> <parameters> | sample <dsname> <table> [<size>] | drop <dsname> | attach <IRI> <dsname> <parameters>

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.

  • Option list prints the currently available data sources.

  • Option show shows information about the data source with name <dsname>.

  • Option add adds 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 number <table> of data source <dsname>.

  • Option drop deletes a data source with name <dsname>.

  • Option attach attaches a tuple table with name <IRI> from a data source with name <dsname> as specified by <parameters>. This is an abbreviation for tupletable add <IRI> <parameters>, where key-value pair dataSourceName = <dsname> is added implicitly (i.e., it does not need to be specified on the command line).

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

10.1.11. dstore

Syntax:

dstore list | create <name> <type> [<parameterKey> <parameterValue>]* | delete <name>

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> and type <type>. See Section 6.2.1 for the list of supported types. The various options of a data store may be specified using a possibly empty list of key-value pairs; see Section 6.2.2 for the list of supported options.

  • Option delete deletes the data store with name <name> from the server.

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

10.1.13. endpoint

Syntax:

endpoint (start | stop)

Description: This command starts/stops the RESTful endpoint that provides access to the server created by the shell. The endpoint will access the same server that is accessible through the command line; thus, the results of any commands that affect the state of the server (e.g., dstore create) will be immediately visible on the endpoint. 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 tls1.

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

  • endpoint.fiber-stack-size determines the stack size for the fibers used by the endpoint to service the requests. The default value is 1 MB and should be sufficient for most cases.

  • 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

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

10.1.15. 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>]

10.1.16. 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 (6.3) or user rule domain (6.4).

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"

10.1.17. 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 9.1.2.1.

  • Option role grants membership of the role with name <super-role> to the role with name <role>. See Section 9.2.5 for more information about role membership.

Section 9 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

10.1.18. help

Syntax:

help [<command_name>]

Description: When executed without arguments, this command prints the list of all available commands. When executed with one or more commands, help information about each of the specified commands will be printed.

10.1.19. import

Syntax:

import [+|-] (! <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, 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 three RDF triple formats if the owl-in-rdf-support option is set to relaxed or strict (See Section 6.2.2.10 ).

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, i.e. 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 current data store.

import ! a1:Person[a1:john] .

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

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

10.1.22. load

Syntax:

load <filename> [<type> [<parameterKey> <parameterValue>]*]"

Description: This commands load creates a new data store using the content of the specified file. The name of the newly created data store is determined using the active shell variable. 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).

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

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

10.1.25. password

Syntax:

password

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

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

10.1.27. quit

Syntax:

quit

Description: This command terminates the RDFox instance.

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

10.1.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 9.1.2.1.

  • Option role revokes membership of the role with name <super-role> from the role <role>. See Section 9.2.5 for more information about role membership.

Section 9 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

10.1.30. role

Syntax:

role [list | show <role> | switch <role> | create <role> | delete <role>]

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

  • Option delete deletes role <role>.

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

10.1.31. rollback

Syntax:

rollback

Description: This command rolls back the currently running transaction.

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

10.1.33. save

Syntax:

save <filename> [raw]

Description: This command saves the contents of the current data store 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.

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

10.1.35. 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 10.2 for details of the available variables.

10.1.36. sleep

Syntax:

sleep <milliseconds>

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

10.1.37. stats

Syntax:

stats list | show <name> | add <name> <parameters> | drop <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 add adds the statistics with name <name>. Information that governs how the statistics are created is specified by the key-value pairs in <parameters>.

  • Option ‘drop’ deletes the statistics with name <name>.

  • Option ‘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%.

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

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

10.1.40. tupletable

Syntax:

tupletable list | show <IRI> | add <IRI> <parameters> | drop <IRI>

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 add adds a new tuple table with name <IRI>. Information about the tuple table is specified by the key-value pairs in <parameters>.

  • Option ‘drop’ deletes a tuple table with name <IRI>.

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

10.2. Shell Variables

Shell variables are set by invoking the set command (see Section 10.1.35). 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.

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 non-merged tuples; IDBrepNoEDB matches the non-merged 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 10.1.13.

  • It can be useful to set the log-frequency variable to a non-zero 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 8.9.2, and text/turtle in the case of queries over exactly three variables called ?S, ?P, and ?O.