Person profiles and user properties

Person profiles are collections of properties about the users behind the events. You can use these user properties to better manage, analyze, and control data.

For example, you can create filters or cohorts based on user properties, which can then be used to create insights, feature flags, and more.

For backward compatibility, PostHog captures events with person profiles by default. You can change this by setting your JavaScript initialization's person_profiles to identified_only or an event's $process_person_profile property to false.

Note: Setting user properties creates a profile for the person you are tracking. Under our current pricing, events without person profiles can be up to 4x cheaper than events with them (due to computer cost of processing them), so it's recommended to only capture person profiles (via identify() or $set) when needed.

How to set user properties

The recommended way to set user properties in person profiles is to include them when capturing an event:

posthog.capture(
    'event_name', 
    { 
        $set: { name: 'Max Hedgehog'  },
        $set_once: { initial_url: '/blog' },
    }
)

You can also set user properties when you call the identify method:

posthog.identify(
  'distinct_id',  // Replace 'distinct_id' with your user's unique identifier
  { email: 'max@hedgehogmail.com', name: 'Max Hedgehog' } // optional: set additional user properties
);

User property values can be strings, booleans, numbers, objects, or arrays. For objects and arrays, you can use HogQL to access nested properties in the PostHog app.

Note: User properties are set in the order the events are ingested, and not according to event timestamps. Since we typically ingest events as soon as we receive them, you only need to take this into consideration when you're importing historical data.

What is the difference between set and set_once?

When using set, it will replace any value that may have been set on a person for a specific property. In contrast, set_once will only set the property if it has never been set before.

set is typically used for properties that may change over time – e.g., email, current plan, organization name. set_once is typically only used for information that is guaranteed to never change – e.g., the first URL a user visited, or the date a user first logged in.

For example:

posthog.capture(
    'event_name', 
    { 
        $set: { name: 'Max Hedgehog'  },
        $set_once: { initial_url: '/blog' },
    }
)
posthog.capture(
    'event_name', 
    { 
        $set: { name: 'Mr. Fox'  },
        $set_once: { initial_url: '/pricing' },
    }
)
// name: 'Mr. Fox'
// initial_url: '/blog'

Further reading

See our full documentation on persons and user properties for more details.