Introduction

agtool query is a command-line query tool. It dispatches queries to the AllegroGraph server and receives the results. The results are the same as sending queries using, say, AGWebView (see WebView).

The agtool program is the general program for AllegroGraph command-line operations. (In earlier releases, there was a separate agquery program.)

Usage

agtool query [OPTIONS] REPO-SPEC [QUERY-FILE]*

The arguments are:

REPO-SPEC
The repository specification identifying the repository to be queried. REPO-SPECs can not only identify specific repositories but also SPARQL endpoints (e.g. http://dbpedia.org/sparql) and more complex repository combinations such as federated repos and repos with reasoning.
QUERY-FILE
Zero or more files or directories containing queries; files with rq/rqr extensions will be interpreted as SPARQL queries, files with txt extension - as Prolog queries. Files with other extensions or no extension will be skipped with warnings. If a directory is specified, all of the files in it will be processed. Use - to read a query from standard-input (default query language is used; see --language).

Options

There are many options. For convenience, we break them into several categories:

Triple-store options

-o LEVEL, --optimize LEVEL
Optimize repository indices (default 0) as soon as the store is opened. Possible values are 0, 1, and 2. See optimize-indices][].
--with-indices INDICES

Specify the indices of the triple-store. The parameter should be a list of index names separated by spaces. When multiple names separated by spaces are specified, the spaces must be escaped or the whole specification can be quoted, like "spogi posgi ospgi".

If not specified, newly created triple-stores will use the standard set of indices and existing triple-stores will retain their current indices. If specified, the current indices are dropped and the newly specified ones are used.

Query options

-i ITERATIONS, --iterations ITERATIONS
Run entire batch (default 1).
--option NAME=VALUE
Specify options, which will be used when running the queries, just like normal SPARQL prefixes. See SPARQL query options.
-r REPETITIONS, --repetitions REPETITIONS
Run each query this many times per iteration (default 1).
--output-format FORMAT
output format used by the query engine (default :table). Available formats are listed along with SPARQL verbs that support them. 
alists              ASK, CONSTRUCT, SELECT  
arrays              CONSTRUCT, DESCRIBE, SELECT, UPDATE  
boolean             ASK, UPDATE  
count               ASK, CONSTRUCT, DESCRIBE, SELECT  
count-cursor        determine the count using a cursor  
in-memory           CONSTRUCT, DESCRIBE  
lists               ASK, CONSTRUCT, DESCRIBE, SELECT, UPDATE  
nquads              CONSTRUCT, DESCRIBE  
ntriples            CONSTRUCT, DESCRIBE  
ntriples-ascii      CONSTRUCT, DESCRIBE  
processed-csv       SELECT  
quads               DESCRIBE  
rdf-n3              CONSTRUCT, DESCRIBE  
rdf/xml             CONSTRUCT, DESCRIBE  
simple-csv          SELECT  
sparql-csv          SELECT  
sparql-csv-rows     SELECT  
sparql-json         ASK, SELECT, UPDATE  
sparql-json-rows    SELECT  
sparql-tsv          SELECT  
sparql-tsv-rows     SELECT  
sparql-ttl          ASK, SELECT, UPDATE  
sparql-xml          ASK, SELECT, UPDATE  
sparql-xml-rows     SELECT  
table               ASK, CONSTRUCT, DESCRIBE, SELECT, UPDATE  
trig                CONSTRUCT, DESCRIBE  
triples             CONSTRUCT, DESCRIBE  
trix                CONSTRUCT, DESCRIBE  
turtle              CONSTRUCT, DESCRIBE
--title TITLE
Value to use for the report title.
--language LANGUAGE
The query language. (default: sparql). Choices are sparql (meaning SPARQL) and select (meaning Prolog select).
--plan
Display a representation of the query plan and then stop.

Reporting options

--baseline FILENAME
Log file to use as a reporting baseline.
--measure MEASURE
What to measure (e.g., time, space). Choices include: 
Choice     What it measures  
------     ----------------  
time       time  
user       user time  
system     system time  
space      cons cells  
minor      minor page faults  
major      major page faults
--report-format FORMAT
Output format for generated reports (default text). Choices are 
Choice  Format  
------  ------  
text    text  
csv     comma-separated value

Other options

