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:
MapAttributeuses DynamoDB's native Map typeJSONAttributestores 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 |