SIEMENS

Teamcenter 11.3

Query Builder
PLM00031 • 11.3
Contents

Getting started with Query Builder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-1

What is Query Builder? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-1

Before you begin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-1
Query Builder interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-2
Query Builder interface overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-2
Saved Queries tree pane . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-2
Saved query properties pane . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-3
Localization button . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-3
Search Class button . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-3
Attribute Selection pane . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-4
Search Criteria pane . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-6
What are perspectives and views? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-9
Basic concepts for using Query Builder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-9
Basic tasks using Query Builder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-9

Creating and managing queries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-1

Creating customized searches using Query Builder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-1

Create queries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-1
Create a generic query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-1
Create a query using the hints feature . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-3
Create a query that includes a keyword search . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-6
Create a new query based on an existing definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-7
Create a query using the IS_NULL or IS_NOT_NULL operator . . . . . . . . . . . . . . . . . . . . 2-7
Create a referenced-by query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-8
Create a saved query on classification attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-10
Create a saved query using a revision rule . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-11
Create a saved query for name-value properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-11
Create a saved query for table properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-11
Specify sort order for a saved query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-13
Combining full-text search with metadata queries . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-13
Create a subclass query on a typed reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-14
Managing queries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-17
Modify a query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-17
Delete a query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-18
Using preferences when querying . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-18
Using class attribute selections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-19
Selecting class attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-19
Add class attributes to search criteria . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-21
Using search criteria clauses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-21
Defining search criteria . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-21
Search criteria clause example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-22
Assign precedence to clauses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-23

PLM00031 11.3 Query Builder 3

 Contents
Contents

Remove clauses from the table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-23

Creating property finder formatter (PFF) objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-23
Property finder formatter (PFF) basics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-23
Create a property finder formatter (PFF) object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-24

Managing the query hints file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-1

Updating the query hints file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-1
Sample hints file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-1

Importing and exporting query definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-1

Overview of 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

Restore My Saved Searches folder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-1
Export saved searches to another Teamcenter installation . . . . . . . . . . . . . . . . . . . . . . . . . . 6-2

Glossary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-1

4 Query Builder PLM00031 11.3

Chapter 1: Getting started with Query Builder

What is Query Builder?

The Query Builder application in Teamcenter allows you to create customized searches for objects
in both local and remote Teamcenter databases. Building query definitions requires knowledge of
the Teamcenter POM (persistent object manager) schema, which is an hierarchical arrangement of
classes, subclasses, and attributes.
Query definitions, also called saved queries, identify search criteria used to find information in
Teamcenter. Administrators define query definitions for end users. For example, you can create a
saved query to find in the database all items that have been shipped.

Note
Query Builder does not support run-time and compound properties.

Before you begin

Prerequisites You do not need any special permissions to use the Query Builder application.
Enable Query Query Builder does not need to be enabled before you can use it, but during
Builder installation, this feature must be selected.
If you have trouble accessing Query Builder, see your system administrator;
it may be a licensing issue.

Note
You can log on to Teamcenter only once. If you try to log on to
more than one workstation at a time, you see an error message.

Configure Query Query Builder does not need to be configured before you use it.
Builder
Start Query Builder
Click Query Builder in the navigation pane.

PLM00031 11.3 Query Builder 1-1

 Chapter
Chapter 1: 1: Getting
Getting started
started with Query
with Query Builder
Builder

Query Builder interface

Query Builder interface overview

1 Saved Queries tree Displays all saved queries in the database.

pane
2 Saved query Displays the name, description, query type, and search class
properties pane of the saved query selected in the Saved Queries tree.
3 Localization button Displays the Language Translations dialog box that lists
existing translation values.
4 Search Class button Displays the Class/Attribute Selection dialog box that lists
the query classes for selection.
5 Attribute Selection Displays the attributes of the selected class and either all
pane inherited class attributes or only the direct attributes of the
class, depending on the display setting you select.
6 Search Criteria Defines the search criteria clauses using attributes, user entry
pane keys, operators, and default values. Boolean operators are
added for multiple search criteria clause processing.

Saved Queries tree pane

The Saved Queries tree pane displays all saved queries in the database. When you select a saved
query in the tree, the details are displayed in the panes on the right side of the box.

1-2 Query Builder PLM00031 11.3

 Getting started with Query Builder

Saved query properties pane

The saved query properties pane displays the name, description, query type, and search class of the
saved query selected in the Saved Queries tree. You can modify these properties and then create or
modify a saved query. You can delete the selected saved query.

Localization button
Clicking the Localization button displays the Language Translations dialog box that lists
existing translation values.
The presence of the Localization button indicates the dialog box content can be localized. For
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:
• View 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.

Search Class button

Clicking the Search Class button displays the Class/Attribute Selection dialog box, which allows
you to navigate and search the Teamcenter POM schema and select classes and attributes for
use in query definitions.
1. Type the class name (or partial name of the class along with a wildcard) in the box at the top of
the dialog box.

2. Click the Search button .

The number of classes matching your search are displayed at the bottom of the dialog box,
and the first result is highlighted in the tree.

PLM00031 11.3 Query Builder 1-3

 Chapter
Chapter 1: 1: Getting
Getting started
started with Query
with Query Builder
Builder

To navigate through the results:

Go to next Press F3, Page Down, or Down Arrow key.
match
Go to previous Press the Page Up or Up Arrow key.
match
Go to first Press the Home key.
match
Go to last Press the End key.
match

Attribute Selection pane

The Attribute Selection pane displays the attributes of the selected class and either all inherited class
attributes or only the direct attributes of the class. The following symbols indicate the attribute type.

Symbol Attribute type

Character

Character array

Date

Date array

Double

Double array

1-4 Query Builder PLM00031 11.3

 Getting started with Query Builder

Symbol Attribute type

Float

Float array

Integer

Integer array

Logical

Logical array

Short

Short array

String

Note
LongString attributes cannot be used in queries.
Use full-text search to search for LongString attributes.

String array

Typed reference

Typed reference array

Untyped reference

Untyped reference array

External reference

External reference array

Note

Note array

Typed relation

Untyped relation

PLM00031 11.3 Query Builder 1-5

 Chapter
Chapter 1: 1: Getting
Getting started
started with Query
with Query Builder
Builder

Symbol Attribute type

Class

External link default

vi overlay

Search Criteria pane

When you perform your search, Teamcenter examines the attribute specified in each of your search
clauses and looks for values that match your search. Following are the search criteria elements.

Element Description
Boolean Rules The Boolean rules (AND/OR) are used to combine clauses to create
a custom query. When you use AND clauses together, both must be
satisfied to return a match (both this clause and that clause). When you
use OR clauses together, either can be satisfied to return a match (either
this clause or that clause). Keyword clauses do not support the OR rule.

Note
The indented search feature only supports AND clauses.

Attribute The selected database attribute displays 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 search criteria definition.
User Entry Name Displays the query box names as they appear in the search 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 Matching values can be equal to, not equal to, less than, or greater than
the value specified in your search clause. Matching values can also be
null or not null. These conditions are called logical operators. You must
specify one of the following logical operators in each search clause.

Logical
operator Description
= Equal to.
!= Not equal to.
> Greater than.
>= Greater than or equal to.

1-6 Query Builder PLM00031 11.3

 Getting started with Query Builder

Element Description
< Less than.
<= Less than or equal to.
IS_NULL Indicates that the reference attribute value
must be blank (not set).
IS_NOT_NULL Indicates that the reference attribute must
have a value.
CONTAINS Indicates that the reference attribute
contains the default value.

Note
The CONTAINS logical operator
is used by full-text search
to search for LongString
attributes.

Logical operators can only be used for string attribute types.

