Retrieve elements by searching

Before you retrieve elements, you need to Specify a database.

You can use PI Builder to search for elements in a PI AF database, and then select the elements to retrieve into Microsoft Excel.

1. On the PI Builder tab, click Elements > Find Elements to open the Element Search window.

2. In the Results table, select the elements you want to retrieve into the worksheet and click OK.

   Note: To retrieve all the elements from the results table into the worksheet, select none of the elements and click OK. Beginning with PI Builder 2018, this also overrides the Results per Page setting and returns all results that match your search criteria.

3. Choose from the following actions:

   To ...	Do this ...
   Type one or more filter conditions directly into the Enter element criteria field	Use the : or := operator to select elements that match a name, description, template, and category. Use special characters as needed. For more information, see Special characters in name searches. Enclose strings that contain spaces or special characters with the " character. Separate filter conditions with a whitespace, for example: Category:"Processing Plants" Name:Cracking Beginning with PI AF 2018 SP2, you can use OR conditions when typing directly. For example: "Name:’ElementName’ (|Attribute1:>5 OR |Attribute2:<2)" "Description:’TestDescription’ OR Name:’TestName’"
   Filter elements under Criteria	Enter values in the following fields as needed. Click Add Criteria to enter criteria for additional fields.

   • Name

     Enter the name of the element to retrieve, based on the filter type. You can enter special characters to match part of a name. See Special characters in name searches.

   • Element Search Root

     Enter the element that you want to use as the root or base level for the element search. Type the exact name or click to open the Element Browser window, where you can view the element hierarchy and select an element. You cannot include wildcard characters in the entered name. If you do not specify an element, you set the main level of the element hierarchy as the root.

     Depending on your PI AF hierarchy, specifying an element in the Element Search Root field can improve search performance.

   • All Descendants

     Select True to retrieve any sub-element in the hierarchy that matches the specified criteria. Select False to retrieve only root-level elements that match the specified criteria.

   • Template

     Select the template that retrieved elements must be based on. After you select a template, you can add criteria to find elements by attribute value.

   • Category

     Select the category that retrieved elements must match.

   • Attribute Value

     • You can specify up to three conditions for an attribute value. For each condition, specify an attribute name, operator, and attribute value, such as Temperature >= 98.

     • In versions prior to PI AF 2018, only available when you specify a template. For more details, see Configure search conditions for attribute values when a template is specified.

     • In PI AF 2018 and later versions, you can specify attribute values without needing to specify a template. For more details, see Configure search conditions for attribute values when no template is specified.

   • Description

     Enter a string (of up to 440 characters) that retrieved elements must match.

   • Element Type

     Select the type that retrieved elements must match.

   • Is Annotated

     (PI AF 2017 or later versions.) Set to True to retrieve only elements that have annotations. Set to False to retrieve only elements that do not have annotations.

   • Creation Date

     (PI AF 2017 or later versions.) Select an operator and enter a date or a PI time abbreviation ( >= *-30d is the default) to retrieve elements that were created in the specified period. You can also click to select a date in the Date and Time Picker window. You can select Creation Date a second time and filter the search for results between two values (< *+1d is the default).

   • Modify Date

     (PI AF 2017 or later versions.) Select an operator and enter a date or a PI time abbreviation ( >= *-30d is the default) to retrieve elements that were modified in the specified period. You can also click to select a date in the Date and Time Picker window. You can select Modify Date a second time and filter the search for results between two values (< *+1d is the default).

     Note: An element's modify date is updated whenever an annotation or child element is added, as well as when a change to its configuration is checked into the database. Most template changes, or any modification to an attribute value that is not a configuration item, will not affect an element's modify date.

   • Results per Page

     Enter the maximum number of elements to show on a single page of the search results.

4. Optional. Specify how you want results to be displayed in the Results table.

   To ...	Do this ...
   Group by template	Select the Template check box.
   Group by category	Select the Category check box.
   Change column selections	Right-click the column heading in the Results table or the white space below. Click Column Visibility. Select or clear column selections as needed.
   Display attributes as columns	Click  and click Select Attributes. In the Select Attributes window, use standard Windows keystrokes to highlight contiguous (SHIFT+<click>) or non-contiguous (CTRL+<click>) attributes. Click . Click OK.
   Display full paths of elements	Right-click the column heading in the Results table or the white space below. Click Show Full Paths.
   Conceal full paths of elements	Right-click the column heading in the Results table or the white space below. Click Hide Full Paths.

5. In the Results table, select the elements you want to retrieve into the worksheet and click OK.

   Tip: To retrieve all the elements from the results table into the worksheet, select none of the elements and click OK. Beginning with PI Builder 2018, this also overrides the Results per Page setting and returns all results that match your search criteria.

6. In the Select Object Types and Column Headers window, select the objects and column headers that you want to appear in the worksheet.

   Note: Use the Template field to retrieve attributes from a template. The attributes defined by the selected template are displayed in the Attributes Columns (from Template 'name') group in the Object Types list.

   If you want to retrieve:	Then:
   Elements from all levels of the hierarchy into the worksheet	Select the Child Elements check box from the Object Types list.
   Information about references to other elements	Select the Element References check box from the Object Types list.
   Attributes into separate rows	Select columns in the Attribute group. With attributes shown in rows, you can edit information about the attributes. See Show attributes in rows.
   Attributes in multiple columns	Select columns in the Attribute Columns group. With attributes shown in columns, you can only edit the attribute value or configuration string. See Show attributes in columns.
   Analyses for the elements	Select columns in the Analysis group.

   See Element columns for a list of available columns for elements.

7. Click OK to retrieve the selected elements into the worksheet and fill the selected columns with any data for those elements.