Querying Data

Bitmapist provides a simple and intuitive API for querying event data through a set of event classes. These classes allow you to check for user activity, count active users, and retrieve lists of user IDs for specific time periods.

Time-Based Event Classes

For time-based events, you can use one of the following classes:

  • HourEvents
  • DayEvents
  • WeekEvents
  • MonthEvents
  • YearEvents

Instantiating for the Current Period

To query events for the current time period, simply instantiate the class with the event name.

from bitmapist import DayEvents, WeekEvents, MonthEvents

# Get active users for the current day (UTC)
active_today = DayEvents('active')

# Get users who completed a task this week
completed_task_this_week = WeekEvents('task:completed')

# Get users who logged in this month
logins_this_month = MonthEvents('login')

Instantiating for a Specific Period

To query data for a past or future date, provide the specific time components to the constructor.

# Active users on January 1st, 2023
day_events = DayEvents('active', 2023, 1, 1)

# Logins during the 15th week of 2023
week_events = WeekEvents('login', 2023, 15)

# Signups in December 2022
month_events = MonthEvents('signup', 2022, 12)

You can also create an event object from any datetime object using the from_date class method.

from datetime import datetime

dt = datetime(2023, 1, 1)
active_on_date = DayEvents.from_date('active', dt)
# This is equivalent to DayEvents('active', 2023, 1, 1)

Unique Event Class

For non-time-based flags, use the UniqueEvents class.

from bitmapist import UniqueEvents

# Query for premium users
premium_users = UniqueEvents('premium_user')

# Query for users in an A/B test group
ab_group = UniqueEvents('ab_test:new_flow')

Common Query Operations

All event objects support the same set of intuitive Python operations.

Getting Counts with len()

To find out how many unique users triggered an event in a given period, use the built-in len() function.

active_count = len(DayEvents('active'))
print(f"There are {active_count} active users today.")

Checking Membership with in

To check if a specific user ID performed an action, use the in operator.

user_id = 123
if user_id in DayEvents('active'):
    print(f"User {user_id} was active today.")

Iterating Over User IDs

You can iterate directly over an event object to get all user IDs that are part of that event set.

print("Active users today:")
for user_id in DayEvents('active'):
    print(user_id)

To get a list of all user IDs, simply cast the event object to a list.

active_ids = list(DayEvents('active'))
print(f"All active IDs: {active_ids}")

Checking if Any Events are Marked

If you only need to know whether any user performed an action (without needing the count), you can use the has_events_marked() method. This can be slightly more efficient than len() if you only need a boolean check.

if DayEvents('special:promo').has_events_marked():
    print("At least one user participated in the special promo today!")