= and the grid runs a Query that reads one partition; leave it out and the grid runs a Scan, which reads the whole table and is billed for every item it reads, including the ones your filters then drop.
The DynamoDB driver is not in the app. Picking DynamoDB in the Choose a Database sheet offers the
download before the form opens, and opening a saved DynamoDB connection installs it without asking.
Settings > Plugins > Browse > DynamoDB Driver installs it up front. See Plugins.
Quick setup
Click New Connection…, select DynamoDB, choose an Auth Method, fill in its fields and the AWS Region, then click Save & Connect.
Access Key + Secret Key shows the key fields; AWS Profile and AWS SSO take a profile name instead
Connection settings
There is no host, port, database or connection URL. A connection is one AWS account in one region, and the sidebar lists that region’s tables. Every region works, as does DynamoDB Local.
The endpoint follows the region’s partition, so
cn-north-1 reaches dynamodb.cn-north-1.amazonaws.com.cn and the European Sovereign Cloud reaches its own domain without a custom endpoint.
Authentication
Pick AWS Profile if the AWS CLI already works on this Mac. Static keys,
credential_process helpers and role_arn chains all resolve; the rules are on AWS IAM Authentication. Expired temporary credentials are fetched again and the request retried once.
DynamoDB Local
http://localhost:8000; fill it in for any other port.
How a table is read
Opening a table, filtering it and paging it all go through one planner. It picks the cheapest read your filters allow and names it at the start of the status bar, followed by how many items came back, how many DynamoDB read to find them, and the read capacity units it charged:Query on index byStatus · 50 returned · 212 read · 26.5 RCU.
A filter on the sort key of the chosen table or index joins the key condition when it is
=, <, <=, >, >=, BETWEEN or STARTS WITH. Other filters become a FilterExpression, which DynamoDB applies after reading, so they narrow the rows without lowering the bill. ENDS WITH, regular expressions, matches that ignore case and a search across every column are checked on the returned items instead. CONTAINS means what DynamoDB’s contains means on either side: text inside a String, or a member of a set or a list. STARTS WITH ignores case until you select Match Case in its operator menu, and only then can it run as a key condition.
A global index is used only when it projects every attribute, and only when every one of its sort keys carries a filter, because an item missing a key attribute is not in the index at all.
Filter on a nested attribute with a path such as address.city or items[0].sku. Autocomplete offers the map paths found in the table’s first 100 items.
Sorting and paging
Clicking the sort key’s header on a Query that reads one partition makes DynamoDB return the items in that order, forwards or backwards. Any other sort needs every matching item. When the read holds them all, the grid sorts them. When it does not, the rows stay in DynamoDB’s order and the status bar says so:In DynamoDB order: sorting by total needs the whole result, or a Query on that sort key.
The next page starts from where the previous one stopped rather than reading the table again from the start. A page can take several requests: DynamoDB counts the items it examined against the request’s limit before a FilterExpression drops any, so the reader keeps going until the page is full or the table has no more.
Row counts
The total under the grid is DynamoDB’s own item count, which it refreshes about every six hours. No count runs on its own. Count Exactly reads every item your filters match withSelect: COUNT, so it is billed as a full read of those items. The query timeout does not stop it; Cmd+. does.
Items in the grid
A table declares only its key attributes, so the columns come from the items themselves: every attribute in the table’s first 100 items and in the page on screen, plus the key attributes of each index. The table’s keys come first. An attribute that appears in none of those items has no column until a page returns it. Column types use the AWS console’s names, taken from the most common type in the column.
Maps, lists and sets open in the JSON editor. Numbers keep all 38 digits; nothing in the grid rounds them.
Saving edits
Each changed row becomes one PartiQL statement, sent when you save, and each value keeps the type it had: an edited Number stays a Number, a String that looks like02134 stays a String, and a String Set edited as JSON goes back as a String Set, nested Binary values included. A new attribute takes the type its column shows. Set NULL removes the attribute from the item.
An update also checks each attribute it changes against the value the grid loaded, so it fails rather than overwrite a value someone else changed since, or recreate an item someone deleted. Duplicate Row copies every attribute but the keys; fill in the new keys before saving.
PartiQL and the DynamoDB API
The editor runs two kinds of statement. PartiQL takes double quotes around names and single quotes around strings, and Amazon’s PartiQL reference has the grammar:
Any other action name is refused. Autocomplete inserts a template for the common ones. Items come back in the grid; any other response comes back as JSON.
- A
ScanorQueryrequest takes a trailingORDER BY,LIMITandOFFSET, which count the items returned. With"Select": "COUNT"it pages to the end and returns one row ofCountandScannedCount. - A PartiQL
SELECTtakes them too. AnORDER BYon the sort key goes to DynamoDB when the WHERE clause fixes the partition key with=; any other is applied to the result. ASELECTthat does not fix the partition key reads the whole table, and the status bar says so. - A
BatchWriteItemsends its unprocessed items again until they are written, and reports the ones still left after 10 attempts rather than calling the batch a success. - A throttled request retries with backoff, and so does a failed one that is safe to send twice: a read, or a write whose repeat changes nothing. Four attempts in all.
Cmd+.stops a running statement.
Creating and changing tables
New Table… opens a form rather than a column grid: the partition and sort key with their types, on-demand or provisioned capacity, the table class, deletion protection, up to 20 global and 5 local secondary indexes. Preview shows theCreateTable request it will send. A local secondary index can only be defined here, when the table is created. The new table opens empty until DynamoDB finishes creating it.
Preview shows the request before Create Table sends it
UpdateTable request, and DynamoDB builds or removes the index in the background. The key’s type comes from the table’s items; when no item read so far holds that attribute, the index is refused, so create it from the editor with an UpdateTable request that declares AttributeDefinitions. An index cannot be edited in place: delete it, save, and add the replacement once the old one is gone. The primary key and a local secondary index go only with the table. DDL shows the CreateTable request that recreates the table, plus the Time to Live and point-in-time recovery settings it carries.
Right-click a table and choose Maintenance for point-in-time recovery, deletion protection, the stream, the table class, switching to on-demand capacity and turning Time to Live off. Table Operations covers the sheet.
Dropping a table from the sidebar sends DeleteTable. It fails while deletion protection is on.
IAM permissions
Browsing, filtering, exporting and the Structure tab call these actions:dynamodb:PartiQLInsert, dynamodb:PartiQLUpdate and dynamodb:PartiQLDelete. Creating, changing and dropping tables adds dynamodb:CreateTable, dynamodb:UpdateTable, dynamodb:DeleteTable, dynamodb:UpdateTimeToLive and dynamodb:UpdateContinuousBackups. A request typed in the editor needs the action it names.
SSL/TLS
Every request goes to the AWS endpoint over HTTPS, signed with Signature Version 4, and there is no SSL/TLS section to set. A custom endpoint may use plain HTTP only when it is on this Mac:localhost, 127.0.0.1 or ::1.
Limitations
- A key attribute cannot be edited in place, and saving the change fails. Duplicate the row, give the copy its new key, save, then delete the original.
- The Structure tab cannot add, change or drop an attribute. Write the attribute to an item and it appears as a column.
- A global index that projects only its keys or chosen attributes is never used for browsing, so a filter on its key scans the table. Query that index from the editor with a
Queryrequest naming itsIndexName. - Import is not available. Write items from the editor with
BatchWriteItemor PartiQLINSERT. - Truncate is not offered, because DynamoDB can only empty a table by deleting every item. Drop the table and create it again from its DDL.
- Saving writes each changed row on its own, so there is no transaction across rows. Group writes that must succeed together in an
ExecuteTransactionorTransactWriteItemsrequest. - A read through a global secondary index is eventually consistent, so an edit saved a moment ago can be missing from it. Refresh, or filter on the table’s own partition key, which reads the table.
- DAX endpoints are not supported. Leave Custom Endpoint empty or point it at a DynamoDB endpoint.
Troubleshooting
Authentication failed: …
DynamoDB rejected the credentials: an unknown key, a bad signature, or a session token that aged out. Check the key and secret, the profile name, or sign in again withaws sso login --profile <name>.
”…” is not an AWS region
AWS Region, or the region in the AWS profile, holds something other than a region name. Region names are lowercase letters, digits and hyphens. Set it to one such asus-east-1.
DynamoDB error: [AccessDeniedException] …
The credentials work but their policy does not allow the action the message names. Add it to the policy, using the list in IAM permissions.DynamoDB error: [ResourceNotFoundException] …
The table is not in this region. Tables are regional; set AWS Region to the one the table was created in.DynamoDB error: [ProvisionedThroughputExceededException] …
The table used up its provisioned read or write capacity and four attempts did not get through. Filter on the partition key so the read runs as a Query, raise the capacity, or switch the table to on-demand from Maintenance.The item … changed after it was loaded. Refresh the table and edit it again.
Someone changed the item between loading it and saving it, and the save was refused so their change survives. Refresh, then make the edit again.Plain HTTP is only allowed for an endpoint on this Mac (localhost). Use https:// for any other host.
Custom Endpoint starts withhttp:// and names another machine. Use https://, or run DynamoDB Local on this Mac.