T eamcenter 10.1 Query Builder Guide Publication Number PLM00031 J Proprietary and restricted rights notice This softw are and related documentation are proprietary to Siemens Product Lifecyc le Management Softw are Inc © 2013 Siemens Product Lifecyc le Management Softw are Inc All Rights Reserved. Siemens and the Siemens logo are registered trademarks of Siemens AG T eamcenter is a trademark or registered trademark of Siemens Product Lifecyc le Management Softw are Inc or its subsidiaries in the United States and in other countries All other trademarks , registered trademarks , or service marks belong to their respective holders 2 Query Builder Guide PLM00031 J Contents Proprietary and restricted rights notice 2 Getting started with Query Builder 1-1 What is Query Builder? 1- 1 Before you begin 1- 1 Query Builder interface 1- 2 Basic concepts for using Query Builder 1- 9 Basic tasks using Query Builder 1- 9 Creating and managing queries 2-1 Creating customized searc hes using Query Builder 2- 1 Create queries 2- 1 Managing queries 2- 16 Using c lass attribute selections 2- 16 Using preferences when querying 2- 19 Using searc h criteria c lauses 2- 20 Managing the query hints file 3-1 Managing the query hints file 3- 1 Sample hints file 3- 1 Importing and exporting query definitions 4-1 Importing and exporting query definitions 4- 1 Import query definitions 4- 1 Export query definitions 4- 2 Application notes 5-1 Attribute index 5- 1 Best practices 6-1 Best practices 6- 1 Restore My Sa ved Searc hes folder 6- 1 Export sa ved searc hes to another T eamcenter installation 6- 2 Glossary A-1 Index Index- 1 PLM00031 J Query Builder Guide 3 Chapter 1 Getting started with Query Builder What is Query Builder? 1- 1 Before you begin 1- 1 Query Builder interface 1- 2 Sa ved Queries tree pane 1- 3 Sa ved query properties pane 1- 3 Localization button 1- 3 Searc h Class button 1- 3 Attribute Selection pane 1- 4 Searc h Criteria pane 1- 6 Ric h c lient perspectives and views 1- 8 Basic concepts for using Query Builder 1- 9 Basic tasks using Query Builder 1- 9 PLM00031 J Query Builder Guide Chapter 1 Getting started with Query Builder What is Query Builder? Query Builder allows you to create customized searc hes for objects in both local and remote T eamcenter databases Building query definitions requires knowledge of the T eamcenter POM (persistent object manager) sc hema, whic h is an hierarc hical arrangement of c lasses , subc lasses , and attributes Query definitions , also called saved queries , identify searc h criteria used to find information in T eamcenter Administrators define query definitions for end users F or example , you can create a sa ved query to find in the database all items that ha ve been shipped. F or more information about searc hing the T eamcenter database using sa ved queries , see the Ric h Client Interface Guide Before you begin Prerequisites Y ou do not need any special permissions to use the Query Builder application. Enable Query Builder Query Builder does not need to be enabled before you can use it, but during installation, this feature must be selected. If you ha ve trouble accessing Query Builder , see your system administrator; it ma y be a licensing issue Note Y ou can log on to T eamcenter only once If you try to log on to more than one workstation at a time , you see an error message Configure Query Builder Query Builder does not need to be configured before you use it. Start Query Builder Clic k Query Builder in the na vigation pane PLM00031 J Query Builder Guide 1-1 C h a p t e r 1 G e t t i n g s t a r t e d w i t h Q u e r y B u i l d e r Query Builder interface 1 Saved Queries tree pane Displa ys all sa ved queries in the database 2 Sa ved query properties pane Displa ys the name , description, query type , and searc h c lass of the sa ved query selected in the sa ved queries tree 3 Localization button Displa ys the Language T ranslations dialog box that lists existing translation values F or more information about the Localization button, see the Localization Guide 4 Search Class button Displa ys the Class/Attribute Selection dialog box that lists the query c lasses for selection. F or more information, see Searc h Class button 5 Attribute Selection pane Displa ys the attributes of the selected c lass and either all inherited c lass attributes or only the direct attributes of the c lass , depending on the displa y setting you select. F or more information, see Attribute Selection pane 1-2 Query Builder Guide PLM00031 J G e t t i n g s t a r t e d w i t h Q u e r y B u i l d e r 6 Search Criteria pane Defines the searc h criteria c lauses using attributes , user entry keys , operators , and default values Boolean operators are added for multiple searc h criteria c lause processing F or more information, see Searc h Criteria pane Saved Queries tree pane The Saved Queries tree pane displa ys all sa ved queries in the database When you select a sa ved query in the tree , the details are displa yed in the panes on the right side of the box. Saved query properties pane The sa ved query properties pane displa ys the name , description, query type , and searc h c lass of the sa ved query selected in the sa ved queries tree Y ou can modify these properties and then create or modify a sa ved query Y ou can delete the selected sa ved query Localization button Clic king the Localization button displa ys the Language T ranslations dialog box that lists existing translation values The presence of the Localization button indicates the dialog box content can be localized. F or example , if the master locale is set to English, you can add a translation for an employee information query Using the Localization button, you can perform the following tasks: • V iew the existing localization text. • Modify the existing localization text. • Add a translation value for a new locale without altering the master value of the property • Remove a translation value without altering the master value of the property F or more information about the Localization button, see the Localization Guide Search Class button Clic king the Search Class button displa ys the Class/Attribute Selection dialog box, whic h allows you to na vigate and searc h the T eamcenter POM sc hema and select c lasses and attributes for use in query definitions 1. Type the c lass name (or partial name of the c lass along with a wildcard) in the box at the top of the dialog box. 2. Clic k the Search button The number of c lasses matc hing your searc h are displa yed at the bottom of the dialog box, and the first result is highlighted in the tree PLM00031 J Query Builder Guide 1-3 C h a p t e r 1 G e t t i n g s t a r t e d w i t h Q u e r y B u i l d e r T o na vigate through the results: Go to next match Press F3, P age Down, or Down Arrow key Go to previous match Press the P age Up or Up Arrow key Go to first match Press the Home key Go to last match Press the End key Attribute Selection pane The Attribute Selection pane displa ys the attributes of the selected c lass and either all inherited c lass attributes or only the direct attributes of the c lass The following symbols indicate the attribute type Symbol Attribute type Character Character arra y Date Date arra y Double 1-4 Query Builder Guide PLM00031 J G e t t i n g s t a r t e d w i t h Q u e r y B u i l d e r Symbol Attribute type Double arra y Float Float arra y Integer Integer arra y Logical Logical arra y Short Short arra y String String arra y Typed reference Typed reference arra y Untyped reference Untyped reference arra y External reference External reference arra y Note Note arra y Typed relation Untyped relation Class External link default PLM00031 J Query Builder Guide 1-5 C h a p t e r 1 G e t t i n g s t a r t e d w i t h Q u e r y B u i l d e r Symbol Attribute type vi overla y Search Criteria pane When you perform your searc h, T eamcenter examines the attribute specified in eac h of your searc h c lauses and looks for values that matc h your searc h. F ollowing are the searc h criteria elements Element Description Boolean Rules The Boolean rules ( AND / OR ) are used to combine c lauses to create a custom query When you use AND c lauses together , both must be satisfied to return a matc h (both this c lause and that c lause). When you use OR c lauses together , either can be satisfied to return a matc h (either this c lause or that c lause). K eyword c lauses do not support the OR rule Note The indented searc h feature only supports AND c lauses F or more information about the indented searc h feature , see the Ric h Client Interface Guide Attributes The selected database attribute displa ys in this box. User Entry L10N Key Specifies the localization key used to look up user entry names The localization key-value pairs are defined in the qry_user_entry_names_locale.xml file The value in this column can be modified and must be unique within the searc h criteria definition. User Entry Name Displa ys the query box names as they appear in the searc h form. The user name is the value of the localization key entered in the User Entry L10N Key column. If the key-value pair is not defined in the qry_user_entry_names_locale.xml file , the user entry name is the same as the key entered in the User Entry L10N Key column. The value in this column cannot be modified. Logical Operators Matc hing values can be equal to , not equal to , less than, or greater than the value specified in your searc h c lause Matc hing values can also be null or not null. These conditions are called logical operators Y ou must specify one of the following logical operators in eac h searc h c lause Logical operator Description = Equal to != Not equal to > Greater than. >= Greater than or equal to 1-6 Query Builder Guide PLM00031 J G e t t i n g s t a r t e d w i t h Q u e r y B u i l d e r Element Description < Less than. <= Less than or equal to IS_NULL Indicates that the reference attribute value must be blank (not set). IS_NO T_NULL Indicates that the reference attribute must ha ve a value Note Logical operators can only be used for string attribute types Y ou can searc h for ranges of values using the > , >= , < , <= logical operators or invert searc h criteria using the != logical operator Default V alue Default values can be specified for the query c lauses Default values can be entered as a text string or selected from the associated list of values , where applicable After the value is set, press Enter to sa ve the default value This box is required only when you do not specify the user entry name , unless the logical operator IS_NULL or IS_NO T_NULL is used. The following keyword variables can be used to displa y default values in the query form: • $USERID • $USERNAME • $GROUP • $T ODA Y The values displa yed in boxes for whic h the $USERID , $USERNAME , and $GROUP variables are used as a default value correspond to the end user who is running the query The $T ODA Y variable displa ys the current date These variables are used in the default T eamcenter queries If you make any c hange to the default queries , the modified values are displa yed unless you explicitly enter the variable name over its displa yed value PLM00031 J Query Builder Guide 1-7 C h a p t e r 1 G e t t i n g s t a r t e d w i t h Q u e r y B u i l d e r Note Siemens PLM Softw are recommends the following when using the Search Criteria pane: • F or eac h c lause , make certain the User entry L10N key value is unique • When you use AND and OR c lauses together , the searc h result displa ys unexpected results Therefore , use the AND operator (rather than the OR operator) and place multiple default values in the Default value column separated by a semicolon, as shown in the following example Attribute User entry L10N key User entry name Default value object_name object_name Name = * AND object_type object_type Type = UGMASTER;DirectModel The Order By tab contains the following searc h criteria elements Element Description Attribute The selected database attribute appears in this box. User Entry L10N Key Specifies the localization key used to look up user entry names The localization key-value pairs are defined in the qry_user_entry_names_locale.xml file The value in this column can be modified and must be unique within the searc h criteria definition. User Entry Name Displa ys the query box names as they appear in the searc h form. The user name is the value of the localization key entered in the User Entry L10N Key column. If the key-value pair is not defined in the qry_user_entry_names_locale.xml file , the user entry name is the same as the key entered in the User Entry L10N Key column. The value in this column cannot be modified. Order By Specifies the sort order or overrides a default sort order defined for a sa ved query Eac h attribute can be set to arrange in either Ascending or Descending order F or more information about using the Order By tab , see Specify sort order f or a saved query Rich client perspectives and views W ithin the T eamcenter ric h c lient user interface , application functionality is provided in per spectives and views Some applications use perspectives and views to arrange how functionality is presented. Other applications use a single perspective and view to present information. Note Y our administrator can use the HiddenP erspectives preference to prevent the displa y of some T eamcenter perspectives in the ric h c lient. F or information about editing preference values , see the Preferences and Environment V ariables Reference 1-8 Query Builder Guide PLM00031 J G e t t i n g s t a r t e d w i t h Q u e r y B u i l d e r If your site has online help installed, you can access application and view help from the ric h c lient Help menu or by pressing F1. F or more information about ric h c lient perspectives and views , see the Ric h Client Interface Guide Basic concepts for using Query Builder Depending on your needs , you can use an existing query from the sa ved queries tree Sa ved queries are subject to standard object protection and are accessed by users through the searc h feature in My T eamcenter F or more information, see Create a new query based on an existing definition Y ou can also use Query Builder to create queries based on the following features: • Queries using the hints feature • Queries that inc lude a keyword searc h • Queries based on an existing definition • Queries using the IS_NULL or IS_NO T_NULL operators • Referenced-by queries • Queries based on c lassification attributes • Subc lass queries on a typed reference Once created, query definitions can be exported and sa ved as XML files that can be shared with other T eamcenter sites Conversely , query data sa ved in XML files can be imported into T eamcenter The XML files are parsed and verified before the data is imported. F or more information, see Importing and exporting query definitions Basic tasks using Query Builder Query Builder is a T eamcenter administrative application that is used to perform the following tasks: • Create customized searc hes for objects in both local and remote T eamcenter databases • Store query hints in the query hints file , queryHint.xml • Export query definitions sa ved as XML files , whic h can be shared with other T eamcenter sites • Import into T eamcenter query definitions sa ved as XML files F or more information about these tasks , see Creating customized searc hes using Query Builder , Managing the query hints file , and Importing and exporting query definitions PLM00031 J Query Builder Guide 1-9 Chapter 2 Creating and managing queries Creating customized searc hes using Query Builder 2- 1 Create queries 2- 1 Create a query using the hints feature 2- 3 Create a query that inc ludes a keyword searc h 2- 6 Create a new query based on an existing definition 2- 7 Create a query using the IS_NULL or IS_NO T_NULL operator 2- 7 Create a referenced-by query 2- 8 Create a sa ved query on c lassification attributes 2- 11 Create a sa ved query using a revision rule 2- 12 Specify sort order for a sa ved query 2- 12 Create a subc lass query on a typed reference 2- 12 Managing queries 2- 16 Modify a query 2- 16 Delete a query 2- 16 Using c lass attribute selections 2- 16 Add c lass attributes to searc h criteria 2- 18 Using preferences when querying 2- 19 Using searc h criteria c lauses 2- 20 Searc h criteria c lause example 2- 21 Assign precedence to c lauses 2- 21 Remove c lauses from the table 2- 22 PLM00031 J Query Builder Guide Chapter 2 Creating and managing queries Creating customized searches using Query Builder Query Builder allows you to create customized searc hes for objects in T eamcenter databases When using Query Builder to create a query , you must provide the following information: • The searc h c lass for the query F or more information, see Using class attribute selections • At least one searc h criteria c lause F or more information, see Using searc h criteria clauses Create queries 1. Clic k the Clear button to remove existing information from the Query Builder boxes 2. In the Name box, type a unique name for the query 3. Optionally , type a description of the query in the Description box. 4. Select Local Query from the Modifiable Query T ypes list. 5. Clic k the Search Class button The Class/Attribute Selection dialog box appears PLM00031 J Query Builder Guide 2-1 C h a p t e r 2 C r e a t i n g a n d m a n a g i n g q u e r i e s 6. Specify the desired searc h c lass by selecting an entry from this dialog box. T ip Y ou can significantly expand or narrow the focus of your query depending on the c lass you select. It is best to limit the searc h to the lowest possible c lass in the hierarc hy T o locate a c lass , type the c lass name (or partial name and wildcards) in the box at the top of the dialog box, and c lic k the Search button The number of c lasses matc hing your searc h are displa yed at the bottom of the dialog box, and the first result is highlighted in the tree T o na vigate through the results: Go to next match Press F3, P age Down, or Down Arrow key Go to previous match Press the P age Up or Up Arrow key Go to first match Press the Home key Go to last match Press the End key 7. T o displa y the searc h results in an indented or hierarc hical form, select Show Indented Results 8. Double-c lic k to select at least one of the attributes in the Attribute Selection tree Direct attributes of the c lass are displa yed in the tree Reference c lasses and attributes can be accessed by double-c lic king the Referenced By node in the attribute tree 2-2 Query Builder Guide PLM00031 J