Querying a Federation via the HeFQUIN Command-Line Programs

HeFQUIN comes with several command-line programs, including two programs to run queries over a federation. One of them, called hefquin-client, provides this functionality through interacting with a HeFQUIN service. The other one, simply called hefquin, uses an instance of the HeFQUIN engine created directly within this program and, thus, can be used without starting up a HeFQUIN service in a separate process. The latter may be your first choice if you simply want to try HeFQUIN, or for experimentation and testing purposes, whereas the HeFQUIN client-server combination should be the preferred choice if you want to run multiple queries, because it avoids initializing the engine for every single query.

You can use the hefquin program as follows, assuming the file MyFedConf.ttl contains the description of your federation and the file ExampleQuery.rq contains the query that you want to run over this federation, and assuming that you have added the HeFQUIN programs to your PATH (otherwise, enter the directory in which you have unpacked the HeFQUIN release and replace hefquin by bin/hefquin).

hefquin --fd MyFedConf.ttl --query ExampleQuery.rq

Similarly, the hefquin-client program can be used by issuing the following command, assuming that the HeFQUIN service you want interact with is available at the address http://localhost:8080/, and assuming again that you have added the HeFQUIN programs to your PATH (otherwise, enter the directory in which you have unpacked the HeFQUIN release and replace hefquin-client by bin/hefquin-client). In this case, the given query (in ExampleQuery.rq) will be executed over the federation for which the service is set up.

hefquin-client --server http://localhost:8080/ --query ExampleQuery.rq

Further arguments can be passed to both programs, which are described in detail below. You can also have the list of supported arguments printed by executing the programs with the argument --help.

hefquin --help

hefquin-client --help

Arguments of Only One of the Programs

--fd=<file> (mandatory argument of the hefquin program)

Refers to a file that contains an RDF-based description of the federation to be queried. The file can be in any RDF serialization format (e.g., Turtle, N-Triples, JSON-LD) and it must use the HeFQUIN Federation Vocabulary. Every instance of type fd:FederationMember described by this document will be considered as a member of the federation to be queried.

This argument may be provided multiple times, which is useful if the federation description is distributed across multiple files (e.g., one file per federation member).

--server=<URI> (mandatory argument of the hefquin-client program)

The address of the HeFQUIN service to be used. This service should be set up using the same version of HeFQUIN as the client program that you are using.

Query-Related Arguments of both Programs

--query=<file> (mandatory argument)

Refers to a file that contains the query to be executed over the federation.

--base=<uri>

This argument can be used to provide a base URI for the query.

--skipExecution

Use this argument if you want HeFQUIN to create the query execution plan for the given query, but without actually executing this plan. This argument would typically be used in combination with arguments for printing the plan in its various stages (--printSourceAssignment, --printLogicalPlan, and --printPhysicalPlan).

Result-Related Arguments of both Programs

--rfmt=<format>

Use this argument to specify the format in which you would like the query result to be printed. The possible values for this argument depend on the type of query. For SELECT queries, the possible values are the following (with TEXT being the default in case the argument is omitted).

TEXT - Simple text output in table form (default).
JSON - Standard JSON format.
XML - Standard XML format.
CSV - Standard CSV format.
TSV - Standard TSV format.
TTL - RDF representation, serialized using the RDF Turtle format.
NTRIPLES - RDF representation, serialized using the N-Triples format.
JSONLD - RDF representation, serialized using the JSON-LD format.
RDF/XML - RDF representation, serialized using the RDF/XML format.
(all RDF representations use the result set vocabulary).

For CONSTRUCT queries, the possible values are the following (with TTL being the default).

TTL - RDF Turtle format (default).
NTRIPLES - N-Triples format.
JSONLD - JSON-LD format.
RDF/XML - RDF/XML format.

--outputToFile=<file>

Use this argument if you want the query result to be written into a file. If this argument is omitted, the result is written to stdout. If the given file already exists, the output is appended to that file (instead of overwriting the file).

--suppressResultPrintout

Use this argument if you want HeFQUIN to execute the query without printing the query result. This argument would typically be used in combination with arguments for measuring query processing times (--time, --printQueryProcMeasurements, and --printQueryProcStats), for which the actual printing of the query result is irrelevant and, in case of the --time argument, may even affect the measurements.

Planning-Related Arguments of both Programs

--printSourceAssignment

Use this argument to instruct the query planning component of HeFQUIN to print the initial logical plan that is the output of the source selection & query decomposition process; i.e., this is the logical plan that is passed as input to the logical query optimizer. If you are interested only in seeing the plan, without executing it, use this argument in combination with the --skipExecution argument.

The plan is printed to stdout. If you want to print it to a file, use the --printSourceAssignmentToFile argument instead.

