homeappabout

Creating Searches

Building a New Search

Selecting a table

The first step for creating a new search is selecting the table containing the data you wish to query. Multi-table searches are not currently supported in the Ardexa Cloud.

Table Availability

All of the following conditions must be met for a table to be available for selection in the tables list:

  • the table must already exist, and be populated with data

  • the user must have the necessary permissions to view the desired table, as explained here.

The Search Page

After selecting a table, the app will populate the rest of the Search page, enabling you to run queries and view results.

Total Available Records

When you first select a table, the total number of records in the table are immediately displayed in the upper-left corner of the view.

Running a Search

The GO Search_-_GO_Button.png button, found on the right-hand side of the page is used to execute a search with the currently selected options.

If you change your search options, you will need to press GO to update the results section. A refresh icon will be displayed at the top of the search results to indicate this:

Building your Search - Inputs

Common time-frames

A search time-frame is period from which you would like the data to be retrieved from the selected table.

Common timeframes are a list of preset periods that are provided by the Ardexa Web App to you for easy selection.

The default value is Last 7 days. If you were to click Search_-_GO_Button.png button with today selected, this example common time-frame would attempt to retrieve all records from the selected table from midnight (last night) until 11pm, 59 minutes today in your local time.

As an example, Last 7 days may translate to: 

Start: 29/09/2023 00:00     End: 06/10/2023 23:59

The [Common timeframes] field offers the custom value at the end of the drop-down selection list. A custom value allows you to set a specific time-frame including hours and minutes. Custom values are not relative to your present time, i.e. they are fixed.

Hint: if you wish to review the literal translation of a pre-set Ardexa [Common timeframe], then do the following:

  1. Select a pre-set Common timeframe value from the list, eg,this month then,

  2. Select the value custom after your initial selection; the literal timeframe translations will now appear in the view.

Note: custom time frames - vs -Common timeframes

However, keeping the selected value as custom will maintain the literal values against the search should you ever decide to save the search.

This is important when you come to retrieve a saved search, as you will be supplied the literal time frames from the past if the value of Common timeframe is kept ascustom.

Hence, the pre-set, relative Common timeframe will not be applied if it is saved with a value of custom. More on the behaviour of custom selection and saved searches below.

Date field

By default, the timeframe will use the built-in event_time field when applying the filter. This may not always be desirable, such as uploading historical data from a database. To change the date field used when applying the Timeframe, simply click the icon on the left of the timeframe box and select the alternate field you wish to use.

Timezones

By default, searches will be run using your local time zone to evaluate the search Timeframe. This can be customised by choosing a different Timezone option in the Timezone drop down:

Setting a specific timezone for a search

Valid options are Local (your current timezone), UTC or a specific timezone specified by location, chosen from the available options.

Preset Timeframe options (Today, Yesterday, Last 7 days) will use the selected timezone to evaluate the exact Timeframe for the search.

Setting a Custom Timeframe with Start and End times will use the selected timezone. Changing the selected timezone will update these times to the local time in the new timezone that is equivalent to the previously specified times.

Specifying a custom search timeframe, in Australia/Sydney time
The same timeframe, expressed in UTC

If you need exact control over the Timeframe and/or time zone used in a search, select a Timeframe of All Time and add one or more filters on a date/time field in your search. These filters accept ISO-8601 timestamps, for example:

Specifying an exact timeframe via filters with ISO-8601 timestamps

Filters

Search filters allow you to selectively determine which records to retrieve from your table by applying custom rules as filters. Filters are used to include or exclude data from being returned in your search. They can be simple or very complex.

A filter is not necessary to run a search; at it's most basic, without a filter, a search will return all records in the table.

A complex search filter

Groups

Filter Groups allow several filters to be evaluated together. By default, searches are created with a single AND group.

AND groups will evaluate all filters in the group, and return records that meet every filter criteria. OR groups will evaluate all filters in the group, and return records that meet at least one filter criteria.

To add a filter to a group, click the ADD FILTER button.

Filters can be nested by adding additional groups via the ADD GROUP button.

Filters

Individual filters are created against a specific field in the selected table, with an operator and zero or more values. Available operators will depend on the data type of the selected field.

Filter operators for a keyword field
Filter operators for a numeric field

Numeric, text and date filter values can be entered in the filter value input.

