# 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. ![](https://1981611109-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LthAmlGL8PG1hh-vzkV-1703796690%2Fuploads%2F0tUIJLWj6zu08jyMIzqb%2Fimage.png?alt=media\&token=1414977e-55dd-416d-984f-a174a03f948f) {% hint style="info" %} ### **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**](https://docs.ardexa.com/knowledge/app.ardexa/audit_logs#who-can-access-and-view-audit-logs). {% endhint %} ### 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**

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: ![](https://1981611109-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LthAmlGL8PG1hh-vzkV-1703796690%2Fuploads%2FwP2gafS6QkdUzNSO6I8H%2Fimage.png?alt=media\&token=e3b8d5b3-3203-4d8e-97db-574331a7b8ab) ## Building your **S**earch **- Inputs** ### Common time-frames ![](https://1981611109-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LthAmlGL8PG1hh-vzkV-1703796690%2Fuploads%2FjJCbiV6X1bvaqczdKSzL%2Fimage.png?alt=media\&token=034a44e8-d44c-457e-abea-6c28534ddca0) 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

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 style="info" %} **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. {% endhint %} {% hint style="warning" %} ### 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 as`custom.` 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. {% endhint %} #### 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

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](https://1981611109-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LthAmlGL8PG1hh-vzkV-1703796690%2Fuploads%2F3TbP0zGEnQUlzHS0ykX1%2FScreenshot%20from%202024-10-31%2011-10-28.png?alt=media\&token=181cbc9f-72b1-46dd-823e-62f6d6fe567c) #### 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.

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. ![](https://1981611109-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LthAmlGL8PG1hh-vzkV-1703796690%2Fuploads%2FlUVJ0Ul3fJLv7nRPVyLs%2FScreenshot%20from%202024-10-31%2016-15-12.png?alt=media\&token=3ca5651f-c7c1-4588-b602-5d3427d3bcd3) #### 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. ![](https://1981611109-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LthAmlGL8PG1hh-vzkV-1703796690%2Fuploads%2FAjOYPfmeY7OnfnIFU9O6%2FScreenshot%20from%202024-10-31%2016-28-59.png?alt=media\&token=15f79cca-9239-429a-bbc2-247fc0c73c85) ### 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` ![](https://1981611109-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LthAmlGL8PG1hh-vzkV-1703796690%2Fuploads%2F3CYGxshvpBS3UKgGe43V%2FScreenshot%20from%202024-10-31%2018-41-42.png?alt=media\&token=73aedc0e-0d24-4894-9e22-4f8970f5d166) 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 {% hint style="info" %} **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" {% endhint %} ![](https://1981611109-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LthAmlGL8PG1hh-vzkV-1703796690%2Fuploads%2FbGfdkpWr6FekoRH8KuOe%2FScreenshot%20from%202024-10-31%2018-45-45.png?alt=media\&token=11842684-4a36-416e-bc8d-e391a0c26dfb) {% hint style="info" %} **Note:** the following core fields will always be provided: * `source` * `device` * `event_time` {% endhint %} ## **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`* {% hint style="info" %} **NOTE:** Like **`audit_logs,`** similar rules apply to searches against the**`incident_logs`** table. Please refer to the [***Audit Logs***](https://docs.ardexa.com/knowledge/app.ardexa/audit_logs#about-audit-logs) section for reference. {% endhint %} Further information on [*Audit Logs* are provided **here**](https://docs.ardexa.com/knowledge/app.ardexa/audit_logs#about-audit-logs).