You can search for ranges of values using the >, >=, <, <= logical
operators or invert search criteria using the != logical operator.
Default Value Default values can be specified for the query clauses. 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 save 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_NOT_NULL is used.
The following keyword variables can be used to display default values in
the query form:
• $USERID

• $USERNAME

• $GROUP

• $TODAY

The values displayed in boxes for which the $USERID, $USERNAME,

and $GROUP variables are used as a default value correspond to the
end user who is running the query. The $TODAY variable displays
the current date. These variables are used in the default Teamcenter
queries. If you make any change to the default queries, the modified
values are displayed unless you explicitly enter the variable name over
its displayed value.

PLM00031 11.3 Query Builder 1-7

 Chapter
Chapter 1: 1: Getting
Getting started
started with Query
with Query Builder
Builder

Element Description

Note
To use a list of values (LOV) for a property on a form business
object, the LOV must be attached to the same property on
the form’s parent business object. The form parent serves
as the storage class for the properties. If this is not done,
the LOV is not attached to the property and does not display
in Teamcenter clients.

Note
Siemens PLM Software recommends the following when using the Search Criteria pane:
• For each clause, make certain the User entry L10N key value is unique.

• When you use AND and OR clauses together, the search result displays 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.

User entry L10N User entry

Attribute key name Default value
object_name object_name Name = *
AND object_type object_type Type = UGMASTER;DirectModel

The Order By tab contains the following search 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 search criteria definition.
User Entry Name Displays the query box names as they appear in the search 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
saved query. Each attribute can be set to arrange in either Ascending
or Descending order.

1-8 Query Builder PLM00031 11.3

 Getting started with Query Builder

What are perspectives and views?

Within the rich client user interface, application functionality is provided in perspectives 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
Your administrator can use the HiddenPerspectives preference to prevent the display of
some Teamcenter perspectives in the rich client.

If your site has online help installed, you can access application and view help from the rich client
Help menu or by pressing F1.

Basic concepts for using Query Builder

Depending on your needs, you can use an existing query from the Saved Queries tree. Saved
queries are subject to standard object protection and are accessed by users through the search
feature in My Teamcenter.
You can also use Query Builder to create queries based on the following features:
• Queries using the hints feature

• Queries that include a keyword search

• Queries based on an existing definition

• Queries using the IS_NULL or IS_NOT_NULL operators

• Referenced-by queries

• Queries based on classification attributes

• Subclass queries on a typed reference

Once created, query definitions can be exported and saved as XML files that can be shared with
other Teamcenter sites. Conversely, query data saved in XML files can be imported into Teamcenter.
The XML files are parsed and verified before the data is imported.

Basic tasks using Query Builder

Query Builder is a Teamcenter administrative application that is used to perform the following tasks:
• Create customized searches for objects in both local and remote Teamcenter databases.

• Store query hints in the query hints file, queryHint.xml.

• Export query definitions saved as XML files, which can be shared with other Teamcenter sites.

PLM00031 11.3 Query Builder 1-9

 Chapter
Chapter 1: 1: Getting
Getting started
started with Query
with Query Builder
Builder

• Import into Teamcenter query definitions saved as XML files.

1-10 Query Builder PLM00031 11.3

Chapter 2: Creating and managing queries

Creating customized searches using Query Builder

Query Builder allows you to create customized searches for objects in Teamcenter databases. When
using Query Builder to create a query, you must provide the following information:
• The search class for the query

• At least one search criteria clause

Create queries

Create a generic query

1. Click 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. (Optional) Type a description of the query in the Description box.

4. Select Local Query from the Modifiable Query Types list.

5. Click the Search Class button .

The Class/Attribute Selection dialog box appears.

PLM00031 11.3 Query Builder 2-1

 Chapter
Chapter 2: 2: Creating
Creating and managing
and managing queries
queries

6. Specify the desired search class by selecting an entry from this dialog box.

Tip
You can significantly expand or narrow the focus of your query depending on the class
you select. It is best to limit the search to the lowest possible class in the hierarchy.

To locate a class, type the class name (or partial name and wildcards) in the box at the top of the
dialog box, and click the Search button . The number of classes matching your search are
displayed at the bottom of the dialog box, and the first result is highlighted in the tree.
To navigate through the results:

Go to next Press F3, Page Down, or Down Arrow key.

match
Go to previous Press the Page Up or Up Arrow key.
match
Go to first Press the Home key.
match
Go to last Press the End key.
match

7. To display the search results in an indented or hierarchical form, select Show Indented Results.

8. Double-click to select at least one of the attributes in the Attribute Selection tree.
Direct attributes of the class are displayed in the tree. Reference classes and attributes can be
accessed by double-clicking the Referenced By node in the attribute tree.

2-2 Query Builder PLM00031 11.3

 Creating and managing queries

The attribute is added to the Search Criteria table.

9. Specify the desired search criteria. You must specify the following required search criteria boxes:
• Attribute

• User Entry L10N Key

• Logical operators

10. Click the Create button .

The query is created, and the name appears in the Saved Queries tree of the Query Builder
application and in the System Defined Searches list in My Teamcenter.

Create a query using the hints feature

Query hints are provided to assist you in navigating the schema by presenting a relationship to
traverse (for example, item-to-item master form) and the steps required to build that relationship into
your query definition.
1. In the Name box, type a unique name for the query.

2. Optionally, type a description of the query in the Description box.

3. Select Local Query from the Modifiable Query Types list.

4. Click the Show Hints button in the saved query properties pane.
The system displays the hints pane.

5. Click the Choose Hint button located at the top of the hint pane.
The system displays the choose hint pane containing the directory of query hints.

6. Expand the Item Queries folder, select Item to Item Master Form, and click OK.
The dialog box closes and the system displays the selected hint in the hint pane. The first entry in
the hint is the base class, followed by the traversal steps, ending with the attribute of the item
master form class that is added to the query clause.

PLM00031 11.3 Query Builder 2-3

 Chapter
Chapter 2: 2: Creating
Creating and managing
and managing queries
queries

7. Select the base class by clicking the Search Class button .

The system displays the Class/Attribute Selection dialog box.

8. To locate the Item class, type Item in the search box and then click the Search button .
The Item class is highlighted in the schema tree of the Class/Attribute Selection dialog box.

2-4 Query Builder PLM00031 11.3

 Creating and managing queries

9. Close the Class/Attribute Selection dialog box by clicking the X in the upper-right corner.
The system displays the item class and its attributes in the Attribute Selection area, and the
Find in Tree and Add Clause to Table buttons are available in the hint pane.

10. The Item to Item Master Form hint traverses the schema to the project_id attribute from the Item
Master Form. To add this attribute to the query definition, click the Add Clause to Table button.
The system adds the clause to the table.

11. If you want to search for project_id attribute of the Item Master Form, click the Find in Tree
button.
The system expands the tree in the Attribute Selection pane to display the Project ID attribute.

12. Double-click any of the other attributes to add them to the clause table.
You can use other hints to add more clauses to the query table by selecting a new hint and
repeating the previous steps.

PLM00031 11.3 Query Builder 2-5

 Chapter
Chapter 2: 2: Creating
Creating and managing
and managing queries
queries

Note
Only those hints applicable to the selected search class are available in the choose
hint pane.

13. Modify the search criteria and clause precedence, as required.

14. Click the Create button to save the query definition.

The query form is also available in the System Defined Searches list in My Teamcenter.

Create a query that includes a keyword search

Including the keywords attribute in a query definition allows you to develop queries to find dataset
files that contain a specific keyword or combinations of keywords.

Note
The Autonomy server must be installed and configured at your site to enable full-text
keyword search functionality.

1. In the Name box, type a unique name for the query.

2. Optionally, type a description of the query in the Description box.

3. Select Keyword Search Query from the Modifiable Query Types list.

4. Click the Search Class button to select the target class for the query.
The Class Selection dialog box displays the POM schema in tree format.

