Flags, Switches and Samples

Waffle supports three separate but ultimately similar concepts: Flags and Switches, and Samples.

Basically, a Flag is tied to a request, while Switches and Samples are not. Consequently, Flags are much more complicated, while Switches are just a named boolean in the database, and Samples are just a percentage stored in the database.


Creating and managing flags is done through the Django admin interface. Each feature flag is represented by a Flag object, which has several properties.

The name of the flag. Will be used to identify the flag everywhere.
You can flip this flag on (Yes) or off (No) for everyone, overriding all other settings. Leave as Unknown to use normally.
Let’s you override the flag value using the url querystring. See Overriding Flags for details.
A percentage of users for whom the flag will be active. This is maintained through cookies, so clever users can get around it. Still, it’s the most common case.
Is this flag always active for superusers?
Is this flag always active for staff?
Is this flag always active for authenticated users?
A list of group IDs for which this flag will always be active.
A list of user IDs for which this flag will always be active.
Activate Rollout mode? See Rollout Mode for details.
Describe where the flag is used.

You can combine multiple settings here. For example, you could offer a feature to 12% of users and all superusers. When combining settings, the flag will be active for the user if any of the settings matches for them.


Switches are also managed through the Django admin. Each Switch object has these properties:

The name of the switch.
Is the switch active or inactive.
Describe where the switch is used.

Like Flags, Switches can be used in views, templates, or wrapped around entire templates. But because they don’t rely on a request objects, Switches can also be used in crons, Celery tasks, daemons—basically anywhere you can access the database.


Samples, also managed through the Django admin, has these properties:

The name.
A number from 0.0 to 100.0 that determines how often the sample will be active.
Describe where the sample is used.

Samples are useful for datamining or other “some of the time” tasks that are not linked to a user or request—that is, unlike Flags, they do not set cookies and can’t be reliably assumed to be a given value for a given user.

Table Of Contents

Previous topic


Next topic

Using Waffle

This Page