--printSourceAssignmentToFile=<file>

Like the --printSourceAssignment argument, but prints the plan to the specified file. If the specified file already exists, the output will be appended rather than overwritten.

--printLogicalPlan

Use this argument to instruct the query planning component of HeFQUIN to print the logical plan that is the output of the logical query optimizer; i.e., this is the logical plan that is passed as input to the physical query optimizer. If you are interested only in seeing the plan, without executing it, use this argument in combination with the --skipExecution argument.

The plan is printed to stdout. If you want to print it to a file, use the --printLogicalPlanToFile argument instead.

--printLogicalPlanToFile=<file>

Like the --printLogicalPlan argument, but prints the plan to the specified file. If the specified file already exists, the output will be appended rather than overwritten.

--printPhysicalPlan

Use this argument to instruct the query planning component of HeFQUIN to print the physical plan that is the output of the physical query optimizer; i.e., this is the physical plan that is used to execute the query. If you are interested only in seeing the plan, without executing it, use this argument in combination with the --skipExecution argument.

The plan is printed to stdout. If you want to print it to a file, use the --printPhysicalPlanToFile argument instead.

--printPhysicalPlanToFile=<file>

Like the --printPhysicalPlan argument, but prints the plan to the specified file. If the specified file already exists, the output will be appended rather than overwritten.

Experiments-Related Arguments of both Programs

--printQueryProcMeasurements

Use this argument to instruct the HeFQUIN engine to print one line of comma-separated measurement values for each query. These values are:

the overall query processing time (in ms), which is the sum of the following three measurements;
the query planning time (in ms), which includes source planning, logical optimization, and physical optimization;
the compilation time (in ms), which is about translating the final physical plan into a so-called executable plan that is set up and ready for execution;
the query execution time (in ms), which is the total time from starting the executable plan until completion of the executable plan.

Note that these measurements are purely related to processing that takes place within the HeFQUIN engine; any pre-processing and post-processing performed by the Jena query processing machinery that HeFQUIN uses is not considered for these measurements.

Since these measurements are printed as a single line in which the different values are separated by commas, this argument can be used to produce a CSV file of measurements for multiple queries (or for multiple executions of the same query). For this use case, you may want to use this argument in combination with the --suppressResultPrintout argument.

The measurements are printed to stdout. If you want to print them directly into a file, use the --printQueryProcMeasurementsToFile argument instead.

--printQueryProcMeasurementsToFile=<file>

Like the --printQueryProcMeasurements argument, but prints the plan to the specified file. If the specified file already exists, the output will be appended rather than overwritten.

--printQueryProcStats

Use this argument to instruct the HeFQUIN engine to print detailed statistics about the query planning and the query execution processes, as collected by the different components involved in these processes (including the operators that have been part of the query execution plan).

The statistics are printed to stdout. If you want to print them directly into a file, use the --printQueryProcStatsToFile argument instead.

--printQueryProcStatsToFile=<file>

Like the --printQueryProcStats argument, but prints the plan to the specified file. If the specified file already exists, the output will be appended rather than overwritten.

--printFedAccessStats

Use this argument to instruct the HeFQUIN engine to print detailed statistics collected by the federation access component of HeFQUIN.

The statistics are printed to stdout. If you want to print them directly into a file, use the --printFedAccessStatsToFile argument instead.

--printFedAccessStatsToFile=<file>

Like the --printFedAccessStats argument, but prints the plan to the specified file. If the specified file already exists, the output will be appended rather than overwritten.

--time

Use this argument to print the overall query processing time (in sec), which includes not only the processing within the HeFQUIN engine but also the pre-processing and post-processing performed by the Jena query processing machinery that HeFQUIN uses. To obtain a more detailed breakdown of the times required for the processing stages within the HeFQUIN engine, use the --printQueryProcMeasurements argument instead.

Notice that the time reported when using this argument may be affected by the time required for printing the query result, while the times reported when using the --printQueryProcMeasurements argument are unaffected because query result printing is part of the post-processing. As the mere printing time is irrelevant from the actual query processing perspective, you may want to disable the printing when using this argument, which can be done by adding the --suppressResultPrintout argument.

Other Arguments of both Programs

--confDescr=<file>

Refers to a file that contains an RDF-based description of the configuration to be used for the HeFQUIN engine and its components. The file can be in any RDF serialization format (e.g., Turtle, N-Triples, JSON-LD), it must use the HeFQUIN Configuration Vocabulary, and contain exactly one instance of type ec:HeFQUINEngineConfiguration. This argument is relevant primarily during development and for conducting experiments with different internal components.

--help

If this argument is given, the program prints a list of all supported arguments and terminates (i.e., all other given arguments are ignored).