Calculated Attributes APIs

You can use the following Customer Profiles calculated attribute APIs

CreateCalculatedAttributeDefinition

Create a new calculated attribute. This requires an existing object type in the domain. You can define attributes that you want to pull from a single source object and the mathematical operations to apply to them in aggregate as well as the time range and object count.

After creation, new object data ingested into Customer Profiles will be included in the calculated attribute, which can be retrieved for a profile using the GetCalculatedAttributeForProfile API. Defining a calculated attribute makes it available for all profiles within a domain. Each calculated attribute can only reference one ObjectType and at most two fields from that ObjectType.

Request


POST /domains/DomainName/calculated-attributes/CalculatedAttributeName



{
    "CalculatedAttributeName": "string",
    "DisplayName": "string",
    "Description": "string",
    "AttributeDetails": {
       "Attributes": [
           {
               "Name": "string"
           }
           ...
       ],
       "Expression": "string",
    },
    "Statistic": "AVERAGE" | "COUNT" | "SUM" | "FIRST_OCCURRENCE" | "LAST_OCCURRENCE" | "MINIMUM" | "MAXIMUM" | "MAX_OCCURRENCE",
    "Conditions": {
        "Range": {
             "Value": "number",
             "Units": "string"
        },
        "ObjectCount": "number",
        "Threshold": {
            "Value": "string",
            "Operator": "EQUAL_TO" | "GREATER_THAN" | "LESS_THAN" | "NOT_EQUAL_TO"
        }
     },
     "Tags": {}
}

Response



{
    "CalculatedAttributeName": "string",
    "DisplayName": "string",
    "Description": "string",
    "AttributeDetails": {
       "Attributes": [
           {
               "Name": "string"
           }
           ...
       ],
       "Expression": "string",
    },
    "Statistic": "AVERAGE" | "COUNT" | "SUM" | "FIRST_OCCURRENCE" | "LAST_OCCURRENCE" | "MINIMUM" | "MAXIMUM" | "MAX_OCCURRENCE"
    "Conditions": {
        "Range": {
             "Value": "number",
             "Units": "string"
        },
        "ObjectCount": "number",
        "Threshold": {
            "Value": "string",
            "Operator": "EQUAL_TO" | "GREATER_THAN" | "LESS_THAN" | "NOT_EQUAL_TO"
        }
    },
    "CreatedAt": number,
    "LastUpdatedAt": number,
    "Tags": {}
}

Request body

CalculatedAttributeName

The unique (per domain) name of the calculated attribute.
- Type : String
- Length Constraints: Minimum length of 1. Maximum length of 64.
- Pattern: ^[a-zA-Z0-9_-]+$
- Required: Yes
DisplayName

The display name of the calculated attribute.
- Length Constraints: Minimum length of 1. Maximum length of 64.
- Pattern: ^[a-zA-Z_][a-zA-Z_0-9-\s]*$
- Required: No
Description

The description of the calculated attribute.
- Type : String
- Length Constraints: Minimum length of 1. Maximum length of 1000.
- Required: No
AttributeDetails

Details of the attributes used in the definition and the mathematical operations involved between the attributes. See the following components:
- Attributes
  
  A list of attribute items specified in the mathematical expression.
  - AttributeItem
    
    The details of a single attribute item specified in the mathematical expression.
    
    Name
    
    The name of an attribute defined in a profile object type.
    
    Type: String
- Expression
  
  Mathematical expression that is performed on attribute items provided in the attribute list. Each element in the expression should follow the structure of \"{ObjectTypeName.AttributeName}\".
  - Example : {ObjA.AttributeA} - {ObjA.AttributeB}
  - Type : String
  - We only support the following mathematical operations: + - * /
  - You cannot make modifications to the Expression once a calculated attribute definition is created
Conditions

Defines the calculated attribute aggregation criteria and threshold.
- Type: Conditions object
  - Range
  - ObjectCount
  - Threshold
Range

The relative time period over which data is included in the aggregation.
- Type: Range object
  - Value: The length of time of the specified units
  - Unit: Unit of time
    
    Valid values: Days
- Required: Yes
- Initial scope: Max of 366 days
ObjectCount

The number of profile objects used for the calculated attribute.
- Type: Number
- Range: 1 through 100
- Required: No
Threshold

The comparison logic to generate a true/false calculated attribute.
- Type: Threshold object
  - Value
    
    The value of the threshold
    
    Type: String
    
    Required: No
  - Operator
    
    The operator of the threshold
    
    Type: ENUM
    
    Valid Values:
    
    GREATER_THAN
    
    LESS_THAN
    
    EQUAL_TO
    
    NOT_EQUAL_TO
