The iquery executable is the basic command-line tool for communicating with SciDB. Use iquery to issue Array Functional Language (AFL) commands and also queries for the prototype Array Query Language (AQL).

It is installed into /opt/scidb/<version>/bin.

Note the following:

You can issue a query from any node.
The iquery interface is case sensitive.
When iquery outputs string attributes, the strings are wrapped in single quotes for most formats.
The maximum length of a query is 16MB.
If you are using Enterprise Edition security features, see Using iquery in Security Mode.

Starting iquery

To start iquery for AQL (the default), do the following:

Type iquery -a at the command line in an active SciDB session. iquery opens an AFL% command prompt.
Enter AFL queries at the command prompt.

Note

AFL statements end with a semicolon (;). If you forget the terminating semicolon, iquery presents a prompt (CON>) where you can enter the terminating semicolon and run the query.

Using iquery

To view the iquery commands reference, type help; at the AFL prompt. The commands appear.

set            - List current options
set lang afl   - Set AFL as querying language
set lang aql   - Set AQL as querying language
set fetch      - Start retrieving query results
set no fetch   - Stop retrieving query results
set timer      - Start reporting query setup time
set no timer   - Stop reporting query setup time
set verbose    - Start reporting details from engine
set no verbose - Stop reporting details from engine
set format <base_format> [ :<options> ] - Switch output format
quit or exit   - End iquery session-

Available base_format values are:
csv     - Comma separated values
csv+    - Comma separated values including coordinates
dcsv    - "Display CSV", a more human-readable CSV variant
dense   - A variant of 'text' suitable for dense data
sparse  - A variant of 'text' suitable for sparse data
opaque  - SciDB raw storage format
store   - A variant of 'text' that includes overlap regions
text    - SciDB native text format
tsv     - Tab separated values (LinearTSV dialect)
tsv+    - Tab separated values including coordinates (LinearTSV)

Option flags for modifying output format.  Not all flags affect all
formats.  These may be combined:
d - Use double quotes in CSV output
E - Use an empty string for null in TSV or CSV output
l - Print label line for TSV or CSV output
N - Use \N for null in CSV output
n - Use the unquoted token 'null' for null in TSV or CSV output
s - Use single quotes in CSV output (normally the default)
? - Use ?0 for null in TSV or CSV output

To pass an AFL query directly to iquery from the command line, use the -aq flag:

iquery -aq "my AFL statement"

You can also pass a file containing an AFL query to iquery with the -f flag:

iquery -af my_input_filename

Each invocation of iquery connects to a SciDB instance, which becomes the query coordinator, passes in a query string, and prints out the instance's response. iquery connects by default to SciDB on port 1239. To use a port number other than the default, specify it using the -p option with iquery. For example, to use port 9999 to run an AFL query contained in the file my_filename do this:

iquery -af my_input_filename -p 9999

The query result prints to stdout. Use -r flag to redirect the output to a file:

iquery -r my_output_filename -af my_input_filename

To change the output format, use the -o flag:

iquery -o csv -r my_output_filename.csv -af my_input_filename

Reserved Words

SciDB reserves certain keywords that you cannot use as identifiers (such as array names, dimension names, or attribute names). The lists are language-dependent.

AFL

The following words are reserved when using AFL.

and array as

asc between case
compression create default
desc else empty
end false if
is not null
or reserve temp
then true using
when

AQL

All the AFL reserved words are also reserved in AQL - which is SciDB's prototype query language. In addition, AQL also reserves the following words.

all by cancel
cross current drop
errors fixed following
from group insert
instance instances into
join library load
on order over
partition preceding query
redimension regrid rename
save select set
shadow start step
temp thin to
unbound unload update
using values variable
where window

Avoiding all of the reserved words as identifiers regardless of the language you use is recommended. Some SciDB utilities use both AQL and AFL, thus using any AQL or AFL reserved word as an identifier could cause errors.

Output Formats

Available output formats are described in the following table:

Output Option	Description
auto	SciDB array format.
csv	Comma-separated values.
csv+	Comma-separated values with dimension indices.
dcsv (default)	Format used in most doc examples. Visually distinguishes dimensions from attributes. This is the default output format.
tsv	Tab-separated values.
tsv+	Tab-separated values with dimension indices.
dense	Ideal for viewing 2-dimensional arrays. Displays empty cells as parentheses. Not recommended for very sparse arrays.
sparse	Sparse SciDB array format.

You can add format modifiers to CSV and TSV options to print label lines and to treat null values in various ways. See save for details.

iquery Switches

To view a list of the iquery switches and their descriptions, type iquery -h or iquery --help at the command line. The switches are explained in the following table:

iquery Switch Option	Description
-A [ --auth-file ] authentication file	SciDB authentication file. When running in namespaces mode, this parameter specifies an authentication file containing username and password. See Using iquery in Security Mode for details.
-a [ --afl ]	Switch to AFL query language mode. Default is AQL.
--admin	Use to prioritize command-and-control type queries such as cancel() over other running queries. --admin is not intended, nor recommended for computationally intensive work loads. Requires root or administrative privileges.
-c [ --host ] host_name	Host of one of the cluster instances. Default is 'localhost'.
-f [ --query-file ] input_filename	File with query to execute.
-h [ --help ]	Show help.
--ignore-errors	Ignore execution errors in batch mode.
-n [ --no-fetch ]	Skip data fetching. Disabled by default. Useful when the result array is large, and you don't need the results displayed on screen.
-o [ --format ] format	Output format. See the previous table for available options. Default is 'dcsv'.
-p [ --port ] port_number	Port for connection. Default is 1239.
-q [ --query ] query	The query to execute.
-r [ --result ] target_filename	Filename where result data is stored.
-t [ --timer ]	For non-streaming queries, this flag returns the execution time to complete the query. For streaming queries that stream/return the data to the client, this flag returns the time for the data to become available. It doesn't measure the computational overhead associated with filter or the data download overhead either (when the returned result is large). For queries such as: iquery -t -aq "filter(sort(foo), a>0)", the flag returns the sort time but not the filter time.
-u [ --plugins ] path	Path to the plugins directory.
-V [ --version ]	Show SciDB version information.
-v [ --verbose ]	Print the debugging information. Disabled by default. Useful for displaying data such as number of chunks and chunk size.
-w [ --precision ] precision	Precision for printing floating point numbers. The iquery command displays floating point values with 6 signficant decimal digits by default. Use the -w flag to display a different number of significant decimal digits.

Browser not supported