lv-client

LiveView Client — A client for querying a LiveView Server from the system command prompt.

SYNOPSIS

lv-client [-u uri][-c][-w waitTimeMS] "command" [help]

lv-client --version

lv-client help

LV> command [--help];

DESCRIPTION

lv-client is the command-line client for creating simple queries against a running LiveView server. You can use lv-client commands in scripts, or directly from a system command prompt. Commands that are supported for use at the command prompt are noted with (command-line support).

Without arguments, lv-client enters an interactive shell mode, showing the prompt LV>. All commands entered in the interactive client must end with a semicolon (;).

OPTIONS

-u uri

Specifies the URI for the LiveView Server instance to communicate with, using the lv:// protocol, or (if SSL authentication is enabled on the server), the lvs:// protocol. If a URI is provided with -u, lv-client connects to the specified LiveView Server immediately on startup, or quits if unsuccessful. When connecting to a server on which LiveView authentication is enabled, place a valid user name and password, separated by a colon and appended with an at-sign, just before the server name. For example: 

lv://lvuser:lvpassword@localhost:10080
lv://lvuser:lvpassword@remote-lv.example.com:10080
-p TCP-port

Specifies the port number on localhost of the LiveView server instance to communicate with. This is a shortcut alternative to specifying the full URI with -u in cases where the server is running on localhost but on a port other than the default 10080.

-c

Returns query output in comma-separated value (CSV) format.

-w waitTimeMS

Specifies a wait time waitTimeMS in milliseconds for the command to continually attempt to connect to LiveView Server before abandoning the connect attempt.

--version

Shows the version of the LiveView Java Client library used to build lv-client.

COMMANDS

addalertaction ruleID action

Adds an alert action to the ruleID provided. Use the listrules command to obtain ruleIDs. The available actions are:

--delete tablename predicate

Where tablename is the table to affect and predicate is the test specified as a StreamBase expression.

--email --to recipient --body "body"

Where recipient is the addressee of the the email, and body is the body of the message, enclosed in quotes.

--javacommand class [--field name:value [--field name2:value2...]]

Where class is the Java class and the fields are name:value pairs. Notice the required colon (:) separating the name and value.

--oscommand "command"

Where command is the command to run. Enclosed the command in quotes if it contains spaces or other characters that would need to be escaped if run at the operating system's command prompt.

--publish

Publishes the alert tuple as a row in the LVAlerts table.

--sendtuple uri streamName [--field name:value [--field name2:value2...]]

Where uri specifies the StreamBase Server to send the tuple to, streamName is the name of the input stream to send to, and fields are name:value pairs for the fields of the tuple.

addalertrule tableName predicate [--quiescence X] --message "messageText" --name "alertName" [--owner "ownerName"]

Adds an alert rule with no actions. If --owner is not specified, defaults to the currently logged-in operating system username.

clearTableName [,TableName2, ...]

Clears all row data from each specified table. You can specify a comma-separated list of table names that you obtain from the listtable command.

Caution

Cleared table data cannot be recovered, so use this command with care.

close queryid

Closes the specified query. Obtain queryid from the LVSessionQueries table.

connect [uri]

Closes any existing connection and connects to the specified LiveView Server instance, or to the default server if no uri argument is provided. With no argument, the connect command connects to the default LiveView Server URI, lv://localhost:10080. When connecting to a server on which LiveView authentication is enabled, place a valid user name and password, separated by a colon and appended with an at-sign, just before the server name. For example: 

lv://lvuser:lvpassword@localhost:10080
lv://lvuser:lvpassword@remote-lv.example.com:10080
connstat

Retrieves information about the current LiveView Server connection (command-line support).

continuous select-statement

Creates a continuous-only query, where select-statement is a complete LiveQL SELECT statement in the form live (select * or collist) from table [where predicate] [limit x] (command-line support).

createtable

Creates a new LiveView table of the specified type and adds it to the project currently running on LiveView Server. Supports the following options:

--name tablename, --schema (schema-def)

where schema-def is a parenthesized, comma-separated list of field name and data type pairs, such as (stock string, price double)

--keys keystring

where keystring is is comma-separated, no-spaces list of primary key field names, optionally followed by a semicolon and a comma-separated, no-spaces list of secondary key field names. Example: --keys stock,transid;price

[--description description], [--aggbasetable base-table-name], [--aggquery querystring]

To create an aggregation table, specify both --agg* options, with the name of the base Data Table to aggregate from, and where querystring is a parenthesized projection string, such as (select stock, sum(price) as totalPrice from basetable group by stock)

delete [from] TableName [predicate-clause]

Deletes rows that match a query predicate that begins with WHERE or WHEN. Does NOT drop a table; use this command to clear all matching rows from the specified table. With no predicate clause specified, this command deletes all rows from the specified table.

Caution

Deleted table data cannot be recovered, so use this command with care.

deletealertaction ruleid actionid

Deletes the specified action from the specified rule. The actionid can be found using the listrules command.

deletealertrule ruleid

Deleted the specified rule. The ruleid can be found using the listrules command.

disablerules [ruleid]

