Storage Options

As part of App Builder, you have access to three storage services for persisting data dynamically from your Runtime actions: Database, Files, and State. Each service is designed for different use cases, with distinct benefits and trade-offs.

Quick comparison

The following table summarizes the key differences between the three storage services:

Usage quotas and limits

The following quotas and limits apply while dealing with Persistent Storage associated with your App Builder application.

Quotas are shared across the organization. Workspace limits are defined at the workspace level. The Database and State services may return 429 (rate-limits) or 403 (storage limits) errors if limits are exceeded.

State storage limits

Database storage limits

State

State provides a high-performance key-value store optimized for low-latency access to small pieces of data.

Benefits

• Fast access — Optimized for latency-sensitive operations
• No provisioning required — Works immediately with your App Builder credentials
• Time-to-live (TTL) — Automatic expiration of data (up to 365 days)
• Multi-region support — Choose from amer, emea, apac, or aus regions
• Simple API — Easy get, put, delete, and list operations
• CLI and SDK support — Manage state from code or command line

Drawbacks

• Size limits — Maximum 1 MB per value, 1 KB per key
• No sharing — Cannot generate shareable URLs for data
• Limited querying — Only key-based access and glob pattern matching
• Storage quotas — Limited to 10 GB per App Builder pack, 1 GB per production workspace
• Eventual consistency for list — List operations may not immediately reflect recent changes

When to use state

• Session data and user preferences
• Caching frequently accessed data
• Temporary data that should auto-expire
• Small configuration values
• Data under 100 KB that needs fast access

Learn more about State

Files

Files provides blob storage for large binary data, built as an abstraction layer over cloud storage services.

Benefits

• Large file support — Store files up to 200 GB
• Shareable URLs — Generate pre-signed URLs for secure sharing
• Streaming support — Efficient handling of large data transfers
• No provisioning required — Works immediately with your App Builder credentials
• Copy operations — Duplicate files without re-uploading
• Strong consistency — Read-after-write consistency guaranteed

Drawbacks

• No TTL — Data persists indefinitely until manually deleted
• No bulk delete — Must delete files individually
• Higher latency — Optimized for throughput, not speed
• Limited querying — Only path-based access, no search capabilities
• Regional constraints — Data stored in US regions only

When to use files

• Storing images, videos, or documents
• Large payloads over 100 KB
• Data that needs to be shared by URL
• Binary data requiring streaming
• Long-term storage without expiration

Learn more about Files

Database

Database Storage provides a document-style database with a MongoDB-compatible API, powered by AWS DocumentDB.

Benefits

• Rich queries — Full query language with filters, projections, and sorting
• Aggregation pipelines — Complex data transformations and analytics
• Indexing — Create indexes for optimized query performance
• Collections — Organize data into logical groups
• Schema validation — Optional enforcement of document structure
• Familiar API — Compatible with MongoDB Node Driver patterns
• Geospatial queries — Location-based data operations
• Strong consistency — CRUD operations are strongly consistent

Drawbacks

• Requires provisioning — Must explicitly create database before use
• More complex — Steeper learning curve than State or Files
• Regional lock-in — Database is tied to a single region (amer, emea, or apac)
• Limited admin commands — Fewer administrative features than standalone MongoDB
• Connection management — Must handle client connections properly

When to use database

• Complex data with relationships between entities
• Data requiring advanced queries and filtering
• Applications needing aggregation and analytics
• Large datasets requiring indexing for performance
• Data that benefits from schema validation
• Applications migrating from MongoDB or DocumentDB

Learn more about Database

Choosing the right storage

Use this decision guide to select the appropriate storage service:

Is your data larger than 100 KB?
├── Yes → Do you need shareable URLs?
│         ├── Yes → Use Files
│         └── No → Is it structured data needing queries?
│                  ├── Yes → Use Database
│                  └── No → Use Files
└── No → Do you need complex queries or relationships?
         ├── Yes → Use Database
         └── No → Do you need automatic expiration?
                  ├── Yes → Use State
                  └── No → Use State (simpler) or Database (more features)

Common patterns

Getting started

All three storage services integrate seamlessly with App Builder:

# State - install the library
npm install @adobe/aio-lib-state

# Files - install the library  
npm install @adobe/aio-lib-files

# Database - install the library and provision
npm install @adobe/aio-lib-db
aio app db provision

For State and Files no additional configuration is needed. These libraries automatically use your App Builder credentials for authentication and authorization.

The Database library does require some additional configuration, but does not require any special entitlements beyond App Builder itself. See the App Builder Data Services API documentation for details.