Computed Fields Overview | Yext Hitchhikers Platform

Computed Field Values allow businesses to configure an algorithm to automatically populate the value for a particular field on an entity.

In order for a field to have its value computed, a user must define a computation method for that field. This configuration is part of the field definition, in the same way that the display name, tooltip, and validation are a part of the field definition.

Computation methods can be defined for any built-in or custom field. Once a computation method has been defined for a field, the computation must be triggered in order for a new value to be computed. Today, a computation can be triggered via Entity Edit (by clicking the wand icon), or by changing the value of a field that the computation depends on.

By default, a field does not have any computation method, meaning that the field’s value must be populated explicitly for each entity.

Computation Methods

The Knowledge Graph offers different computation methods which can be selected to compute a field’s value. When configuring a computation method for a field, you will see the full list of supported methods included in the dropdown. More details on each method are below.

Supported Field Types Per Method

Each method has a designated set of supported field types. A computation returns structured data, and this data must be compatible with the type of the field for which it is selected. As such, computation methods can only be selected for a given field if the field is of a type included in the method’s supported field types.

Supported Methods

There are a number of built-in computation methods with predefined algorithms and expected inputs. You have the option to provide additional instructions to these pre-defined computation methods to tailor it to your specific use case, although this is not required.

Note

Aside from the computation methods which specify “Markdown” in the name, the expected behavior will be that the method returns plain text. These methods are available for Rich-Text (v1) and Markdown field types since plain text is allowed in those fields, but leveraging one of these methods for a formatted field will not return formatted content (without additional instructions to do so).

Field Type Support

The response format of the computed value must be compatible with the given field type. This refers to both the format and the validation on the field.

For example, to generate content for a field that is a list of strings, the output format of the generated field must match that of a list of strings, i.e., [“item1”, “item2”, “item3”]. Additionally, if validation on the field exists such that a maximum of two items are allowed, a computed value of a list of three items would result in an error.

For fields that require a specified JSON format for the response (any objects or lists) the user can instruct the model to return the data in the required format. Built-in computation methods already have these instructions included.

However, when using a custom prompt to generate a list field, the user should include something like the following in the prompt: Return the list as a JSON array, formatted as: [“item1", “item2"].

While this won’t guarantee that the response format is correct, the model generally handles this type of instruction well.

Object Field Types

For Object field types, a computation method can be defined for each individual subfield, or for the entire object itself. This allows you to leverage different logic for different properties of object fields.

The computation can only be defined once for each subfield. That means if the computation is defined for an object, any individual subfield computations cannot be defined for subfields within that object.

Inputs

When a computation is triggered for an entity, the execution of that computation will receive a set of parameters, known as inputs. You can think of inputs as the user-defined data that is passed to the program as it is executing.

For an example input configuration, visit the Leverage Computed Field Values guide.

Required vs. Optional Inputs

For each built-in computation method, there is a defined list of inputs that a user can provide during configuration. These inputs are either Required or Optional.

• Required Inputs: Users must provide values for these inputs in order to save the configuration. Additionally, the computation cannot be executed for a particular entity profile if the value of a required input is not populated.
• Optional Inputs: Users can choose to provide values for optional inputs. If a value is not provided, or the value for a field input is null when executing for a particular entity profile, the input will not be passed to the computation when it is executed.

Static vs. Dynamic Inputs

There are two categories of inputs:

• Static Inputs: These are defined statically as part of the computation method configuration. Every time the computation is executed, it will receive the exact value you have provided as a static input.
• Dynamic Inputs (aka Field Inputs): For a given input, users can reference a field using the embedded field syntax , making that input dynamic. When referencing a field as an input, the system will take the field value from the profile for which the computation is being executed and pass that value as part of the computation execution. Dynamic field inputs ensure that the data being passed to your computation is relevant to calculate the value for the entity in question.

Localization

When computing a value for a particular Entity Profile (also known as a language profile), any dynamic inputs will be resolved to the field values on the profile in question. For example, if the computation inputs include [[name]] and [[description]]:

• When a value is computed for an English profile, the name and description for that English profile will be passed to the computation
• When a value is computed for a Spanish profile, the the name and description for that Spanish profile will be passed to the computation

Input values that are not dynamic can optionally be localized. Users can select a language for which to provide localized inputs, and those localized values will be utilized for computations on that language profile.

If an input is not localized, the default input values will be used.

Models may perform better when instructions are provided in the same language as the expected language of the response, so localizing inputs is encouraged when generating content for alternate language profiles.

Using Fields as Dynamic Computation Inputs

In order to reference fields in computation inputs, users specify the Field ID in the familiar double-bracketed notation, as they would when embedding fields on entities. However, the set of fields which can be used in computation inputs is a superset of what can be used on entities, and there are some other notable differences. This section will outline the specifics around using fields in computation inputs.

Supported and Non-Supported References

Input Field Embeds support:

• All built-in and custom fields of a primitive type (e.g., strings, numbers, booleans)
• Fields using the Markdown type, using the following notation: [[c_markdownField.markdown]]
• All list fields and list properties of objects containing primitive types, as a delimited list
• All properties of built-in and custom structured fields, to any depth (as long as each path contains a single item, and the final item is a primitive type or list of primitive types)

