scidb (version 1.2-0)

iquery: Simple SciDB query tool

Description

Issue SciDB queries and optionally return output in a data frame.

Usage

iquery(query, `return` = FALSE, afl = TRUE, iterative = FALSE, n = 10000, excludecol, binary = FALSE, ...)

Arguments

query

A SciDB query string (character). Separate multiple queries with semicolons.

return

Set to TRUE to return output. Otherwise don't return query output. Only available when afl=TRUE

afl

TRUE indicates query is in AFL form, FALSE indicates AQL.

iterative

Set to TRUE to return a result iterator. FALSE returns entire result at once.

n

Maximum number of rows to return when iterating through results. Set to Inf to return everything. Ignored when binary=TRUE.

excludecol

An optional numeric range of columns to exclude from iterative results (only applies when iterative=TRIE).

binary

TRUE indicates efficient binary transfer method. Set to FALSE to use read.table and UTF8 encoded text transfer, parsed by read.table (more flexible parsing for unusual types).

...

Options passed on to read.table used to parse results when binary=FALSE. See details.

Value

If return=TRUE, return the query result in data frame form (similar to the SciDB iquery command-line -olcsv+ output option).If return=FALSE, return the query ID number.SciDB errors encountered during query processing are propagated to R and can be handled with normal R error handling mechanisms.Set itreative=TRUE to return a result iterator. Use the iterator nextElem function to iteratively return results, a maximum of n results at a time. See help in the iterators package for examples and options.

Details

The iquery function is an analog of the command-line SciDB iquery program. Use it to issue arbitrary SciDB queries.

Several return options are available. Select binary=TRUE to bring the entire result of the query to R using an efficient binary transfer. Note that for now, selecting binary=TRUE implies n=Inf--that is, the whole result comes back at once.

When binary=TRUE is selected, two optional arguments become available:

• buffer=100000: The binary returned data will be parsed in chunks of at most buffer rows. Adjust this for performance.

row.names=NULL: Similarly to R's read.table function, set this value to be a vector of row labels for the output, or optionally a single number indicating the output column to use as row names for the output data.frame.

unpack=TRUE: Set unpack to FALSE to return only the array attribute data values. The default unpack=TRUE returns coordinate indices and the array attribute values.

Select binary=FALSE to use a delimited text transfer option. Data are transferred using delimited text and parsed through R's read.table function. When this option is selected, any ... arguments are passed directly to read.table. You can limit the number of returned results to n when this option is set.

Select iterative=TRUE to return an iterator that iterators over n output rows at a time. This option only supports delimted text transfers.

Examples

## Not run: 
# iquery("list('instances')",return=TRUE)
# 
# # A simple example that iterates through results using foreach
# # Build an array with 1 million numbers from zero to 1.
# iquery("store(build(<x:double>[i=1:1000000,100000,0],i/1000000),X)")
# # Apply a function and return result in an iterator:
# i <- iquery("apply(X, y, sin(x))", return=TRUE, iterative=TRUE)
# 
# # Sum up x and y (and dimension i too)
# library("foreach")
# foreach(j=i, .combine=function(...)colSums(rbind(...))) 
# 
# # Compare with the much faster equivalent inside SciDB:
# iquery("aggregate(apply(X, y, sin(x)),sum(x),sum(y))", return=TRUE)
# 
# ## End(Not run)