Filtering profiles and groups

This page describes how to create filters that limit which profiles and groups are returned by the Client.get_profiles(), Segment.get_profiles() and Client.get_groups() methods.

Usage

To create a filter, use the get_filter function on a ProfileProperty instance. This will create a new Filter instance based on the type of the given property. Use the filtering methods such as is_empty() to filter the profiles.

>>> from blueconic import Client, get_filter
>>> bc = Client()
>>> segment_id = bc.get_blueconic_parameter_value("My segment", "segment")
>>> email_property = bc.get_profile_property("email")
>>> no_email_filter = get_filter(email_property).is_empty()
>>> for profile in bc.get_profiles(segment_id, count=1000, filters=no_email_filter):
...     # loops over profiles that satisfy the filters

Multiple filters can be combined using the & operator. This will return a FilterConfig that you can use to get profiles that match all the filters in the config.

>>> filter = filter1 & filter2
>>> for profile in bc.get_profiles(segment_id, filters=filter):
...     # loops over profiles that match filter1 and filter2

Client.get_profiles() and Client.get_groups() accept a single filterconfig, or a list of filterconfigs. When a list is passed in, profiles must match at least one of the filterconfigs.

>>> for profile in bc.get_profiles(segment_id, filters=[filter1, filter2]):
...     # loops over profiles that match filter1 or filter2

Or for groups:

>>> for group in bc.get_groups(group_type_id, filters=[filter1, filter2]):
...     # loops over groups that match filter1 or filter2

API reference

get_filter(prop, group_property=None)

Create a filter for the given property. Based on the property type, an appropriate Filter subclass is returned.

Property type	Description	Filter type
SELECT	Text	TextFilter
EMAIL	Email address	TextFilter
RANGE	Number	NumberFilter
DECIMAL	Decimal	DecimalFilter
CURRENCY	Currency	DecimalFilter
DATETIME	Date time	DatetimeFilter

Parameters:

• prop (Union[str, ProfileProperty]) – The property to filter on.

• group_property – In case this property is supplied, it specifies the group property that will be filtered on.

The first argument will be the ID property to join on. :type group_property: Union[str, ProfileProperty], optional :returns: A Filter instance for the given property. :rtype: Filter

Usage:

>>> from blueconic import Client, get_filter
>>> bc = Client()
>>> email_property = bc.get_profile_property("email")
>>> email_filter = get_filter(email_property)
>>>
>>> # For getting a filter on group properties
>>> store_name_group_property = bc.get_profile_property("store_name")
>>> store_name_filter = get_filter("store_name", store_name_group_property)
>>>
>>> # For getting a filter on id properties
>>> favorite_store_id_property = bc.get_profile_property("favorite_store")
>>> favorite_store_filter = get_filter("favorite_store", favorite_store_id_property)

class Filter(profile_property, *, is_and=False, is_not=False)

Base class to filter profiles based on property values.

is_empty()

Return a filter for profiles that do not contain any value for the given property.

not_is_empty()

Return a filter for profiles that contain at least value for the given property.

property id

The id of the filtered property.

Returns:

The id of the filtered property.

Return type:

str

class TextFilter(profile_property, *, selectvalues=None, is_and=False, is_not=False, group_type_id_property=None)

Filter for text and email properties.

contains_all(*values)

Return a filter for profiles that contain all of the given values.

Parameters:

values (str) – The values to match.

contains_any(*values)

Return a filter for profiles that contain any of the given values.

Parameters:

values (str) – The values to match.

not_contains_all(*values)

Return a filter for profiles that do not contain all of the given values.

Parameters:

values (str) – The values to match.

not_contains_any(*values)

Return a filter for profiles that do not contain any of the given values.

Parameters:

values (str) – The values to match.

class NumberFilter(profile_property, *, min=None, max=None, **kwargs)

Filter for number properties.

in_range(min=None, max=None)

Return a filter for profiles that have a value in the given range.

Parameters:

• min (int, optional) – The lower bound of the range.

• max (int, optional) – The upper bound of the range.

not_in_range(min=None, max=None)

Return a filter for profiles that do not have a value in the given range.

Parameters:

• min (int, optional) – The lower bound of the range.

• max (int, optional) – The upper bound of the range.

class DecimalFilter(profile_property, *, min=None, max=None, **kwargs)

Filter for decimal and currency properties.

in_range(min=None, max=None)

Return a filter for profiles that have a value in the given range.

Parameters:

• min (Union[int, float], optional) – The lower bound of the range.

• max (Union[int, float], optional) – The upper bound of the range.

not_in_range(min=None, max=None)

Return a filter for profiles that do not have a value in the given range.

Parameters:

• min (Union[int, float], optional) – The lower bound of the range.

• max (Union[int, float], optional) – The upper bound of the range.

class DatetimeFilter(profile_property, *, min=None, max=None, filtermode='daterange', lastdays=None, nextdays=None, lasthours=None, nexthours=None, **kwargs)

Filter for date time properties.

in_last_days(days)

Return a filter for profiles that have a value in the given last days.

Parameters:

days (int) – The days to look back.

in_last_hours(hours)

Return a filter for profiles that have a value in the given last hours.

Parameters:

hours (int) – The hours to look back.

in_next_days(days)

Return a filter for profiles that have a value in the given next days.

Parameters:

days (int) – The days to look ahead.

in_next_hours(hours)

Return a filter for profiles that have a value in the given next hours.

Parameters:

hours (int) – The hours to look ahead.

in_range(min=None, max=None)

Return a filter for profiles that have a value in the given range.

Parameters:

• min (datetime, optional) – The lower bound of the range.

• max (datetime, optional) – The upper bound of the range.

not_in_last_days(days)

Return a filter for profiles that do not have a value in the given last days.

Parameters:

days (int) – The days to look back.

not_in_last_hours(hours)

Return a filter for profiles that do not have a value in the given last hours.

Parameters:

hours (int) – The hours to look back.

not_in_next_days(days)

Return a filter for profiles that do not have a value in the given next days.

Parameters:

days (int) – The days to look ahead.

not_in_next_hours(hours)

Return a filter for profiles that do not have a value in the given next hours.

Parameters:

hours (int) – The hours to look ahead.

not_in_range(min=None, max=None)

Return a filter for profiles that do not have a value in the given range.

Parameters:

• min (datetime, optional) – The lower bound of the range.

• max (datetime, optional) – The upper bound of the range.

class FilterConfig(*filters)

A FilterConfig represents a number of filters on properties. When passed to Client.get_profiles, it will only return profiles that match all of the filters in this FilterConfig.

A FilterConfig can be created by combining filters using &.

Usage:

>>> from blueconic import Client, get_filter
>>> bc = Client()
>>> no_email = get_filter("email").is_empty()
>>> active = get_filter("visits").in_range(min=3)
>>> config = no_email & active
>>> for profile in bc.get_profiles("allvisitors", filters=config):
...     ...