AGquery: command-line query tool

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. A change from earlier releases is the -username option, is now the --user option and -u can be used as an abbreviation.)

Usage

agtool query [OPTIONS] DBNAME [QUERY-FILE]*

The arguments are:

DBNAME: the AllegroGraph triple store name
QUERY-FILE: zero or more files or directories containing SPARQL queries; If a directory is specified, all of the files in it will be processed. Use - for standard input.

Options

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

Connection options
Triple-store options
Query options
Reporting options
Other options

Connection options

-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 triple-store; use with --password (default username).
--password PASSWORD: password for the triple-store; use with --user (default password).
--server SERVER: server where the triple-store lives (if unspecified, this argument is ignored). This allows you to query a remote triple-store.

Triple-store options

-m MODE, --mode MODE

the reasoning mode. The choices are:

rdfs           RDFS++  
restriction    restriction

-o LEVEL, --optimize LEVEL

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

--specification SPECIFICATION

triple-store specification for a remote-triple-store (if unspecified, this argument is ignored). See Session specifications in AGWebView.

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

--engine ENGINE

Name of the query engine to use (default default). Choices are:

sparql-1.1, sbqe, set-based    Use the set based engine  
default                        Use the default engine

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

--results-format FORMAT

output format used by the query engine (default table). Choices are:

arrays          arrays  
strings         strings  
lists           lists  
sparql-xml      sparql-xml  
count           count  
count-cursor    determine the count using a cursor  
table           table

--title TITLE

Value to use for the report title.

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

--answer-file ANSWER-FILE

provide answers for the queries you are running, in order to verify results.

--log FILENAME

Save results to log.

--profile STYLE

Profile queries. Styles include:

time     profile time  
space    profile space  
count    count calls (and profile time)

--profile-file FILENAME

Send profile report to this file (use standard output if unspecified).

--quiet

Reduce output (default no).

--seed RANDOM-SEED

Specify an initial random seed.

--setup FILENAME

Run code before starting queries.

--spogi YES-OR-NO

Turn the SPOGI cache on or off (default yes).

--squeeze-memory

Squeeze / release memory before each query.

--summary-only YES-OR-NO

Report only the summary.

--teardown FILENAME

Run code before exiting.

-v, --verbose

Include more output.

--warmup

Calls warmup-triple-store before querying if specified.

Examples:

A typical call using the lubm50 database and associated queries.

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

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

agtool query --results-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

The agquery command-line query tool