• Certain meta properties, which can be referenced by prefixing the property with meta (e.g., [[meta.entityType]]). These properties include:

  • accountId
  • countryCode
  • entityType
  • id
  • language
  • timestamp
  • uid

Input field embeds do not support:

• Inputs from fields on entities referenced via Entity Relationships

  • For example, if a Doctor entity has an Entity Reference field linking to a Location entity, you cannot embed any field data that’s stored on the linked Location to be used as an input to generate a field value on the Doctor entity.

• Values from lists of structured objects

• Fields using the Rich Text v2 type

• Fields and properties which are themselves structured objects

  • As covered above, you can reference the properties of these objects as long as the properties are of acceptable types.

• Non-profile fields, including:

  • Labels
  • Folder ID
  • Google Attributes
  • Categories
  • ECLs

Syntax and Default Display Values

Field inputs are accessed by including the Field ID in the familiar bracketed notation (i.e., [[address.line1]]). The paths to each field match the Entities API format. Any field (including meta fields) available in the Entities API which matches the criteria above can be used as an input.

Rendered Value Options

The rendered value will generally appear in the same way as it appears in the API JSON format (not including the JSON-syntax-like quotes). However, for some value types, one or more additional “display” formats may be supported in order to better flow with natural language prose.

For example, the API format of a phone number is the non-localized E.164 format (e.g., +12125551234) but the preferred display format for most use cases is the number’s national format, e.g., (212) 555-1234 in the US.

By default, the API format will be rendered. Note that this is different from profile field embed behavior, where most fields will return a localized format by default.

Certain value types for input field embeds support formatting cues that allow you designate a rendered format different from the default. These formatting cues are added as suffixes to the input embed syntax. As in the example above, adding the suffix $national to the embed syntax [[mainPhone.$national]] will render the value in the preferred display format.

Formatting cues supported by each type are summarized below.

Input Validation

Each input has a set of validation defined by the system. When attempting to compute a value, if the value used for the input is invalid according to that validation, the computation will not be executed.

For example, for the Summarize Text Computation Method, the Text to Summarize input has a maxLength of 5,000 characters. When configuring this method, you might choose to embed some field [[c_longTextBody]] for this input. However, if the value for that [[c_longTextBody]] field on a particular entity was >5,000 characters, the system would not compute the value, since that input field would be invalid according to the input constraints.

Access Controls and Required Subscriptions

There are a number of access controls to consider which may impact your access to computed field values, and associated functionality such as content generation.

Account Feature

In order to use Computed Field Values, the Preview Feature: Computed Field Values must be turned on in your account. This feature can be turned on via Account Settings > Account Features by any user with sufficient permission.

With this feature disabled, there will be no functionality related to computed field values available in an account.

Once the feature is set to be promoted from Preview, the Account Feature will be enabled at General Availability of the next release.

Subscription

The use of content generation in Yext requires the purchase of a Content Generation subscription, which grants a capacity of words generated to an account. Without purchasing this subscription, users will not be able to configure a computation method which relies on Content Generation; these computation methods will appear as locked in the Field Configuration UI.

At this time, all computation methods currently supported are based on Content Generation, so the current computed field values functionality will be unavailable without the purchase of a Content Generation subscription.

User Permissions

Any user with access to Manage Custom Fields will have permission to configure computed field values.

Any user with access to Edit Items With Approval or Edit for a field with a computation method defined will see the button to compute that field’s value in Entity Edit. The user’s ability to save the computed value will remain consistent with their permission on that field.

Configuration as Code

Computed field values are configured as part of the field definition. As such, computed field values can be configured via Configuration as Code, as part of the field resource .

Supported Computation Methods - Input Reference

The following tables detail the list of inputs for each supported computation method.

Write a Blog Post (Markdown)

Write Markdown Web Page Body Content

Write a Business Description

Write a Bio for an Individual

Write a Generic Description

Write a Web Page Meta Description

Summarize Content

Rewrite Content

Generate Keywords

Generate FAQs

Custom Generative Computation

Logs

Computation Logs can be viewed via the Logs API by querying the /computationLogs table.

The logs include all information around each computation, such as what triggered the computation, what inputs were sent to the model, what the model responded with, and whether the execution was a success or failure (and any associated error messages).

Limitations

Limited Configuration for Ongoing Compuations

Currently, all dynamic inputs will trigger a re-computation when changed. For example, if the name field is used as an input to generate a Blog Post, changing the name will always trigger a recomputation (either as a suggestion or by writing directly to the profile, as configured by the System Controlled Setting).

Built In Computations Optimized for English

All built-in computation methods have execution logic optimized for English. For content generation-based methods, through the additional prose instructions, a user could technically instruct the system to output content in a different language (even dynamically, based on the locale of the profile in question). This can be accomplished by embedding the locale code as a dynamic input within the additional instructions.

However, to provide an entirely localized prompt and set of instructions, we recommend using the Custom Generative Computation method and take advantage of the localization support.

Limited Computation Method Support

The current list of supported computation methods is limited to only content generation-based methods.

No Relationship Support in Inputs

The system does not currently support traversing across entity relationships for input values. This limitation means that only fields on the entity in question can be used as inputs.

Logs Unavailable in the UI

At this time, we do not have computation logs included in the UI. Logs can be accessed via the Logs API, as detailed above.