DynamoDB

Squid can connect to an Amazon DynamoDB database to serve as a data source for your Squid application.

DynamoDB is a serverless NoSQL key-value database from AWS. With Squid, you can query your DynamoDB tables through the Squid Client SDK and let AI agents answer questions using your DynamoDB data.

note

The DynamoDB connector currently supports read operations. Queries and document lookups work through the standard Squid query API, while inserts, updates, deletes, and native queries are not yet supported.

To connect your DynamoDB database to Squid, complete the following steps:

1. Open the Squid Console and select your application to use with DynamoDB.
2. Click the Connectors tab, and then click Available connectors.
3. Select the DynamoDB connector.
4. Provide the following configuration information:

• Connector ID - Choose an ID that is brief and helps identify the connector. This cannot be changed later.
• Region - The AWS region of your DynamoDB tables. For example, us-east-1.
• Access Key ID - The access key ID of an IAM user with access to your tables.
• Secret Access Key - The matching secret access key. To keep it private, store it in Squid Secrets.
• Endpoint URL - Optional. A custom endpoint, such as http://localhost:9001 for DynamoDB Local.
• Tables to Process - Optional. A comma-separated list of tables to include in schema discovery. Use forward slashes to specify a regex pattern (e.g. /^temp_.*/). Leave empty to include all tables.

Required IAM permissions

The IAM user needs the following permissions on the tables you want to expose:

• dynamodb:ListTables
• dynamodb:DescribeTable
• dynamodb:Scan
• dynamodb:GetItem

Since the connector is read-only, no write permissions are required.

Discovering the schema

After adding the connector, use the Schema tab to discover your tables. Squid reads each table's key schema and samples up to 100 items to infer the remaining attributes and their types. You can adjust the generated schema before saving it.

Querying your data

Query DynamoDB tables from the Client SDK the same way as any other Squid collection, passing the connector ID:

Client code

const users = await squid
  .collection<User>('users', 'YOUR_DYNAMODB_CONNECTOR_ID')
  .query()
  .eq('status', 'active')
  .snapshot();

A few DynamoDB-specific behaviors to be aware of:

• Queries are executed as DynamoDB scans with server-side filters, so they don't require or use secondary indexes. On large tables, broad queries can be slow and consume read capacity.
• When no limit is set, queries return at most 1000 items.
• Results are not sorted; DynamoDB returns items in scan order.
• Looking up documents by ID is supported for tables with a simple (partition-key-only) primary key. Tables with a composite (partition + sort) key cannot be queried by document ID.

Securing your database

By default, security rules are required, and in a production environment, it's essential to never allow access to the connector without them. Learn more about securing your database data in the security rules documentation.

Datatype mapping

The following table outlines the datatype mapping between DynamoDB and Squid:

DynamoDB Type	Squid Type
S (string)	string
N (number)	number
B (binary)	string (base64)
BOOL	boolean
L (list)	array
M (map)	map
SS, NS, BS (sets)	array
NULL	null

To learn how to work with your data in Squid, view the Client SDK documentation.