The Query page provides access to form-based queries.
Topics:
- How do I select a query?
- How do I run a query?
- How can I print a query result?
- How can I import data from the query result?
- What does the View Latest button do?
- How do I include the results of a query in a report?
See Also:
How do I select a query?
By default all the queries are shown in a table grouped by Category. Simply click on a query in the table to access the query form. If you want to list only the queries within a particular Category, set the Category in the filter bar at the top of the page.
To return to the list of queries, change the Category or Section filters at the top of the page to All.
Finally, you can use the Sentinel:Search>Report function to search for reports using keywords.
Note: Queries are referred to as Sections in the list because they can be included as sections in reports (see Sentinel:Report>Edit).
How do I run a query?
A query form has a tabular structure. Each row is used to specify a particular query parameter. The first column contains the parameter name, the second column contains the parameter input box, the third column may contain a "helper tool" that assist in filling in the input box and finally there may be a fourth column indicating any parameter values that are missing or have errors.
It is usually easier to set parameters using the helper tools rather than typing in settings directly into the input boxes. There are a number of types of helper tool:
- common options, consists of a selection box containing common values for the input. Changing the value in the helper sets the value of the input. Type directly into the query input box if you want to use a value that isn't in the list.
- list builder, consists of a selection box containing possible items to add to the input list. To add an item to the input list select it and click on the Add button. To clear all the items in the input list, click on the Clear button.
- filter builder, consists of a selection box containing attributes that can be compared, a selection box containing comparison operators and an input area to specify that values to be compared to the selected attribute. Clicking the Add button appends the comparison to the current filter. There are also boolean operator buttons (& and |) and bracket buttons that can be used to combine comparison expressions to form more complex filters. The filter builder only enables buttons and inputs when they are allowed in the filter expression that is being constructed.
Query forms may have a number of different inputs. There may be Usage information at the bottom of the form giving brief, form specific, instructions. In addition,there are a number of common fields that are found in many queries, including: Interval, Truncate, Group and Where.
The Interval input is specifies the time period over which the query will be run.
There are a number of predefined intervals, including:
- today
- yesterday
- thisweek
- lastweek
- thismonth
- lastmonth
- last24hours
- last7days
- last30days
- now - 2hours
- last tuesday
- midnight + 45 minutes
- 10pm yesterday,9am today
- 20051230
- 20051230,20060104
- 20080418 18:00, 20080419 20:00
- 20080418 6pm, 20080419 8pm
The Truncate input specifies the number of rows of result to be returned. Values from any truncated rows will be summed and will appear as one additional row at the bottom of a table, or as an Other category in a chart.
Note: If a result table contains fewer rows than the number specified by the truncate setting, then you will be sure that you have details for all the records that matches the query settings. A large truncate value can be used ensure that all records are returned. In this case you should still select a truncate value that ensures that the query won't fail because the server runs out of memory and that your web browser won't fail trying to display the result. A value of 1,000 is usually sufficient for most purposes.
The Group input is used when computing time series to specify the size of each time grouping within the overall query interval.
The group size can be specified either as a number of minutes, or using special tokens. The following examples show typical group values:
- 5
- minute
- hour
- day
- week
- month
- year
Finally, the Where input is used to specify a filter that will be applied during the query to select specific data.
A basic filter expression consists of the name of an attribute, an operator and a set of comma separated values. The allowed operators are:
- = equals
- != not equals
- ~ matches a reqular expression
- !~ does not match a regular expression
Expressions can be combined using brackets and the boolean operators:
- & boolean AND
- | boolean OR
The following examples illustrate typical where filters:
- ipsource = 10.1.1.23
- ipdestination != 10.0.0.0/24,10.0.1.0/24
- serverport = TCP:80,TCP:81,TCP:8080-8088
- sourcezone ~ research.*
- ipsource = 10.0.0.1 & ipdestination = 10.0.0.2
- ipsource = 10.0.0.1 & (sourceport = TCP:80 | destinationport = TCP:80)
- sourcezone = EXTERNAL | destinationzone = EXTERNAL
Note: The special zone EXTERNAL refers to addresses that aren't contained in any of the CIDRs specified using File > Configure.
WARNING Care should be taken if a value in a filter expression contains any of the following special characters: (, ), &, |, !, =, ~, ",', \, comma or space. If the value contains any of these characters then the whole value string can be enclosed in single or double quotes, or the special characters can be individually escaped with a \. The following examples show different ways of using the value "Research & Development" in filters:
- serverzone = "Research & Development", Sales
- clientzone = 'Research & Development'
- sourcezone = Research\ \&\ Development
- serverpath = ">>Research & Development>Data Center"
Note: Special characters typically occur because they are used in Zone or Group names when configuring Traffic Sentinel (see File>Configure). Care should be taken when filtering on zone, group or path attributes.
Once the query parameters have been specified, click on the Submit button to run the query. If there are any errors in the inputs the form will be returned with the errors highlighted, otherwise the query result will be shown.
Click on the Defaults button to restore all the inputs to their default values. Click on the Reset button to restore the inputs to the values the last time you ran the query.
How can I print a query result?
When viewing the results of a query the two buttons, PDF and HTML provide access printer friendly versions of the result. Click on the PDF button to access the result in Adobe's Portable Document Format (PDF). If you have a PDF viewer installed then it should automatically launch and display the result. You can use PDF viewer to print the result. Alternatively, you can click on the HTML to access a copy of the result without navigation bars. Use your web browser to print the result.
How can I import data from a query result?
When viewing a query result you will notice small TXT, HTML and possibly Image links below each chart and table in the table. Click on the TXT button to get a text version of the data (in comma separated value format). Click on the HTML link to access the data as an HTML table. Click on the Image button to access the the chart image.
Copy the URL associated with the data if you want to import data into other tools (such as Excel or Perl).
What does the View Latest button do?
If an existing report contains a section that matches the query then the View Latest button will select the report and section in the View page.
How do I include the results of a query in a report?
The Copy to Editor button will be enabled if you have a report open in the Sentinel:Report>Edit page. Clicking on the button will switch to the Edit page and add a section matching the current query results. The new section can be modified to add a title and description (see How do I change section settings?).
Note: If the Copy to Editor button is disabled, click on the Edit tab and open an existing report, or create a new report. Return to your query results and the button will be enabled.