Skip to content

Attribute types

Attributes define the fields in your model. Each attribute maps to a DynamoDB type.

Overview

Type DynamoDB Python Use case
StringAttribute S str Text, IDs, keys
NumberAttribute N int, float Counts, prices
BooleanAttribute BOOL bool Flags
BinaryAttribute B bytes Files, images
ListAttribute L list Ordered items
MapAttribute M dict Nested objects
JSONAttribute S dict, list Complex JSON
EnumAttribute S Enum Status, types
DatetimeAttribute S datetime Timestamps (ISO)
TTLAttribute N datetime Auto-expiring items
StringSetAttribute SS set[str] Unique strings
NumberSetAttribute NS set[int|float] Unique numbers
CompressedAttribute S str Large text
EncryptedAttribute S str Sensitive data

Common parameters

All attributes share these parameters:

Parameter Type Default Description
hash_key bool False Is this the partition key
range_key bool False Is this the sort key
default Any None Default value or AutoGenerate strategy
null bool True Allow None values

Tip

Use AutoGenerate strategies for automatic ID and timestamp generation. See Auto-generate strategies.

Basic types

StringAttribute

Store text values. Most common attribute type.

from pydynox import Model, ModelConfig
from pydynox.attributes import StringAttribute

class User(Model):
    model_config = ModelConfig(table="users")

    pk = StringAttribute(hash_key=True)
    name = StringAttribute()
    email = StringAttribute(null=False)  # Required

NumberAttribute

Store integers and floats. DynamoDB stores all numbers as strings internally.

from pydynox.attributes import NumberAttribute

class Product(Model):
    model_config = ModelConfig(table="products")

    pk = StringAttribute(hash_key=True)
    price = NumberAttribute()
    quantity = NumberAttribute(default=0)

BooleanAttribute

Store true/false values.

from pydynox.attributes import BooleanAttribute

class User(Model):
    model_config = ModelConfig(table="users")

    pk = StringAttribute(hash_key=True)
    is_active = BooleanAttribute(default=True)
    is_verified = BooleanAttribute(default=False)

BinaryAttribute

Store raw bytes. Useful for small files or binary data.

from pydynox.attributes import BinaryAttribute

class Document(Model):
    model_config = ModelConfig(table="documents")

    pk = StringAttribute(hash_key=True)
    thumbnail = BinaryAttribute()

ListAttribute

Store ordered lists. Can contain mixed types.

from pydynox.attributes import ListAttribute

class Post(Model):
    model_config = ModelConfig(table="posts")

    pk = StringAttribute(hash_key=True)
    tags = ListAttribute(default=[])
    comments = ListAttribute()

MapAttribute

Store nested objects as DynamoDB's native Map type.

from pydynox.attributes import MapAttribute

class User(Model):
    model_config = ModelConfig(table="users")

    pk = StringAttribute(hash_key=True)
    address = MapAttribute()

user = User(
    pk="USER#1",
    address={"street": "123 Main St", "city": "NYC", "zip": "10001"}
)

JSON and enum types

JSONAttribute

Store dict or list as a JSON string. Different from MapAttribute:

  • MapAttribute uses DynamoDB's native Map type
  • JSONAttribute stores as a string (useful for complex nested structures)
"""JSONAttribute example - store dict/list as JSON string."""

from pydynox import Model, ModelConfig
from pydynox.attributes import JSONAttribute, StringAttribute


class Config(Model):
    model_config = ModelConfig(table="configs")

    pk = StringAttribute(hash_key=True)
    settings = JSONAttribute()


# Save a dict
config = Config(
    pk="CFG#1",
    settings={"theme": "dark", "notifications": True, "max_items": 50},
)
config.save()
# Stored as '{"theme": "dark", "notifications": true, "max_items": 50}'

# Load it back
loaded = Config.get(pk="CFG#1")
print(loaded.settings["theme"])  # "dark"

# Works with lists too
config2 = Config(pk="CFG#2", settings=["item1", "item2", "item3"])
config2.save()

When to use JSONAttribute over MapAttribute:

  • Deep nesting (DynamoDB has limits on nested maps)
  • You need to store the exact JSON structure
  • Compatibility with other systems expecting JSON

EnumAttribute

Store Python enum as its value. Keeps your code type-safe.

"""EnumAttribute example - store Python enum as string."""

from enum import Enum

from pydynox import Model, ModelConfig
from pydynox.attributes import EnumAttribute, StringAttribute


class Status(Enum):
    PENDING = "pending"
    ACTIVE = "active"
    INACTIVE = "inactive"


class User(Model):
    model_config = ModelConfig(table="users")

    pk = StringAttribute(hash_key=True)
    status = EnumAttribute(Status, default=Status.PENDING)


# Create with enum value
user = User(pk="USER#1", status=Status.ACTIVE)
user.save()
# Stored as "active" in DynamoDB

# Load it back - returns the enum
loaded = User.get(pk="USER#1")
print(loaded.status)  # Status.ACTIVE
print(loaded.status == Status.ACTIVE)  # True

# Default value works
user2 = User(pk="USER#2")
print(user2.status)  # Status.PENDING
Parameter Type Default Description
enum_class type[Enum] Required The Enum class

Date and time types

DatetimeAttribute

Store datetime as ISO 8601 string. Sortable as string, good for range queries.

"""DatetimeAttribute example - store datetime as ISO string."""

from datetime import datetime, timezone

