dynein

Dynein uses a JSON-like format called dynein format to express DynamoDB items. While it is inspired by PartiQL and valid JSON should be parsed correctly, it is not strictly intended to be JSON-compatible. It is designed to be easier to write and to make data types recognizable at a glance.

Note: The current implementation may not be able to read all valid JSON.

Dynein supports two ways to format the right-hand value in sort key conditions. By default, Dynein attempts to parse the input using the strict format first, then falls back to the non-strict format.

Strict Format

In strict mode, you must provide the value using the correct type defined in the table schema (e.g., wrapping strings in quotes). If the type does not match the table definition, Dynein will raise an error.

Non-strict Format

In non-strict mode, Dynein attempts to infer your intention. It will automatically attempt to align your input with the table's expected types. For equality, you can also provide the value directly without an operator.

Format Flags

• --strict: Enforces strict format. Raises an error if input is non-strict.
• --no-strict: Disables strict mode enforcement, even if strict_mode is enabled in your configuration.

Dynein supports a declarative approach to managing DynamoDB resources via AWS CloudFormation. This feature allows you to define tables in .cfn.yml files and manage them through dynein.

Note: This feature is currently under development and may not be available in all versions.

• dy admin plan: (In development) Shows the changes that would be applied to your infrastructure.
• dy admin apply: (In development) Executes the CloudFormation templates to provision or update resources.

# Example mytable.cfn.yml
Resources:
  MyDDB:
    Type: AWS::DynamoDB::Table
    Properties:
      AttributeDefinitions:
      - AttributeName: pk
        AttributeType: S
      KeySchema:
      - AttributeName: pk
        KeyType: HASH
      BillingMode: PAY_PER_REQUEST

If an attribute path contains spaces or special characters (like backticks), wrap the path segment in backticks (`). To include a literal backtick within a path, use double backticks ( ``).

Non-ASCII characters (like CJK) do not require quoting if they follow Unicode ID_Start and ID_Continue standards.

# Path with spaces
$ dy upd 55 --set 'map.`Do you have spaces?` = "Allowed"'

# Path with a backtick
$ dy upd 55 --set 'map.`Dou you ``?` = "Maybe"'

# Non-ASCII path (no quotes needed)
$ dy upd 55 --set 'map.路径 = "A word of Chinese"'

Sets are represented by double angle brackets << ... >>. All elements in a set must be of the same type. Dynein automatically infers the type based on the elements.

Constraints:

• Each value must be unique.
• Order is not preserved.
• DynamoDB does not support empty sets (though empty strings/binary values are allowed inside a set).

Supported sets include Number Sets, String Sets, and Binary Sets.

# Number Set
dy put 35 -i '{"number-set": <<0, -1, 1, 2>>}'

# String Set
dy put 36 -i '{"string-set": <<"0", "-1", "One", "Two">>}'

# Binary Set
dy put 37 -i '{"binary-set": <<b"\x00", b"0x01", b"0x02", b64"Aw==">>}'

The dy query command retrieves items from a DynamoDB table that match a specified partition key and an optional sort key condition.

• Partition Key (Required): Must be an exact match. It is passed as the first positional argument.
• Sort Key Condition (Optional): Specified using the -s flag. If omitted, all items matching the partition key are returned.

Example: To retrieve all items with partition key 0001:

dy query 0001

Example: To retrieve items where the sort key begins with 0:

dy query 0001 -s 'begins_with "0"'

Binary data can be expressed in two ways:

1. Binary Literals (b"...")

You can use escape sequences like \x41 (7-bit character code) or standard escapes like \n, \t, \r. You can skip leading whitespace by using a backslash \ at the end of a line.

2. Base64 Literals (b64"..." or b64'...")

You can provide a base64 encoded string. You may omit the = padding at the end, but you cannot include linebreaks or spaces within the quoted base64 string.

# Binary literal with escapes and multi-line support
# input.json content:
{
  "binary": b"Thi\x73 is a \
              bin.\r\n"
}

dy put 20 -i "$(cat input.json)"

# Base64 literals
dy put 21 -i "{'bin':b64'$(echo -n "Hello" | base64)'}"
dy put 23 -i '{"bin":b64"AA"}'

You can add a Global Secondary Index (GSI) to an existing DynamoDB table using the dy admin create index command. After creating the index, you can use the dy use command to switch context to that table and then perform scans or queries specifically against the new index using the --index flag.

# Create a GSI named top_rank_users_index with 'rank' as the partition key (N)
$ dy admin create index top_rank_users_index --keys rank,N --table app_users

# Switch context to the table
$ dy use app_users

# Scan using the new index
$ dy scan --index top_rank_users_index

The dy bootstrap command creates sample tables and loads test data (based on AWS documentation sample tables) to help you learn the tool and DynamoDB.

• List available samples: dy bootstrap --list
• Bootstrap a specific sample: dy bootstrap --sample <name>

Example usage after bootstrapping:

$ dy bootstrap
$ dy scan --table Thread

Once a table is in the ACTIVE status, you can interact with its data.

• dy put: Adds an item to a table. Use the --item flag with a JSON string to define the attributes. If a context is set via dy use, you do not need to specify the table name.
• dy scan: Retrieves items from the table. If no context is set, use the --table or -t flag.

# Put an item into the 'app_users' table (assuming 'dy use app_users' was called)
$ dy put myapp 1234 --item '{"rank": 99}'

# Scan the table to view items
$ dy scan

Dynein supports DynamoDB Local. To interact with a local instance (e.g., running in Docker or Kubernetes), append the --region local flag to every command. This tells dynein to redirect requests to the local endpoint instead of AWS.

# Start DynamoDB Local via Docker
$ docker run -p 8000:8000 -d amazon/dynamodb-local

# Interact with the local instance
$ dy --region local admin create table localdb --keys pk
$ dy --region local use -t localdb
$ dy --region local put firstItem
$ dy --region local scan

Use the dy import command to load data into a table. The default format is json. You must specify the --format and provide an --input-file.

Type Inference for Sets: By default, all JSON lists are inferred as the DynamoDB List (L) type. To enable legacy behavior where JSON lists are automatically inferred as String Set (SS) or Number Set (NS) based on their content, use the --enable-set-inference flag.

# Standard JSON import
$ dy import --table target_movie --format json --input-file movie.json

# Import with set type inference enabled (converts lists to SS or NS where applicable)
$ dy import --table target_movie --format jsonl --enable-set-inference --input-file load.json