Models and Fields

Declare a Model by inheriting from Model. Then simply define your choice of fields. Models are flexible to allow any number of fields and types of fields. A primary key field (or at least the Redis equivalent) will be automatically added if necessary.

from popoto import Model

class MyObject(Model):
    # add fields


A KeyField makes objects fast and easy to query for. In the background, Popoto uses all KeyFields to compile the primary key on Redis. There almost no performance downside to using many KeyFields.

from popoto import Model, AutoKeyField, UniqueKeyField, KeyField

class User(Model):
    uuid = AutoKeyField()
    username = UniqueKeyField(max_length=20)
    name = KeyField(max_length=100, unique=False)

It's recommended that at least one KeyField has unique=True enforced.

These KeyFields will each enforce uniqueness across all saved instances: AutoKeyfield, UniqueKeyfield, and KeyField(unique=True)

from popoto import Model, AutoKeyField, UniqueKeyField, KeyField

class User(Model):
    uuid = AutoKeyField()
    username = UniqueKeyField()
    email = KeyField(unique=True)

However, it is enough for all KeyFields to be considered "unique together" In this example, a unique Box is the combination of dimensions. The combined dimensions together will be unique to every instance.

class Box(Model):
    length = KeyField(type=float)
    width = KeyField(type=float)
    height = KeyField(type=float)

Finally, it is also possible to declare a Model without a KeyField and Popoto will create and maintain a hidden unique key.

from popoto import Model, DecimalField, SortedField
from datetime import datetime

class BitcoinPrice(Model):
    usd_value = DecimalField()
    timestamp = SortedField(type=datetime)

The above example may be useful in situations where all queries are made via special purpose fields, such as SortedField, GeoField, or GraphField


All fields inherit from base Field. A basic Field on any model will provide type validation on create and update events.

The following types are supported for use: int, float, Decimal, str, bool, list, dict, bytes,, datetime.datetime, datetime.time

The default type for value = Field() is type str - string

from popoto import *
from decimal import Decimal
from datetime import datetime, date, time

class EveryTypeModel(Model):
    string_val = Field(type=str)
    int_val = Field(type=int)
    float_val = Field(type=float)
    decimal_val = Field(type=Decimal)
    boolean_val = Field(type=bool)
    list_val = Field(type=list)
    set_val = Field(type=set)
    tuple_val = Field(type=tuple)
    dict_val = Field(type=dict)
    bytes_val = Field(type=bytes)
    date_val = Field(type=date)
    datetime_val = Field(type=datetime)
    time_val = Field(type=time)

Named fields shown below are equivalent to the fields above. You may declare fields to your preference.

class EveryTypeModel(Model):
    int_val = IntField()
    float_val = FloatField()
    decimal_val = DecimalField()
    string_val = StringField()
    boolean_val = BooleanField()
    list_val = ListField()
    set_val = SetField()
    tuple_val = TupleField()
    dict_val = DictField()
    bytes_val = BytesField()
    date_val = DateField()
    datetime_val = DatetimeField()
    time_val = TimeField()

Null Values

KeyField and SortedField values are considered required null=False by default. All other fields are optional null=True by default. You may explicitly declare whether to allow null values using the null keywword

class MyModel(Model):
    optional_value = Field(null=True)
    required_value = Field(null=False)

Default Values

All fields will accept a default value for new objects.

class MyModel(Model):
    status = Field(type=str, default="unknown")
    is_true = Field(type=bool, default=False)
    access_count = Field(type=int, default=0)

String Max Length

Set a limit to string length. On SQL-like databases, this is often required. However, on Redis (and Popoto), there is no performance requirement or advantage to setting the max_length. Use it if you want Popoto to raise exceptions on model validation.

class Tweet(Model):
    text = Field(type=str, max_length=280)


Use a SortedField for numerical attributes. A SortedField provides fast and efficient access to ordered instances (via Redis ZADD, ZRANGE). Querying for instances by order of a timestamp or attribute counter is one of the most powerful and common reasons for employing a Redis database.

A SortedField is necessary in order to use these query filters: __lt=, __gt=, etc. See details on filters at Query Filters

import datetime

class SortedDateModel(Model):
    name = KeyField()
    birthday = SortedField(

lisa = SortedDateModel.create(name="Lisa",, 3, 27))
rose = SortedDateModel.create(name="Rose",, 2, 11))
jisoo = SortedDateModel.create(name="Jisoo",, 1, 3))
jennie = SortedDateModel.create(name="Jennie",, 1, 16))

oldest = SortedDateModel.query.filter(, 1, 1))[0]
assert jisoo == oldest
younger_than_rose = SortedDateModel.query.filter(birthday__gt=rose.birthday)
assert lisa in younger_than_rose

To use a SortedField also as a KeyField, use SortedKeyField

class BitcoinPrice(Model):
    timestamp = SortedKeyField(type=datetime)
    usd_value = DecimalField()

In some cases, you may always sort against a required KeyField. You will see significant performance improvements if you define sort_by (must be a tuple). Going forward, whenever a query filter is called on the SortedField, then all fields in 'sort_by' will also need to be defined in the filter.

In the example below, we've generalized the above BitcoinPrice model to be a generic asset. Because we will query by timestamp ranges for only one asset at a time, we can declare sort_by="asset".

class AssetPrice(Model):
    asset = KeyField()
    timestamp = SortedKeyField(type=datetime, sort_by=('asset',))
    usd_value = DecimalField()

)  ## return Bitcoin prices over 1 day period

Note: because asset was specified as a sort_by in the timestamp field, the query requires the asset to be defined. This limitation, if you choose to use it, enables maximum performance with Redis.


The GeoField employs another popular Redis feature - geospatial search. A common use case is searching for objects within a radius of another object. Use the GeoField to set coordinates on a model to enable these powerful query filters.

Popoto provides a namedtuple Coordinates. Although, any tuple of (float, float) for (latitude, longitude) is allowed.

from GeoField import Coordinates

class GeoModel(Model):
    name = KeyField()
    coordinates = GeoField()

rome = GeoModel.create(
    coordinates=Coordinates(latitude=41.902782, longitude=12.496366)

vatican = GeoModel.create(
    coordinates=Coordinates(latitude=41.904755, longitude=12.454628)

assert vatican in GeoModel.query.filter(coordinates=rome.coordinates, coordinates_radius=5, coordinates_radius_unit='km')


The DataFrameField allows for storage of Pandas DataFrame objects for generic blocks of tabular data. A common use case is storing machine learning training data and results. No more pesky csv files. Use a database!

import pandas as pd

class DataModel(Model):
    name = KeyField()
    dataframe = DataFrameField()

chicago_home_prices = DataModel.create(
    name="Chicago Home Price",

              Price         Year
count      5.000000     5.000000
mean   27600.000000  2016.000000
std     4878.524367     1.581139
min    22000.000000  2014.000000
25%    25000.000000  2015.000000
50%    27000.000000  2016.000000
75%    29000.000000  2017.000000
max    35000.000000  2018.000000

Reserved Field Names

The following names are reserved and cannot be used as field names:

  • limit: is used in query.filter() to limit the size of the returned objects list
  • values: is used in query.filter() to restrict which values are returned for objects
  • order_by: is used in query.filter() to order the results