5. Expand the POM_application_object class and locate the WorkspaceObject class. Expand the
WorkspaceObject class, and then double-click the Dataset class.
The system displays the Dataset class on the Search Class button, and the Dataset class and
its attributes are displayed in the Attribute Selection pane.

6. Add the Keywords attribute to the Search Criteria table by either double-clicking the attribute in
the tree or by selecting it in the tree and clicking the Add button .
The system displays the attribute (tc_fts_keyword) and default operator (=) in the table.

7. Optionally, modify the default operator and default attribute value.

8. Optionally, add other search clauses to the table.

9. Click the Create button .

The system adds the query to the Saved Queries tree. The query form is also available in the
System Defined Searches list in My Teamcenter.

2-6 Query Builder PLM00031 11.3

 Creating and managing queries

Create a new query based on an existing definition

1. Select an existing query from the Saved Queries tree.

2. In the Name box, type a unique name for the query.

3. Change the information in the Description box, Search Class box, and/or Search Criteria
table columns.

4. Click the Create button .

The system adds the query to the Saved Queries tree. The query form is also available in the
System Defined Searches+ list in My Teamcenter.

Create a query using the IS_NULL or IS_NOT_NULL operator

The IS_NULL and IS_NOT_NULL operators allow you to create queries to find objects with null
attribute values, such as items that do not have descriptions, or objects with an attribute containing
any value other than null. Clauses that use this operator are treated as having a fixed value;
therefore, there is no need to enter a name and default value for the clause.
The following steps illustrate the process of creating a null-value query to find released ItemRevision
objects:
1. In the Name box, type a unique name for the query.

2. Optionally, type a description of the query in the Description box.

3. Select Local Query from the Modifiable Query Types list.

4. Click the Search Class button to select the target class for the query.
The Class Selection dialog box displays the POM schema in tree format.

5. Expand the POM_application_object class and locate the WorkspaceObject class.

6. Expand the WorkspaceObject class and select the ItemRevision class by selecting it and
closing the dialog box.
ItemRevision is now displayed on the Search Class button, and the ItemRevision class and
its attributes are displayed in the Attribute Selection pane.

7. Click the Display Settings button and select All Attributes. Add the Release Status attribute to
the Search Criteria table by selecting it in the tree and clicking the Add button .
The attribute and default operator (IS_NULL) are displayed in the table.

8. Change the operator from IS_NULL to IS_NOT_NULL by clicking the right corner of the operator
cell and selecting IS_NOT_NULL from the list.

9. Click the Create button to create the query.

PLM00031 11.3 Query Builder 2-7

 Chapter
Chapter 2: 2: Creating
Creating and managing
and managing queries
queries

The system adds the query to the Saved Queries tree. The query form is also available in the
System Defined Searches list in My Teamcenter.

Create a referenced-by query

You can create queries using clauses on a reversed-reference relationship.
The following example illustrates the process of creating a query using clauses on a
reversed-reference relationship. In this case, the purpose of the query is to find dataset objects that
are referenced, through an IMAN_specification relationship, by an item revision with a specific name.
1. In the Name box, type a unique name for the query.

2. Optionally, type a description of the query in the Description box.

3. Select Local Query from the Modifiable Query Types list.

4. Click the Search Class button to select the target class for the query.
The Class Selection dialog box displays the POM schema in tree format.

5. Expand the POM_application_object class and locate the WorkspaceObject class.

6. Expand the WorkspaceObject class and select the Dataset class by double-clicking it. The
dataset is now displayed on the Search Class button. The Dataset class and its attributes
are displayed in the Attribute Selection box.
Attribute Selection box

Dataset
Revision Anchor [ RevisionAnchor ]
ref_names
Tool Used [ Tool ]
Classification
ref_types
Format
References

7. Double-click the Referenced By node in the Attribute Selection pane.

The Class Attribute Selection dialog box appears.

Note
If you select the Referenced By attribute, the Class Attribute Selection dialog box
appears. Use this dialog to select the class and through what attribute the given object
is referenced in that class. You can add selected attributes to the search criteria table.

2-8 Query Builder PLM00031 11.3

 Creating and managing queries

8. Click the Search Class button to select the referencing class for the query.
The Class Selection dialog box displays the POM schema in tree format.

9. Expand the POM_application_object class and locate the WorkspaceObject class.

10. Expand the WorkspaceObject class and select the ItemRevision class by highlighting it and
closing the dialog box.
The referencing class and its attributes are displayed in the Class Attribute Selection dialog box.

Note
Only those attributes that may reference the objects of the class being queried, in this
case the Dataset class, are displayed in the dialog box.

11. Select a referencing attribute, in this case IMAN_specification, by double-clicking the node.
The referencing attribute, Specifications, and class, ItemRevision, are displayed in the
Attribute Selection area.

PLM00031 11.3 Query Builder 2-9

 Chapter
Chapter 2: 2: Creating
Creating and managing
and managing queries
queries

12. Select the attributes of the referencing class on which you want to build query clauses. In this case,
locate and double-click the Name attribute. The attribute is displayed in the Search Criteria table.
Note that the display name of the attribute is ItemRevision←IMAN_specification.object_name.
The ← symbol indicates a reversed-reference relationship.

13. Type a key name in the User Entry Key box. This makes the User Entry Key unique when you
perform a query from the My Teamcenter search pane.

14. Click the Create button to create the query.

The system adds the query to the Saved Queries tree. The query form is also available in the
System Defined Searches list in My Teamcenter.

Create a saved query on classification attributes

With this function, and appropriate privileges, you create a saved query on Classification attributes,
using Query Builder. In particular, you can create a saved query that combines Classification attributes
and Teamcenter attributes. The following examples illustrate a few scenarios where the user can
create a saved query to perform searches using Classification attributes and/or Teamcenter attributes:
• Define a query that restricts the search to Bolt and makes all Bolt attributes available as the
search criteria. In the Find application, the user can enter values for one or more Bolt attributes.

• Define a query that restricts the search to Bolt but makes a subset of Bolt attributes (for example,
Length and Radius) available as the search criteria.

• Define a query that restricts the search to item and makes item attributes and bolt attributes
through the IMAN_classification reference be available as the search criteria.

1. Select a Classification class from the class schema using the Class Selection dialog box,
accessed by clicking the Search Class button .

Note
When creating a saved query, the search class must have at least one own attribute
(an attribute not inheriting from its parent class). Otherwise, the search returns objects
from its parent class, rather than the specified class.

2. After selecting a Classification class, select Classification attributes through the Attribute
Selection pane to build query clauses.

The Classification hierarchy used by Query Builder is exactly the same as the Classification hierarchy
used in the Classification applications. The highest level of the hierarchy represents groups that do
not contain attributes and cannot be used in a search. These group nodes are shown with a different
icon. The nodes below the group level correspond to a Classification class. The class level nodes
can be used to build saved queries.
After a Classification attribute is selected from the Attribute Selection tree, its internal attribute ID is
shown as Attribute name in the Search Criteria table while its attribute display name is shown as
User Entry Name in the Search Criteria table. You can modify the user entry name if required.

2-10 Query Builder PLM00031 11.3

 Creating and managing queries

A Classification object (ICO) is attached to a Teamcenter object through the Tc_classification

relationship. This Tc_classification relationship is shown as one of the attributes for a Teamcenter
class whose instances are classified. For such a Teamcenter class (for example, item and item
revisions), you can expand its Tc_classification attribute in the Attribute Selection tree to access
the Classification attributes. In doing so, you build a saved query that combines Classification
attribute search criteria and Teamcenter attribute search criteria.

Note
When you double-click the Tc_classification attribute, only the Classification hierarchy is
shown in the Class Selection dialog box to enable you to select a Classification class and
use its attributes to build query clauses.

