Skip Headers

# Configuring Query Keys

Previous

Next

A query key is a schema-independent alias for a database field name. For example, consider a class `Employee` with attribute `firstName` mapped directly to a database field `F_NAME` in database table `EMPLOYEE`. Without a query key, when you create a query or expression that involves `Employee` attribute `firstName`, you must use the database management system-specific field name `F_NAME`. This makes it more difficult to build a query and ties the query to the schema. With a query key, you can refer to this field using a schema-independent alias, such as `firstName`.

Table: Descriptor Support for Query Keys summarizes which descriptors support query keys.

Descriptor Support for Query Keys

Descriptor | Using TopLink Workbench | Using Java
--- | --- | ---
Relational Descriptors |  |
Object-Relational Descriptors |  |
EIS Descriptors |  |
XML Descriptors |  |

Using query keys offers the following advantages:

- Enhances code readability in TopLink expressions and simplifies expression development. You can compose expressions entirely within the context of your object model.

- Increases portability by making code independent of the database schema. If you rename a field in your schema, you can redefine the query key without changing any code that uses it.

- Query keys used with interface descriptors allow the implementor descriptor's tables to have different field names.

Query keys are automatically generated for all mapped attributes. The name of the query key is the name of the class attribute specified in your object model.

For information on how to use query keys in queries and expressions, see "Query Keys".

When query keys are generated and how you can add or modify query keys depends on the type of mapping or descriptor involved:

- Direct Mappings

- Relationship Mappings

- Interface Descriptors

Direct Mappings

TopLink Workbench automatically generates query keys for all direct mappings at the time you create the mapping.

TopLink Workbench provides support for adding or modifying query keys for simple unmapped attributes that could be mapped by a direct mapping: for example, the `version` field used for optimistic locking or the `type` field used for inheritance. You cannot modify or remove automatically generated query keys.

Relationship Mappings

TopLink automatically generates query keys for all relationship mappings at run time.

For example, if you have a class `Customer` with attribute `orders` mapped in a one-to-many relationship to class `PurchaseOrders`, then the TopLink runtime will generate a query key named `orders` for this `Customer` attribute.

TopLink Workbench does not currently support adding or modifying the query keys for relationship mappings. If you must add or modify such a query key, you must do so in Java code, using a descriptor amendment method.

Interface Descriptors

Interface descriptors (see "Relational Interface Descriptors") define only the query keys that are shared among their implementors. In the descriptor for an interface, only the name of the query key is specified.

TopLink Workbench provides support for choosing the implementors of an interface that share at least one common automatically generated query key (see "Configuring Interface Query Keys").