--results-format
old name for --output-format. Still works but use will generate a deprecation warning.
--answer-file ANSWER-FILE
provide answers for the queries you are running, in order to verify results.
--log FILENAME
Save results to log.
--quiet
Reduce output (default off, turn on by specifying --quiet). When specified, there will be less output and in particular logging information will be writen to the agquery.log file rather than to the output, which will therefore be results only. Here is an example using the kennedy.ntriples example file. We have this query in the file kenn.rq: 
SELECT ?s ?p  { ?s ?p <http://www.franz.com/simple#Harvard> . }  
LIMIT 2

We run with --quiet unspecified (so output is not quiet): 

% agtool query --output-format sparql-tsv kennedy kenn.rq  
2020-10-02T14:22:44| preparing SPARQL query from file /disk1/dm/kenn.rq  
kenn  
?s	?p  
<http://www.franz.com/simple#person47>	<http://www.franz.com/simple#alma-mater>  
<http://www.franz.com/simple#person42>	<http://www.franz.com/simple#alma-mater>  
 
Query information:  
  time      : output: 0.002864, overall: 0.093739, parse: 0.001000, plan: 0.023250, query: 0.006297, system: 0.005060, total: 0.033411, user: 0.047469  
  memory    : consCells: 2994464, majorPageFaults: 0, maximumChunk: 2800000, maximumMap: 2958368, minorPageFaults: 4524  
  other     : generation: 2, info: "bindings-set", rowCount: 2

And we run with --quiet: 

% agtool query --quiet --output-format sparql-tsv kennedy kenn.rq  
?s	?p  
<http://www.franz.com/simple#person47>	<http://www.franz.com/simple#alma-mater>  
<http://www.franz.com/simple#person42>	<http://www.franz.com/simple#alma-mater>
--standard-namespaces YES-OR-NO
Include standard namespace definitions in queries. Default is yes. If specified no then the AllegroGraph set of standard namespace PREFIX definitions will not be prepended to the text of query. Furthermore if the query is going to an AllegroGraph repository that agtool will open itself then the set of namespaces known to AllegroGraph is cleared before the query is run.
--spogi YES-OR-NO
Turn the SPOGI cache on or off (default yes).
-v, --verbose
Include more output.
--warmup
Calls warmup-triple-store before querying if specified.

Connection options (deprecated)

All the information that can be specified by these options can be specified in the REPO-SPEC argument. Use of these options is deprecated but they are still supported for backward compatibility. REPO-SPECs are described in the Repsoitory Specification document.

-p PORT, --port PORT
Server port (default 10035).
-c CATALOG, --catalog CATALOG
CATALOG name on server; use "" or leave unspecified for the root catalog (the default is the root catalog). Note: the root catalog has no name. Specifying "root" will not be interpreted as the root catalog.
-u USERNAME, --user USERNAME
Username for the server; use with --password.
--password PASSWORD
The password for USERNAME.
--server SERVER
Server where the triple-store lives (if unspecified, this argument is ignored). This allows you to query a remote triple-store.

The agtool query-options command

agtool query-options REPO OPTIONS-LIST

make the options in OPTIONS-LIST query options for any repo/user pair (the user muct be specified in the REPO spec). See [query-options](agtool.html#query-options] in the agtool document.

Examples:

A typical call using the lubm50 repository and associated queries. 

agtool query --catalog stores lubm-50 /queries/lubm-50/*.rq

Another example would be the following which uses a book repository. Note we get the query from standard input. 

agtool query --output-format count sp2b-1e4 - <<EOF  
PREFIX rdf:     <http://www.w3.org/1999/02/22-rdf-syntax-ns#>  
PREFIX rdfs:    <http://www.w3.org/2000/01/rdf-schema#>  
PREFIX swrc:    <http://swrc.ontoware.org/ontology#>  
PREFIX foaf:    <http://xmlns.com/foaf/0.1/>  
PREFIX bench:   <http://localhost/vocabulary/bench/>  
PREFIX dc:      <http://purl.org/dc/elements/1.1/>  
PREFIX dcterms: <http://purl.org/dc/terms/>  
 
SELECT ?inproc ?author ?booktitle ?title  
       ?proc ?ee ?page ?url ?yr ?abstract  
WHERE {  
  ?inproc rdf:type bench:Inproceedings .  
  ?inproc dc:creator ?author .  
  ?inproc bench:booktitle ?booktitle .  
  ?inproc dc:title ?title .  
  ?inproc dcterms:partOf ?proc .  
  ?inproc rdfs:seeAlso ?ee .  
  ?inproc swrc:pages ?page .  
  ?inproc foaf:homepage ?url .  
  ?inproc dcterms:issued ?yr  
  OPTIONAL {  
    ?inproc bench:abstract ?abstract  
  }  
}  
ORDER BY ?yr  
EOF

It returns: 

   147   0.364