Create a saved query using a revision rule

1. In Query Builder, create a query.

2. Select an applicable revision rule from the Revision Rule list.

Create a saved query for name-value properties

To query for name-value property information on a business object, you can use the
FindObjectsWithNameValuePairs saved query provided in Query Builder.

If you prefer, you can create your own saved query for table properties.

Create a saved query for table properties

You can create a saved query for table properties or name-value properties.

PLM00031 11.3 Query Builder 2-11

 Chapter
Chapter 2: 2: Creating
Creating and managing
and managing queries
queries

1. In the Name box, type a unique name for the query.

2. Optionally, type a description of the query in the Description box.

3. Select Local Query from the Modifiable Query Types list.

4. Click Search Class to select the target class for the query.

5. Expand the POM_application_object class and locate the WorkspaceObject class.

6. Click Display Settings and select All Attributes and Real Names.

7. While in the Attribute Selection box, double-click the Referenced_By node.

The Class Attribute Selection dialog box appears.

8. Click Search Class and search for your table row business object.
This appears under Fnd0TableRow node.

9. Select the table row business object and open fnd0OwingObject, which lists the table row
properties for your search.

10. Add the owning object and build your search by selecting the attributes on which you want to
build the query clauses. When finished, click Create to create the query.

2-12 Query Builder PLM00031 11.3

 Creating and managing queries

Your new query now appears in the Saved Queries tree pane and is available in the Select a
Query list in My Teamcenter.

Specify sort order for a saved query

Note
Default sort attributes are defined on the Order By tab in Query Builder. In My Teamcenter,
the Search view Sort dialog box lets users specify sort order or override a default sort
order defined for a saved query.

1. Create a query.

2. Next to the Search Criteria section, click the Order By tab, and then select an attribute to
display the Order By tab.

3. In the Order By tab:

a. Select an attribute and use the arrow keys to move it up or down in the Sort By precedence
order list.

b. For each attribute, specify whether to arrange in Ascending or Descending order.

Combining full-text search with metadata queries

You can embed a keyword search entry into a saved query on the dataset class and execute both the
metadata query and keyword search in one operation.

PLM00031 11.3 Query Builder 2-13

 Chapter
Chapter 2: 2: Creating
Creating and managing
and managing queries
queries

Combining full-text search with metadata queries allows you to define a query, for example, that
searches for files containing the word brake that are owned by user jsmith and were modified
after 01-Jan-2004.
This functionality is included in the Dataset standard query form. .
Custom queries combining full-text search and metadata search can be defined by your Teamcenter
administrator. .
Alternatively, the metadata of dataset objects can be indexed together with the associated data files.
This allows you to use Autonomy to perform both keyword search and metadata search.

Create a subclass query on a typed reference

You can create saved queries based on a subclass of a typed reference and then build clauses
against the attributes of the subclass instead of against the attributes of the referenced class.
For example, the contents attribute in the Folder class is a typed reference of the referenced class
WorkspaceObject. You can, therefore, select the Dataset class as a referenced class of the
contents attribute and build query clauses against the attributes of the Dataset class, rather than
against the WorkspaceObject class.
The following steps illustrate the process of creating a query of a subclass on a typed reference. In
this case, the purpose of the query is to find folders containing datasets that are checked out.
1. In the Name box, type a unique name for the query.

2. Optionally, type a description of the query in the Description box.

3. Click the Search Class button to select the target class for the query. The Class
Selection dialog box displays the POM schema in tree format.

4. Expand the POM_application_object class and locate the WorkspaceObject class.

5. Expand the WorkspaceObject class and select the Folder class by selecting it and closing
the dialog box.
Folder is displayed on the Search Class button, and the Folder class and its attributes are
displayed in the Attribute Selection pane.

6. In the Attribute Selection pane, double-click the Contents [WorkspaceObject] attribute.

The Class Selection dialog box displays the referenced class, in this case, WorkspaceObject,
and all of its subclasses.

2-14 Query Builder PLM00031 11.3

 Creating and managing queries

7. Select the Dataset subclass by double-clicking the node in the tree.

The Attribute Selection pane displays the Contents [Dataset] attribute and its attributes of the
Dataset class.

8. Expand the rev_chain_anchor [RevisionAnchor] attribute node by double-clicking it.

The Class Selection dialog box displays the RevisionAnchor class.

PLM00031 11.3 Query Builder 2-15

 Chapter
Chapter 2: 2: Creating
Creating and managing
and managing queries
queries

9. Expanded the rev_chain_anchor [RevisionAnchor] in the tree; the attributes are displayed in
the Attribute Selection pane.

10. Expand the IMAN_RES_checkout class by double-clicking it.

The Class Selection dialog box displays the POM_object schema.

11. Select the ImanReservation class and expand it.

The ImanReservation attributes are displayed in the Attribute Selection pane.

12. Double-click the reservation_state attribute.

The attribute is added to the Search Criteria table.

13. Type a default value 0 for this query clause.

2-16 Query Builder PLM00031 11.3

 Creating and managing queries

14. Click the Create button to create the query.

The system adds the query to the Saved Queries tree. The query form is also available in the
System Defined Searches list in My Teamcenter.

Managing queries

Modify a query
1. Select a query from the Saved Queries tree.
Information about that query is displayed in the boxes on the right side of the window.

2. Change the information in the Name, Description, or Search Class box, and/or Search Criteria
table columns.

3. Click Modify to save your changes in the database.

PLM00031 11.3 Query Builder 2-17

 Chapter
Chapter 2: 2: Creating
Creating and managing
and managing queries
queries

Delete a query

1. Select a query from the Saved Queries tree.

2. Click Delete. Teamcenter displays the Delete Confirmation dialog box.

3. Click Yes to delete the query from the database and remove it from the Saved Queries tree.

Using preferences when querying

When querying, you can use the following preferences to further refine your query:

• QRY_exception_list

Specifies the list of queries to be excluded from using join approach on relations and references.

• QRY_query_name_SortKeys

Determines the class attributes used to sort the query results. This preference must be used in
conjunction with the QRY_query_name_SortOrders preference, which determines sort order.

• QRY_query_name_SortOrders

Determines the sort order of query results. This preference must be used in conjunction with
the QRY_query_name_SortKeys preference, which determines the class attributes used to
sort query results.

• QRY_query_name_REVRULE

Specifies the revision rule applied to search results for searches against ItemRevision and
its subclasses.

• TC_QRY_search_by_rev_rule

Locates the latest item revisions based on revision rules. For example, when querying to
locate the latest working item revision, you can set this preference to Latest Working before
conducting your query.

• TC_QRY_display_latest_dataset_only

Displays only the latest version of dataset objects when you set this preference to 1 before
conducting your query.

• SEARCH_RESULT_LOAD_ALL_LIMIT

Specifies the maximum number of loaded searches. The default value is 400.

Also, you can set the Open_previous_open_search preference to 1 to display a previous search
result in the search results view.

2-18 Query Builder PLM00031 11.3

 Creating and managing queries

Using class attribute selections

Selecting class attributes

To create query definitions, you select the class attributes to use in the search criteria. Class
attributes can be found on the:
• Search class.
When a Search Class is selected, its attributes are displayed in the Attribute Selection box.
Attribute Selection box

User
Nationality
mailbox [ Folder ]
Person [ Person ]
TTCDate
Default Volume [ ImanVolume ]
IP Clearance
newstuff_folder [ Folder ]

• Parent classes.
When all attributes for the Search Class are displayed, inherited attributes are also displayed in
the Attribute Selection box.
Attribute Selection box

User
Owning Site [ POM_imc ]
pid
object_properties
lsd
timestamp
Status
user_data_source

• Reference classes.
When classes related to the Search Class are displayed, the reference class attributes are
also displayed in the Attribute Selection box.
Attribute Selection box

