Skip to content

Data types

This page consolidates the supported data types for custom attributes, event properties, and catalogs. Each custom data type has slightly different data type support and constraints.

Definitions

Use this table to see which data types you can use for user profile attributes, event data, or catalog items. Refer to the sections that follow for usage and constraints for each type.

Important considerations

  • Array: Custom attributes and event properties have size limits. Datetimes are not supported inside arrays in event properties. Catalogs support only string arrays, with a maximum of 100 elements.
  • Object: In Braze, this appears as “nested custom attributes” for custom attributes, “nested objects” for event properties, and “JSON object” for catalogs.
  • Time: In event properties, this type is labeled “Datetime.”

Custom attribute data types

Custom attributes support the data types listed in the Definitions table. The following describes usage and segmentation for each supported data type.

For Boolean attributes, the following segmentation options are available.

For Number attributes, the following segmentation options are available.

Number attribute details

  • “Exactly 0” and “Less Than” filters include users with NULL fields
    • To exclude users without a value for custom attributes, you need to include the is not blank filter.

String attributes can be up to 255 characters long. Note that if you input any values with spaces in between, before, or after words, Braze will also check for the same spaces.

For String attributes, the following segmentation options are available.

Arrays have a maximum size of 100 KB. The default length for an attribute is up to 500 items (for example, if you’re sending an attribute such as “Movies Watched” set to 500, when a user watches a 501st movie, the first movie is removed and the most recent is added). Note that if you input any values with spaces in between, before, or after words, Braze will also check for the same spaces.

For Array attributes, the following segmentation options are available.

Time filters using relative dates (for example, more than 1 day ago, less than 2 days ago) measure 1 day as 24 hours. For example, to build a segment that targets users with a time attribute between 24 and 48 hours in the future, apply the filters in more than 1 day in the future and in less than 2 days in the future.

For Time attributes, the following segmentation options are available.

Time attribute details

  • Day of Recurring Event
    • When using the “Day of Recurring Event” filter, and are then prompted to select the “Calendar Day of Recurring Event”, if you select IS LESS THAN or IS MORE THAN, the current date will be counted for that segmentation filter.
    • For example, if on March 10, 2020, you selected the date of the attribute to be LESS THAN ... March 10, 2020, attributes will be considered for the days up to, and including March 10, 2020.
  • Less than X Days Ago: The “Less than X Days Ago” filter includes dates between X days ago and the current date/time.
  • Less than X Days in the Future: Includes dates between the current date/time and X days in the future.

You can use nested custom attributes to send objects as a data type for custom attributes. For more information, refer to Nested custom attributes.

Use an array of objects to group related attributes. For more details, refer to Array of objects.

You can change the data type of your custom attribute, but you should be aware of the impacts. Refer to Changing custom attribute or event data type for more.

Consolidated operators

We’ve consolidated the list of operators available to use in attribute filters, custom attribute filters, and nested custom attribute filters. If you have existing filters using these operators, they will be automatically updated to use the new operators.

Event property data types

When you log an event, you can attach extra information (for example, product name or price) as event properties. Each property has a name and a value. Event property values support the data types in the Definitions table (Time is labeled “Datetime” in event properties).

Expected format

Property values are sent as an object: keys are the property names, and values are the property values. Property names must be non-empty strings, 255 characters or fewer, with no leading dollar signs ($).

Event-property-specific rules:

  • Time (Datetime): Use ISO 8601 or yyyy-MM-dd'T'HH:mm:ss:SSSZ format. Not supported within arrays.
  • Array: Datetimes are not supported within arrays.
  • Nested object: See Nested objects.
  • Payload: Event property objects that contain array or object values can be up to 100 KB.

You can change the data type of your custom event property, but be aware of the impacts of changing data types after data has been collected.

For full event property behavior, reserved keys, and usage in triggers and personalization, see Custom event properties.

Purchase events and revenue

Purchase and revenue data is recorded through purchase events or recommended eCommerce events.

Logging purchase events establishes the Lifetime Value (LTV) for each user profile, and this data is viewable on the revenue page in time-series. You can segment on money spent, last purchase date, number of purchases in a time window, and more.

Purchase event property data types

Purchase event property values (the properties object on a purchase) support the data types in the Definitions table, with the same structure and naming rules as event properties.

The properties values must be an object up to 50 KB where the keys are the property names and the values are the property values. Property names must be strings, 255 characters or fewer, with no leading dollar signs ($).

Property values can be any of the following data types:

The following keys are reserved and cannot be used as property names: time, product_id, quantity, event_name, price, and currency. Using a reserved key in the properties object returns the error “Invalid ‘properties’ field”.

For the full purchase object schema and examples, see Purchase object. For logging purchase events, segmentation filters, and full details, refer to Purchase events.

Changing custom attribute or event data type

To change the data type of a custom attribute or event:

  1. Go to Data Settings and select either Custom Attributes or Custom Events.
  2. Find your attribute or event from the list, and select More actions.
  3. Select a new Data type from the dropdown.
  4. Select Save.

If you change the data type of a custom attribute or event (for example, changing time to string), consider the following:

  • Filters are not automatically updated. Segments, campaigns, Canvases, or other locations that use the changed attribute or event are not updated. Before you change the data type, stop any campaigns or Canvases that use the attribute in segments or filters, and remove the attribute from filters that reference it.
  • Existing user data is not retroactively updated. If the changed attribute was on a user profile before the change, that value remains the old data type. Users can fall out of segments that contain the changed attribute because the filter looks for the new data type. Update those user profiles (for example, with the /users/track endpoint) so they match the new type and re-enter the segment if needed.
  • New data must match the new type. API calls that send the previous data type for the changed attribute are not accepted. Send the new data type.

Catalog data types

Catalogs support the types listed in the Definitions table. The following table lists each type, how it can be created or updated, and format and examples.

Format and examples

For creating and updating catalogs, see Create a catalog.
Github   Edit this page on GitHub
New Stuff!