Skip to content

Declare an analytics property ​

Custom event properties first arrive as observed. Declaring a property gives it a stable type and makes it available to goal predicates. Declared enum properties can also be used as analytics and funnel breakdowns.

The console displays declared properties but does not author them. Use an agent, the CLI, or the API.

1. Send the property ​

Post at least one custom event carrying the property. For example:

javascript
track('select_plan', { plan: 'pro' });

See Collect analytics events for the complete track example.

2. Review observed properties ​

text
On acme-marketing, check the observed analytics properties and show
their inferred types, cardinality, recommendations, and safe samples.

The agent runs edge_property_check. Samples that match a PII detector appear as (blocked), not as the original value. Review the distinct-value count before choosing enum: an unbounded value such as an order id is not a useful breakdown.

3. Declare it ​

value_type is enum, string, int, or bool. An enum must provide allowed_values.

text
Declare plan on acme-marketing as an enum with starter, pro, and
enterprise values.
bash
edge api POST /v1/distributions/d3f7a1c4-90b2-4e6a-8f15-6c2b7e0a9d38/properties/plan/declare --input - <<'EOF'
{
        "value_type": "enum",
        "allowed_values": ["starter", "pro", "enterprise"]
      }
EOF
bash
curl -s -X POST \
  https://api.edge.deca-dev.com/v1/distributions/d3f7a1c4-90b2-4e6a-8f15-6c2b7e0a9d38/properties/plan/declare \
  -H "Authorization: Bearer $EDGE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "value_type": "enum",
        "allowed_values": ["starter", "pro", "enterprise"]
      }'

The agent runs edge_property_declare. Declaration is metadata-only: retained historical values become queryable without rewriting old events.

Maintain the declaration ​

Use edge_property_update or PATCH /v1/distributions/{id}/properties/{key} to change:

  • value_type and allowed_values
  • max_cardinality
  • on_violation: truncate or drop_value

Archive a property with edge_property_archive or DELETE on the same HTTP path. Archiving stops using it as a declared property; it does not erase historical events. Reserved revenue properties cannot be archived.

Use it ​

The Analytics console shows declared properties in the Properties view. Enum properties can be selected as breakdowns, and declared properties can be referenced by a conversion goal.

Next ​