PLM00031 11.3 Query Builder 2-19

 Chapter
Chapter 2: 2: Creating
Creating and managing
and managing queries
queries

Nationality
Mailbox [ Folder ] Reference class
Person [ Person ] Reference class
Owning Site [ POM_imc ]
pid
object_properties
lsd
timestamp

• Referenced by classes.
When classes related to the Search Class are not displayed, the Referenced By attribute is
used to locate additional reference classes to display in the Attribute Selection box.
Attribute Selection box

Default Volume [ ImanVolume ]

IP Clearance
newstuff_folder [ Folder ]
Gov Clearance
OS Name
Geography
home_folder [ Folder ]
Referenced By

Use the Display Settings box to display:

• Only attributes defined on the class or all attributes; those inherited from the parent.

• Attribute user interface display names or the attribute real database names.

Display Settings

Class Attributes
All Attributes

Display Names
Real Names

Double-click an attribute to add it to the Search Criteria table.

2-20 Query Builder PLM00031 11.3

 Creating and managing queries

• The attributes without the plus symbol can be directly set when searching for objects.

• The attributes with the plus symbol refer to another class in the class structure, which may
have direct attributes, or may have more attributes with plus symbols.

Add class attributes to search criteria

1. Select a class as the search class.

2. Set Display Settings to All Attributes and Real Names.

Display Settings

Class Attributes
All Attributes

Display Names
Real Names

3. Populate the Attribute Selection list with the attributes required to build the search criteria.
The attributes are either class attributes, parent class attributes, or reference class attributes.
Reference classes are classes related to the search class. To list reference class attributes:
• Double-click references with the plus symbol to list more attributes or to open the Class
Selection Dialog. Double-click a class from the Class Selection Dialog to add the class
and its attributes to the Attribute Selection list.

• Double-click Referenced By at the bottom of the Attribute Selection list to open the Class
Attribute Selection Dialog. Double-click the Search Class box to search for a class. Select
a reference and click OK to add the reference and its attributes to the Attribute Selection list.

Note
Navigating reference classes requires knowledge of the Teamcenter data model.

4. Double-click attributes without the plus symbol to directly add them to the Search Criteria
table.

Using search criteria clauses

Defining search criteria
Search criteria is specified using statements or clauses in the Search Criteria table. Each clause
searches the class and examines a specific attribute in that class, and each clause can examine only
one attribute. Therefore, if you want to build a complex query that examines multiple attributes, you
must build several search clauses (one for each attribute you want to examine).

PLM00031 11.3 Query Builder 2-21

 Chapter
Chapter 2: 2: Creating
Creating and managing
and managing queries
queries

When you perform your search (run your query), Teamcenter examines the attribute specified in each
of your search clauses and looks for values that match your search criteria. The Search Criteria
pane defines the elements in the Search Criteria table.
Attribute User Entry L10N Key User Entry Name Default Value
person.user_name PersonName Person Name =
AND user_id UserId User Id =

The Search Criteria table example finds users that meet the person name and user ID criteria
values entered by the user.
Double-click an attribute in the Attribute Selection box to add it to the Search Criteria table.
The combination of the User Entry L10N Key and Default Value elements dictate how the search
criteria is presented to the user.
1. The User Entry L10N Key has a value and the Default Value is blank.
Result: The attribute displays in the saved query for the user to populate.

2. The User Entry L10N Key has a value and the Default Value has a value.
Result: The attribute displays in the saved query with the default value. The user can change the
default value in the saved query pane.

3. The User Entry L10N Key is blank and the Default Value has a value.
Result: The attribute does not display in the saved query. The value is evaluated in the query.

Note
When the User Entry L10N Key is blank, the Default Value must have a value.

Search criteria clause example

Saved query: Admin – Object Ownership
Search class: WorkspaceObject

Attribute User Entry L10N Key User Entry Name Default Value
1 owning_user.user_id OwningUser Owning User = $USERID
2 AND owning_group.name OwningGroup Owning Group = $GROUP
3 AND object_type Type Type = ItemRevision

1. The user ID of the owning user of the WorkspaceObject is the user logged on and executing
the query.
Result: The attribute displays the user ID of the current user in the saved query. The query looks
for workspace objects owned by the value of the user ID.

2. The name of the owning group of the WorkspaceObject is the current group of the user logged
on and executing the query.

2-22 Query Builder PLM00031 11.3

 Creating and managing queries

Result: The attribute displays the group name of the current user in the saved query. The query
looks for workspace objects owned by the value of the group name.

3. The object type of WorkspaceObject is ItemRevision.

Result: The attribute displays ItemRevision in the saved query. The query looks for workspace
objects with a type that matches the value of type.

The resulting saved query:

Assign precedence to clauses

1. Select the clause or clauses that you want to move up or down in the list.

2. Click the Gain Precedence button to move the clauses up or click the Lose Precedence
button to move the clauses down.

3. Continue clicking the buttons until the clauses are moved to the position you want.

Remove clauses from the table

1. Select the clause or clauses that you want to remove from the list.

2. Click the Remove Search Clause button.

The selected clauses are removed from the list.
Creation or modification is not committed to the database until you click Create or Modify,
respectively.

Creating property finder formatter (PFF) objects

Property finder formatter (PFF) basics
The property finder formatter (PFF) can be used to gather and report properties data related to the
objects listed in the search results.
• PFF objects provide the necessary links and relationships required to locate object properties
data without reformatting the query instance.

• The PFF objects enable you to view additional information about the search results objects
that a single query could not provide.

PLM00031 11.3 Query Builder 2-23

 Chapter
Chapter 2: 2: Creating
Creating and managing
and managing queries
queries

• A set of property finder formatter (PFF) objects corresponding to the basic search types are
delivered as part of the standard Teamcenter installation. Additional PFF objects can be created.

• To define a PFF object, you must understand where and how properties data is stored and
the relationships between data objects. Therefore, PFF objects are generally created by a
Teamcenter administrator.

Note
If you build queries using property finder formatter objects, you cannot include the dot
character (.) in class names.

Create a property finder formatter (PFF) object

1. Execute the search for which you want to create a PFF object.

2. In the Search Results view, click the Select PFF button to activate the Edit Property Formatter
button.

3. In the Search Results view, click the Edit Property Formatter button.
The Edit dialog box appears.

4. Type a name for the PFF object in the Name box.

The name should reflect the name of the query or business process to which the PFF search is
related. For example, if the PFF search finds additional data related to the item revision saved
query, you could name the PFF object Item Revision.

5. (Optional) Type a description for the PFF object in the Description box.

6. Select a class to include in the PFF property search criteria.

a. Click the Principle Query Object button.
The Class/Attribute Selection Popup dialog box appears.

b. Select the class that matches the base class of the query.
To search for a class in the popup menu, type the class name or a partial name and wildcard
character in the box, and click Find .

Tip
You can determine the base class of the query by viewing the query details in
the search criteria definition.

c. Close the Class/Attribute Selection Popup dialog box.

The name of the selected class appears in the Principle Query Object button.
The class and its attributes appear in the Property Selection section.

2-24 Query Builder PLM00031 11.3

 Creating and managing queries

Note
To display all attributes, rather than only the class attributes, click the Display
Setting button and select All Attributes. If you change display settings after
adding search clauses to the Search Criteria table, the table is cleared.

7. Add a search clause for each property of the primary class that you want to include in the PFF to
the Search Criteria table.
a. In the Property Selection tree, expand the class name to display the class properties, if
necessary.

b. In the Property Selection tree, double-click the property you want to include in the PFF
search criteria.
A row for the property is added to the Search Criteria table.

8. (Optional) Select a secondary class to include in the PFF property search criteria and add the
applicable search clauses to the Search Criteria table.
a. Click the Add Clauses From button.
The Class/Attribute Selection Popup dialog box appears.

