# Developing with the DynamoDB Accelerator (DAX) client To use DAX from an application, you use the DAX client for your programming language. The DAX client is designed for minimal disruption to your existing Amazon DynamoDB applications—with only a few simple code modifications needed. **Note** DAX clients for various programming languages are available on the following site: [http://dax-sdk.s3-website-us-west-2.amazonaws.com](http://dax-sdk.s3-website-us-west-2.amazonaws.com) This section demonstrates how to launch an Amazon EC2 instance in your default Amazon VPC, connect to the instance, and run a sample application. It also provides information about how to modify your existing application so that it can use your DAX cluster. **Topics** + [Tutorial: Running a sample application using DynamoDB Accelerator (DAX)](DAX.client.sample-app.md) + [Modifying an existing application to use DAX](DAX.client.modify-your-app.md) # Tutorial: Running a sample application using DynamoDB Accelerator (DAX) This tutorial demonstrates how to launch an Amazon EC2 instance in your default virtual private cloud (VPC), connect to the instance, and run a sample application that uses Amazon DynamoDB Accelerator (DAX). **Note** To complete this tutorial, you must have a DAX cluster running in your default VPC. If you haven't created a DAX cluster, see [Creating a DAX cluster](DAX.create-cluster.md) for instructions. **Topics** + [Step 1: Launch an Amazon EC2 instance](DAX.client.launch-ec2-instance.md) + [Step 2: Create a user and policy](DAX.client.create-user-policy.md) + [Step 3: Configure an Amazon EC2 instance](DAX.client.configure-ec2-instance.md) + [Step 4: Run a sample application](DAX.client.run-application.md) # Step 1: Launch an Amazon EC2 instance When your Amazon DynamoDB Accelerator (DAX) cluster is available, you can launch an Amazon EC2 instance in your default Amazon Virtual Private Cloud (Amazon VPC). You can then install and run DAX client software on that instance. **To launch an EC2 instance** 1. Sign in to the AWS Management Console and open the Amazon EC2 console at [https://console.aws.amazon.com/ec2/](https://console.aws.amazon.com/ec2/). 1. Choose **Launch Instance**, and do the following: ** Step 1: Choose an Amazon Machine Image (AMI)** 1. In the list of AMIs, find the **Amazon Linux AMI**, and choose **Select**. **Step 2: Choose an Instance Type** 1. In the list of instance types, choose **t2.micro**. 1. Choose **Next: Configure Instance Details**. **Step 3: Configure Instance Details** 1. For **Network**, choose your default VPC. 1. Choose **Next: Add Storage**. **Step 4: Add Storage** 1. Skip this step by choosing **Next: Add Tags**. **Step 5: Add Tags** 1. Skip this step by choosing **Next: Configure Security Group**. **Step 6: Configure Security Group** 1. Choose **Select an existing security group**. 1. In the list of security groups, choose **default**. This is the default security group for your VPC. 1. Choose **Next: Review and Launch**. **Step 7: Review Instance Launch** 1. Choose **Launch**. 1. In the **Select an existing key pair or create a new key pair** window, do one of the following: + If you don't have an Amazon EC2 key pair, choose **Create a new key pair** and follow the instructions. You are asked to download a private key file (`.pem` file). You need this file later when you log in to your Amazon EC2 instance. + If you already have an existing Amazon EC2 key pair, go to ** Select a key pair** and choose your key pair from the list. You must already have the private key file (`.pem` file) available in order to log in to your Amazon EC2 instance. 1. After configuring your key pair, choose **Launch Instances**. 1. In the console navigation pane, choose **EC2 Dashboard**, and then choose the instance that you launched. In the lower pane, on the **Description** tab, find the **Public DNS** for your instance, for example: `ec2-11-22-33-44.us-west-2.compute.amazonaws.com`. Make a note of this public DNS name because you need it for [Step 3: Configure an Amazon EC2 instance](DAX.client.configure-ec2-instance.md). **Note** It takes a few minutes for your Amazon EC2 instance to become available. In the meantime, proceed to [Step 2: Create a user and policy](DAX.client.create-user-policy.md) and follow the instructions there. # Step 2: Create a user and policy In this step, you create a user with a policy that grants access to your Amazon DynamoDB Accelerator (DAX) cluster and to DynamoDB using AWS Identity and Access Management. You can then run applications that interact with your DAX cluster. ## Sign up for an AWS account If you do not have an AWS account, complete the following steps to create one. **To sign up for an AWS account** 1. Open [https://portal.aws.amazon.com/billing/signup](https://portal.aws.amazon.com/billing/signup). 1. Follow the online instructions. Part of the sign-up procedure involves receiving a phone call or text message and entering a verification code on the phone keypad. When you sign up for an AWS account, an *AWS account root user* is created. The root user has access to all AWS services and resources in the account. As a security best practice, assign administrative access to a user, and use only the root user to perform [tasks that require root user access](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_root-user.html#root-user-tasks). AWS sends you a confirmation email after the sign-up process is complete. At any time, you can view your current account activity and manage your account by going to [https://aws.amazon.com/](https://aws.amazon.com/) and choosing **My Account**. ## Create a user with administrative access After you sign up for an AWS account, secure your AWS account root user, enable AWS IAM Identity Center, and create an administrative user so that you don't use the root user for everyday tasks. **Secure your AWS account root user** 1. Sign in to the [AWS Management Console](https://console.aws.amazon.com/) as the account owner by choosing **Root user** and entering your AWS account email address. On the next page, enter your password. For help signing in by using root user, see [Signing in as the root user](https://docs.aws.amazon.com/signin/latest/userguide/console-sign-in-tutorials.html#introduction-to-root-user-sign-in-tutorial) in the *AWS Sign-In User Guide*. 1. Turn on multi-factor authentication (MFA) for your root user. For instructions, see [Enable a virtual MFA device for your AWS account root user (console)](https://docs.aws.amazon.com/IAM/latest/UserGuide/enable-virt-mfa-for-root.html) in the *IAM User Guide*. **Create a user with administrative access** 1. Enable IAM Identity Center. For instructions, see [Enabling AWS IAM Identity Center](https://docs.aws.amazon.com//singlesignon/latest/userguide/get-set-up-for-idc.html) in the *AWS IAM Identity Center User Guide*. 1. In IAM Identity Center, grant administrative access to a user. For a tutorial about using the IAM Identity Center directory as your identity source, see [ Configure user access with the default IAM Identity Center directory](https://docs.aws.amazon.com//singlesignon/latest/userguide/quick-start-default-idc.html) in the *AWS IAM Identity Center User Guide*. **Sign in as the user with administrative access** + To sign in with your IAM Identity Center user, use the sign-in URL that was sent to your email address when you created the IAM Identity Center user. For help signing in using an IAM Identity Center user, see [Signing in to the AWS access portal](https://docs.aws.amazon.com/signin/latest/userguide/iam-id-center-sign-in-tutorial.html) in the *AWS Sign-In User Guide*. **Assign access to additional users** 1. In IAM Identity Center, create a permission set that follows the best practice of applying least-privilege permissions. For instructions, see [ Create a permission set](https://docs.aws.amazon.com//singlesignon/latest/userguide/get-started-create-a-permission-set.html) in the *AWS IAM Identity Center User Guide*. 1. Assign users to a group, and then assign single sign-on access to the group. For instructions, see [ Add groups](https://docs.aws.amazon.com//singlesignon/latest/userguide/addgroups.html) in the *AWS IAM Identity Center User Guide*. To provide access, add permissions to your users, groups, or roles: + Users and groups in AWS IAM Identity Center: Create a permission set. Follow the instructions in [Create a permission set](https://docs.aws.amazon.com//singlesignon/latest/userguide/howtocreatepermissionset.html) in the *AWS IAM Identity Center User Guide*. + Users managed in IAM through an identity provider: Create a role for identity federation. Follow the instructions in [Create a role for a third-party identity provider (federation)](https://docs.aws.amazon.com//IAM/latest/UserGuide/id_roles_create_for-idp.html) in the *IAM User Guide*. + IAM users: + Create a role that your user can assume. Follow the instructions in [Create a role for an IAM user](https://docs.aws.amazon.com//IAM/latest/UserGuide/id_roles_create_for-user.html) in the *IAM User Guide*. + (Not recommended) Attach a policy directly to a user or add a user to a user group. Follow the instructions in [Adding permissions to a user (console)](https://docs.aws.amazon.com//IAM/latest/UserGuide/id_users_change-permissions.html#users_change_permissions-add-console) in the *IAM User Guide*. **To use the JSON policy editor to create a policy** 1. Sign in to the AWS Management Console and open the IAM console at [https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/). 1. In the navigation pane on the left, choose **Policies**. If this is your first time choosing **Policies**, the **Welcome to Managed Policies** page appears. Choose **Get Started**. 1. At the top of the page, choose **Create policy**. 1. In the **Policy editor** section, choose the **JSON** option. 1. Enter or paste a JSON policy document. For details about the IAM policy language, see [IAM JSON policy reference](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies.html). 1. Resolve any security warnings, errors, or general warnings generated during [policy validation](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_policy-validator.html), and then choose **Next**. **Note** You can switch between the **Visual** and **JSON** editor options anytime. However, if you make changes or choose **Next** in the **Visual** editor, IAM might restructure your policy to optimize it for the visual editor. For more information, see [Policy restructuring](https://docs.aws.amazon.com/IAM/latest/UserGuide/troubleshoot_policies.html#troubleshoot_viseditor-restructure) in the *IAM User Guide*. 1. (Optional) When you create or edit a policy in the AWS Management Console, you can generate a JSON or YAML policy template that you can use in CloudFormation templates. To do this, in the **Policy editor** choose **Actions**, and then choose **Generate CloudFormation template**. To learn more about CloudFormation, see [AWS Identity and Access Management resource type reference](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/AWS_IAM.html) in the *AWS CloudFormation User Guide*. 1. When you are finished adding permissions to the policy, choose **Next**. 1. On the **Review and create** page, enter a **Policy name** and a **Description** (optional) for the policy that you are creating. Review **Permissions defined in this policy** to see the permissions that are granted by your policy. 1. (Optional) Add metadata to the policy by attaching tags as key-value pairs. For more information about using tags in IAM, see [Tags for AWS Identity and Access Management resources](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_tags.html) in the *IAM User Guide*. 1. Choose **Create policy** to save your new policy. **Policy document** – Copy and paste the following document to create the JSON policy. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Action": [ "dax:*" ], "Effect": "Allow", "Resource": [ "*" ] }, { "Action": [ "dynamodb:*" ], "Effect": "Allow", "Resource": [ "*" ] } ] } ``` ------ # Step 3: Configure an Amazon EC2 instance When your Amazon EC2 instance is available, you can log in to the instance and prepare it for use. **Note** The following steps assume that you are connecting to your Amazon EC2 instance from a computer running Linux. For other ways to connect, see [Connect to Your Linux Instance](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/AccessingInstances.html) in the *Amazon EC2 User Guide*. **To configure the EC2 instance** 1. Open the Amazon EC2 console at [https://console.aws.amazon.com/ec2/](https://console.aws.amazon.com/ec2/). 1. Use the `ssh` command to log in to your Amazon EC2 instance, as shown in the following example. ``` ssh -i my-keypair.pem ec2-user@public-dns-name ``` You need to specify your private key file (`.pem` file) and the public DNS name of your instance. (See [Step 1: Launch an Amazon EC2 instance](DAX.client.launch-ec2-instance.md).) The login ID is `ec2-user`. No password is required. 1. After you log in to your EC2 instance, configure your AWS credentials as shown following. Enter your AWS access key ID and secret key (from [Step 2: Create a user and policy](DAX.client.create-user-policy.md)), and set the default Region name to your current Region. (In the following example, the default Region name is `us-west-2`.) ``` aws configure AWS Access Key ID [None]: AKIAIOSFODNN7EXAMPLE AWS Secret Access Key [None]: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY Default region name [None]: us-west-2 Default output format [None]: ``` After launching and configuring your Amazon EC2 instance, you can test the functionality of DAX using one of the available sample applications. For more information, see [Step 4: Run a sample application](DAX.client.run-application.md). # Step 4: Run a sample application To help you test Amazon DynamoDB Accelerator (DAX) functionality, you can run one of the available sample applications on your Amazon EC2 instance. **Topics** + [Node.js and DAX](DAX.client.run-application-nodejs-3.md) + [DAX SDK for Go](DAX.client.run-application-go-2.md) + [Java and DAX](DAX.client.run-application-java.md) + [.NET and DAX](DAX.client.run-application-dotnet.md) + [Python and DAX](DAX.client.run-application-python.md) # Node.js and DAX # Default client configuration for Node.js When configuring the DAX JavaScript SDK client, you can customize various parameters to optimize performance, connection handling, and error resilience. The following table outlines the default configuration settings that control how your client interacts with the DAX cluster, including timeout values, retry mechanisms, credential management, and health monitoring options. For more information, see [DynamoDBClient Operations](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/client/dynamodb/). **DAX JS SDK client defaults** | Parameter | Type | Description | | --- | --- | --- | | `region` optional | `string` | The AWS Region to use for the DAX client (example - 'us-east-1'). This is a required parameter if not provided through the environment variable. | | `endpoint` required | `string` | The endpoint of the Cluster to which the SDK connects. Examples: Non-encrypted – dax-cluster-name.region.amazonaws.com Encrypted – daxs://my-cluster.l6fzcv.dax-clusters.us-east-1.amazonaws.com | | `requestTimeout` default 6000 ms | `number` | This defines the maximum time the client will wait for a response from DAX. | | `writeRetries` default 1 | `number` | The number of retries to attempt for write requests that fail. | | `readRetries` default 1 | `number` | The number of retries to attempt for read requests that fail. | | `maxRetries` default 1 | `number` | The maximum number of retries to attempt on failed requests. If readRetries/writeRetries are set, then the configuration set in readRetries and writeRetries take priority over maxRetries. | | `connectTimeout` default 10000 ms | `number` | The timeout (in milliseconds) for establishing a connection to any of the cluster nodes. | | `maxConcurrentConnections` default 100 | `number` | Limits the total number of concurrent connections that a client instance can create per node in a DAX cluster. | | `maxRetryDelay` default 7000 ms | `number` | When the DAX server indicates recover is needed by setting `waitForRecoveryBeforeRetrying` flag to true, the client will pause before retry attempts. During these recovery periods, the `maxRetryDelay` parameter determines the maximum waiting time between retries. This recovery-specific configuration only applies when the DAX server is in recovery mode. For all other scenarios, retry behavior follows one of two patterns: either an exponential delay based on the retry count (governed by `writeRetries`, `readRetries`, or `maxRetries` parameters), or an immediate retry depending on the exception type. | | `credentials` optional | `[AwsCredentialIdentity](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-aws-sdk-credential-providers/)` \$1 `[AwsCredentialIdentityProvider](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-aws-sdk-credential-providers/)` | The AWS credentials to use for authenticating requests. This can be provided as an AwsCredentialIdentity or an AwsCredentialIdentityProvider. If not provided, the AWS SDK will automatically use the default credentials provider chain. Example: `\$1 accessKeyId: 'AKIA...', secretAccessKey: '...', sessionToken: '...' \$1` \$1 @default Uses default AWS credentials provider chain. | | `healthCheckInterval` default 5000 ms | `number` | The interval (in milliseconds) between cluster health checks. A lower interval will check more frequently. | | `healthCheckTimeout` default 1000 ms | `number` | The timeout (in milliseconds) for the health check to complete. | | `skipHostnameVerification` default false | `boolean` | Skip hostname verification of TLS connections. This has no impact on un-encrypted clusters. The default is to perform hostname verification, setting this to True will skip verification. Be sure you understand the implication of turning it off, which is the inability to authenticate the cluster that you are connecting to. | | `unhealthyConsecutiveErrorCount` default 5 | `number` | Sets the number of consecutive errors required to signal node unhealthy within health check interval. | | `clusterUpdateInterval` default 4000 ms | `number` | Returns the interval between polling of cluster members for membership changes. | | `clusterUpdateThreshold` default 125 | `number` | Returns the threshold below which the cluster will not be polled for membership changes. | | `credentailProvider` optional \$1 default null | `[AwsCredentialIdentityProvider](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-aws-sdk-credential-providers/)` | User Defined Provider for AWS credentials used to authenticate requests to DAX. | **Pagination configuration for DaxDocument** | Name | Type | Detail | | --- | --- | --- | | `client` | DaxDocument | Instance of DaxDocument type. | | `pageSize` | number | Determines the number of items per page. | | `startingToken` Optional | any | LastEvaluatedKey from previous response can be used for subsequent requests. | For usage of pagination, see [TryDax.js](DAX.client.tutorial-TryDax.md). # Migrating to DAX Node.js SDK V3 This migration guide will help you transition your existing DAX Node.js applications. The new SDK requires Node.js 18 or higher and introduces several important changes in how you'll structure your DynamoDB Accelerator code. This guide will walk you through the key differences, including syntax changes, new import methods, and updated asynchronous programming patterns. ## V2 Node.js DAX usage ``` const AmazonDaxClient = require('amazon-dax-client'); const AWS = require('aws-sdk'); var region = "us-west-2"; AWS.config.update({ region: region, }); var client = new AWS.DynamoDB.DocumentClient(); if (process.argv.length > 2) { var dax = new AmazonDaxClient({ endpoints: [process.argv[2]], region: region, }); client = new AWS.DynamoDB.DocumentClient({ service: dax }); } // Make Get Call using Dax var params = { TableName: 'TryDaxTable', pk: 1, sk: 1 } client.get(params, function (err, data) { if (err) { console.error( "Unable to read item. Error JSON:", JSON.stringify(err, null, 2) ); } else { console.log(data); } }); ``` ## V3 Node.js DAX usage For Using DAX Node.js V3 Node version 18 or above is the preferred version. To move to Node 18, use the following: ``` import { DaxDocument } from '@amazon-dax-sdk/lib-dax'; import { DynamoDBDocument } from '@aws-sdk/lib-dynamodb'; import { DynamoDBClient } from '@aws-sdk/client-dynamodb'; let client: DynamoDBDocument | DaxDocument = DynamoDBDocument.from( new DynamoDBClient({ region: 'us-west-2' }) ); if (process.argv.length > 2) { client = new DaxDocument({ endpoints: [process.argv[2]], region: 'us-west-2', }); } const params = { TableName: 'TryDaxTable', Key: { pk: 1, sk: 1 }, }; try { const results = await client.get(params); console.log(results); } catch (err) { console.error(err); } ``` The DAX SDK for Node.js v3.x is compatible with [AWS SDK for Node.js v3.x](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/introduction/). The DAX SDK for Node.js v3.x supports the use of [aggregated](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/introduction/#high-level-concepts) clients. Please note that DAX doesn't support the creation of bare-bones clients. For more details on unsupported features, see [Features not in parity with AWS SDK V3](#DAX.client.run-application-nodejs-3-not-in-parity). Follow these steps to run the Node.js sample application on your Amazon EC2 instance. **To run the Node.js sample for DAX** 1. Set up Node.js on your Amazon EC2 instance, as follows: 1. Install node version manager (`nvm`). ``` curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash ``` 1. Use nvm to install Node.js. ``` nvm install 18 ``` 1. Use nvm to use Node 18 ``` nvm use 18 ``` 1. Test that Node.js is installed and running correctly. ``` node -e "console.log('Running Node.js ' + process.version)" ``` This should display the following message. `Running Node.js v18.x.x` 1. Install the DaxDocument Node.js client using the node package manager (`npm`). ``` npm install @amazon-dax-sdk/lib-dax ``` ## TryDax sample code To evaluate the performance benefits of DynamoDB Accelerator (DAX), follow these steps to run a sample test that compares read operation times between standard DynamoDB and a DAX cluster. 1. After you've set up your workspace and installed the `lib-dax` as a dependency, copy [TryDax.js](DAX.client.tutorial-TryDax.md) into your project. 1. Run the program against your DAX cluster. To determine the endpoint for your DAX cluster, choose one of the following: + **Using the DynamoDB console** — Choose your DAX cluster. The cluster endpoint is shown on the console, as in the following example. ``` dax://my-cluster.l6fzcv.dax-clusters.us-east-1.amazonaws.com ``` + **Using the AWS CLI** — Enter the following command. ``` aws dax describe-clusters --query "Clusters[*].ClusterDiscoveryEndpoint" ``` The cluster endpoint is shown in the output, as in the following example. ``` { "Address": "my-cluster.l6fzcv.dax-clusters.us-east-1.amazonaws.com", "Port": 8111, "URL": "dax://my-cluster.l6fzcv.dax-clusters.us-east-1.amazonaws.com" } ``` 1. Now run the program by specifying the cluster endpoint as a command line parameter. ``` node TryDax.js dax://my-cluster.l6fzcv.dax-clusters.us-east-1.amazonaws.com ``` You should see output similar to the following: ``` Attempting to create table; please wait... Successfully created table. Table status: ACTIVE Writing data to the table... Writing 20 items for partition key: 1 Writing 20 items for partition key: 2 Writing 20 items for partition key: 3 ... Running GetItem Test Total time: 153555.10 µs - Avg time: 383.89 µs Total time: 44679.96 µs - Avg time: 111.70 µs Total time: 36885.86 µs - Avg time: 92.21 µs Total time: 32467.25 µs - Avg time: 81.17 µs Total time: 32202.60 µs - Avg time: 80.51 µs Running Query Test Total time: 14869.25 µs - Avg time: 2973.85 µs Total time: 3036.31 µs - Avg time: 607.26 µs Total time: 2468.92 µs - Avg time: 493.78 µs Total time: 2062.53 µs - Avg time: 412.51 µs Total time: 2178.22 µs - Avg time: 435.64 µs Running Scan Test Total time: 2395.88 µs - Avg time: 479.18 µs Total time: 2207.16 µs - Avg time: 441.43 µs Total time: 2443.14 µs - Avg time: 488.63 µs Total time: 2038.24 µs - Avg time: 407.65 µs Total time: 1972.17 µs - Avg time: 394.43 µs Running Pagination Test Scan Pagination [ { pk: 1, sk: 1, someData: 'XXXXXXXXXX' }, { pk: 1, sk: 2, someData: 'XXXXXXXXXX' }, { pk: 1, sk: 3, someData: 'XXXXXXXXXX' } ] [ { pk: 1, sk: 4, someData: 'XXXXXXXXXX' }, { pk: 1, sk: 5, someData: 'XXXXXXXXXX' }, { pk: 1, sk: 6, someData: 'XXXXXXXXXX' } ] ... Query Pagination [ { pk: 1, sk: 1, someData: 'XXXXXXXXXX' }, { pk: 1, sk: 2, someData: 'XXXXXXXXXX' }, { pk: 1, sk: 3, someData: 'XXXXXXXXXX' } ] [ { pk: 1, sk: 4, someData: 'XXXXXXXXXX' }, { pk: 1, sk: 5, someData: 'XXXXXXXXXX' }, { pk: 1, sk: 6, someData: 'XXXXXXXXXX' } ] ... Attempting to delete table; please wait... Successfully deleted table. ``` Take note of the timing information. The number of microseconds required for the `GetItem`,`Query`,`Scan` tests. 1. In this case, you ran the programs against the DAX cluster. Now, you'll run the program again, this time against DynamoDB. 1. Now run the program again, but this time, without the cluster endpoint URL as a command line parameter. ``` node TryDax.js ``` Look at the output and take note of the timing information. The elapsed times for `GetItem`, `Query`, and `Scan` should be significantly lower with DAX as compared to DynamoDB. ## Features not in parity with AWS SDK V3 + [Bare-bones](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/introduction/#high-level-concepts) clients – Dax Node.js V3 doesn’t support bare-bones clients. ``` const dynamoDBClient = new DynamoDBClient({ region: 'us-west-2' }); const regularParams = { TableName: 'TryDaxTable', Key: { pk: 1, sk: 1 } }; // The DynamoDB client supports the send operation. const dynamoResult = await dynamoDBClient.send(new GetCommand(regularParams)); // However, the DaxDocument client does not support the send operation. const daxClient = new DaxDocument({ endpoints: ['your-dax-endpoint'], region: 'us-west-2', }); const params = { TableName: 'TryDaxTable', Key: { pk: 1, sk: 1 } }; // This will throw an error - send operation is not supported for DAX. Please refer to documentation. const result = await daxClient.send(new GetCommand(params)); console.log(result); ``` + [Middleware Stack](https://aws.amazon.com/blogs/developer/middleware-stack-modular-aws-sdk-js/) – Dax Node.js V3 doesn’t support using Middleware functions. ``` const dynamoDBClient = new DynamoDBClient({ region: 'us-west-2' }); // The DynamoDB client supports the middlewareStack. dynamoDBClient.middlewareStack.add( (next, context) =>> async (args) => { console.log("Before operation:", args); const result = await next(args); console.log("After operation:", result); return result; }, { step: "initialize", // or "build", "finalizeRequest", "deserialize" name: "loggingMiddleware", } ); // However, the DaxDocument client does not support the middlewareStack. const daxClient = new DaxDocument({ endpoints: ['your-dax-endpoint'], region: 'us-west-2', }); // This will throw an error - custom middleware and middlewareStacks are not supported for DAX. Please refer to documentation. daxClient.middlewareStack.add( (next, context) => async (args) => { console.log("Before operation:", args); const result = await next(args); console.log("After operation:", result); return result; }, { step: "initialize", // or "build", "finalizeRequest", "deserialize" name: "loggingMiddleware", } ); ``` # TryDax.js ``` import { DynamoDB, waitUntilTableExists, waitUntilTableNotExists } from "@aws-sdk/client-dynamodb"; import { DaxDocument, daxPaginateScan, daxPaginateQuery } from "@amazon-dax-sdk/lib-dax"; import { DynamoDBDocument, paginateQuery, paginateScan } from "@aws-sdk/lib-dynamodb"; const region = "us-east-1"; const tableName = "TryDaxTable"; // Determine the client (DynamoDB or DAX) let client = DynamoDBDocument.from(new DynamoDB({ region })); if (process.argv.length > 2) { client = new DaxDocument({ region, endpoint: process.argv[2] }); } // Function to create table async function createTable() { const dynamodb = new DynamoDB({ region }); const params = { TableName: tableName, KeySchema: [ { AttributeName: "pk", KeyType: "HASH" }, { AttributeName: "sk", KeyType: "RANGE" }, ], AttributeDefinitions: [ { AttributeName: "pk", AttributeType: "N" }, { AttributeName: "sk", AttributeType: "N" }, ], ProvisionedThroughput: { ReadCapacityUnits: 25, WriteCapacityUnits: 25 }, }; try { console.log("Attempting to create table; please wait..."); await dynamodb.createTable(params); await waitUntilTableExists({ client: dynamodb, maxWaitTime: 30 }, { TableName: tableName }); console.log("Successfully created table. Table status: ACTIVE"); } catch (err) { console.error("Error in table creation:", err); } } // Function to insert data async function writeData() { console.log("Writing data to the table..."); const someData = "X".repeat(10); for (let ipk = 1; ipk <= 20; ipk++) { console.log("Writing 20 items for partition key: ", ipk) for (let isk = 1; isk <= 20; isk++) { try { await client.put({ TableName: tableName, Item: { pk: ipk, sk: isk, someData } }); } catch (err) { console.error("Error inserting data:", err); } } } } // Function to test GetItem async function getItemTest() { console.log("Running GetItem Test"); for (let i = 0; i < 5; i++) { const startTime = performance.now(); const promises = []; for (let ipk = 1; ipk <= 20; ipk++) { for (let isk = 1; isk <= 20; isk++) { promises.push(client.get({ TableName: tableName, Key: { pk: ipk, sk: isk } })); } } await Promise.all(promises); const endTime = performance.now(); const iterTime = (endTime - startTime) * 1000; const totalTime = iterTime.toFixed(2).padStart(3, ' '); const avgTime = (iterTime / 400).toFixed(2).padStart(3, ' '); console.log(`\tTotal time: ${totalTime} \u00B5s - Avg time: ${avgTime} \u00B5s`); } } // Function to test Query async function queryTest() { console.log("Running Query Test"); for (let i = 0; i < 5; i++) { const startTime = performance.now(); const promises = []; for (let pk = 1; pk <= 5; pk++) { const params = { TableName: tableName, KeyConditionExpression: "pk = :pkval and sk between :skval1 and :skval2", ExpressionAttributeValues: { ":pkval": pk, ":skval1": 1, ":skval2": 2 }, }; promises.push(client.query(params)); } await Promise.all(promises); const endTime = performance.now(); const iterTime = (endTime - startTime) * 1000; const totalTime = iterTime.toFixed(2).padStart(3, ' '); const avgTime = (iterTime / 5).toFixed(2).padStart(3, ' '); console.log(`\tTotal time: ${totalTime} \u00B5s - Avg time: ${avgTime} \u00B5s`); } } // Function to test Scan async function scanTest() { console.log("Running Scan Test"); for (let i = 0; i < 5; i++) { const startTime = performance.now(); const promises = []; for (let pk = 1; pk <= 5; pk++) { const params = { TableName: tableName, FilterExpression: "pk = :pkval and sk between :skval1 and :skval2", ExpressionAttributeValues: { ":pkval": pk, ":skval1": 1, ":skval2": 2 }, }; promises.push(client.scan(params)); } await Promise.all(promises); const endTime = performance.now(); const iterTime = (endTime - startTime) * 1000; const totalTime = iterTime.toFixed(2).padStart(3, ' '); const avgTime = (iterTime / 5).toFixed(2).padStart(3, ' '); console.log(`\tTotal time: ${totalTime} \u00B5s - Avg time: ${avgTime} \u00B5s`); } } // Function to test Pagination async function paginationTest() { console.log("Running Pagination Test"); console.log("Scan Pagination"); const scanParams = { TableName: tableName }; const paginator = process.argv.length > 2 ? daxPaginateScan : paginateScan; for await (const page of paginator({ client, pageSize: 3 }, scanParams)) { console.log(page.Items); } console.log("Query Pagination"); const queryParams = { TableName: tableName, KeyConditionExpression: "pk = :pkval and sk between :skval1 and :skval2", ExpressionAttributeValues: { ":pkval": 1, ":skval1": 1, ":skval2": 10 }, }; const queryPaginator = process.argv.length > 2 ? daxPaginateQuery : paginateQuery; for await (const page of queryPaginator({ client, pageSize: 3 }, queryParams)) { console.log(page.Items); } } // Function to delete the table async function deleteTable() { const dynamodb = new DynamoDB({ region }); console.log("Attempting to delete table; please wait...") try { await dynamodb.deleteTable({ TableName: tableName }); await waitUntilTableNotExists({ client: dynamodb, maxWaitTime: 30 }, { TableName: tableName }); console.log("Successfully deleted table."); } catch (err) { console.error("Error deleting table:", err); } } // Execute functions sequentially (async function () { await createTable(); await writeData(); await getItemTest(); await queryTest(); await scanTest(); await paginationTest(); await deleteTable(); })(); ``` # DAX SDK for Go Follow this procedure to run the Amazon DynamoDB Accelerator (DAX) SDK for Go sample application on your Amazon EC2 instance. **To run the SDK for Go sample for DAX** 1. Set up the SDK for Go on your Amazon EC2 instance: 1. Install the Go programming language (`Golang`). ``` sudo yum install -y golang ``` 1. Test that Golang is installed and running correctly. ``` go version ``` A message like this should appear. ``` go version go1.23.4 linux/amd64 ``` 1. Install the sample Golang application. ``` go get github.com/aws-samples/sample-aws-dax-go-v2 ``` 1. Run the following Golang programs. The first program creates a DynamoDB table named `TryDaxGoTable`. The second program writes data to the table. ``` go run ~/go/pkg/mod/github.com/aws-samples/sample-aws-dax-go-v2@v1.0.0/try_dax.go -service dynamodb -command create-table ``` ``` go run ~/go/pkg/mod/github.com/aws-samples/sample-aws-dax-go-v2@v1.0.0/try_dax.go -service dynamodb -command put-item ``` 1. Run the following Golang programs. ``` go run ~/go/pkg/mod/github.com/aws-samples/sample-aws-dax-go-v2@v1.0.0/try_dax.go -service dynamodb -command get-item ``` ``` go run ~/go/pkg/mod/github.com/aws-samples/sample-aws-dax-go-v2@v1.0.0/try_dax.go -service dynamodb -command query ``` ``` go run ~/go/pkg/mod/github.com/aws-samples/sample-aws-dax-go-v2@v1.0.0/try_dax.go -service dynamodb -command scan ``` Take note of the timing information—the number of milliseconds required for the `GetItem`, `Query`, and `Scan` tests. 1. In the previous step, you ran the programs against the DynamoDB endpoint. Now, run the programs again, but this time, the `GetItem`, `Query`, and `Scan` operations are processed by your DAX cluster. To determine the endpoint for your DAX cluster, choose one of the following: + **Using the DynamoDB console** — Choose your DAX cluster. The cluster endpoint is shown on the console, as in the following example. ``` dax://my-cluster.l6fzcv.dax-clusters.us-east-1.amazonaws.com ``` + **Using the AWS CLI** — Enter the following command. ``` aws dax describe-clusters --query "Clusters[*].ClusterDiscoveryEndpoint" ``` The cluster endpoint is shown in the output, as in the following example. ``` { "Address": "my-cluster.l6fzcv.dax-clusters.us-east-1.amazonaws.com", "Port": 8111, "URL": "dax://my-cluster.l6fzcv.dax-clusters.us-east-1.amazonaws.com" } ``` Now run the programs again, but this time, specify the cluster endpoint as a command line parameter. ``` go run ~/go/pkg/mod/github.com/aws-samples/sample-aws-dax-go-v2@v1.0.0/try_dax.go -service dax -command get-item -endpoint my-cluster.l6fzcv.dax-clusters.us-east-1.amazonaws.com:8111 ``` ``` go run ~/go/pkg/mod/github.com/aws-samples/sample-aws-dax-go-v2@v1.0.0/try_dax.go -service dax -command query -endpoint my-cluster.l6fzcv.dax-clusters.us-east-1.amazonaws.com:8111 ``` ``` go run ~/go/pkg/mod/github.com/aws-samples/sample-aws-dax-go-v2@v1.0.0/try_dax.go -service dax -command scan -endpoint my-cluster.l6fzcv.dax-clusters.us-east-1.amazonaws.com:8111 ``` ``` go run ~/go/pkg/mod/github.com/aws-samples/sample-aws-dax-go-v2@v1.0.0/try_dax.go -service dax -command paginated-scan -endpoint my-cluster.l6fzcv.dax-clusters.us-east-1.amazonaws.com:8111 ``` ``` go run ~/go/pkg/mod/github.com/aws-samples/sample-aws-dax-go-v2@v1.0.0/try_dax.go -service dax -command paginated-query -endpoint my-cluster.l6fzcv.dax-clusters.us-east-1.amazonaws.com:8111 ``` ``` go run ~/go/pkg/mod/github.com/aws-samples/sample-aws-dax-go-v2@v1.0.0/try_dax.go -service dax -command paginated-batch-get -endpoint my-cluster.l6fzcv.dax-clusters.us-east-1.amazonaws.com:8111 ``` Look at the rest of the output, and take note of the timing information. The elapsed times for `GetItem`, `Query`, and `Scan` should be significantly lower with DAX than with DynamoDB. 1. Run the following Golang program to delete `TryDaxGoTable`. ``` go run ~/go/pkg/mod/github.com/aws-samples/sample-aws-dax-go-v2@v1.0.0/try_dax.go -service dynamodb -command delete-table ``` ## Features not in parity with AWS SDK for Go V2 Middleware Stack – DAX Go V2 doesn’t support the use of Middleware Stacks through APIoptions. For more information, see [Customizing the AWS SDK for Go v2 Client Requests with Middleware](https://docs.aws.amazon.com/sdk-for-go/v2/developer-guide/middleware.html#:~:text=You%20can%20customize%20AWS%20SDK,step's%20input%20and%20output%20types). Example: ``` // Custom middleware implementation type customSerializeMiddleware struct{} // ID returns the identifier for the middleware func (m *customSerializeMiddleware) ID() string { return "CustomMiddleware" } // HandleSerialize implements the serialize middleware handler func (m *customSerializeMiddleware) HandleSerialize( ctx context.Context, in middleware.SerializeInput, next middleware.SerializeHandler, ) ( out middleware.SerializeOutput, metadata middleware.Metadata, err error, ) { // Add your custom logic here before the request is serialized fmt.Printf("Executing custom middleware for request: %v\n", in) // Call the next handler in the middleware chain return next.HandleSerialize(ctx, in) } func executeGetItem(ctx context.Context) error { client, err := initItemClient(ctx) if err != nil { os.Stderr.WriteString(fmt.Sprintf("failed to initialize client: %v\n", err)) return err } st := time.Now() for c := 0; c < iterations; c++ { for i := 0; i < pkMax; i++ { for j := 0; j < skMax; j++ { // Create key using attributevalue.Marshal for type safety pk, err := attributevalue.Marshal(fmt.Sprintf("%s_%d", keyPrefix, i)) if err != nil { return fmt.Errorf("error marshaling pk: %v", err) } sk, err := attributevalue.Marshal(fmt.Sprintf("%d", j)) if err != nil { return fmt.Errorf("error marshaling sk: %v", err) } key := map[string]types.AttributeValue{ "pk": pk, "sk": sk, } in := &dynamodb.GetItemInput{ TableName: aws.String(table), Key: key, } // Custom middleware option customMiddleware := func(o *dynamodb.Options) { o.APIOptions = append(o.APIOptions, func(stack *middleware.Stack) error { // Add custom middleware to the stack return stack.Serialize.Add(&customSerializeMiddleware{}, middleware.After) }) } // Apply options to the GetItem call out, err := client.GetItem(ctx, in, customMiddleware) if err != nil { return err } writeVerbose(out) } } } d := time.Since(st) os.Stdout.WriteString(fmt.Sprintf("Total Time: %v, Avg Time: %v\n", d, d/iterations)) return nil } ``` Output: ``` failed to execute command: custom middleware through APIOptions is not supported in DAX client exit status 1 ``` # Default client configuration for Go This guide will walk you through the configuration options that allow you to fine-tune your DAX client's performance, connection management, and logging behavior. By understanding the default settings and how to customize them, you can optimize your Go application's interaction with DAX. **Topics** + [DAX Go SDK Client Defaults](#DAX-client-config-Go-sdk-client-defaults) + [Client creation](#DAX-client-config-Go-client-creation) ## DAX Go SDK Client Defaults | Parameter | Type | Description | | --- | --- | --- | | `Region` required | `string` | The AWS Region to use for the DAX client (example- 'us-east-1'). This is a required parameter if not provided through the environment. | | `HostPorts` required | `[] string` | List of DAX cluster endpoints to which SDK connects. For example: Non-Encrypted – dax://my-cluster.l6fzcv.dax-clusters.us-east-1.amazonaws.com Encrypted – daxs://my-cluster.l6fzcv.dax-clusters.us-east-1.amazonaws.com | | `MaxPendingConnectionsPerHost` default 10 | `number` | Number of concurrent connection attempts. (Connections can be in the process of being established concurrently.) | | `ClusterUpdateThreshold` default 125 \$1 time.Millisecond | `time.Duration` | The minimum time that must elapse between cluster refreshes. | | `ClusterUpdateInterval` default 4 \$1 time.Second | `time.Duration` | The interval at which the client will automatically refresh the DAX cluster information. | | `IdleConnectionsReapDelay` default 30 \$1 time.Second | `time.Duration` | The interval at which the client will close idle connections in the DAX client. | | `ClientHealthCheckInterval` default 5 \$1 time.Second | `time.Duration` | The interval at which the client will perform health checks on the DAX cluster endpoints. | | `Credentials` default | `aws.CredentialsProvider` | The AWS credentials used by the DAX client to authenticate requests to the DAX service. See [Credentials and Credential Providers](https://docs.aws.amazon.com/sdk-for-go/v2/developer-guide/migrate-gosdk.html#credentials--credential-providers). | | `DialContext` default | `func` | A custom function used by the DAX client to establish connections to the DAX cluster. | | `SkipHostnameVerification` default false | bool | Skip hostname verification of TLS connections. This setting only affects encrypted clusters. When set to True, it disables hostname verification. Disabling verification means you can't authenticate the identity of the cluster you're connecting to, which poses security risks. By default, hostname verification is enabled. | | `RouteManagerEnabled` default false | `bool` | This flag is used to remove routes facing network errors. | | `RequestTimeout` default 60 \$1 time.Second | `time.Duration` | This defines the maximum time the client will wait for a response from DAX. Priority: Context timeout (if set) > `RequestTimmeout` (if set) > Default 60s `RequestTimeout`. | | `WriteRetries` default 2 | `number` | The number of retries to attempt for write requests that fail. | | `ReadRetries` default 2 | `number` | The number of retries to attempt for read requests that fail. | | `RetryDelay` default 0 | `time.Duration` | The delay for non-throttled errors (in seconds) for retry attempts when a request fails. | | `Logger` optional | `logging.Logger` | Logger is an interface for logging entries at certain classifications. | | `LogLevel` default utils.LogOff | `number` | This loglevel is defined for DAX only. It can be imported using [github.com/aws/aws-dax-go-v2/tree/main/dax/utils](https://github.com/aws/aws-dax-go-v2/tree/main/dax/utils).

