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 | --help
lv-client help
command
LV>
command
[--help];
LV> help
command
;
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), thelvs://
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 onlocalhost
but on a port other than the default 10080.Note
When both -u and -p options are omitted, the default is
lv://localhost:10080
. - -c
-
Returns query output in comma-separated value (CSV) format, with the final line like
"# Rows = X"
, which allows most CSV readers to simply ignore that line, and avoid generating an error. - -j
-
Emits and accepts data as JSON.
- -t
-
Also emit a client-local timestamp with every query event.
- -g
-
Compress traffic from the LiveView Server.
- -b
-
For live queries, use the basic QueryListener and not the LiveResult listener.
- -C
-
Comma separated list of client capabilities.
- -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. - --help [
command
] -
Without arguments, shows an overview of all commands accepted by lv-client, then returns to the terminal prompt. --help followed by the name of an lv-client command shows a usage summary for that command, then returns to the terminal prompt. This syntax is also valid at the LV> prompt in interactive mode.
- --version
-
Shows the version of the current lv-client command (which is really the version of the LiveView Java Client library used to build lv-client).
- --no-check-certificate
yyyy-mm-dd
-
Do not validate TLS certificates for the given day. Insecure.
COMMANDS
- addalertaction
ruleID
action
-
Adds an alert action to the
ruleID
provided. Use the listrules command to obtainruleID
s. The available actions are:- --delete
tablename
predicate
-
Where
tablename
is the table to affect andpredicate
is the condition test specified as a StreamBase expression that resolves to a Boolean value. - --email --to
recipient
--body"body"
-
Where
recipient
is the addressee of the email, andbody
is the body of the message, enclosed in quotes. - --javacommand
class
[--fieldname:value
[--fieldname2:value2...
]] -
Where
class
is the name of a Java class on the current classpath, and the--field
options specify name:value replacement values for fields in the outgoing alert tuple. The colon separatingname
andvalue
is required. - --lvpublish
uri
tableName
[--fieldname:value
[--fieldname2:value2
...]] -
Publishes the alert tuple as a row in the specified
tableName
running on the LiveView server instance aturl
with--field
options that specify name:value pairs for fields of the alert tuple. The colon separatingname
andvalue
is required.This command option differs from
--publish
, because it lets you send an alert tuple to any table running on any LiveView server, including remote servers, whereas--publish
sends an alert tuple only to the LValerts table on the current LiveView server instance. This option is similar to the--sendtuple
option, except that it sends tuples to LiveView data tables, not to StreamBase Server input streams. - --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 on the current LiveView server. Compare with
--lvpublish
, above. - --sendtuple
uri
streamName
[--fieldname:value
[--fieldname2: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 arename:value
pairs for the fields of the tuple. The colon separatingname
andvalue
is required. Compare with--lvpublish
, above.
- --delete
- addalertrule
tableName
--wherepredicate
[--quiescenceX
] --message "messageText
" --name "alertName
" [--owner "ownerName
"] -
First syntax of addalertrule. Discussion of this command follows the second syntax, below.
- addalertrule
tableName
--cron cronstring --message "messageText
" --name "alertName
" [--owner "ownerName
"] -
Adds an alert rule with no alert action. The alert rule so added is not enabled; you can obtain the new rule's ruleID with the listrules command, add an associated alert action to that ruleID with the addalertaction command, then enable the rule with the enablerules command.
You can specify either a query-based rule with the first syntax, or specify a time-based rule with the second syntax.
In a query-based rule, you must specify a LiveView table name and a predicate expression to apply to rows in that table. Depending on your shell, you may have to quote the predicate expression or collapse all spaces from it to get the expression accepted.
Use the
--quiescence
option to specify a number of milliseconds to delay subsequent triggering after the initial firing of this alert. This can be useful if this alert rule triggers frequently once its condition is met and multiple, repeated alerts are undesired. The delay time starts once the actions for the initial trigger have completed.In a time-based rule, you specify only --cron and a cronstring such as “0 0 12 ? * WED”, which means "every Wednesday at 12:00:00 PM". The cron library used is the Quartz Job Scheduling Library; see its documentation for the specification of its cron expression strings.
If --owner is not specified, it defaults to the currently logged-in operating system username.
- clear
TableName
[,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 formlive (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 (command-line support). 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
], [--aggbasetablebase-table-name
], [--aggqueryquerystring
] -
To create an aggregation table, specify both
--agg*
options, with the name of the base Data Table to aggregate from, and wherequerystring
is a parenthesized projection string, such as(select stock, sum(price) as totalPrice from basetable group by stock)
- --name
- 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 (command-line support).
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 (command-line support). - deletealertrule
ruleid
-
Deleted the specified rule. The
ruleid
can be found using the listrules command (command-line support). - describe
[--verbose]
select-statement
-
Returns the projection schema of the supplied query where
select-statement
is a complete LiveQL SELECT statement in the form(select * or collist) from table [where predicate] [limit x]
(command-line support). - 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 (command-line support). - 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 and when followed by a command name, displays usage text for that command. (command-line support). The --help option also provides command-level help for each lv-client subcommand, but not at the command-line.
- killpublisher [
sessionid publisherid
] | [--wherepredicate-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 (command-line support). - killquery [
sessionid queryid
] | [--wherepredicate-clause
] -
Kills the query having the specified combination of session ID and query ID. Obtain
queryid
from the LVSessionQueries table. Or, if used with apredicate-clause
, kills all queries currently listed in the LVSessionQueries table that satisfy the provided predicate against LVSessionQueries (command-line support). - killsession [
sessionid
] | [--wherepredicate-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 (command-line support). - listalertaction
ruleid
-
Lists the actions belonging to the specified rule. Use rule ID numbers obtained using the listrules command (command-line support).
- 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 formlive (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. Use the
--delete
option to specify an amount of data in bytes or a flush interval in milliseconds after which the published data is deleted. (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).
- sessioncontrol --acceptnew | --stopnew
-
Issuing this command has no effect unless the currently logged in username has the
session
entitlement as described in the Using LiveView Authentication and Authorization section of the LiveView Server System Configuration page of the LiveView Admin Guide. Use this command when you must prevent new client connection sessions from logging into LiveView Server, such as when you must send an alert to all users that the server must be taken down shortly. Specify the--stopnew
option to prevent further connections, or the--acceptnew
option to reverse that condition (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 (command-line support). - status
-
Displays status of underlying StreamBase server (command-line support).
- 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.
-
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" -
Use the command line to list the tables in the running LiveView application:
lv-client listtables
-
Connect to the default URI and start the lv-client interactive shell:
lv-client -u lv://localhost:10080
-
Create a snapshot query that returns all rows from the
ItemsSales
table wherelastSoldPrice
is greater than 10 andquantityRemaining
is less than 20:SELECT * FROM ItemsSales WHERE lastSoldPrice > 10 AND quantityRemaining < 20;
-
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;"
-
The next two lines run at a StreamBase Command Prompt on Windows to 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 connstatThe 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