b. Select the secondary class.

Note
The secondary search class must match one of the object types returned by the
original query, and the data you are searching for must be related to the secondary
object type.

To search for a class in the popup menu, type the class name or a partial name and wildcard
character in the box, and click Find .

c. Close the Class/Attribute Selection Popup dialog box.

The name of the selected class appears in the Add Clauses From button.
The class and its properties appear in the Property Selection section.

Caution
If you change display settings after adding properties to the Search Criteria table
(for the primary class attributes for example), the Search Criteria table is cleared.

d. Add a search clause to the Search Criteria table for each property of the secondary class
you want to include in the PFF.
A. In the Property Selection tree, expand the class name to display the class properties, if
necessary.

PLM00031 11.3 Query Builder 2-25

 Chapter
Chapter 2: 2: Creating
Creating and managing
and managing queries
queries

B. In the Property Selection tree, double-click the property you want to include into the
PFF search criteria.
A row for the property is added to the Search Criteria table.

9. (Optional) Change the column name that appears in the PFF report for a property.
• Double-click the Column Names cell for the property and type a new name.

10. (Optional) Set the precedence of the search clauses.

• Use the up-arrow and down-arrow buttons located to the right of the Search Criteria table to
adjust the sequence of the search clauses.

11. (Optional) Verify that the PFF search returns the correct data before you create the object.
a. Close the Edit dialog box.

Note
The PFF definition is retained in the Edit dialog box and appears there the next
time you open the Edit dialog box.

b. In the Search Results view, click to execute the PFF.

The results of the PFF search appear in tabular format in the Search Results view.

Note
If you specify criteria for a PFF object to be used for an ad hoc query but do not
click Create, the file size, byte size, and MIME type information is not displayed
in the ad hoc results.

12. To create the PFF object, click Create.

The PFF object appears in the Saved Property Formatter Finder tree in the Edit dialog box.

2-26 Query Builder PLM00031 11.3

Chapter 3: Managing the query hints file

Updating the query hints file

Query hints are stored in the queryHint.xml file located in the tc_root\data directory. Use either
an XML editor or text editor to edit the hint file.

Note
• If using a plain text editor, you must manually convert the greater than (>) and less
than (<) characters to the XML equivalents, &gt; and &lt;, respectively.

• There is no mechanism during an upgrade for preserving your customizations to the

queryHint.xml file.

The XML file contains two element types:

• Folders
Used to group hints by category. They have two associated attributes: folder name and
description. The folder name is displayed in the Choose Hint dialog box tree and the description
is the tool tip displayed when the user places the mouse over the folder. Folders can be nested to
arbitrary depths and can contain both folders and hints.

• Hints
Contain four fields: name, description, search class, and query clause. The hint name is the
text you see in the hint tree. The description is the tool tip displayed when the user hovers the
mouse over the hint. The search class is the origin of the query, and the query clause is the hint
that provides the path to the attribute.

The simplest way to obtain the query clause is to copy it from the Query Builder Search Criteria table
from an existing query and paste it into the XML file.

Sample hints file

<?xml version="1.0" encoding="UTF-8"?>
<!--
===============================================================================
Copyright (c) 2003-2005 UGS Corporation
Unpublished - All Rights Reserved
===============================================================================
Filename: queryHint.xml
Define dtd for tc query hints
-->
<!DOCTYPE ImanQueryHintFile [
<!ELEMENT folder ( (folder | hint)* )>
<!ATTLIST folder name CDATA #REQUIRED
description CDATA #REQUIRED>
<!ELEMENT hint EMPTY>
<!ATTLIST hint name CDATA #REQUIRED

PLM00031 11.3 Query Builder 3-1

 Chapter
Chapter 3: 3: Managing
Managing the query
the query hintshints
file file

description CDATA #REQUIRED

class CDATA #REQUIRED
hint_text CDATA #REQUIRED>
<!ELEMENT ImanQueryHintFile ((folder | hint)*)>
]>

<ImanQueryHintFile>
<!-- =============================================== -->
<!-- ========= item hints ========================== -->
<!-- =============================================== -->
<folder name="Item Queries" description="Query Hints for Item Relationships">
<hint name="Item to Item Revision" description="adding item revision criteria to the item
search" class="Item" hint_text="ItemRevision&lt;-items_tag.item_revision_id"/>
<hint name="Item to Item Master Form" description="adding master form criteria to the item
search" class="Item" hint_text="Form:IMAN_master_form.ItemMaster:data_file.project_id"/>
<hint name="Item to Item Revision Form" description="adding criteria from an item
revision master form into the item search" class="Item"
hint_text="ItemRevision&lt;-items_tag.Form:IMAN_master_form_rev.ItemVersionMaster:data_file.project_id"/>
<hint name="Item to IMAN_Specification" description="adding criteria from an underlying
item revision's dataset to the item search" class="Item"
hint_text="ItemRevision&lt;-items_tag.Dataset:IMAN_specification.format_used"/>
<hint name="Item to IMAN_Aliasid" description="adding criteria from an associated alias
identifier to the item search" class="Item"
hint_text="Alias:IMAN_aliasid.alias_id"/>
</folder>
<!-- =============================================== -->
<!-- ========= item revision hints ================= -->
<!-- =============================================== -->
<folder name="Item Revision Queries" description="Query Hints for Item Revision Relationships">
<hint name="Item Revision to IMAN_Specification" description="adding dataset criteria
to the item revision search" class="ItemRevision"
hint_text="Dataset:IMAN_specification.format_used"/>
<hint name="Item Revision to Item Revision Master Form" description="adding master
form criteria to the item revision search" class="ItemRevision"
hint_text="Form:IMAN_master_form_rev.ItemVersionMaster:data_file.project_id"/>
<hint name="Item Revision to Item" description="adding item criteria to the item revision
search" class="ItemRevision" hint_text="items_tag.item_id"/>
</folder>
<!-- =============================================== -->
<!-- ========= dataset hints ================= -->
<!-- =============================================== -->
<folder name="Dataset Queries" description="Query Hints for Dataset Relationships">
<hint name="Specification Dataset to owning Item Revision" description="adding item revision
criteria to the specification dataset search" class="Dataset"
hint_text="ItemRevision&lt;-IMAN_specification.object_name"/>
<hint name="Dataset with unknown relation to Item Revision" description="adding item
revision criteria to the dataset search" class="Dataset"
hint_text="ImanRelation&lt;-secondary_object.ItemRevision:primary_object.object_name"/>
</folder>
<!-- =============================================== -->
<!-- ========= folder hints ================= -->
<!-- =============================================== -->
<folder name="Folder Queries" description="Query Hints for Folder Relationships">
<hint name="Contents to owning Folder" description="adding folder criteria
to the content object search" class="WorkspaceObject"
hint_text="Folder&lt;-contents.object_name"/>
<hint name="Folder to Contents" description="adding content object criteria
to the folder search" class="Folder" hint_text="contents.object_name"/>
</folder>
<!-- =============================================== -->
<!-- ========= product structure hints ================= -->
<!-- =============================================== -->
<folder name="Product Structure Queries" description="Query Hints for Product
Structure Relationships">
<hint name="Assembly to child Components (Imprecise Structure)"
description="adding child component item criteria to the assembly item
revision search" class="ItemRevision"
hint_text="structure_revisions.PSOccurrence&lt;-parent_bvr.Item:child_item.item_id"/>
<hint name="Child Components to Assembly (Imprecise Structure)"
description="adding assembly item
revision criteria to the child component item search" class="Item" hint_text=
"PSOccurrence&lt;-child_item.parent_bvr.ItemRevision&lt;-structure_revisions.object_name"/>
<hint name="Assembly to child Components (Precise Structure)" description="adding child
component item revision criteria to the assembly item revision search" class="ItemRevision"
hint_text="structure_revisions.PSOccurrence&lt;-parent_bvr.ItemRevision:child_item.object_name"/>
<hint name="Child Components to Assembly (Precise Structure)" description="adding assembly
item revision criteria to the child component item revision search" class="ItemRevision" hint_text
="PSOccurrence&lt;-child_item.parent_bvr.ItemRevision&lt;-structure_revisions.object_name"/>
</folder>
<!-- =============================================== -->
<!-- ========= workspace object hints ============== -->
<!-- =============================================== -->
<folder name="Workspace Object" description="Query Hints for Workspace Objects">
<hint name="Contents to owning Folder" description="adding folder criteria to the content
object search" class="WorkspaceObject" hint_text="Folder&lt;-contents.object_name"/>
<hint name="Workspace Object owner id" description="adding owner criteria to the workspace
object search" class="WorkspaceObject" hint_text="owning_user.user_id"/>
<!-- note that this hint is repeated below.
hints can be duplicated under different folder haedings as needed -->
<hint name="Workspace Object in an EPMJob" description="adding EPMJob criteria

