Traffic Sentinel : Help
Help Index Top > Report > Query

The Query page provides access to form-based queries.

Topics:

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).

Back to Top

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:

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:

In addition, time intervals can be specified in the same format as the Unix at(1) command. If necessary the interval can be specified in the form start,stop where the interval runs from the start of the first inteval to the start of the second interval. The following examples demonstrate typical custom time intervals:

The resolution used to compute time intervals is determined by the highest resolution token. For example "midnight + 45 minutes" has a resolution of minute and will generate a 1 minute interval starting at 15 minutes past midnight and "now - 2hours" has a resolution of hour and will generate an interval that falls on an hour boundary and extends for 1 hour.

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:

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:

Expressions can be combined using brackets and the boolean operators:

The following examples illustrate typical where filters:

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:

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.

Back to Top

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.

Back to Top

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).

Back to Top

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.

Back to Top

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.

Back to Top