Crate Shell. Release

Transcription

1 Crate Shell Release Jul 10, 2017

2

3 Contents 1 Installation & Usage Limitations Command Line Arguments Example Usage Crash Commands 9 4 Status Messages 11 5 Response Formats tabular json json_row csv raw mixed i

4 ii

5 The Crash Shell (crash) provides a CLI for the Crate Server. Contents 1

6 2 Contents

7 CHAPTER 1 Installation & Usage If the package was installed using pip the shell can be started by invoking crash in a terminal. We recommend to install it to the Python user install directory to avoid unwanted dependency conflicts. pip install --user crash Note: If crash is installed in the Python user install directory please ensure that ~/.local/bin (Linux), or %APPDATA%\Python\<version>\Scripts (Windows) is added to the system path. crash by default will try to connect to localhost:4200. To connect to another host use the connect command inside the shell or use the --hosts argument when launching the shell. crash started with the -v switch (once or more times) will log useful information when it comes to debugging, like what connection attempts are made and full tracebacks of server errors. For more information about the available command line arguments see Command Line Arguments. When you connect to a server that is not reachable or whose hostname cannot be resolved you will get an error: cr> \connect : server_url node_name version connected message NULL FALSE Server not CONNECT ERROR cr> \connect : server_url node_name version connected message NULL FALSE Server not a CONNECT ERROR 3

8 Successful connects will give you some information about the servers you connect to: cr> \connect :44209; server_url node_name version connected message crate... TRUE OK CONNECT OKCLUSTER CHECK OKCrate... does not support the "\check nodes" command. If you connect to more than one server, the command will succeed if at least one server is reachable: cr> \connect : :4295; server_url node_name version connected message crate... TRUE OK NULL FALSE Server not CONNECT OKCLUSTER CHECK OKCrate... does not support the "\check nodes" command. Once the shell is connected, SQL statements can be executed simply by entering them without any special arguments like this: cr> SELECT schema_name, table_name FROM information_schema.tables... ORDER BY table_name; schema_name table_name sys checks sys cluster information_schema columns sys jobs sys jobs_log sys nodes sys operations sys operations_log sys repositories information_schema routines information_schema schemata sys shards sys snapshots information_schema table_constraints information_schema table_partitions information_schema tables SELECT 16 rows in set (... sec) When the Crate shell is started with the option -v debugging information will be printed: cr> select x from y; SQLActionException[TableUnknownException: Table 'doc.y' unknown]... 4 Chapter 1. Installation & Usage

9 Limitations Nested Objects and Arrays Note: Since crate it is possible to use object and array literals and the limitation does not apply when connecting to a crate instance running > While it is possible to select or filter by nested objects it is currently not possible to insert them using crash. In order to do that the Crate REST endpoint or a client library like crate-python has to be used. The same also applies for arrays Limitations 5

10 6 Chapter 1. Installation & Usage

11 CHAPTER 2 Command Line Arguments The crash binary supports several command line arguments. Argument -h, --help -v, --verbose -c COMMAND, --command COMMAND --hosts HOSTS --history HISTORY --config CONFIG Description Show the help message end exit. Print debug information to stdout. Execute the SQL statement and exit. The Crate hosts to connect to. The history file the Crate shell uses. Path to the configuration file which contains default values for Crash. Defaults to the user configuration directory of the operating system, which is e.g on Linux ~/.config/crate, ~/Library/Application Support/Crate on OSX or C:\\Users\user\AppData\Local\Crate\Crate on Windows. Specifies the output format of the SQL response. --format FORMAT --version Print the crash version and exit. --sysinfo Print system and cluster information. -A, Disable autocomplete of SQL keywords on startup. Autocomplete requires a minimum --no-autocompleteterminal height of 8 lines due to size of the dropdown overlay for suggestions. Disabling autocomplete removes this limitation. Example Usage $ crash --hosts st1.crate.io:4200 st2.crate.io st3.crate.io \ --format json \ -c 'select * from sys.nodes' > output.json 7

12 8 Chapter 2. Command Line Arguments

13 CHAPTER 3 Crash Commands Note: Crash client commands are available since version 0.11.x! Crash has several client commands, which start with a backslash (\). You can get a list of commands by typing \?: Command Description \? List all available commands. \c, \connect Connect to the given server. Same as --host command line option. \dt Print existing tables. The list does not include tables in the sys and information_schema schema. \format Switch the output format of the SQL response. Same as --format command line option. Available formats are: tabular, raw, json, json_row, csv and mixed see Response Formats for details \q Quit Crate shell \check Query the sys tables for failing cluster and node checks if no arguments are provided. The following arguments are allowed: nodes: to query the sys.node_checks table for failing node checks. cluster: to query the sys.checks table for failing cluster checks. \r <filename> Reads statements from the given file and executes them \sysinfo Query the sys tables for system and cluster information \autocomplete Turn autocomplete feature on or off. Works as a toggle. 9

14 10 Chapter 3. Crash Commands

15 CHAPTER 4 Status Messages The SUCCESS status messages are only printed when crash is used as an interactive tty. If the output is routed, e.g. dumped into a file or piped into another command (such as jq) for further processing of the response, these messages are omitted. The synopsis of the SUCCESS message is as follows: SUCCESS <STMT>, <NUM> row(s) affected (<DURATION> sec) If the SQL statement (SELECT) returns selected columns: SUCCESS <STMT> <NUM> row(s) in set (<DURATION> sec) The STMT is the definition/manipulation/query keyword, such as CREATE, INSERT, UPDATE, DELETE, SELECT, etc. NUM is the number of rows that were affected by the SQL statement. It is -1 for statements that do not affect any rows or if the row count of a statement is unknown. DURATION is the time it took to process the SQL statement on the server from request to response. 11

16 12 Chapter 4. Status Messages

17 CHAPTER 5 Response Formats tabular This is the default output format. It prints the SQL response in a tabular form. Each column of the table represents a selected column of the SQL statement. Example: name version crate crate json The json format prints the result as JSON formatted object array where the key of the object is the column name and the value the value of the row. This is useful if you want to print the result of an SQL statement into a file. Example: [ { "name": "crate1", "version": "0.46.3" }, { "name": "crate2", "version": "0.46.3" 13

18 ] } json_row This format is related to format_json. However it prints each dataset row-by-row in separate lines. This output is compatible with COPY FROM statement. Therefore it is useful if you want to export specific datasets in order to import them later via COPY FROM. Example: {"name": "crate1", "version": "0.46.3"} {"name": "crate2", "version": "0.46.3"} csv The csv format prints the resuls as a comma separated value (csv) list, where the delimiter is a comma (,), the quote character is a single quote (''), and the escape character is a blackslash (\). Please note that column headers that contain a single quote (e.g. nested objects) will be escaped. The first line of the csv output contains the name of the selected columns. Example: name,version crate1, crate2, However, objects or arrays are returned as a (JSON-) string: Example: name,settings[\'udc\'] crate,'{"enabled": true, "initial_delay": "10m", "interval": "1d", "url": " udc.crate.io"}' raw The raw format prints the results as it is retured by the Crate Python library. It contains a JSON object with 4 keys: cols, rows, rowcount, and duration. Example: { "rows": [ [ "crate1", "0.46.0" ], [ "crate2", 14 Chapter 5. Response Formats

19 "0.46.0" ] ], "cols": [ "name", "0.46.3" ], "rowcount": 1, "duration": } mixed The mixed output lists each column in a row and multiple rows are separated by a line delimiter. The name of the column is on the left, separated by from the value on the right side. Example: name crate1 version name crate2 version mixed 15