How Custom Apps Access Databases and Store Data

How Data Is Organized

DynamoDB organizes data using two keys: a partition key (pid) and a sort key. Think of the partition key as the folder and the sort key as the file name within that folder. For custom apps, the partition key is typically your account ID, and the sort key identifies the specific record.

Each record is a JSON document that can contain any fields you need. Unlike SQL databases, you do not define a schema in advance. If you want to add a new field to your records, you simply start including it. Existing records without the field are unaffected. This flexibility is one of the reasons custom apps can be built and modified so quickly.

The Four Database Functions

Reading a Single Record

When your app needs one specific record, it uses a query with the exact partition key and sort key. For example, reading a customer's booking with ID "booking-1234" from your account. This returns the complete JSON document for that record in a single fast operation.

Reading Multiple Records

When your app needs all records that match a pattern, it uses a batch query with a sort key prefix. For example, querying all records starting with "booking-" returns every booking in your account. This is how list pages load all items, and how background jobs process all records of a given type.

Updating a Record

When your app needs to change data, it updates a single field on a record identified by its partition key and sort key. For example, changing the status of booking-1234 from "Booked" to "Confirmed." Updates are atomic, meaning the change either fully succeeds or does not happen at all. If the record does not exist yet, the update creates it automatically.

Inserting a New Record

When your app creates a new record, it inserts a document with a partition key, sort key, and the initial data. The app typically generates a unique sort key using a timestamp or counter. Inserts can include an optional time-to-live (TTL) value that automatically deletes the record after a specified number of seconds, useful for temporary data like session tokens or verification codes.

How Data Appears in the Admin

The admin pages generated for your custom app display data from the database automatically. The list page runs a batch query to load all records and displays them in a table with the columns you specified. The edit page reads a single record and presents it as a form. When you save changes, the admin writes the updated fields back to the database.

The admin also supports search, filtering, and sorting, all powered by querying and organizing the data from DynamoDB. Bulk operations like deleting multiple records or updating a field across many records at once are handled through the admin's bulk edit feature.

Performance and Scaling

DynamoDB delivers consistent performance regardless of data size. Whether your app has 100 records or 10 million, read and write operations take the same amount of time (typically single-digit milliseconds). You never need to worry about database tuning, indexing, or query optimization for custom apps.

The database also handles concurrent access automatically. Multiple users can read and write data simultaneously without conflicts, which is important for apps used by teams or for apps with API endpoints receiving external traffic.

Advanced Data Patterns

For apps that need to store multiple types of related data (like a CRM with contacts, deals, and notes), the AI builder organizes data using different sort key prefixes within the same partition. This keeps related data together for fast queries while maintaining clean separation between record types. For apps that need to connect to external databases, see the Connecting AI to Your Database pillar for MySQL, PostgreSQL, and NoSQL integration.