Amazon Q

By integrating Amazon Q with DX, you can analyze Amazon Q daily usage metrics and AI assistant interactions. Please refer to the API documentation below and our schema explorer to see what data DX imports.

Prerequisites

To connect Amazon Q to DX, you need:

An AWS account with Amazon Q access
Access to AWS IAM to create a Policy and Role
An S3 bucket configured for Amazon Q data storage

Setup instructions

Amazon Q connections use IAM role-based authentication for secure cross-account access.

Step 1 - Get your External ID from DX

In DX, navigate to Settings > Data connectors > Add connector > Amazon Q
Copy the External ID displayed - you’ll need this for the trust policy

Step 2 - Create an IAM policy for S3 access

In your AWS account, create a custom IAM policy with S3 read permissions:

Go to IAM > Policies > Create policy
Select the JSON tab and paste the following (replace YOUR_BUCKET_NAME with your actual bucket name):

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "DXAmazonQReadOnly",
      "Effect": "Allow",
      "Action": ["s3:GetObject", "s3:ListBucket"],
      "Resource": [
        "arn:aws:s3:::YOUR_BUCKET_NAME",
        "arn:aws:s3:::YOUR_BUCKET_NAME/*"
      ]
    }
  ]
}

Name the policy (e.g., DX-AmazonQ-Policy) and create it

Step 3 - Create an IAM role with trust policy

Create an IAM role that DX can assume:

Go to IAM > Roles > Create role
Select Custom trust policy and paste the following (replace YOUR_EXTERNAL_ID_FROM_DX with the External ID from Step 1):

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::703671904508:role/dx-datacloud"
      },
      "Action": "sts:AssumeRole",
      "Condition": {
        "StringEquals": {
          "sts:ExternalId": "YOUR_EXTERNAL_ID_FROM_DX"
        }
      }
    }
  ]
}

Click Next and attach the policy you created in Step 2
Name the role (e.g., DX-AmazonQ-Role) and create it
Copy the Role ARN (e.g., arn:aws:iam::123456789012:role/DX-AmazonQ-Role)

Step 4 - Configure the connection in DX

Navigate to the connections page in DX and select “+ Connection” in the top right. Enter the following in the connection form:

Role ARN: The ARN of the IAM role you created
Region: The AWS region where your S3 bucket is located
Bucket Name: The name of your S3 bucket containing Amazon Q data
Connection Name: A descriptive name for this connection (e.g., “Amazon Q Production”)
User mapping directory path: Path to the directory containing the user mapping files (e.g., if your file is at example/user_mapping.csv, enter example/)
Usage metrics directory path: Path to AWSLogs directory (e.g., if your directory is at example/AWSLogs/, enter example/)

Click “Add connection” to establish the connection.

User mapping CSV format

Your user mapping CSV must contain aws_user_uuid and user_email as headers.

API reference

The table below lists the specific AWS services and permissions that are used by DX.

Service	Documentation
`sts:AssumeRole`	Link
`s3:GetObject`	Link
`s3:ListBucket`	Link

Errors

The table below lists potential error codes when adding a connection in DX.

Error	Description
`invalid_credentials`	Your IAM role configuration is not valid.
`access_denied`	DX cannot assume the IAM role. Check the trust policy and external ID.
`missing_role_arn`	IAM role ARN is required for Amazon Q connections.
`invalid_role_arn`	The IAM role ARN format is invalid. Expected format: `arn:aws:iam::{account-id}:role/{role-name}`
`bucket_not_found`	The specified S3 bucket does not exist or is not accessible.
`no_users_found`	No users found in the user mapping CSV (provide a valid user mapping CSV with `aws_user_uuid` and `user_email` columns).
`no_metrics_found`	No usage metrics found in the provided directory.
`invalid_permissions`	Your IAM role does not have the required permissions to access S3.