Custom Fields

Dynamic fields are used across most nodes to model arbitrary/dynamic data added to the system. Due to the dynamic nature of these fields, the system does not automatically know how to index and treat these values. So in order to enable filtering and sorting by dynamic fields, they must be defined as custom fields.

Once defined, a custom field appears as a regular system field on the node it belongs to. A custom field maps a dynamic field, and updating the field’s value is a matter of updating the underlying dynamic value.

Custom fields have a defined type. If the underlying value is not compatible with this type, the field will be regarded as NULL in terms of sorting and filtering. Additionally the field will be empty upon returning. This ensures that you can trust the Graph to return a valid value or nothing, but never an invalid value.

Custom fields does not apply any restriction on the underlying dynamic field. It’s still perfectly fine to write an invalid value. Similarly, a custom field can be defined over a dynamic field that doesn’t exist, and will start to return values once a valid value has been set.

Note

Custom Fields is a Graph-only feature. That means that Rules do not have access to custom fields. Use the underlying dynamic field in rules instead.

Dimensions

Custom fields can be configured to use one of the supported dimensions:

• locale for translated values
• channel for values that are unique between channels

If a field is defined with a dimension, the underlying value is expected to be an object with a property mathing the dimension’s key. Not all dimensions must be present. It’s fine to only provide the dimensions that have an actual value.

For more info about dimensions, refer to Dimensions.

Querying Dimensions

When querying a dimensional field, you may chose to get all dimensions, or specific ones. To get all dimensions, simply specify the field itself. If you want one or more dimensions, separate the field and dimension key with a period.

When filtering however, you must specify the dimension you want to filter by.

Example:

HTTP

POST https://<hantera-hostname>/resources/graph
Authorization: Bearer <YOUR TOKEN>
Content-Type: application/json

[{
  "edge": "orders",
  "filter": "myField.b2b == 'value'",
  "node": {
    "fields": ["myField"],
  }
}]

curl

curl -i -X POST \
  https://<hantera-hostname>/resources/graph \
  -H 'Authorization: Bearer <YOUR TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '[{
  "edge": "orders",
  "filter": "myField.b2b == 'value'",
  "node": {
    "fields": ["myField"],
  }
}]'

Powershell

Invoke-WebRequest `
-Uri "https://<hantera-hostname>/resources/graph" `
-Method POST ` `
-Headers @{Authorization="Bearer <YOUR TOKEN>"; 'Content-Type'="application/json"}
-Body '[{
  "edge": "orders",
  "filter": "myField.b2b == 'value'",
  "node": {
    "fields": ["myField"],
  }
}]'

Types

Type	Description
text	Unique text values
enum	A small set of common text values. All set values will be collected and included in graph meta model.
number	Numeric (decimal) value. If the underlying value is a string, automatic conversion will be done assuming period (.) as decimal separator.
boolean	Boolean value. Underlying text values of “true” and “false” will be automatically converted.
instant	Datetime timestamp. Underlying value must be ISO-8601 compatible text value.
[text]	Array of unique text values. Underlying value must be a JSON array. Allows array predicates. Sorting is not allowed.
[enum]	Array of a small set of common text values. Underlying value must be a JSON array. Allows array predicates. Sorting is not allowed.

Configuring a Custom Field

Custom Fields are defined in the Registry using the following key pattern:

graph/<node>/fields/<name>

The value should be an object with the following properties:

Property	Description
type	The type of the value (see section above).
source	The underlying field that provides the value. Example: dynamic->'myField'
dimension	optional What type of dimension to use. Valid values: none channel locale If the property is not set, the field will have no dimension (none).

Index Creation

When a field has been defined in the registry, the index will be created in the background. The field will be available for filtering and sorting once the index is complete. This can take anything from a few seconds to hours depending on the size of the dataset.

To follow the progress, you can refer to the System Signals. Also, the graph meta model will tell you when the index is valid by marking the field as filterable.

Troubleshooting

After a field has been defined, it should be pretty much immediately available in the graph (even if the index has not been completed). If the field doesn’t show up, there should be an error in the signals explaining what the problem is:

h_ manage signals

Example

Here’s an example manifest for defining a Custom Field:

uri: /resources/registry/graph/sku/fields/name
spec:
  type: text
  source: dynamic->'name'
  dimension: locale