- Required: No
Statistic

The aggregation operation to perform for the calculated attribute.
- Type: ENUM
- Valid Values:
  - FIRST_OCCURRENCE
  - LAST_OCCURRENCE
  - COUNT
  - SUM
  - MINIMUM
  - MAXIMUM
  - AVERAGE
  - MAX_OCCURRENCE

UpdateCalculatedAttributeDefinition

Update a calculated attribute definition. Updates are limited to display name, description, time range, object count, and threshold. This API supports partial updates, so only the parameters that require updating need to be included.

When updating the Conditions, note that increasing the date range of a calculated attribute will not trigger inclusion of historical data greater than the current date range.

Request


PUT /domains/DomainName/calculated-attributes/CalculatedAttributeName



{
    "DisplayName": "string",
    "Description": "string",
    "Conditions": {
        "Range": {
             "Value": "number",
             "Units": "string"
        },
        "ObjectCount": "number",
        "Threshold": {
            "Value": "string",
            "Operator": "EQUAL_TO" | "GREATER_THAN" | "LESS_THAN" | "NOT_EQUAL_TO"
        }
   }
}

Response



{
    "CalculatedAttributeName": "string",
    "DisplayName": "string",
    "Description": "string",
    "AttributeDetails": {
       "Attributes": [
           {
               "Name": "string"
           }
           ...
       ],
       "Expression": "string",
    },
    "Statistic": "AVERAGE" | "COUNT" | "SUM" | "FIRST_OCCURRENCE" | "LAST_OCCURRENCE" | "MINIMUM" | "MAXIMUM" | "MAX_OCCURRENCE"
    "Conditions": {
        "Range": {
             "Value": "number",
             "Units": "string"
        },
        "ObjectCount": "number",
        "Threshold": {
            "Value": "string",
            "Operator": "EQUAL_TO" | "GREATER_THAN" | "LESS_THAN" | "NOT_EQUAL_TO"
        }
    },
    "CreatedAt": number,
    "LastUpdatedAt": number,
    "Tags": {}
}

Request body

DisplayName

The display name of the calculated attribute.
- Length Constraints: Minimum length of 1. Maximum length of 64.
- Pattern: ^[a-zA-Z_][a-zA-Z_0-9-\s]*$
- Required: No
Description

The description of the calculated attribute.
- Type : String
- Length Constraints: Minimum length of 1. Maximum length of 1000.
- Required: No
Conditions

Defines the calculated attribute aggregation criteria and threshold.
- Type: Conditions object
  - Range
  - ObjectCount
  - Threshold
Range

The relative time period over which data is included in the aggregation.
- Type: Range object
  - Value: The length of time of the specified units
  - Unit: Unit of time
    
    Valid values: Days
- Required: Yes
- Initial scope: Max of 366 days
ObjectCount

The number of profile objects used for the calculated attribute.
- Type: Number
- Range: 1 through 100
- Required: No
Threshold

The comparison logic to generate a true/false calculated attribute.
- Type: Threshold object
  - Value
    
    The value of the threshold
    
    Type: String
    
    Required: No
  - Operator
    
    The operator of the threshold
    
    Type: ENUM
    
    Valid Values:
    
    GREATER_THAN
    
    LESS_THAN
    
    EQUAL_TO
    
    NOT_EQUAL_TO
- Required: No

GetCalculatedAttributeDefinition

Retrieve a calculated attribute definition.

Request


GET /domains/DomainName/calculated-attributes/CalculatedAttributeName

Request Body


The request does not have a request body.

Response



{
    "CalculatedAttributeName": "string",
    "DisplayName": "string",
    "Description": "string",
    "AttributeDetails": {
       "Attributes": [
           {
               "Name": "string"
           }
           ...
       ],
       "Expression": "string",
    },
    "Statistic": "AVERAGE" | "COUNT" | "SUM" | "FIRST_OCCURRENCE" | "LAST_OCCURRENCE" | "MINIMUM" | "MAXIMUM" | "MAX_OCCURRENCE"
    "Conditions": {
        "Range": {
             "Value": "number",
             "Units": "string"
        },
        "ObjectCount": "number",
        "Threshold": {
            "Value": "string",
            "Operator": "EQUAL_TO" | "GREATER_THAN" | "LESS_THAN" | "NOT_EQUAL_TO"
        }
    },
    "CreatedAt": number,
    "LastUpdatedAt": number,
    "Tags": {}
}