Special fields that map to a specific object in the Ardexa Cloud such as Alert, Device, Source (when a Device has been selected in another filter) User and Entity will allow values to be selected from a drop-down list.

Run the Search

Click the GO button to execute your search.

Search Outputs

Search Outputs define how search results will be presented. Changing these options will require the search to be re-run for the changes to appear. Multiple output options can be enabled on the same search to view different representations of the data returned by the search.

Table Output

Tabular output is enabled on all searches by default. Toggling the Enable option on the TABLE output tab will enable/disable this option.

Rows

This option limits the maximum number of records displayed in the table. Up to 10 thousand records can be displayed by a simple search in the Table view.

Date format

This option defines how date fields should be formatted in search results. Options are:

  • Long (default): formats the date in a "Long" format, according to your browser settings / locale

  • ISO: formats the date as an ISO-8601 date/time

Output timezone

This option controls which timezone the results will be displayed in. The options are:

  • Selected timezone (default): translates all dates into the timezone selected in the Timezone option on the search. This option is useful for sequencing events collected in different timezones.

  • As collected: displays all dates in the timezone in which they were collected. This option is useful for troubleshooting issues in a device's local time, or identifying data collected in an incorrect timezone

Columns

This section controls which fields will be displayed as columns in the table. To add a column, drag it from the "Hidden Columns" section and drop it in the Columns list. Columns can also be re-ordered via drag and drop.

To find a specific column in a table with many fields, use the filter on the Hidden Columns section.

The Add all / Hide all buttons can also be used to quickly add/remove multiple fields. The fields list also supports Ctrl- and Shift- click to select multiple fields.

Customization Settings

This section controls some specialised options for dealing with search results.

Only show duplicate records

This option will display duplicate records only. Handy for problem data analysis.

Only show device fields

A single search table may potentially be populated by many devices and their sources. This scenario will result in many data columns in your search tables, with some of these columns not being relevant to other devices. Yet, at times you may only be interested in viewing data and columns populated by a particular device or devices.

You can use this switch in a search to limit the display columns to fields logged by scenarios on a device selected in your search filters.

  • This switch will remove all columns for display that are not associated to a device mentioned in your search's filters.

  • This allows you to focus on columns that are sourced from specific device fields. A handy tool when a given table is sourced from a multitude of devices. In this scenario, fields on other devices also populate columns to the same table under search, however they are not relevant to you in your current search parameters, in which case the Device Only Fields switch can assist you.

  • When activated, columns displayed are reduced where a search filter of device and it's value are provided in your search filters.

  • Filters using the operators IN LIKE and = are evaluated.

Example - Using the Device Only Fields Switch.

Consider the following example where we have a complex nesting of search filters using various devices in the workgroup.

  • The columns in this table agent-black-box are sourced from the device test-pi

To restrict table columns to those fields only sourced from test-pi we would need to do the following:

  1. Include the device in a search filter (any filter)

  2. Enable the "Only show device fields" option

Note: If all devices provided in the search filter are not source providers for the table then all the available columns will disappear.

To return your search columns, either;

  • correct your search filter, or

  • disable "Only show device fields"

Note: the following core fields will always be provided:

  • source

  • device

  • event_time

Understanding Search Results

Concept: resolved data vs raw data

Search fields contain a variety of resolved data and raw data. Where the data for a particular field is resolved, the option to search against that data is provided to the user as a pre-defined list in a dropdown. eg:

Fields containing resolved data:

  • [user_id] will resolve to a list of user names within the current workgroup.

  • Precise data matches can only be used for operators LIKE, NOT LIKE, IN, NOT IN

Fields containing raw data:

  • [action] being a potentially endless list is not provided as a resolved list for selection.

  • Precise data matches are not necessary for operators LIKE, NOT LIKE, IN, NOT IN. Hence, wildcards can be used.

Working with Logs

Events, such as device activity, source activity and user actions are collected and stored in the audit_logs and incident_logs tables for later interpretation.

incident_logs

Incident logs capture events from alerts that have been pre-created under the [ALERTS] tab. The extent and variety logged are only limited by the definition and number of the alerts you create.

Access

  • User role(s) of type: owner, admin, power, standard, read-only

NOTE: Like audit_logs, similar rules apply to searches against theincident_logs table. Please refer to the Audit Logs section for reference.

Further information on Audit Logs are provided here.

PreviousSearchesNextSharing Searches

Last updated

Was this helpful?