3-2 Query Builder PLM00031 11.3

 Managing the query hints file

to the workspace object search" class="WorkspaceObject"

hint_text="EPMTask&lt;-attachments.EPMJob&lt;-root_task.object_name"/>
</folder>
<!-- =============================================== -->
<!-- ========= EPMJob hints ======================= -->
<!-- =============================================== -->
<folder name="Workflows" description="Query Hints for EPMJobs">
<hint name="Job by state" description="adding job state criteria to the EPMJob search"
class="EPMJob" hint_text="root_task.state_value"/>
<!-- note that this hint is repeated above.
hints can be duplicated under different folder haedings as needed -->
<hint name="Workspace Object in an EPMJob" description="adding EPMJob criteria
to the workspace object search" class="WorkspaceObject"
hint_text="EPMTask&lt;-attachments.EPMJob&lt;-root_task.object_name"/>
</folder>
<!-- ==================================================== -->
<!-- === one of every releationship type hints ========= -->
<!-- -->
<!-- This block includes an example of each type of -->
<!-- hint in a relationship by relationship type basis -->
<!-- -->
<!-- It is not intended that these be made available -->
<!-- in a production environment. This is why the are -->
<!-- commented out -->
<!-- -->
<!-- The below hints also demonstrate the sub-folder -->
<!-- capability of the hint tree. It is possibly to -->
<!-- organize hints by tc class (as above) or by -->
<!-- organization - as detailed below. -->
<!-- -->
<!-- -->
<!-- ==================================================== -->
<!-- commented out...
<folder name="Dept 1 hints" description="hints for joe's department">
<hint name="simpleName" description="no levels of indirection" class="Item"
hint_text="item_id"/>
<hint name="inClass" description="inClass classification... " class="Item"
hint_text="&lt;Complex_analysis&gt;:IMAN_Classification.1000"/>
<hint name="inClass2" description="inClass classification...with funny name "
class="Item" hint_text="&lt;33333&gt;:IMAN_Classification.1003"/>
<hint name="alias" description="iman alias relationship" class="Item"
hint_text="Alias:iman_alias"/>
<hint name="owner id" description="one level of indirection" class="Item"
hint_text="owning_user.user_id"/>
<hint name="item rev reference" description="references example" class="Item"
hint_text="ItemRevision&lt;-items_tag.owning_user.user_id"/>
</folder>
<folder name="Designer's Hints" description="a list of queries used in the design group">
<folder name="engine design" description="yes we can nest n-levels deep">
<hint name="simpleName" description="no levels of indirection" class="Item"
hint_text="item_id"/>
<hint name="inClass" description="inClass classification... " class="Item"
hint_text="&lt;Complex_analysis&gt;:IMAN_Classification.1000"/>
<hint name="alias" description="iman alias relationship" class="Item"
hint_text="Alias:iman_alias"/>
<hint name="owner id" description="one level of indirection" class="WorkspaceObject"
hint_text="owning_user.user_id"/>
<hint name="item rev reference" description="references example" class="Item"
hint_text="ItemRevision&lt;-items_tag.owning_user.user_id"/>
</folder>
<hint name="simpleName" description="no levels of indirection" class="Item"
hint_text="item_id"/>
<hint name="inClass" description="inClass classification... " class="Item"
hint_text="&lt;Complex_analysis&gt;:IMAN_Classification.1000"/>
<hint name="alias" description="iman alias relationship" class="Item"
hint_text="Alias:iman_alias"/>
<hint name="owner id" description="one level of indirection" class="WorkspaceObject"
hint_text="owning_user.user_id"/>
<hint name="item rev reference" description="references example" class="Item"
hint_text="ItemRevision&lt;-items_tag.owning_user"/>
</folder>
-->
</ImanQueryHintFile>

PLM00031 11.3 Query Builder 3-3

Chapter 4: Importing and exporting query definitions

Overview of importing and exporting query definitions

Query definitions can be exported and saved as XML files that can be shared with other Teamcenter
sites. Conversely, query data saved in XML files can be imported into Teamcenter. The XML files are
parsed and verified before the data is imported.
The Verify button is used to validate that the POM class matches existing classes in the database
before importing.

Note
It is possible that data that is correctly formatted in the XML file may be incompatible with
the local database schema. This results in errors when you attempt to create the query
definition using the imported data.

Import query definitions

You can import a query definition from an XML file and create the corresponding query in the
Teamcenter database.
1. Click the Import button in the Query Builder dialog box.
The system displays the Import dialog box. The last query definition file that was imported to
Teamcenter is displayed.

2. Click the Browse button to locate the XML file containing the definition you want to import.
The system displays the Read Query Definition dialog box.

3. Locate the XML file and click the Import button.

The system displays the contents of the XML file in the Import dialog box.

4. Click the Verify button.

If the file format is valid, the query data is displayed in the Query Builder pane. If parser errors
are encountered, an informational message describing the nature of the errors is displayed.

5. Click OK to load the query in the saved query tree and dismiss the Import dialog box.

6. Optionally, modify the name, description, or query clauses.

7. Click the Create button .

PLM00031 11.3 Query Builder 4-1

 Chapter
Chapter 4: 4: Importing
Importing and exporting
and exporting queryquery definitions
definitions

The system verifies that the definition is compatible with the local database schema. If so, the
query is saved in the database. If not, an error message describes the discrepancies.

Export query definitions

Perform the following steps to export a query definition to an XML file:
1. Select the query in the Saved Queries tree that you want to export.
The system displays the query definition in the right pane of the Query Builder pane.

2. Click the Export button.

The system displays the query, in XML format, in the Print dialog box.

3. Click the Save button to save the definition to a user-specified file.

The system displays the Save dialog box.

4. Determine the directory to which the file is saved.

5. Type a name in the File name box, including the .xml file extension.

6. Click the Save button .

The system saves the file to the specified location and closes the Save dialog box.

7. Click the Close button in the Print dialog box.

4-2 Query Builder PLM00031 11.3

Chapter 5: Application notes

Attribute index
If there are more than 5,000 instances of the search class to be found, you must add an index to
the attribute on which you are searching. Doing this helps the search performance. However, if the
table is very small (that is, the class has less than 500 instances), a full-table scan is more effective
than an index scan.
If you do not create an index on an attribute, a full-table scan of the Oracle table automatically
takes place. This affects the System Global Area (SGA) of the Oracle server. SGA is the portion
of memory where Oracle caches the queries and their execution plan. You can use the following
command to add an index to an attribute:
$TC_BIN/install -add_index

PLM00031 11.3 Query Builder 5-1

Chapter 6: Best practices

Restore My Saved Searches folder