URI request parameters

DomainName

The unique name of the domain.
- Length Constraints: Minimum length of 1. Maximum length of 64.
- Pattern: ^[a-zA-Z0-9_-]+$
- Required: Yes
CalculatedAttributeName

The unique (per domain) name of the calculated attribute.
- Type : String
- Length Constraints: Minimum length of 1. Maximum length of 64.
- Pattern: ^[a-zA-Z0-9_-]+$
- Required: Yes

DeleteCalculatedAttributeDefinition

Delete an existing calculated attribute definition. Note that deleting a default calculated attribute is possible, however once deleted you will be unable to undo that action and will need to recreate it on your own using the CreateCalculatedAttributeDefinition API if you want it back.

Request


DELETE /domains/DomainName/calculated-attributes/CalculatedAttributeName

Request Body


The request does not have a request body.

Response


The response does not have a response body.

URI request parameters

DomainName

The unique name of the domain.
- Length Constraints: Minimum length of 1. Maximum length of 64.
- Pattern: ^[a-zA-Z0-9_-]+$
- Required: Yes
CalculatedAttributeName

The unique (per domain) name of the calculated attribute.
- Type : String
- Length Constraints: Minimum length of 1. Maximum length of 64.
- Pattern: ^[a-zA-Z0-9_-]+$
- Required: Yes

ListCalculatedAttributeDefinitions

Retrieve all calculated attribute definitions for a domain.

Request


GET /domains/DomainName/calculated-attributes?max-results=MaxResults&next-token=NextToken

Request Body


The request does not have a request body.

Response



{
    "Items": [
        {
            "CalculatedAttributeName": "string",
            "DisplayName": "string",
            "Description": "string",
            "CreatedAt": "timestamp",
            "LastUpdatedAt": "timestamp"
        },
        ...
    ],
    "NextToken": "string"
}

URI request parameters

DomainName

The unique name of the domain.
- Length Constraints: Minimum length of 1. Maximum length of 64.
- Pattern: ^[a-zA-Z0-9_-]+$
- Required: Yes
MaxResults

The maximum number of objects returned per page.
- Valid Range: Minimum value of 1. Maximum value of 100
NextToken

The pagination token from the previous ListCalculatedAttributeDefinition API call.
- Length Constraints: Minimum length of 1. Maximum length of 1024

GetCalculatedAttributeForProfile

Initiates the calculation and retrieves the result of a single calculated attribute for a single profile.

Request


GET /domains/DomainName/profile/ProfileId/calculated-attributes/CalculatedAttributeName

Request Body


The request does not have a request body.

Response



{
    "Name": "string",
    "DisplayName": "string",
    "Value": "string",
    "IsDataPatrial": "string"
}

URI request parameters

DomainName

The unique name of the domain.
- Length Constraints: Minimum length of 1. Maximum length of 64.
- Pattern: ^[a-zA-Z0-9_-]+$
- Required: Yes
CalculatedAttributeName

The unique (per domain) name of the calculated attribute.
- Type : String
- Length Constraints: Minimum length of 1. Maximum length of 64.
- Pattern: ^[a-zA-Z0-9_-]+$
- Required: Yes

ListCalculatedAttributesForProfile

Initiates the calculation and retrieves the results of all calculated attributes for a single profile.

Request


GET /domains/DomainName/profile/ProfileId/calculated-attributes?max-results=MaxResults&next-token=NextToken

Request Body


The request does not have a request body.

Response



{
    "Items": [
        {
            "CalculatedAttributeName": "string",
            "DisplayName": "string",
            "Value": "string",
            "IsDataPartial" : "string"
        },
        ...
    ],
    "NextToken": "string"
}

URI request parameters

DomainName

The unique name of the domain.
- Length Constraints: Minimum length of 1. Maximum length of 64.
- Pattern: ^[a-zA-Z0-9_-]+$
- Required: Yes
ProfileId
- Pattern: [a-f0-9]{32}
- Required: Yes
MaxResults

The maximum number of objects returned per page.
- Valid Range: Minimum value of 1. Maximum value of 100
NextToken

The pagination token from the previous ListCalculatedAttributeDefinition API call.
- Length Constraints: Minimum length of 1. Maximum length of 1024

Warning Javascript is disabled or is unavailable in your browser.

To use the Amazon Web Services Documentation, Javascript must be enabled. Please refer to your browser's Help pages for instructions.

Document Conventions

Customer Profiles Calculated Attributes

Creating a custom calculated attribute definition