What Are the Profile Definition Keys?

  • Article

A profile definition key is a specially marked profile definition property that the Profiles System uses for profile instance retrieval and storage mapping. The key values must be non-null and unique.

Properties determine the data that is collected with the profile definition. When you add a property to a profile, you must define one or more keys for every valid profile definition. You can identify UNIQUE, PRIMARY, DUAL, JOIN, and HASHING keys by examining the Advanced Attributes section of the selected profile definition in the Profiles Schema Manager.

The Profiles System uses keys to look up and save profile instances. You can use any property that is defined as a key in the API ProfileContext.GetProfile(string keyName**, string** keyValue**, string** profileType**)** or ProfileContext.GetProfile(string keyName**, int** keyValue**, string** profileType**)**. All values stored in a key property must be unique (equivalent to a SQL column with NOT NULL and UNIQUE constraints).

The Profiles System builds in-memory indexes on profile properties that are marked as a key. This lets the Profiles System quickly retrieve profile instances that are in the internal in-memory cache. All values for a property marked as a key must be unique. Note that you can mark only properties of type STRING or NUMBER as a key, and all core operations can rely on key values to identify a profile instance.

This section describes the following profile definition key types:

  • PRIMARY key

  • JOIN key

  • DUAL key

  • UNIQUE key

  • HASHING key

Note

If you mark a profile definition as a PRIMARY, JOIN, or UNIQUE key, the SQL Server column that contains the key property data should have a unique constraint. All key types should have a SQL unique constraint.

The only time a key is explicitly used is by a programmer when invoking ProfileContext.GetProfile or ProfileContext.CreateProfile (the PRIMARY key value must be provided). However, the keys are used under-the-covers by the Profiles System any time a profile is created, retrieved, updated, or deleted.

PRIMARY key

Every profile definition must have exactly one property marked as a PRIMARY key. This tells the Profiles System that the property is the main unique key for profile. You should mark the profile property most frequently used to operate on profile object instances as the PRIMARY key. Once a profile instance has been created, its PRIMARY key value cannot be changed.

A PRIMARY key is identified by a red "P" or a green "D" (for a dual PRIMARY and JOIN key) that comes before the property in the profile definition in the Profiles Schema Manager.

Note

You must provide the value for the PRIMARY key property when calling ProfileContext.CreateProfile.

JOIN key

Every profile definition must have exactly one property marked as a JOIN key. This is a special type of key that is only used when a profile is aggregated across multiple physical data sources, for example, when part of a profile is stored in SQL Server and part is stored in Active Directory directory service. While there is only one JOIN key on the profile, this property is actually stored in each data source containing the profile’s data. This allows the Profiles System to link together the pieces from each data source. Values for the JOIN key property cannot be null, and once a profile instance has been created, its JOIN key value cannot be changed.

For optimal performance, you should also mark the PRIMARY key on the profile definition as the JOIN key. If you do not provide a value for the JOIN key property when you create the profile object, the Profiles System automatically generates a value for this member.

A JOIN key is identified by either a blue "J" or a green "D" (for a dual primary and JOIN key) that comes before the property in the profile definition in the Profiles Schema Manager. JOIN key values are replicated across all data stores.

DUAL key

The DUAL key specifies that the property will serve as both the PRIMARY and JOIN key. Typically, profiles define a DUAL key instead of separate PRIMARY and JOIN keys. You should only use separate PRIMARY and JOIN keys when the profile is aggregated.

UNIQUE key

A profile can have any number of UNIQUE keys. This key instructs the Profiles System to build an index on the property so that instances can be retrieved programmatically. Every profile definition property marked as a key has the UNIQUE key property turned on.

All core profile object management operations in the Profiles System work with key members only. The Profiles System does not guarantee the uniqueness of properties that are marked as UNIQUE keys. Instead, it relies on constraints on objects in the underlying data stores (tables for relational databases or classes for directory stores) to implicitly enforce uniqueness. The Profiles System only checks the in-memory cache to validate that a property marked as a UNIQUE key is truly unique. Therefore, it is possible for the Profiles System to attempt to persist a non-unique value. To prevent this invalid data from being committed, a unique constraint should be placed on the data member that holds the UNIQUE property value. If non-unique data is persisted to the data store, you may receive errors when retrieving profile instances because the Profile System cannot build the in-memory index on the property.

Values for the UNIQUE key property cannot be null, but unlike the PRIMARY and JOIN keys, the value of a UNIQUE key can be changed at any time.

A UNIQUE key is identified by a blue "U" in the Profile Schema Manager.

HASHING key

Every profile definition can have one property marked as the HASHING key. The profile partitioning layer uses the HASHING key to hash a profile object to a unique partition in a data source. The presence of a HASHING key is the only way to indicate that instances of a profile definition will be stored across multiple partitions of a data source. Partitioning causes the Profiles System to store some subset of the profile instances in a different physical location, for example, you could have half of your profiles in SQL Server database A, and half in SQL Server database B. The Profiles System uses the HASHING key to determine in which database to store a particular profile instance. If no HASHING key is defined, all profile instances are stored in the default partition.

You should mark the JOIN key on the profile definition as the HASHING key. For optimal performance, you should mark the same property as the PRIMARY key, the JOIN key, and the HASHING key.

You can identify a HASHING key by examining the Advanced Attributes section of a selected profile definition in the Profiles Schema Manager.

Note

After the profile object has been committed to the underlying stores, the HASHING key property value cannot be updated.

Dd451732.alert_caution(en-US,CS.90).gifImportant Note:

For partitioned ANSI SQL stores only, profile object retrieval operations based on a non-HASHING key and the Refresh method of the Profile object could fail. However, this is not true for LDAP version 3-compliant stores.

See Also

Other Resources

Managing Your Profiles

About the Profiles Schema Manager

How to Add a Property to a Profile Definition

How to Change a Profile Property

Profile Key Manager