const (    
 LogOff LogLevelType = 0   
 LogDebug LogLevelType = 1   
 LogDebugWithRequestRetries
 LogLevelType = 2
)

| **Note** For `time.Duration`, the default unit is nanosecond. If we don’t specify any unit for any parameter then it will consider that as nano seconds: `daxCfg.ClusterUpdateInterval = 10` means 10 nano seconds. (`daxCfg.ClusterUpdateInterval = 10 * time.Millisecond` means 10 milliseconds). ## Client creation **To create a DAX client:** + Create DAX config, then create DAX client using DAX config. Using this, you can overwrite a DAX configuration if required. ``` import ( "github.com/aws/aws-dax-go-v2/dax/utils" "github.com/aws/aws-dax-go-v2/dax" ) // Non - Encrypted : 'dax://my-cluster.l6fzcv.dax-clusters.us-east-1.amazonaws.com'. // Encrypted : daxs://my-cluster.l6fzcv.dax-clusters.us-east-1.amazonaws.com'. config := dax.DefaultConfig() config.HostPorts = []string{endpoint} config.Region = region config.LogLevel = utils.LogDebug daxClient, err := dax.New(config) ``` # Migrating to DAX Go SDK V2 This migration guide will help you transition your existing DAX Go applications. ## V1 DAX Go SDK usage ``` package main import ( "fmt" "os" "github.com/aws/aws-dax-go/dax" "github.com/aws/aws-sdk-go/aws" "github.com/aws/aws-sdk-go/aws/session" "github.com/aws/aws-sdk-go/service/dynamodb" ) func main() { region := "us-west-2" endpoint := "dax://my-cluster.l6fzcv.dax-clusters.us-east-1.amazonaws.com" // Create session sess, err := session.NewSession(&aws.Config{ Region: aws.String(region), }) if err != nil { fmt.Printf("Failed to create session: %v\n", err) os.Exit(1) } // Configure DAX client cfg := dax.DefaultConfig() cfg.HostPorts = []string{endpoint} cfg.Region = region // Create DAX client daxClient, err := dax.New(cfg) if err != nil { fmt.Printf("Failed to create DAX client: %v\n", err) os.Exit(1) } defer daxClient.Close() // Don't forget to close the client // Create GetItem input input := &dynamodb.GetItemInput{ TableName: aws.String("TryDaxTable"), Key: map[string]*dynamodb.AttributeValue{ "pk": { N: aws.String("1"), }, "sk": { N: aws.String("1"), }, }, } // Make the GetItem call result, err := daxClient.GetItem(input) if err != nil { fmt.Printf("Failed to get item: %v\n", err) os.Exit(1) } // Print the result fmt.Printf("GetItem succeeded: %+v\n", result) } ``` ## V2 DAX Go SDK usage ``` package main import ( "context" "fmt" "os" "github.com/aws/aws-dax-go-v2/dax" "github.com/aws/aws-sdk-go-v2/config" "github.com/aws/aws-sdk-go-v2/service/dynamodb" "github.com/aws/aws-sdk-go-v2/service/dynamodb/types" "github.com/aws/aws-sdk-go-v2/feature/dynamodb/attributevalue" "github.com/aws/aws-sdk-go-v2/aws" ) func main() { ctx := context.Background() region := "us-west-2" endpoint := "dax://my-cluster.l6fzcv.dax-clusters.us-east-1.amazonaws.com" // Create DAX config config := dax.DefaultConfig() // Specify Endpoint and Region config.HostPorts = []string{endpoint} config.Region = region // Enabling logging config.LogLevel = utils.LogDebug // Create DAX client daxClient, err := dax.New(config) if err != nil { fmt.Printf("Failed to create DAX client: %v\n", err) os.Exit(1) } defer daxClient.Close() // Don't forget to close the client // Create key using attributevalue.Marshal for type safety pk, err := attributevalue.Marshal(fmt.Sprintf("%s_%d", keyPrefix, i)) if err != nil { return fmt.Errorf("error marshaling pk: %v", err) } sk, err := attributevalue.Marshal(fmt.Sprintf("%d", j)) if err != nil { return fmt.Errorf("error marshaling sk: %v", err) } // Create GetItem input input := &dynamodb.GetItemInput{ TableName: aws.String("TryDaxTable"), Key: map[string]types.AttributeValue{ "pk": pk, "sk": sk, }, } // Make the GetItem call result, err := daxClient.GetItem(ctx, input) if err != nil { fmt.Printf("Failed to get item: %v\n", err) os.Exit(1) } // Print the result fmt.Printf("GetItem succeeded: %+v\n", result) } ``` For more API usage details, see [AWS samples](https://github.com/aws-samples/sample-aws-dax-go-v2). # Java and DAX DAX SDK for Java 2.x is compatible with [AWS SDK for Java 2.x](https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/). It's built on top of Java 8\$1 and includes support for non-blocking I/O. For information about using DAX with AWS SDK for Java 1.x, see [Using DAX with AWS SDK for Java 1.x](DAX.client.java-sdk-v1.md). ## Using the client as a Maven dependency Follow these steps to use the client for the DAX SDK for Java in your application as a dependency. 1. Download and install Apache Maven. For more information, see [Downloading Apache Maven](https://maven.apache.org/download.cgi) and [Installing Apache Maven](https://maven.apache.org/install.html). 1. Add the client Maven dependency to your application's Project Object Model (POM) file. In this example, replace *x.x.x* with the actual version number of the client. ``` software.amazon.dax amazon-dax-client x.x.x ``` ## TryDax sample code After you've set up your workspace and added the DAX SDK as a dependency, copy [TryDax.java](DAX.client.TryDax.java.md) into your project. Run the code using this command. ``` java -cp classpath TryDax ``` You should see output similar to the following. ``` Creating a DynamoDB client Attempting to create table; please wait... Successfully created table. Table status: ACTIVE Writing data to the table... Writing 10 items for partition key: 1 Writing 10 items for partition key: 2 Writing 10 items for partition key: 3 ... Running GetItem and Query tests... First iteration of each test will result in cache misses Next iterations are cache hits GetItem test - partition key 1-100 and sort keys 1-10 Total time: 4390.240 ms - Avg time: 4.390 ms Total time: 3097.089 ms - Avg time: 3.097 ms Total time: 3273.463 ms - Avg time: 3.273 ms Total time: 3353.739 ms - Avg time: 3.354 ms Total time: 3533.314 ms - Avg time: 3.533 ms Query test - partition key 1-100 and sort keys between 2 and 9 Total time: 475.868 ms - Avg time: 4.759 ms Total time: 423.333 ms - Avg time: 4.233 ms Total time: 460.271 ms - Avg time: 4.603 ms Total time: 397.859 ms - Avg time: 3.979 ms Total time: 466.644 ms - Avg time: 4.666 ms Attempting to delete table; please wait... Successfully deleted table. ``` Take note of the timing information—the number of milliseconds required for the `GetItem` and `Query` tests. In this case, you ran the program against the DynamoDB endpoint. Now you'll run the program again, this time against your DAX cluster. To determine the endpoint of your DAX cluster, choose one of the following: + In the DynamoDB console, select your DAX cluster. The cluster endpoint is shown in the console, as in the following example. ``` dax://my-cluster.l6fzcv.dax-clusters.us-east-1.amazonaws.com ``` + Using the AWS CLI, enter the following command: ``` aws dax describe-clusters --query "Clusters[*].ClusterDiscoveryEndpoint" ``` The cluster endpoint address, port, and URL are shown in the output, as in the following example. ``` { "Address": "my-cluster.l6fzcv.dax-clusters.us-east-1.amazonaws.com", "Port": 8111, "URL": "dax://my-cluster.l6fzcv.dax-clusters.us-east-1.amazonaws.com" } ``` Now run the program again, but this time, specify the cluster endpoint URL as a command line parameter. ``` java -cp classpath TryDax dax://my-cluster.l6fzcv.dax-clusters.us-east-1.amazonaws.com ``` Look at the output and take note of the timing information. The elapsed times for `GetItem`and `Query` should be significantly lower with DAX than with DynamoDB. ## SDK metrics With DAX SDK for Java 2.x, you can collect metrics about the service clients in your application and analyze the output in Amazon CloudWatch. See [Enabling SDK metrics](https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/metrics.html) for more information. **Note** The DAX SDK for Java only collects `ApiCallSuccessful` and `ApiCallDuration` metrics. # TryDax.java ``` import java.util.Map; import software.amazon.awssdk.services.dynamodb.DynamoDbAsyncClient; import software.amazon.awssdk.services.dynamodb.model.AttributeDefinition; import software.amazon.awssdk.services.dynamodb.model.AttributeValue; import software.amazon.awssdk.services.dynamodb.model.BillingMode; import software.amazon.awssdk.services.dynamodb.model.CreateTableRequest; import software.amazon.awssdk.services.dynamodb.model.DeleteTableRequest; import software.amazon.awssdk.services.dynamodb.model.DescribeTableRequest; import software.amazon.awssdk.services.dynamodb.model.GetItemRequest; import software.amazon.awssdk.services.dynamodb.model.KeySchemaElement; import software.amazon.awssdk.services.dynamodb.model.KeyType; import software.amazon.awssdk.services.dynamodb.model.PutItemRequest; import software.amazon.awssdk.services.dynamodb.model.QueryRequest; import software.amazon.awssdk.services.dynamodb.model.ScalarAttributeType; import software.amazon.dax.ClusterDaxAsyncClient; import software.amazon.dax.Configuration; public class TryDax { public static void main(String[] args) throws Exception { DynamoDbAsyncClient ddbClient = DynamoDbAsyncClient.builder() .build(); DynamoDbAsyncClient daxClient = null; if (args.length >= 1) { daxClient = ClusterDaxAsyncClient.builder() .overrideConfiguration(Configuration.builder() .url(args[0]) // e.g. dax://my-cluster.l6fzcv.dax-clusters.us-east-1.amazonaws.com .build()) .build(); } String tableName = "TryDaxTable"; System.out.println("Creating table..."); createTable(tableName, ddbClient); System.out.println("Populating table..."); writeData(tableName, ddbClient, 100, 10); DynamoDbAsyncClient testClient = null; if (daxClient != null) { testClient = daxClient; } else { testClient = ddbClient; } System.out.println("Running GetItem and Query tests..."); System.out.println("First iteration of each test will result in cache misses"); System.out.println("Next iterations are cache hits\n"); // GetItem getItemTest(tableName, testClient, 100, 10, 5); // Query queryTest(tableName, testClient, 100, 2, 9, 5); System.out.println("Deleting table..."); deleteTable(tableName, ddbClient); } private static void createTable(String tableName, DynamoDbAsyncClient client) { try { System.out.println("Attempting to create table; please wait..."); client.createTable(CreateTableRequest.builder() .tableName(tableName) .keySchema(KeySchemaElement.builder() .keyType(KeyType.HASH) .attributeName("pk") .build(), KeySchemaElement.builder() .keyType(KeyType.RANGE) .attributeName("sk") .build()) .attributeDefinitions(AttributeDefinition.builder() .attributeName("pk") .attributeType(ScalarAttributeType.N) .build(), AttributeDefinition.builder() .attributeName("sk") .attributeType(ScalarAttributeType.N) .build()) .billingMode(BillingMode.PAY_PER_REQUEST) .build()).get(); client.waiter().waitUntilTableExists(DescribeTableRequest.builder() .tableName(tableName) .build()).get(); System.out.println("Successfully created table."); } catch (Exception e) { System.err.println("Unable to create table: "); e.printStackTrace(); } } private static void deleteTable(String tableName, DynamoDbAsyncClient client) { try { System.out.println("\nAttempting to delete table; please wait..."); client.deleteTable(DeleteTableRequest.builder() .tableName(tableName) .build()).get(); client.waiter().waitUntilTableNotExists(DescribeTableRequest.builder() .tableName(tableName) .build()).get(); System.out.println("Successfully deleted table."); } catch (Exception e) { System.err.println("Unable to delete table: "); e.printStackTrace(); } } private static void writeData(String tableName, DynamoDbAsyncClient client, int pkmax, int skmax) { System.out.println("Writing data to the table..."); int stringSize = 1000; StringBuilder sb = new StringBuilder(stringSize); for (int i = 0; i < stringSize; i++) { sb.append('X'); } String someData = sb.toString(); try { for (int ipk = 1; ipk <= pkmax; ipk++) { System.out.println(("Writing " + skmax + " items for partition key: " + ipk)); for (int isk = 1; isk <= skmax; isk++) { client.putItem(PutItemRequest.builder() .tableName(tableName) .item(Map.of("pk", attr(ipk), "sk", attr(isk), "someData", attr(someData))) .build()).get(); } } } catch (Exception e) { System.err.println("Unable to write item:"); e.printStackTrace(); } } private static AttributeValue attr(int n) { return AttributeValue.builder().n(String.valueOf(n)).build(); } private static AttributeValue attr(String s) { return AttributeValue.builder().s(s).build(); } private static void getItemTest(String tableName, DynamoDbAsyncClient client, int pk, int sk, int iterations) { long startTime, endTime; System.out.println("GetItem test - partition key 1-" + pk + " and sort keys 1-" + sk); for (int i = 0; i < iterations; i++) { startTime = System.nanoTime(); try { for (int ipk = 1; ipk <= pk; ipk++) { for (int isk = 1; isk <= sk; isk++) { client.getItem(GetItemRequest.builder() .tableName(tableName) .key(Map.of("pk", attr(ipk), "sk", attr(isk))) .build()).get(); } } } catch (Exception e) { System.err.println("Unable to get item:"); e.printStackTrace(); } endTime = System.nanoTime(); printTime(startTime, endTime, pk * sk); } } private static void queryTest(String tableName, DynamoDbAsyncClient client, int pk, int sk1, int sk2, int iterations) { long startTime, endTime; System.out.println("Query test - partition key 1-" + pk + " and sort keys between " + sk1 + " and " + sk2); for (int i = 0; i < iterations; i++) { startTime = System.nanoTime(); for (int ipk = 1; ipk <= pk; ipk++) { try { // Pagination API for Query. client.queryPaginator(QueryRequest.builder() .tableName(tableName) .keyConditionExpression("pk = :pkval and sk between :skval1 and :skval2") .expressionAttributeValues(Map.of(":pkval", attr(ipk), ":skval1", attr(sk1), ":skval2", attr(sk2))) .build()).items().subscribe((item) -> { }).get(); } catch (Exception e) { System.err.println("Unable to query table:"); e.printStackTrace(); } } endTime = System.nanoTime(); printTime(startTime, endTime, pk); } } private static void printTime(long startTime, long endTime, int iterations) { System.out.format("\tTotal time: %.3f ms - ", (endTime - startTime) / (1000000.0)); System.out.format("Avg time: %.3f ms\n", (endTime - startTime) / (iterations * 1000000.0)); } } ``` # .NET and DAX Follow these steps to run the .NET sample on your Amazon EC2 instance. **Note** This tutorial uses the .NET 9 SDK. It shows how you can run a program in your default Amazon VPC to access your Amazon DynamoDB Accelerator (DAX) cluster. It works with the [AWS SDK v4 for .NET ](https://docs.aws.amazon.com/sdk-for-net/v4/developer-guide/welcome.html). For details about changes in V4 and information about migrating, see [Migrating to version 4 of the AWS SDK for .NET](https://docs.aws.amazon.com/sdk-for-net/v4/developer-guide/net-dg-v4.html). If you prefer, you can use the AWS Toolkit for Visual Studio to write a .NET application and deploy it into your VPC. For more information, see [Creating and Deploying Elastic Beanstalk Applications in .NET Using AWS Toolkit for Visual Studio](https://docs.aws.amazon.com/elasticbeanstalk/latest/dg/create_deploy_NET.html) in the *AWS Elastic Beanstalk Developer Guide*. **To run the .NET sample for DAX** 1. Go to the [Microsoft Downloads page](https://www.microsoft.com/net/download?initial-os=linux) and download the latest .NET 9 SDK for Linux. The downloaded file is `dotnet-sdk-N.N.N-linux-x64.tar.gz`. 1. Extract the SDK files. ``` mkdir dotnet tar zxvf dotnet-sdk-N.N.N-linux-x64.tar.gz -C dotnet ``` Replace `N.N.N` with the actual version number of the .NET SDK (for example: `9.0.305`). 1. Verify the installation. ``` alias dotnet=$HOME/dotnet/dotnet dotnet --version ``` This should print the version number of the .NET SDK. **Note** Instead of the version number, you might receive the following error: error: libunwind.so.8: cannot open shared object file: No such file or directory To resolve the error, install the `libunwind` package. ``` sudo yum install -y libunwind ``` After you do this, you should be able to run the `dotnet --version` command without any errors. 1. Create a new .NET project. ``` dotnet new console -o myApp ``` This requires a few minutes to perform a one-time-only setup. When it is complete, run the sample project. ``` dotnet run --project myApp ``` You should receive the following message: `Hello World!` 1. The `myApp/myApp.csproj` file contains metadata about your project. To use the DAX client in your application, modify the file so that it looks like the following. ``` Exe net9.0 ``` 1. Download the sample program source code (`.zip` file). ``` wget http://docs.aws.amazon.com/amazondynamodb/latest/developerguide/samples/TryDax.zip ``` When the download is complete, extract the source files. ``` unzip TryDax.zip ``` 1. Now run the sample programs of *dotNet*, one at a time. For each program, copy its contents into the `myApp/Program.cs`, and then run the `MyApp` project. Run the following .NET programs. The first program creates a DynamoDB table named `TryDaxTable`. The second program writes data to the table. ``` cp TryDax/dotNet/01-CreateTable.cs myApp/Program.cs dotnet run --project myApp cp TryDax/dotNet/02-Write-Data.cs myApp/Program.cs dotnet run --project myApp ``` 1. Next, run some programs to perform `GetItem`, `Query`, and `Scan` operations on your DAX cluster. To determine the endpoint for your DAX cluster, choose one of the following: + **Using the DynamoDB console** — Choose your DAX cluster. The cluster endpoint is shown on the console, as in the following example. ``` dax://my-cluster.l6fzcv.dax-clusters.us-east-1.amazonaws.com ``` + **Using the AWS CLI** — Enter the following command. ``` aws dax describe-clusters --query "Clusters[*].ClusterDiscoveryEndpoint" ``` The cluster endpoint is shown in the output, as in the following example. ``` { "Address": "my-cluster.l6fzcv.dax-clusters.us-east-1.amazonaws.com", "Port": 8111, "URL": "dax://my-cluster.l6fzcv.dax-clusters.us-east-1.amazonaws.com" } ``` Now run the following programs, specifying your cluster endpoint as a command line parameter. (Replace the sample endpoint with your actual DAX cluster endpoint.) ``` cp TryDax/dotNet/03-GetItem-Test.cs myApp/Program.cs dotnet run --project myApp dax://my-cluster.l6fzcv.dax-clusters.us-east-1.amazonaws.com cp TryDax/dotNet/04-Query-Test.cs myApp/Program.cs dotnet run --project myApp dax://my-cluster.l6fzcv.dax-clusters.us-east-1.amazonaws.com cp TryDax/dotNet/05-Scan-Test.cs myApp/Program.cs dotnet run --project myApp dax://my-cluster.l6fzcv.dax-clusters.us-east-1.amazonaws.com ``` Take note of the timing information—the number of milliseconds required for the `GetItem`, `Query`, and `Scan` tests. 1. Run the following .NET program to delete `TryDaxTable`. ``` cp TryDax/dotNet/06-DeleteTable.cs myApp/Program.cs dotnet run --project myApp ``` For more information about these programs, see the following sections: + [01-CreateTable.cs](DAX.client.run-application-dotnet.01-CreateTable.md) + [02-Write-Data.cs](DAX.client.run-application-dotnet.02-Write-Data.md) + [03-GetItem-Test.cs](DAX.client.run-application-dotnet.03-GetItem-Test.md) + [04-Query-Test.cs](DAX.client.run-application-dotnet.04-Query-Test.md) + [05-Scan-Test.cs](DAX.client.run-application-dotnet.05-Scan-Test.md) + [06-DeleteTable.cs](DAX.client.run-application-dotnet.06-DeleteTable.md) # 01-CreateTable.cs The `01-CreateTable.cs` program creates a table (`TryDaxTable`). The remaining .NET programs in this section depend on this table. ``` using System; using System.Collections.Generic; using System.Threading.Tasks; using Amazon.DynamoDBv2; using Amazon.DynamoDBv2.Model; namespace ClientTest { class Program { public static async Task Main(string[] args) { AmazonDynamoDBClient client = new AmazonDynamoDBClient(); var tableName = "TryDaxTable"; var request = new CreateTableRequest() { TableName = tableName, KeySchema = new List() { new KeySchemaElement{ AttributeName = "pk",KeyType = "HASH"}, new KeySchemaElement{ AttributeName = "sk",KeyType = "RANGE"} }, AttributeDefinitions = new List() { new AttributeDefinition{ AttributeName = "pk",AttributeType = "N"}, new AttributeDefinition{ AttributeName = "sk",AttributeType = "N"} }, ProvisionedThroughput = new ProvisionedThroughput() { ReadCapacityUnits = 10, WriteCapacityUnits = 10 } }; var response = await client.CreateTableAsync(request); Console.WriteLine("Hit to continue..."); Console.ReadLine(); } } } ``` # 02-Write-Data.cs The `02-Write-Data.cs` program writes test data to `TryDaxTable`. ``` using System; using System.Collections.Generic; using System.Threading.Tasks; using Amazon.DynamoDBv2; using Amazon.DynamoDBv2.Model; namespace ClientTest { class Program { public static async Task Main(string[] args) { AmazonDynamoDBClient client = new AmazonDynamoDBClient(); var tableName = "TryDaxTable"; string someData = new string('X', 1000); var pkmax = 10; var skmax = 10; for (var ipk = 1; ipk <= pkmax; ipk++) { Console.WriteLine($"Writing {skmax} items for partition key: {ipk}"); for (var isk = 1; isk <= skmax; isk++) { var request = new PutItemRequest() { TableName = tableName, Item = new Dictionary() { { "pk", new AttributeValue{N = ipk.ToString() } }, { "sk", new AttributeValue{N = isk.ToString() } }, { "someData", new AttributeValue{S = someData } } } }; var response = await client.PutItemAsync(request); } } Console.WriteLine("Hit to continue..."); Console.ReadLine(); } } } ``` # 03-GetItem-Test.cs The `03-GetItem-Test.cs` program performs `GetItem` operations on `TryDaxTable`. ``` using System; using System.Collections.Generic; using System.Threading.Tasks; using Amazon.DAX; using Amazon.DynamoDBv2.Model; using Amazon.Runtime; namespace ClientTest { class Program { public static async Task Main(string[] args) { string endpointUri = args[0]; Console.WriteLine($"Using DAX client - endpointUri={endpointUri}"); var clientConfig = new DaxClientConfig(endpointUri) { AwsCredentials = FallbackCredentialsFactory.GetCredentials() }; var client = new ClusterDaxClient(clientConfig); var tableName = "TryDaxTable"; var pk = 1; var sk = 10; var iterations = 5; var startTime = System.DateTime.Now; for (var i = 0; i < iterations; i++) { for (var ipk = 1; ipk <= pk; ipk++) { for (var isk = 1; isk <= sk; isk++) { var request = new GetItemRequest() { TableName = tableName, Key = new Dictionary() { {"pk", new AttributeValue {N = ipk.ToString()} }, {"sk", new AttributeValue {N = isk.ToString() } } } }; var response = await client.GetItemAsync(request); Console.WriteLine($"GetItem succeeded for pk: {ipk},sk: {isk}"); } } } var endTime = DateTime.Now; TimeSpan timeSpan = endTime - startTime; Console.WriteLine($"Total time: {timeSpan.TotalMilliseconds} milliseconds"); Console.WriteLine("Hit to continue..."); Console.ReadLine(); } } } ``` # 04-Query-Test.cs The `04-Query-Test.cs` program performs `Query` operations on `TryDaxTable`. ``` using System; using System.Collections.Generic; using System.Threading.Tasks; using Amazon.Runtime; using Amazon.DAX; using Amazon.DynamoDBv2.Model; namespace ClientTest { class Program { public static async Task Main(string[] args) { string endpointUri = args[0]; Console.WriteLine($"Using DAX client - endpointUri={endpointUri}"); var clientConfig = new DaxClientConfig(endpointUri) { AwsCredentials = FallbackCredentialsFactory.GetCredentials() }; var client = new ClusterDaxClient(clientConfig); var tableName = "TryDaxTable"; var pk = 5; var sk1 = 2; var sk2 = 9; var iterations = 5; var startTime = DateTime.Now; for (var i = 0; i < iterations; i++) { var request = new QueryRequest() { TableName = tableName, KeyConditionExpression = "pk = :pkval and sk between :skval1 and :skval2", ExpressionAttributeValues = new Dictionary() { {":pkval", new AttributeValue {N = pk.ToString()} }, {":skval1", new AttributeValue {N = sk1.ToString()} }, {":skval2", new AttributeValue {N = sk2.ToString()} } } }; var response = await client.QueryAsync(request); Console.WriteLine($"{i}: Query succeeded"); } var endTime = DateTime.Now; TimeSpan timeSpan = endTime - startTime; Console.WriteLine($"Total time: {timeSpan.TotalMilliseconds} milliseconds"); Console.WriteLine("Hit to continue..."); Console.ReadLine(); } } } ``` # 05-Scan-Test.cs The `05-Scan-Test.cs` program performs `Scan` operations on `TryDaxTable`. ``` using System; using System.Threading.Tasks; using Amazon.Runtime; using Amazon.DAX; using Amazon.DynamoDBv2.Model; namespace ClientTest { class Program { public static async Task Main(string[] args) { string endpointUri = args[0]; Console.WriteLine($"Using DAX client - endpointUri={endpointUri}"); var clientConfig = new DaxClientConfig(endpointUri) { AwsCredentials = FallbackCredentialsFactory.GetCredentials() }; var client = new ClusterDaxClient(clientConfig); var tableName = "TryDaxTable"; var iterations = 5; var startTime = DateTime.Now; for (var i = 0; i < iterations; i++) { var request = new ScanRequest() { TableName = tableName }; var response = await client.ScanAsync(request); Console.WriteLine($"{i}: Scan succeeded"); } var endTime = DateTime.Now; TimeSpan timeSpan = endTime - startTime; Console.WriteLine($"Total time: {timeSpan.TotalMilliseconds} milliseconds"); Console.WriteLine("Hit to continue..."); Console.ReadLine(); } } } ``` # 06-DeleteTable.cs The `06-DeleteTable.cs` program deletes `TryDaxTable`. Run this program after you have finished testing. ``` using System; using System.Threading.Tasks; using Amazon.DynamoDBv2.Model; using Amazon.DynamoDBv2; namespace ClientTest { class Program { public static async Task Main(string[] args) { AmazonDynamoDBClient client = new AmazonDynamoDBClient(); var tableName = "TryDaxTable"; var request = new DeleteTableRequest() { TableName = tableName }; var response = await client.DeleteTableAsync(request); Console.WriteLine("Hit to continue..."); Console.ReadLine(); } } } ``` # Python and DAX Follow this procedure to run the Python sample application on your Amazon EC2 instance. **To run the Python sample for DAX** 1. Install the DAX Python client using the `pip` utility. ``` pip install amazon-dax-client ``` 1. Download the sample program source code (`.zip` file). ``` wget http://docs.aws.amazon.com/amazondynamodb/latest/developerguide/samples/TryDax.zip ``` When the download is complete, extract the source files. ``` unzip TryDax.zip ``` 1. Run the following Python programs. The first program creates an Amazon DynamoDB table named `TryDaxTable`. The second program writes data to the table. ``` python 01-create-table.py python 02-write-data.py ``` 1. Run the following Python programs. ``` python 03-getitem-test.py python 04-query-test.py python 05-scan-test.py ``` Take note of the timing information—the number of milliseconds required for the `GetItem`, `Query`, and `Scan` tests. 1. In the previous step, you ran the programs against the DynamoDB endpoint. Now run the programs again, but this time, the `GetItem`, `Query`, and `Scan` operations are processed by your DAX cluster. To determine the endpoint for your DAX cluster, choose one of the following: + **Using the DynamoDB console** — Choose your DAX cluster. The cluster endpoint is shown on the console, as in the following example. ``` dax://my-cluster.l6fzcv.dax-clusters.us-east-1.amazonaws.com ``` + **Using the AWS CLI** — Enter the following command. ``` aws dax describe-clusters --query "Clusters[*].ClusterDiscoveryEndpoint" ``` The cluster endpoint is shown in the output, as in this example. ``` { "Address": "my-cluster.l6fzcv.dax-clusters.us-east-1.amazonaws.com", "Port": 8111, "URL": "dax://my-cluster.l6fzcv.dax-clusters.us-east-1.amazonaws.com" } ``` Run the programs again, but this time, specify the cluster endpoint as a command line parameter. ``` python 03-getitem-test.py dax://my-cluster.l6fzcv.dax-clusters.us-east-1.amazonaws.com python 04-query-test.py dax://my-cluster.l6fzcv.dax-clusters.us-east-1.amazonaws.com python 05-scan-test.py dax://my-cluster.l6fzcv.dax-clusters.us-east-1.amazonaws.com ``` Look at the rest of the output, and take note of the timing information. The elapsed times for `GetItem`, `Query`, and `Scan` should be significantly lower with DAX than with DynamoDB. 1. Run the following Python program to delete `TryDaxTable`. ``` python 06-delete-table.py ``` For more information about these programs, see the following sections: + [01-create-table.py](DAX.client.run-application-python.01-create-table.md) + [02-write-data.py](DAX.client.run-application-python.02-write-data.md) + [03-getitem-test.py](DAX.client.run-application-python.03-getitem-test.md) + [04-query-test.py](DAX.client.run-application-python.04-query-test.md) + [05-scan-test.py](DAX.client.run-application-python.05-scan-test.md) + [06-delete-table.py](DAX.client.run-application-python.06-delete-table.md) # 01-create-table.py The `01-create-table.py` program creates a table (`TryDaxTable`). The remaining Python programs in this section depend on this table. ``` import boto3 def create_dax_table(dyn_resource=None): """ Creates a DynamoDB table. :param dyn_resource: Either a Boto3 or DAX resource. :return: The newly created table. """ if dyn_resource is None: dyn_resource = boto3.resource("dynamodb") table_name = "TryDaxTable" params = { "TableName": table_name, "KeySchema": [ {"AttributeName": "partition_key", "KeyType": "HASH"}, {"AttributeName": "sort_key", "KeyType": "RANGE"}, ], "AttributeDefinitions": [ {"AttributeName": "partition_key", "AttributeType": "N"}, {"AttributeName": "sort_key", "AttributeType": "N"}, ], "BillingMode": "PAY_PER_REQUEST", } table = dyn_resource.create_table(**params) print(f"Creating {table_name}...") table.wait_until_exists() return table if __name__ == "__main__": dax_table = create_dax_table() print(f"Created table.") ``` # 02-write-data.py The `02-write-data.py` program writes test data to `TryDaxTable`. ``` import boto3 def write_data_to_dax_table(key_count, item_size, dyn_resource=None): """ Writes test data to the demonstration table. :param key_count: The number of partition and sort keys to use to populate the table. The total number of items is key_count * key_count. :param item_size: The size of non-key data for each test item. :param dyn_resource: Either a Boto3 or DAX resource. """ if dyn_resource is None: dyn_resource = boto3.resource("dynamodb") table = dyn_resource.Table("TryDaxTable") some_data = "X" * item_size for partition_key in range(1, key_count + 1): for sort_key in range(1, key_count + 1): table.put_item( Item={ "partition_key": partition_key, "sort_key": sort_key, "some_data": some_data, } ) print(f"Put item ({partition_key}, {sort_key}) succeeded.") if __name__ == "__main__": write_key_count = 10 write_item_size = 1000 print( f"Writing {write_key_count*write_key_count} items to the table. " f"Each item is {write_item_size} characters." ) write_data_to_dax_table(write_key_count, write_item_size) ``` # 03-getitem-test.py The `03-getitem-test.py` program performs `GetItem` operations on `TryDaxTable`. This example is given for the Region eu-west-1. ``` import argparse import sys import time import amazondax import boto3 def get_item_test(key_count, iterations, dyn_resource=None): """ Gets items from the table a specified number of times. The time before the first iteration and the time after the last iteration are both captured and reported. :param key_count: The number of items to get from the table in each iteration. :param iterations: The number of iterations to run. :param dyn_resource: Either a Boto3 or DAX resource. :return: The start and end times of the test. """ if dyn_resource is None: dyn_resource = boto3.resource('dynamodb') table = dyn_resource.Table('TryDaxTable') start = time.perf_counter() for _ in range(iterations): for partition_key in range(1, key_count + 1): for sort_key in range(1, key_count + 1): table.get_item(Key={ 'partition_key': partition_key, 'sort_key': sort_key }) print('.', end='') sys.stdout.flush() print() end = time.perf_counter() return start, end if __name__ == '__main__': parser = argparse.ArgumentParser() parser.add_argument( 'endpoint_url', nargs='?', help="When specified, the DAX cluster endpoint. Otherwise, DAX is not used.") args = parser.parse_args() test_key_count = 10 test_iterations = 50 if args.endpoint_url: print(f"Getting each item from the table {test_iterations} times, " f"using the DAX client.") # Use a with statement so the DAX client closes the cluster after completion. with amazondax.AmazonDaxClient.resource(endpoint_url=args.endpoint_url, region_name='eu-west-1') as dax: test_start, test_end = get_item_test( test_key_count, test_iterations, dyn_resource=dax) else: print(f"Getting each item from the table {test_iterations} times, " f"using the Boto3 client.") test_start, test_end = get_item_test( test_key_count, test_iterations) print(f"Total time: {test_end - test_start:.4f} sec. Average time: " f"{(test_end - test_start)/ test_iterations}.") ``` # 04-query-test.py The `04-query-test.py` program performs `Query` operations on `TryDaxTable`. ``` import argparse import time import sys import amazondax import boto3 from boto3.dynamodb.conditions import Key def query_test(partition_key, sort_keys, iterations, dyn_resource=None): """ Queries the table a specified number of times. The time before the first iteration and the time after the last iteration are both captured and reported. :param partition_key: The partition key value to use in the query. The query returns items that have partition keys equal to this value. :param sort_keys: The range of sort key values for the query. The query returns items that have sort key values between these two values. :param iterations: The number of iterations to run. :param dyn_resource: Either a Boto3 or DAX resource. :return: The start and end times of the test. """ if dyn_resource is None: dyn_resource = boto3.resource("dynamodb") table = dyn_resource.Table("TryDaxTable") key_condition_expression = Key("partition_key").eq(partition_key) & Key( "sort_key" ).between(*sort_keys) start = time.perf_counter() for _ in range(iterations): table.query(KeyConditionExpression=key_condition_expression) print(".", end="") sys.stdout.flush() print() end = time.perf_counter() return start, end if __name__ == "__main__": # pylint: disable=not-context-manager parser = argparse.ArgumentParser() parser.add_argument( "endpoint_url", nargs="?", help="When specified, the DAX cluster endpoint. Otherwise, DAX is not used.", ) args = parser.parse_args() test_partition_key = 5 test_sort_keys = (2, 9) test_iterations = 100 if args.endpoint_url: print(f"Querying the table {test_iterations} times, using the DAX client.") # Use a with statement so the DAX client closes the cluster after completion. with amazondax.AmazonDaxClient.resource(endpoint_url=args.endpoint_url) as dax: test_start, test_end = query_test( test_partition_key, test_sort_keys, test_iterations, dyn_resource=dax ) else: print(f"Querying the table {test_iterations} times, using the Boto3 client.") test_start, test_end = query_test( test_partition_key, test_sort_keys, test_iterations ) print( f"Total time: {test_end - test_start:.4f} sec. Average time: " f"{(test_end - test_start)/test_iterations}." ) ``` # 05-scan-test.py The `05-scan-test.py` program performs `Scan` operations on `TryDaxTable`. ``` import argparse import time import sys import amazondax import boto3 def scan_test(iterations, dyn_resource=None): """ Scans the table a specified number of times. The time before the first iteration and the time after the last iteration are both captured and reported. :param iterations: The number of iterations to run. :param dyn_resource: Either a Boto3 or DAX resource. :return: The start and end times of the test. """ if dyn_resource is None: dyn_resource = boto3.resource("dynamodb") table = dyn_resource.Table("TryDaxTable") start = time.perf_counter() for _ in range(iterations): table.scan() print(".", end="") sys.stdout.flush() print() end = time.perf_counter() return start, end if __name__ == "__main__": # pylint: disable=not-context-manager parser = argparse.ArgumentParser() parser.add_argument( "endpoint_url", nargs="?", help="When specified, the DAX cluster endpoint. Otherwise, DAX is not used.", ) args = parser.parse_args() test_iterations = 100 if args.endpoint_url: print(f"Scanning the table {test_iterations} times, using the DAX client.") # Use a with statement so the DAX client closes the cluster after completion. with amazondax.AmazonDaxClient.resource(endpoint_url=args.endpoint_url) as dax: test_start, test_end = scan_test(test_iterations, dyn_resource=dax) else: print(f"Scanning the table {test_iterations} times, using the Boto3 client.") test_start, test_end = scan_test(test_iterations) print( f"Total time: {test_end - test_start:.4f} sec. Average time: " f"{(test_end - test_start)/test_iterations}." ) ``` # 06-delete-table.py The `06-delete-table.py` program deletes `TryDaxTable`. Run this program after you have finished testing Amazon DynamoDB Accelerator (DAX) functionality. ``` import boto3 def delete_dax_table(dyn_resource=None): """ Deletes the demonstration table. :param dyn_resource: Either a Boto3 or DAX resource. """ if dyn_resource is None: dyn_resource = boto3.resource("dynamodb") table = dyn_resource.Table("TryDaxTable") table.delete() print(f"Deleting {table.name}...") table.wait_until_not_exists() if __name__ == "__main__": delete_dax_table() print("Table deleted!") ``` # Modifying an existing application to use DAX If you already have a Java application that uses Amazon DynamoDB, you can modify it so that it can access your DynamoDB Accelerator (DAX) cluster. You don't have to rewrite the entire application because the DAX Java client is similar to the DynamoDB low-level client included in the AWS SDK for Java 2.x. See [Working with items in DynamoDB](https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/examples-dynamodb-items.html) for details. **Note** This example uses AWS SDK for Java 2.x. For the legacy SDK for Java 1.x version, see [Modifying an existing SDK for Java 1.x application to use DAX](DAX.client.modify-your-app.java-sdk-v1.md). To modify your program, replace the DynamoDB client with a DAX client. ``` Region region = Region.US_EAST_1; // Create an asynchronous DynamoDB client DynamoDbAsyncClient client = DynamoDbAsyncClient.builder() .region(region) .build(); // Create an asynchronous DAX client DynamoDbAsyncClient client = ClusterDaxAsyncClient.builder() .overrideConfiguration(Configuration.builder() .url() // for example, "dax://my-cluster.l6fzcv.dax-clusters.us-east-1.amazonaws.com" .region(region) .addMetricPublisher(cloudWatchMetricsPub) // optionally enable SDK metric collection .build()) .build(); ``` You can also use the high-level library that is part of the AWS SDK for Java 2.x, replacing the DynamoDB client with a DAX client. ``` Region region = Region.US_EAST_1; DynamoDbAsyncClient dax = ClusterDaxAsyncClient.builder() .overrideConfiguration(Configuration.builder() .url() // for example, "dax://my-cluster.l6fzcv.dax-clusters.us-east-1.amazonaws.com" .region(region) .build()) .build(); DynamoDbEnhancedAsyncClient enhancedClient = DynamoDbEnhancedAsyncClient.builder() .dynamoDbClient(dax) .build(); ``` For more information, see [Mapping items in DynamoDB tables](https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/examples-dynamodb-enhanced.html).