If you mistakenly delete your My Saved Searches folder, you can restore your saved searches.
The following steps illustrate the process for creating a query to restore the contents of your My
Saved Searches folder.
1. In the Name box, type a unique name for the query.

2. (Optional) Type a description of the query in the Description box.

3. Click the Search Class button to select the target class for the query.
The Class Selection dialog box displays the POM schema in tree format.

4. Expand the POM_application_object class and locate the SavedSearch class.

5. In the Attribute Selection pane, click the Display Settings button. From the Display Settings
dialog box, select All Attributes and Display Names.

6. Select the Owner subclass by double-clicking the node in the tree.

The Attribute Selection pane displays the Owner [User] attribute and its attributes of the
SavedSearch class.

7. In the Search Criteria pane, specify the following search criteria:

• Name

• Description

• Type

PLM00031 11.3 Query Builder 6-1

 Chapter
Chapter 6: 6: Best Best practices
practices

8. Click the Create button to create the query.

The system restores the Saved Queries tree.

Export saved searches to another Teamcenter installation

1. Export the saved query to a directory of your choice:
a. Select the saved query from the Saved Queries tree pane.

b. Click the Export button.

The file is displayed in XML format in the Print dialog window.

c. From the Print dialog window, click the Save button to save the definition to a
user-specified file.

2. To import the saved query to a new Teamcenter installation:

6-2 Query Builder PLM00031 11.3

 Best practices

a. Open Query Builder from the new Teamcenter installation and click the Import button.

b. Select the saved query file to be imported and click Verify and then OK.

c. When the file is displayed, click the Create button to create the query.

PLM00031 11.3 Query Builder 6-3

Appendix A: Glossary

dataset
Teamcenter workspace object used to manage data files created by other software applications.
Each dataset can manage multiple operating system files, and each dataset references a dataset tool
object and a dataset business object.

folder
Graphical representation of an aggregation of objects, such as a group, class, or subclass. For easy
distinction in the class hierarchy, each of these aggregations has a different type of folder icon
associated with it: a group folder icon, a class folder icon, or a subclass folder icon.

form
Teamcenter workspace object used to display product information (properties) in a predefined
template. Forms are often used to create an electronic facsimile of a hardcopy form in Teamcenter.
See also master form.

item
Workspace object generally used to represent a product, part, or component. Items can contain other
workspace objects including other items and object folders.

item relation
Description of an association between a Teamcenter item and a piece of information that describes or
is related to the item.

item revision
Workspace object generally used to manage revisions to items.

item revision relation

Description of an association between a Teamcenter item revision and a piece of information that
describes or is related to the item revision.

key
Field in a record holding unique data that identifies the record from all other records in the file or
database. Each key value must be unique in each record.

PLM00031 11.3 Query Builder A-1

 Appendix
Appendix A: A: Glossary
Glossary

List of Values (LOV)

Pick list of values accessed by end users from a menu at the end of a data field. LOVs ensure
consistent data entries in the rich client.

master form
Teamcenter workspace object used to display product information (properties) in a predefined
template. Master forms are used to display product information in a standardized format.

My Teamcenter
In the Teamcenter rich client and thin client, application that is the main access point for managing
product information. My Teamcenter provides the functionality for creating objects in the Teamcenter
database, querying the database for objects, checking in and checking out objects, and managing
tasks. Users can also open objects, automatically launching the related application.
Each user has a personal My Teamcenter window that displays product information as graphical
objects. Although users share product information across the enterprise, they organize this
information individually in personal workspaces.

owner
User that owns an object, initially the user who created it. Ownership can be transferred from the
owner to another user. An object owner usually has privileges that are not granted to other users
(for example, the privilege to delete the object).

owning group
Group that owns an object, usually the group of the user creating the object. Because users
commonly share data with other members of a group, additional privileges may be granted to the
owning group (for example, the privilege to write to the object).

owning site
Multi-Site Collaboration site where the master object resides. The owning site is the only site where
the object can be modified.

persistent object manager (POM)

Interface between Teamcenter objects and the Relational Database Management System (RDBMS).
The persistent object manager provides definition of classes by inheritance from other classes and
definition of attributes, manipulation of in-memory objects and support for their saving and retrieval to
and from the underlying RDBMS, support for applications accessing the same data concurrently,
protection against the deletion of data used by more than one application, and support for the access
control lists attributed to objects.

perspective
Container in the rich client user interface for a set of views and editors collected to accomplish
specified tasks. See also view.

A-2 Query Builder PLM00031 11.3

 Glossary

PLM XML
Siemens PLM Software format for facilitating product life cycle interoperability using XML. PLM XML
is open and based on standard W3C XML schemas. Representing a variety of product data both
explicitly and via references, PLM XML provides a lightweight, extensible, and flexible mechanism for
transporting high-content product data over the Internet.

POM
See persistent object manager (POM).

properties
Keys and values that specify the configuration settings for an application in the Teamcenter rich client.

Query Builder
Teamcenter application that enables a system administrator to create and maintain customized
searches for objects in the Teamcenter databases, both local and remote. Saved queries are
subject to standard object protection and can be accessed by users through the search feature in
My Teamcenter.

query form
Predefined query used in My Teamcenter to quickly search the database without building a custom
query. Query forms limit search criteria to boxes displayed in the form. Accessing additional search
capabilities requires building a custom query.

relation
Description of an association between a Teamcenter object and a piece of information that describes
or is related to the object.

revision rule
Parameter set by the user that determines which revision of an item is used to configure product
context.

rich client
Java-based user interface to Teamcenter installed on user workstations. The rich client accesses
Teamcenter databases using a remote or local server. Compare to thin client.

thin client
Teamcenter user interface that provides a streamlined browser-based view of product information
stored in a Teamcenter database. The thin client is configured in the web tier, which creates and
serves its web pages to the client. Compare to rich client.

value
Content of a field or variable. It can refer to alphabetic, numeric, or alphanumeric data.

PLM00031 11.3 Query Builder A-3

 Appendix
Appendix A: A: Glossary
Glossary

view
Software element in a rich client user interface perspective. It provides the ability to navigate
hierarchies of information, display information about selected objects, open an editor, or display
properties. See also perspective.

A-4 Query Builder PLM00031 11.3

Siemens Industry Software

Headquarters
Europe
Granite Park One
Stephenson House
5800 Granite Parkway
Sir William Siemens Square
Suite 600
Frimley, Camberley
Plano, TX 75024
Surrey, GU16 8QD
USA
+44 (0) 1276 413200
+1 972 987 3000

Asia-Pacific
Americas
Suites 4301-4302, 43/F
Granite Park One
AIA Kowloon Tower, Landmark East
5800 Granite Parkway
100 How Ming Street
Suite 600
Kwun Tong, Kowloon
Plano, TX 75024
Hong Kong
USA
+852 2230 3308
+1 314 264 8499

About Siemens PLM Software

© 2017 Siemens Product Lifecycle Management

Siemens PLM Software, a business unit of the Siemens
Software Inc. Siemens and the Siemens logo are
Industry Automation Division, is a leading global provider
registered trademarks of Siemens AG. D-Cubed,
of product lifecycle management (PLM) software and
Femap, Geolus, GO PLM, I-deas, Insight, JT, NX,
services with 7 million licensed seats and 71,000 customers
Parasolid, Solid Edge, Teamcenter, Tecnomatix and
worldwide. Headquartered in Plano, Texas, Siemens
Velocity Series are trademarks or registered trademarks
PLM Software works collaboratively with companies
of Siemens Product Lifecycle Management Software
to deliver open solutions that help them turn more
Inc. or its subsidiaries in the United States and in other
ideas into successful products. For more information
countries. All other trademarks, registered trademarks
on Siemens PLM Software products and services, visit
or service marks belong to their respective holders.
www.siemens.com/plm.