scidb-hquery 2.8.0.432 → 2.8.0.434
raw patch · 4 files changed
+370/−9 lines, 4 filesPVP ok
version bump matches the API change (PVP)
API changes (from Hackage documentation)
Files
- CHANGELOG.md +8/−0
- README.md +355/−0
- scidb-hquery.cabal +6/−8
- src/Main.hs +1/−1
CHANGELOG.md view
@@ -11,3 +11,11 @@ ## 2.8.0.432 -- 2019-07-08 * Corrected problems discovered with cabal candidate package 2.8.0.431.++## 2.8.0.433 -- 2019-07-11++* Added README.md to extra-source-files.++## 2.8.0.434 -- 2019-07-12++* Improved README.md and description documentation.
+ README.md view
@@ -0,0 +1,355 @@+# SciDB and the hquery command++SciDB is a column-oriented database management system (DBMS) designed+for multidimensional data management and analytics common to+scientific, geospatial, industrial, and financial applications. See+<http://www.paradigm4.com/> and <http://www.paradigm4.com/forum> for+more information about the Data Management and Analytics Software+System (DMAS) known as SciDB.++The hquery command is a Haskell command line and interactive+interpreter for SciDB AFL queries via shim. See also++ * hquery -y,+ * hquery -h, or+ * hquery -m++for more information++There is a primitive API derived after the creation of hquery+defined by the following data structures and actions:++ * Environment+ * Err+ * mkGlobalManagerEnv+ * runQueries+ * unsafeRunQuery+ * getSciDbVersion++# The hquery manual page++```hquery(1) User Command hquery(1)++NAME+ hquery - Haskell query for SciDB via shim++SYNOPSIS+ hquery [-V n] [-t hstfile] [-c certstore] [-n]+ [-r http[s]] [-i host] [-p port] [-a true|false]+ [-e true|false] [-o fmt] [-b num] [-d|-s]+ [-u usr] [-w pw]+ [-f qyfile] [query...]+ hquery -g+ hquery -h+ hquery -l+ hquery -m+ hquery -v+ hquery -y++AVAILABILITY+ Marcus D. Gabriel. All rights reserved 2014-19(c).++ marcus@gabriel.name++ License terms: GNU GPL version 3 (hquery -l)++DESCRIPTION+ The command hquery with no operands and no options will begin an+ interacitve session with a SciDB server using SciDB's shim+ protocol at http://localhost:8080.++ With operands, each string will be executed as a SciDB AFL (Array+ Functional Language) query returning a result in SciDB DCSV+ format and fetching only 23 lines per query by default. If+ stdin is non-empty, it will be execute before the operands.+ SciDB AFL queries are case insensitive and terminated by+ semi-colons (;).++ Before submitting a query to the shim server, the command+ hquery will+ 1. return syntax and parsing errors+ 2. report bad nestings, e.g., 'uniq(store(A,B));'+ 3. report unknown commands, ignoring them++ Additionally, the command hquery reports SciDB/shim server+ query exceptions without terminating the process.++ The command hquery accepts Haskell sytle comments and accepts+ the setting of the following following global variables:++ -- Number of lines to fetch+ n=Integer;+ -- Format of the output+ format={'csv'|'csv+'|'dcsv'|'dense'|'sparse'|'opaque'+ |'store'|'text'|'tsv'|'tsv+'};+ -- True to fetch data, false to not fetch data+ fetch={true|false};+ -- True to read lines, false to read bytes+ readinglines={true|false};+ -- Prefix to execute before a query by shim, e.g.,+ prefix='a_query(\'a_string\');'++ Prefix is an optional, semi-colon separated, AFL statements+ to precede a query in the same SciDB connection context.+ It is mainly used for SciDB namespace and role setting.+ There is no terminating semi-colon so trailing semi-colons+ are removed otherwise the prefix is sent to shim unverified+ and unaltered via the variable 'prefix'.++ The command 'quit;' or 'exit;' ends the interactive session+ with exit status 0. The command "vars;" displays the interpreter+ variables and values, and the command "funs;" displays the+ currently defined interpreter functions and definitions: exit,+ funs, quit, upload, and vars.++ The upload command takes one argument, a local file path+ string, and returns a shim server-side file path. It is used+ in queries such as load, input, load_module that take a shim+ server-side file path. Examples are++ load(m4x4_missing,+ upload('/home/scidb/scidb/m4x4_missing.scidb'));++ input(m4x4_missing,+ upload('/home/scidb/scidb/m4x4_missing.scidb'));++ load_module(upload('/home/scidb/scidb/module_1.txt'));++ join(input(m4x4,upload('/tmp/a\\'y\\'b.txt')),+ input(m4x4,upload('/tmp/z.txt')));++ All of the above is case insensitive and terminated with a+ semi-colon (;).++INTERACTIVE SESSION+ Multi-line queries are supported interactively as they+ are in non-interactive execution. Ctrl-D at a new prompt+ ends the interactive session. Ctrl-C returns to the+ interactive prompt, used to end input, especially+ multi-line input.++ The default prompt is 'True/dcsv/23?', for example,++ True/dcsv/23? list('arrays');++ which displays up to 23 lines of arrays, that is,++ Fetch/Format/NumberOfLines?++ You can change the global variables 'n', 'format', 'fetch',+ 'readinglines', and 'prefix' during execution which changes+ the prompt:++ True/dcsv/23? n=200; -- Fetch 200 lines+ True/dcsv/200? n=0; -- Fetch all lines+ True/dcsv/0? format='csv'; -- Set format to csv+ True/csv/0? fetch=false; -- Fetch no lines regardless+ -- the value of n+ False/csv/0? fetch=true;format=dcsv;n=23;+ True/dcsv/23? readinglines=false; -- Fetch all bytes regardless+ -- the value of n+ Bytes/dcsv/23? prefix='set_namespace(\'sensor_data\');';+ Bytes/dcsv/23p list('arrays'); -- List sensor_data arrays+ Bytes/dcsv/23p quit;++ In other words, the prompt indicates the default behaviour for+ the next query executed.++OPTIONS+ The following options are supported:++ -a True|false, true to read lines, false to read bytes+ (--reading-lines). If false, the number of lines to+ fetch (-b) is ignored and the entire output buffer is+ downloaded. This follows the recommendataion of the+ shim documentation.++ -b Number, number of lines to fetch (--number).++ -c Certificate store file, a certificate store to load and use+ for SSL/TLS connections (--certificate-store). The insecure+ option (-n) over-rides the certificate store (-c).++ -d Use basic digest access authorization, used by either the+ http and https protocols (--digest-authorization). Digest+ authorization (-d) over-rides SciDB authorization (-s).++ -e True|false, true to fetch lines, false to not fetch lines+ (--fetch).++ -f Query file, a readable file of queries. Multi-line queries+ are supported in a file (--file). If stdin is non-empty,+ it is executed before the file of queries. If operands are+ present, they are executed after the file of queries.++ -g Get and display the SciDB version via shim and then exit+ (--scidb-version). This performs a simple check for shim + and SciDB availability.++ -h Display a short hquery summary (--help).++ -i IP address or hostname, default localhost (--host).++ -l Display the hquery license terms (--license).++ -m Display this internal manual page (--manual).++ -n Do not use certificate validation, insecure because+ of potential man-in-the-middle attacks (--insecure).+ The insecure option (-n) over-rides the certificate+ store (-c).++ -o Format, ouput format such as dcsv, csv, csv+, tsv, tsv+,+ etc (--format).++ -p Port number, default 8080 for protocol (-r) http and default+ 8083 for protocol (-r) https (--port).++ -r Protocol, e.g., http or https, default http (--protocol).+ If the protocol is http, the certificate store (-c) and+ insecure (-n) options are disabled.++ -s Use SciDB access authorization, requires the https protocol+ (--scidb-authorization). This option sets the https protocol+ except when digest authorization (-d) over-rides SciDB+ authorization (-s).++ -t History file, defualt ~/.hquery_history or /tmp/.hquery_history+ if ~ does not exist (--history).++ -u Username, defualt null (--username). Used by the digest or+ SciDB authorization option (-d or -s). Displays an error+ and exits if neither is used with digest or SciDB+ authorization.++ -v The version of hquery (--version).++ -w Password, default null (--password). Used by the digest or+ SciDB authorization option (-d or -s). Displays an error+ and exits if neither is used with digest or SciDB+ authorization.++ -y A synopsis of the internal manual page (--synopsis).++ -x Prefix, a prefix to execute before a query by shim+ (--prefix). Note that the prefix on the command line+ is verified before being sent to shim. Prefix is a+ semi-colon separated set of statements. It is mainly+ used for SciDB namespace and role setting. There is no+ terminating semi-colon so trailing semi-colons are removed.++ -V Same as -V1 (--verbose).+ -V0 Quiet. No information is sent to stderr (--verbose=0).+ -V1 Shows some HTTP exceptions and trace information (--verbose=1).+ -V2 Shows additional URL information (--verbose=2).++OPERANDS+ SciDB AFL queries.++USAGE NOTES+ The development of the utility hquery began with SciDB community+ edition 13 and continued with 14, 15, 16, 18, and 19.++ This version of hquery has been lightly tested with ghc+ version 8.2.2 and 8.6.5 and SciDB 18.1 and 19.3 community edition.+ Currently the command hquery has never been tested on a SciDB+ enterprise edition, and thus it is not known if SciDB+ authorization (-s) or prefix (-x) actually works.++EXAMPLES+ To list all currently defined arrays with SciDB authorization+ required, use++ hquery -i coordinator -s -u ScidB -w SciDBPassword \+ "n=0; list('arrays');"++ To list up to 100 lines of functions with digest authorization+ required, use++ hquery -i coordinator -d -u Digest \+ -w DigestPassword "n=100; list('arrays');"++ To list up to 23 lines of operators, 23 being the default, use++ hquery -i coordinator "list('operators');"++ To list all functions by reading bytes instead of lines, use++ hquery -i coordinator -a false "list('functions');"++ To create an array A, use++ hquery -i coordinator "create array A <x:double> [i=0:99:0:10];"++ To execute the file of queries HQTests.qy with no authorization+ required via a TLS connection, use++ hquery -c ssl_cert.pem -r https -i coordinator -f HQTest.qy++ To execute the file of queries HQTests.qy with digest authorization+ required via a TLS connection insecurely, use++ hquery -n -r https -i coordinator -d -u Digest \+ -w DigestPassword -f HQTests.qy++ To list all arrays in the sensor_data namespace, use++ hquery -i coordinator -b 0 -x "set_namespace('sensor_data');" \+ "list('arrays');"++ To display a synopsis of this internal manual page, use++ hquery -y++ To display a summary of usage, use++ hquery -h++ To display this internal manual page, use++ hquery -m++ENVIRONMENT VARIABLES+ HOME Home directory for the history file, by defualt+ ~/.hquery_history.++ PAGER Page the internal manual page or license terms+ using "${PAGER}", otherwise print it.++EXIT STATUS+ An exit status of 0 is returned if successful, otherwise non-zero+ is returned.++ EXIT CODE MEANING+ 1 Unknown error.+ 2 No authorization specified (-s|-d) with+ username/password.+ 3 Invalid protocol, hostname, port, or history+ file option.+ 4 Cannot connect to hostname:port.+ 5 Unreadable query file.+ 6 Unreadable certicate store file.+ 7 Invalid certificate store.+ 8 Network/certificate manager initialization error.+ 9 Empty, bad or no digest authentication.+ 10 Unauthorized access.+ 11 Could not connect to SciDB.+ 12 Input syntax error for a SciDB query.+ 13 Fetch (-e) or reading-lines (-a) not true or false.+ 14 Bad command-line prefix (-x).+ 15..255 Unknown error.++FILES+ ~/.hquery_history++SEE ALSO+ SciDB, SciDB iquery, SciDB shim at https://www.paradigm4.com/ + and https://www.paradigm4.com/forum for more information.++NOTES+ Please send bug reports to+ https://github.com/mdgabriel/scidb-hquery/issues.++BUGS+ No known bugs to date.+```
scidb-hquery.cabal view
@@ -1,6 +1,6 @@ cabal-version: 2.4 name: scidb-hquery-version: 2.8.0.432+version: 2.8.0.434 license: GPL-3.0-only license-file: LICENSE copyright: All rights reserved 2014-19(c).@@ -10,13 +10,10 @@ bug-reports: https://github.com/mdgabriel/scidb-hquery/issues synopsis: Haskell query for SciDB via shim description:- The command @hquery@ with no operands and no options will begin an+ The command hquery with no operands and no options will begin an interacitve session with a SciDB server using SciDB's shim- protocol at host localhost and port 8080. See- https:\/\/github.com\/mdgabriel\/scidb-hquery.git,- @hquery -m@, and- http:\/\/www.paradigm4.com- for more infomation.+ protocol at host localhost and port 8080. See the [homepage](https://github.com/mdgabriel/scidb-hquery.git),+ "hquery -m", and [www.paradigm4.com](http://www.paradigm4.com) for more infomation. category: program, client, database, library build-type: Custom -- The entry src/SciDbAFL.cf in extra-source-files below is a@@ -24,12 +21,13 @@ -- so that cabal new-sdist works. extra-source-files: CHANGELOG.md+ README.md src/SciDbAFL.cf source-repository head type: git location: https://github.com/mdgabriel/scidb-hquery.git- tag: 2.8.0.432+ tag: 2.8.0.434 custom-setup setup-depends: base >=4.12.0.0 && <4.13,
src/Main.hs view
@@ -455,7 +455,7 @@ Config { argOrder = RequireOrder, -- Update revision number: TOGGLE CASE- release = "2.8.0.432",+ release = "2.8.0.434", flagsOps = " [[-g|-h|-l|-m|-v|-y] |"++ "\n [-V n] [-t hstfile] [-c certstore] [-n]"++ "\n [-r http[s]] [-i host] [-p port] [-a true|false]"++