from pydynox import Model, ModelConfig
from pydynox.attributes import DatetimeAttribute, StringAttribute
from pydynox.hooks import before_save


class Event(Model):
    model_config = ModelConfig(table="events")

    pk = StringAttribute(hash_key=True)
    created_at = DatetimeAttribute()


# Save with datetime
event = Event(pk="EVT#1", created_at=datetime.now(timezone.utc))
event.save()
# Stored as "2024-01-15T10:30:00+00:00"

# Load it back - returns datetime object
loaded = Event.get(pk="EVT#1")
print(loaded.created_at)  # datetime object
print(loaded.created_at.year)  # 2024


# Auto-set timestamps with hooks
class Article(Model):
    model_config = ModelConfig(table="articles")

    pk = StringAttribute(hash_key=True)
    created_at = DatetimeAttribute(null=True)
    updated_at = DatetimeAttribute(null=True)

    @before_save
    def set_timestamps(self):
        now = datetime.now(timezone.utc)
        if self.created_at is None:
            self.created_at = now
        self.updated_at = now


article = Article(pk="ART#1")
article.save()
print(article.created_at)  # Auto-set on first save
print(article.updated_at)  # Updated on every save

Naive datetimes (without timezone) are treated as UTC.

TTLAttribute

Store datetime as epoch timestamp for DynamoDB's auto-delete feature.

from pydynox.attributes import TTLAttribute, ExpiresIn

class Session(Model):
    model_config = ModelConfig(table="sessions")

    pk = StringAttribute(hash_key=True)
    expires_at = TTLAttribute()

# Create session that expires in 1 hour
session = Session(pk="SESSION#123", expires_at=ExpiresIn.hours(1))
session.save()

ExpiresIn helpers:

Method Description
ExpiresIn.seconds(n) n seconds from now
ExpiresIn.minutes(n) n minutes from now
ExpiresIn.hours(n) n hours from now
ExpiresIn.days(n) n days from now
ExpiresIn.weeks(n) n weeks from now

Warning

TTL must be enabled on the DynamoDB table. The attribute name must match exactly.

Set types

StringSetAttribute

Store unique strings. DynamoDB native set type (SS).

from pydynox.attributes import StringSetAttribute

class User(Model):
    model_config = ModelConfig(table="users")

    pk = StringAttribute(hash_key=True)
    roles = StringSetAttribute()

user = User(pk="USER#1", roles={"admin", "editor"})
user.save()

# Check membership
print("admin" in user.roles)  # True

NumberSetAttribute

Store unique numbers. DynamoDB native set type (NS).

"""StringSetAttribute and NumberSetAttribute examples."""

from pydynox import Model, ModelConfig
from pydynox.attributes import (
    NumberSetAttribute,
    StringAttribute,
    StringSetAttribute,
)


class User(Model):
    model_config = ModelConfig(table="users")

    pk = StringAttribute(hash_key=True)
    tags = StringSetAttribute()
    scores = NumberSetAttribute()


# Create with sets
user = User(
    pk="USER#1",
    tags={"admin", "verified", "premium"},
    scores={100, 95, 88},
)
user.save()

# Load it back - returns Python sets
loaded = User.get(pk="USER#1")
print(loaded.tags)  # {'admin', 'verified', 'premium'}
print(loaded.scores)  # {100, 95, 88}

# Check membership
print("admin" in loaded.tags)  # True
print(100 in loaded.scores)  # True

# Sets don't allow duplicates
user2 = User(pk="USER#2", tags={"a", "a", "b"})
print(user2.tags)  # {'a', 'b'}

Note

Empty sets are stored as None. On load, you get an empty Python set.

Special types

CompressedAttribute

Auto-compress large text. Saves storage costs and avoids the 400KB limit.

from pydynox.attributes import CompressedAttribute, CompressionAlgorithm

class Document(Model):
    model_config = ModelConfig(table="documents")

    pk = StringAttribute(hash_key=True)
    body = CompressedAttribute()  # Uses zstd by default
    logs = CompressedAttribute(algorithm=CompressionAlgorithm.Lz4)
Parameter Type Default Description
algorithm CompressionAlgorithm Zstd Compression algorithm
level int 3 Compression level
min_size int 100 Min bytes to compress
threshold float 0.9 Only compress if ratio below this

Algorithms:

Algorithm Best for
Zstd Most cases (default)
Lz4 Speed over size
Gzip Compatibility

EncryptedAttribute

Encrypt sensitive data using AWS KMS.

from pydynox.attributes import EncryptedAttribute, EncryptionMode

class User(Model):
    model_config = ModelConfig(table="users")

    pk = StringAttribute(hash_key=True)
    ssn = EncryptedAttribute(key_id="alias/my-key")
Parameter Type Default Description
key_id str Required KMS key ID or alias
mode EncryptionMode ReadWrite ReadWrite, WriteOnly, or ReadOnly
region str None AWS region
context dict None Encryption context

Modes:

Mode Encrypt Decrypt Use case
ReadWrite Full access
WriteOnly Ingest service
ReadOnly Report service

Choosing the right type

Need Use
Simple text StringAttribute
Numbers NumberAttribute
True/false BooleanAttribute
Nested object MapAttribute
Complex JSON JSONAttribute
Type-safe status EnumAttribute
Sortable timestamp DatetimeAttribute
Auto-expiring items TTLAttribute
Unique values StringSetAttribute / NumberSetAttribute
Large text CompressedAttribute
Sensitive data EncryptedAttribute