STREAM Online Help > Menu Command Reference
This section provides information on the commands available from the menu bar and context menus:
1. Register Stream
This command is used to register a stream schema with the system and to associate it with a given name. Streams are append-only sequences of tuples, and can be populated with either inputs to the system or by CQL views in the system. When selected, a window will be displayed that allows the user to enter in the stream name and stream attributes.
Valid stream and attribute names consist of one or more alphanumeric characters and must start with a letter. Reserved words like "select" and "count" are not allowed as stream or relation names or as attribute names.
Stream attributes should be listed in a comma-separated list of attributes, each of which is composed of an identifier followed by a type. If the data type is "char" it is followed by a length. In BNF, this is:
<attribute_list> ::= <attribute> {"," <attribute>} <attribute> ::= <identifier> <type> <type> ::= "char"<length>|"float"|"integer" <length> ::= <digit> {<digit>} <identifier> ::= <letter> {<letter>|<digit>} <letter> ::= "A"|...|"Z"|"a"|...|"z" <digit> ::= "0"|...|"9"Some examples of valid attributes are:
"firstname char20" - A character field (string) of length 20 with the name "firstname".
"age integer" - An integer field named "age".
"score float" - A floating point field named "score".Note that there currently is no way to deregister streams from the demo client.
2. Register Relation
This command is used to register a relation schema with the system and to associate it with a given name. (Relations differ from streams in that they support deletions as well as the insertions supported by streams.) When selected, a window will be displayed that allows the user to enter in the relation name and relation attributes. These must follow the same rules as in the Register Stream command.
Note that there currently is no way to deregister relations from the demo client.
3. Register CQL Query
Selecting this command will bring up a window that will allow the user to enter a query in CQL that will be executed by the system. The user can also decide how to have results reported back in one of the following formats:
- In a scrollable tabular format (default) with the result tuples displayed in increasing timestamp order from bottom to top of the results window. That is, more recent tuples are displayed on top. The results window is configured to display the 10,000 most recent updates to the query result. Once the number of result updates so far exceeds 10,000, the oldest ones are dropped from the bottom of the scrollable results window.
- A graph of the number of result tuples received at the client per second. For this format you need to check the "Statistics only" box.
- Printed to a local file by checking the "Write to File" box. You will be prompted for the file name.
A quick introduction to CQL is available here. We recommend that users of the demo read this introduction to CQL before attempting to register new queries. The CQL syntax supported currently by STREAM differs slightly from the example CQL queries that have appeared in papers and talks on CQL and also from the queries in the Stream Query Repository. The authoritative source on CQL query syntax supported currently by STREAM is available here.
3. Create CQL View
Selecting this command will create a CQL View Query. A CQL View Query has the same syntax as a standard CQL query. The difference is that the output is redirected into a stream or relation in the system. This stream or relation is specified by entering its name in the "Into" box of the dialog. Note that this stream or relation must first be registered with the system using the "Register Stream" or "Register Relation" menu option above. All tuples that are returned as a result of this query will flow into this stream or relation, which can be treated in the same way as an external stream or relation.
4. Drop Current Plan
Drops the query plan that is currently being displayed. This command will remove all plan entities associated with the corresponding CQL query or view from the system.
If no plan is currently displayed, this command has no effect.
5. Drop All Plans
Drops all query plans that have been registered by the client on behalf of the user. This command will remove all plan entities associated with the corresponding plans from the system. Note that some plans belong to queries that are necessary for the functioning of the client and these plans will not be dropped, e.g., the plan corresponding to "SELECT * from SysStream".
6. Exit
Closes the client. This command will not stop the server, and additional clients can later connect to the server.
1. Query Plan X: [CQL Statement]
At the top of the view menu is a list of all queries that have been registered with this server. Query plans are numbered in the order that the corresponding query was registered with the server.
Selecting a query from this list will display the corresponding plan in the plan display pane of the visualizer, where it can be examined and manipulated.
2. CQL View Plan X: [CQL Statement]
Next in the view menu is a list of all CQL views that have been registered with the server.
Like for CQL queries, selecting a view from this list will display its plan in the plan display pane of the visualizer, where it can be examined and manipulated.
3. Show Catalog
This command will display a list of currently registered streams and relations and their schemas. This list will be displayed in the plan display pane. Note that each CQL View is a stream or a relation, so it will be listed here. Since we do not support deregistration of streams or relations, each registering registered by the client will be listed here.
The script menu displays a list of available scripts that can be executed against the server.
1. [Script Name]
Selecting a script from the list of available scripts will cause it to be exectued on the server. Scripts can perform a number of tasks, including registering streams and relations, registering CQL queries, and registering CQL Views. When the script is running a progress bar will be displayed on the screen. If there is an error in script execution, an error message will be displayed. However, if the script is successful, there may be no notification of this fact. If the script successfully registers a query, this query will immediately appear in the view menu upon script completion.
The "Benchmark Setup" script, for example, registers a number of streams and relations related to the benchmark, then creates CQL Views to select into these streams and relations. Finally, it registers the output query the results of which are displayed to the user.
2. Refresh Script List
This command rescans the script directory to find any newly added scripts. The user can write his or her own scripts and add them to the directory [home dir]/.stream/scripts.
3. Script Syntax
Each line in a script file performs a specific task. Tasks include registering streams, registering relations, registering CQL queries, and specifying the queries corresponding to CQL Views. The syntax for each task has the form task name : task specification with the name and the specification of the task separated by a colon. Please note that the command for a task should appear completely in one line (i.e., no linebreaks in between) and a line should contain at most one command. If you are running the demo, then [home dir]/.stream/scripts in your file system contains the script files corresponding to each of the scripts seen from the Script Menu. It is useful to take a look at some of these script files.
3.1 Registering a Stream The task name is catalog and the task specification has the format register stream <stream name> (<schema of the stream>). The name and the schema of the stream have the same format as in the Register Stream command in the File Menu. For example:
catalog : register stream CarSegStr(car_id integer, speed integer, expr_way integer, dir integer, seg integer)
3.2 Registering a Relation The task name is catalog and the task specification has the format register relation <relation name> (<schema of the relation>). The name and the schema of the relation have the same format as in the Register Relation command in the File Menu. For example:
catalog : register relation CurCarSeg(car_id integer, expr_way integer, dir integer, seg integer)
3.3 Specifying the CQL Query for a CQL View First of all, note that the creation of a CQL View consists of two steps, and therefore two tasks: (1) First, the CQL View has to be registered with the data stream server. If the CQL View is a stream, then use the register stream <CQL View name> (<schema of the CQL View>) command above; otherwise, if the CQL View is a relation, then use the register relation <CQL View name> (<schema of the CQL View>) command. (2) Specify the CQL query that generates the CQL View, which is described next. The task name for specifying the query that generates the CQL View is view and the task specification has the format <CQL View name> : <Text of CQL query for the CQL View>. Examples:
view : CarSegStr : istream (select car_id, speed, expr_way, dir, x_pos / 5280 as seg from CarLocStr)
view : CurCarSeg : select CarSegStr.car_id, expr_way, dir, seg from CarSegStr partition by CarSegStr.car_id rows 1
3.4 Registering a CQL Query The task name is query and the task specification has the format <Text of CQL query>. Examples:
query: SELECT * FROM R ROWS 10, S ROWS 10 WHERE R.name = S.name
query : RSTREAM( SELECT E.car_id, E.seg, T.toll FROM CarSegEntryStr E [NOW], SegToll T WHERE E.expr_way = T.expr_way AND E.dir = T.dir AND E.seg = T.seg )
Stream sources can be used to send tuples from the client to the server. Stream sources for the CarLocStr stream used by the benchmark and several others are provided. However, the user can create his or her own stream sources from files containing comma-separated values such as the following example:
char20, float, int Hamburger, 2.49, 35 Cheeseburger, 2.99, 43 French Fries, 1.19, 20 ...The first line in the file specifies the schema for the data, and additional lines specify data tuples. Note that the whitespace between items is not necessary and is ignored.
1. [Stream Name]
Selecting a stream source from this list of available stream sources will bring up a stream source control window that allows the user to specify the rate at which tuples will be sent to the server. Clicking on the "Start" button in this window will begin sending tuples to the server. Tuples will continue to be sent until the "Pause" button is pressed, looping around the stream source file as many times as necessary.
2. Refresh List
This command rescans the script directory to find any newly added stream sources. The user can write his or her own stream and add them to the directory [home dir]/.stream/scripts.
3. Create New Source
Creates a temporary stream source from a comma-separated value text file as described earlier in this section. The user will be prompted for a stream name and a file containing the stream data.
A Note on Application-Defined Time
By default, the client adds a timestamp to each tuple, using the current system time at the machine where the client is running. A timestamp contains a seconds field and a microseconds field. If your data comes with timestamps, then you might want to make the stream server use these timestamps instead of the default local system time. To make the stream server use specified tuple timestamps all you have to do is to add a seconds (non-negative integer) and a microseconds (integer from 0 to 999999) field before each tuple in the data file. These two fields describe the tuple's timestamp. The schema specification in the first line of the data file remains unchanged as shown below:
char20, float, int 10, 0, Hamburger, 2.49, 35 10, 1000, Cheeseburger, 2.99, 43 20, 123, French Fries, 1.19, 20 ...
You can still control the rate at which the tuples are sent to the data stream server, and this rate will not have any effect on the tuple timestamps or the query result produced by the system.
Right clicking on an entity in the plan display will bring up the plan entity context menu. Currently, this menu only has one option:
1. Add Monitor
Adds a monitor to this entity. Plan entities in the system can report certain statistics to a special system monitoring stream named SysStream. If a monitor is registered on a particular statistic, the client will register an internal CQL query with the system to continuously retrieve the values of this statistic and display the results to the user. This query is a windowed aggregate query on the SysStream stream and will show up immediately in the View menu. (Note that the SysStream can be queried like any other stream.) The user can choose the statistic she wishes to monitor, the interval between reports (in seconds), and the number of previous values (steps) to be displayed.
After a monitor is registered, the user is presented with a graph next to the entity that tracks the value of the statistic over time. The number in the upper left corner of the graph is the maximum value on the y-axis (not the current value). To deregister a monitor, right-click on the graph and select "close monitor".
Right clicking on an unoccupied space in the plan display will bring up the plan context menu. This menu provides four options related to the visualization of the query and plan:
1. Show Query
Shows the CQL query text for the current plan.
2. Clean Up Layout
Resets all entities in the current plan that may have been moved, back to their default positions.
3. Increase Spacing
Increases the spacing between entities in the plan. Note that this will also clean up the layout.
4. Decrease Spacing
Decreases the spacing between entities in the plan. Note that this will also clean up the layout.