Disables all alert rules, or a specified alert rule. To specify a rule, use a rule ID number obtained using the listrules command. (command-line support).

droptable tablename [--wait waitTime]

Drops the specified Data Table and any dependent tables such as Aggregation or Preprocessor tables. The --wait option specifies a number of seconds to wait for the command to return, with status updates during the wait period. With no --wait option, the command returns to the prompt immediately, without reporting on the success or failure of the command.

enablerules [ruleid]

Enables all or a specified set of alert rules. To specify a rule, use its ruleID number obtained using the listrules command. (command-line support).

help

Displays available commands (command-line support). The --help option also provides command-level help for each lv-client subcommand.

killpublisher [sessionid publisherid] | [--where predicate-clause]

Kills the publisher having the specified combination of session ID and publisher ID. Or, if used with a predicate-clause, kills all publishers from the LVSessionPublishers table that satisfy the predicate against LVSessionPublishers.

killquery [sessionid queryid] | [--where predicate-clause]

Kills the query having the specified combination of session ID and query ID. Obtain queryid from the LVSessionQueries table. Or, if used with a predicate-clause, kills all queries currently listed in the LVSessionQueries table that satisfy the provided predicate against LVSessionQueries.

killsession [sessionid ] | [--where predicate-clause]

Kills the session with the specified session ID. Or, if used with the predicate-clause, kills all the sessions from the LVSessions table that satisfy the predicate against LVSessions.

listalertaction ruleid

Lists the actions belonging to the specified rule. Use rule ID numbers obtained using the listrules command.

listen queryid

Listens to a running live query. Use this command when multiple live queries are running to restrict the listening session to one query at a time. Obtain queryid from the LVSessionQueries table or the livestat command. Press X then Enter to stop listening.

listrules [ruleid]

Lists all or specified alert rules. To specify a rule, use the rule id number (command-line support).

listtable [TableName] [-a], listtables [TableName] [-a]

Lists tables available for querying. If you give the command a table name as a argument, it returns the field names and associated data types of the specified table (command-line support). Internal-only fields are suppressed by default; append -a to include those fields in the output.

live select-statement

Creates a live query, where select-statement is a complete LiveQL SELECT statement in the form live (select * or collist) from table [where predicate] [limit x] (command-line support).

livestat

Lists the status and IDs of current live queries.

print queryid

Prints current results of a live query. Obtain queryid from the LVSessionQueries table.

publish TableName [--delete [bufferSize [flushIntervalMS]]]

Reads CSV data from standard input and publishes to the specified table (command-line support).

quit

Quits the interactive client.

select LiveQL-statement

Runs a snapshot query. The select command uses the syntax of the LiveQL SELECT statement (command-line support).

shutdown

Shuts down the connected LiveView Server (command-line support).

starttable tablename [--wait waitTime]

Starts or restarts the specified Data Table and all dependent tables, such as Aggregation or Preprocessor tables. The --wait option specifies a number of seconds to wait for the command to return, with status updates during the wait period. With no --wait option, the command returns to the prompt immediately, without reporting on the success or failure of the command.

version

At the command prompt, with no current server connection, displays the version of the LiveView Client API used to build the lv-client command. In interactive mode, when connected to a LiveView Server instance, displays the version of the server (command-line support).

EXAMPLES

This example runs simple queries against the Hello LiveView sample project as loaded into the StreamBase Studio workspace in the project folder sample_lv-helloliveview. All commands are run from the StreamBase Command Prompt.

  1. To run the Hello LiveView sample for the Windows username sbuser, use the following command. (This single command is shown on two lines for clarity.) 

    lv-server run "C:\Users\sbuser\Documents\
  StreamBase Studio 7.6 Workspace\sample_lv-helloliveview"

  2. Use the command line to list the tables in the running LiveView application: 

    lv-client listtables

  3. Connect to the default URI and start the lv-client interactive shell: 

    lv-client -u lv://localhost:10080

  4. Create a snapshot query that returns all rows from the ItemsSales table where lastSoldPrice is greater than 10 and quantityRemaining is less than 20: 

    SELECT * FROM ItemsSales WHERE lastSoldPrice > 10 AND 
  quantityRemaining < 20;

  5. Exit the interactive client and run the same query from the system command line: 

    quit;
lv-client -u lv://localhost:10080 "SELECT * FROM ItemsSales 
   WHERE lastSoldPrice > 10 AND quantityRemaining < 20;"

  6. The next two lines run at a StreamBase Command Prompt on Windows start LiveView Server running the Hello LiveView sample, waits three minutes for the server to come up (180,000 milliseconds), then checks the connection status. 

    start /min lv-server run "C:\Users\sbuser\Documents\
  StreamBase Studio 7.6 Workspace\sample_lv-helloliveview"
lv-client -w 180000 connstat

    The following two lines are the same, but run from a Linux or OS X terminal: 

    lv-server run "/Users/sbuser/Documents/
  Streambase Studio 7.6 Workspace\sample_lv-helloliveview"
lv-client -w 180000 connstat

SEE ALSO

sbc
lv-server