Execute Queries Using the CGE query Command

Describes how to use the query command to execute multiple queries simultaneously. Also includes the purpose, syntax, output and examples of using the CGE query command

The query command is used to execute queries against the running database. This command can be used to execute a single query or a sequence of queries.

Queries that need to be executed may be specified in a number of ways:

By providing a list of files, which contain lists of files containing queries to be executed
By providing the names of query files directly
Via stdin (only if no queries are specified in other ways and the --non-interactive option is not used)

The supported input methods have the precedence shown in the list above. This means that if any list files are specified, those queries are executed before any directly specified queries. This command may only be used to execute SPARQL queries. To execute updates, use the update command or to execute mixtures of queries and updates use the sparql command.

An example of using the query command is shown below:

$ cge-cli query --list queries.txt extra-query.rq

The above command will execute all the queries specified in the queries.txt file before executing the query specified in the extra-query.rq file. Executing queries by default produces only information about where to obtain the results and not the result itself.

An example of using the query command is shown below:

$ cge-cli query types.rq
0   28  1756    0   file:///lus/scratch/rvesse/results/queryResults.2016-06-13T13.47.22Z000.28889.tsv

Here we can see that the database returns a simple tab separated string with the following fields:

Table 1. query Command's Output Description
Column Index	Information
0	Status - will be 0 for successful queries
1	Result count - number of results returned
2	Result size - results size in bytes
3	Execution time - query execution time in seconds
4	Results location - path to the file containing the results
5	Error message - should be blank for successful queries

Results File Format

The file containing the results is in SPARQL Results TSV format and contains only the tabular results for the query. This means that if an ASK/CONSTRUCT/DESCRIBE query has been created, the results file will not contain the final results.

Printing Results

This simple format makes it easy to process with standard command line tools. For example, the following command can be used to display the results in the console:

$ cge-cli query --quiet types.rq | cut -d$'\t' -f 5 | xargs cat

As noted earlier, the results file contains only the tabular results for the query. If results of an ASK/CONSTRUCT/DESCRIBE query are desired to be printed, see the 'Streaming Results' section below.

Streaming Results

As already seen, it is possible to use simple command line tools to extract and dump the query results to stdout. However, this only works for SELECT queries, and when the results can be accepted in SPARQL Results TSV format. Use the --stream option of the query command if it is desired to retrieve the final results in an arbitrary format. This option may only be used when executing a single query and it takes the MIME type of the desired results format.

$ cge-cli query --stream application/sparql-results+xml types.rq

Results are returned in SPARQL Results XML format. Supported formats include the following:

Table 2. Output Result Formats
Query Types	MIME Types	Output Format
ASK and SELECT	`application/sparql-results+xm`l	SPARQL Results XML
	`application/sparql-results+json`	SPARQL Results JSON
	`text/csv`	SPARQL Results CSV
	`text/tab-separated-values`	SPARQL Results TSV
CONSTRUCT and DESCRIBE	`application/n-triples`	NTriples
	`text/turtle`	Turtle
	`application/rdf+xml`	RDF/XML
	`application/rdf+json`	RDF/JSON
	`application/ld+json`	JSON-LD

CAUTION: Requesting a format that does not match the query type or is unknown will result in an error.

There are also three special values that may be passed to this option:

text
json
xml

When these values are specified, the CLI will automatically select an appropriate text (line-based), JSON or XML output format in which to stream the results, while taking into account the type of query being evaluated. For example providing --stream text might produce SPARQL results TSV for an ASK/SELECT query but produce NTriples for a CONSTRUCT/DESCRIBE query. When these special values are used, the exact output format will not be known in advance but will be guaranteed to fall into the general format given.

Execution of Multiple Queries

When multiple queries are executed, they are executed in the order specified (subject to the aforementioned precedence of list files over individual files) and the command will print a results header for each query.

$ cge-cli query types.rq list-graphs.rq ask-types.rq

A results header is retrieved for each query run.

For more information, see the cge-cli-query(1) man page