Use Autonomous AI Database API for DynamoDB

Autonomous AI Database API for DynamoDB make it possible to store, manage and retrieve data in an Autonomous AI Database using a key-value format.

About using Autonomous AI Database API for DynamoDB

Oracle Autonomous AI Database offers the Autonomous AI Database API for DynamoDB, with Oracle’s fully managed Autonomous AI Database, enabling you to use existing DynamoDB tools and SDKs to work seamlessly with Autonomous AI Database.

Using the Oracle Autonomous AI Database API for DynamoDB compatibility API, you can continue to use your existing DynamoDB clients and make minimal changes to your applications to work with Autonomous AI Database. You can use standard DynamoDB SDKs to integrate your existing DynamoDB applications with Autonomous AI Database. The APIs offer familiar DynamoDB operations such as, GetItem, DeleteItem, CreateTable, and DeleteTable, enabling you to migrate DynamoDB applications to Autonomous AI Database.

By using Autonomous AI Database API for DynamoDB, you can take advantage of Autonomous AI Database features while maintaining DynamoDB compatibility.

See Amazon DynamoDB for more information.

Prerequisites

Lists the prerequisites to use Autonomous AI Database API for DynamoDB with your Autonomous AI Database.

Before you enable Autonomous AI Database API for DynamoDB for your database, note the following:

Enable Autonomous AI Database API for DynamoDB on Autonomous AI Database

Describes the steps generate access key and secret key to invoke DynamoDB API from your Autonomous AI Database instance.

Perform the following prerequisite steps as necessary:

Follow these steps to enable DynamoDB APIs on an Autonomous AI Database instance:

  1. On the More actions drop-down list, select Manage tags.

    This shows the Add Tags page.

  2. Provide the following values to assign tags to Autonomous AI Database.

    • Namespace: To add a free-from tag, leave the value blank.

    • Key: adb$feature

    • Value: {"name":"DynamoDB_API","enable":true}

    Click Add to add the tag.

    After you click Add, the Lifecycle state field shows Updating and Autonomous AI Database generates an Update Autonomous AI Database Tags work request. To view the request, on the details page, select the Work requests tab.

    It may take up to ten (10) minutes for Autonomous AI Database API for DynamoDB to be enabled.

    After enabling the Oracle AI Database API for DynamoDB on your Autonomous AI Database, you use the https://dataaccess.adb.{oci-region_name}.oraclecloudapps.com/adb/keyvaluestore/v1/{database-ocid} REST endpoint to perform DynamoDB operations. To access the Oracle Autonomous DynamoDB API, you need a valid access key ID, secret access key, and the necessary privileges for your operations, for example, the CREATE_TABLE privilege is required to create a DynamoDB table.

    The URI for the Oracle Autonomous DynamoDB API operations is:

    https://dataaccess.adb.{oci-region_name}.oraclecloudapps.com/adb/keyvaluestore/v1/{database-ocid}

    For example:

    https://dataaccess.adb.us-phoenix-1.oraclecloudapps.com/adb/keyvaluestore/v1/OCID1.AUTONOMOUSDATABASE.OC1.PHX.ANYHQLJRGDV...EXAMPLE

Configure Access to Invoke DynamoDB APIs

This section provides the steps to create and manage access keys required to authenticate and use DynamoDB-compatible APIs after you enabled your Autonomous AI Database.

Use REST endpoint https://dataaccess.adb.{oci-region-name}.oraclecloudapps.com/adb/auth/v1/databases/{database-ocid}/accesskeys to manage the access to DynamoDB tables. To do this, provide your database username and credentials; the specified user must have the PDB_DBA role granted. These access keys are required for authenticating API calls to the Autonomous AI Database for DynamoDB.

You must ensure that the access key is assigned the necessary permissions to perform DynamoDB-compatible operations. You can specify these permissions when creating the access key or modify an existing key to assign the required permissions.

The following is a list of permissions for access keys:

Permission Description
CREATE_TABLE Access to perform table creation
READ_ANY Access to perform table and items read operations on all DynamoDB compatible key tables associated with the Autonomous AI Database. It does not include backup, restore, import and export operations.
READ_WRITE_ANY Access to perform table and items read and write operations on all DynamoDB compatible tables associated with the Autonomous AI Database. It does not include backup, restore, import and export operations.
ADMIN_ANY Access to perform any operations including create table, backup, restore, import and export all DynamoDB compatible tables associated with the Autonomous AI Database.
READ <Table(s)> Access to perform table and items read operations on specific DynamoDB compatible table associated with the Autonomous AI Database. It does not include backup, restore, import and export operations.
READ_WRITE on <Table(s)> Access to perform table and items read and write operations on specific DynamoDB compatible table associated with the Autonomous AI Database. It does not include backup, restore, import and export operations.
ADMIN on <Table(s)> Access to perform any operations including backup, restore, import and export on specific DynamoDB compatible table associated with the Autonomous AI Database.
<operation name> on <Table(s)> For example, GetItem on <Table(s)> Access to perform specific operation on specific DynamoDB compatible table associated with Autonomous AI Database.

Create an access key

To create an Access Key and Secret Key in your database, you must be logged in as the ADMIN user or have been granted the PDB_DBA role.

Syntax and a sample request for creating an access key in your database:

Use the POST https://dataaccess.adb.{oci-region-name}.oraclecloudapps.com/adb/auth/v1/databases/{database-ocid}/accesskeys REST endpoint API request to generate the Access Key and Secret Key:

Syntax

POST "https://dataaccess.adb.{oci-region-name}.oraclecloudapps.com/adb/auth/v1/databases/{database-ocid}/accesskeys"
{
  "name"          : "{<access_key_name>}",         // Required. The name you assign to the access key.
  "description"   : "{<access_key_description>}",  // Optional. A description for the access key.
  "permissions"   : [                             // Optional. Array of permission objects.
    {
      "actions"   : [<List of permissions>],      // Required. List of permitted actions (e.g., "read", "write").
      "resources" : [<List of Tables>]            // Optional. Only applicable for permissions that get applied on Table.
    }
    // ... additional permission objects as needed
  ],
  "expiration_minutes": 120                       // Optional. The key's expiration time in minutes.
}

Path Parameters (provide proper authentication and replace placeholders with your actual OCI region and database OCID):

Sample response format

{
  "name": "<access_key_name>",
  "description": "<access_key_description>",
  "access_key_id": "<access_key_id>",
  "secret_access_key": "<generated secret>",
  "expiration_timestamp": "<access_key_expiration_timestamp>",
  "permissions": [
    {
      "actions"  : [<permissions list>],
      "resources": [<optional DynamoDb table list>]
    }
    // ...more permission objects
  ]
}

Example

This example demonstrates how to send a POST request to the Oracle Autonomous AI Database REST API to create a new access key with administrative permissions. The request specifies the key name and required permissions, and the response includes the newly generated access key ID, secret, expiration time, and permissions.

# Request
curl -X POST 'https://dataaccess.adb.us-phoenix-1.oraclecloudapps.com/adb/auth/v1/databases/OCID1.AUTONOMOUSDATABASE.OC1.PHX.ANYHQLJRGDV...EXAMPLE/accesskeys'\
--user "AdminUser:TestPass#" \
--header 'Request-Id: 8g89mz8qnet9ufxg4dwrus8m' \
--header 'Content-Type: application/json' \
--data-raw '{
    "name": "adminkey",
    "permissions": [
        {
            "actions": [
                "ADMIN_ANY"
            ]
        }
    ],
    "expiration_minutes": 120
}'

# Sample Response
{
    "access_key_id": "ak_og67ZI8bdS.....BiHCda7l",
    "secret_access_key": "NzYwZDE5M2E4NDVjZ.....FmMzBiNQ>>",
    "expiration_time": "2025-12-07T03:35:12Z",
    "permissions": [
        {
            "actions": [
                "ADMIN_ANY"
            ]
        }
    ]
}

Request Parameters:

Response Parameters:

Retrieve Access Key Information

After you created an access key, use the GET /accesskeys REST API request to look up its details, such as its name, associated permissions, expiration time, and other relevant metadata. This enables you to programmatically confirm access rights, audit credentials, or show access key information.

Syntax and example to retrieve access key details:

Syntax

GET https://dataaccess.adb.{oci-region-name}.oraclecloudapps.com/adb/auth/v1/databases/{database-ocid}/accesskeys/{access_key_id}
    Authorization: Basic <Base64-encoded
    database username and password>request-id: <optional request-id>

Example

The following call retrieves detailed information about the specified access key. This allows you to confirm the attributes and permissions associated with the access key:

# Request
curl -X GET 'https://dataaccess.adb.us-phoenix-1.oraclecloudapps.com/adb/auth/v1/databases/OCID1.AUTONOMOUSDATABASE.OC1.PHX.ANYHQLJRGDV...EXAMPLE/accesskeys/ak_og67ZI8bdS.....BiHCda7l' \
--user "AdminUser:TestPass#" \
--header 'Request-Id: xcz5efdb7rfrbsfkkwwl7d38' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json'

# Sample Response
{
    "access_key_id": "ak_og67ZI8bdS.....BiHCda7l",
    "expiration_timestamp": "2025-12-07T03:35:12.751Z",
    "permissions": [
        {
            "actions": [
                "ADMIN_ANY"
            ]
        }
    ]
}

Request Parameters

Update an access key

After you have created and retrieved your access key, you use the PUT /accesskeys REST API to update the attributes of an existing access key.

Syntax and example to update an access key:

Syntax

PUT https://dataaccess.adb.{oci-region-name}.oraclecloudapps.com/adb/auth/v1/databases/{database-ocid}/accesskeys/{access_key_id}
    Authorization: Basic <Base64-encoded database username and password>
    request-id: <optional request-id>
    Content-Type: application/json

{
  "permissions": [<permissions array>],
  "extend_expiration_minutes_by": <integer>
}

Example

The following request updates the access key to extend the expiration time by 120 minutes.

# Request
curl -X PUT 'https://dataaccess.adb.us-phoenix-1.oraclecloudapps.com/adb/auth/v1/databases/OCID1.AUTONOMOUSDATABASE.OC1.PHX.ANYHQLJRGDV...EXAMPLE/accesskeys/ak_og67ZI8bdS.....BiHCda7l' \
--user "AdminUser:TestPass#" \
--header 'Request-Id: xzpqvei6e7x52ri94odpv0a4' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data-raw '{
    "extend_expiration_minutes_by" : 120
}'

# Sample Response

{
    "access_key_id": "ak_og67ZI8bdS.....BiHCda7l",
    "expiration_timestamp": "2025-12-07T05:35:12.751Z",
    "permissions": [
        {
            "actions": [
                "ADMIN_ANY"
            ]
        }
    ],
    "message": "Expiration extended by 120 min"
}

Request parameters

Response parameters

Delete an access key

You can delete an existing access key when it is no longer required. You use the DELETE /accesskeys REST API to remove an access key from your database.

Syntax and example to remove an access key from your database:

Syntax

DELETE https://dataaccess.adb.{oci-region-name}.oraclecloudapps.com/adb/auth/v1/databases/{database-ocid}/accesskeys/{access_key_id}
    Authorization: Basic <Base64-encoded database username and password>
    request-id: <optional request-id>

Example

The following request removes the specified access key from your Autonomous AI Database. Once deleted, the key can no longer be used for authentication or database access. A successful deletion returns an HTTP status code of 204 No Content or 200 OK, with no response body.

# Request
curl -X DELETE 'https://dataaccess.adb.us-phoenix-1.oraclecloudapps.com/adb/auth/v1/databases/OCID1.AUTONOMOUSDATABASE.OC1.PHX.ANYHQLJRGDV...EXAMPLE/accesskeys/ak_og67ZI8bdS.....BiHCda7l' \
--user "AdminUser:TestPass#" \
--header 'Request-Id: xzpqvei6e7x52ri94odpv0a4' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
# Sample Response

{
    "message": "Access key deleted successfully.",
    "access_key_id": "ak_og67ZI8bdS.....BiHCda7l",
    "status": "DELETED"
}

Request parameters

Response parameters

Steps to Invoke DynamoDB-Compatible API

After enabling DynamoDB API and creating an access key, you can use the DynamoDB Client SDK to invoke Oracle AI Database API for DynamoDB.

Follow these steps to configure your DynamoDB client to invoke Autonomous AI Database API for DynamoDB.

Configure DynamoDbClient with Autonomous AI Database DynamoDB-Compatible Endpoint**

Code Elements

You can also configure or override the DynamoDB client endpoint using other programming languages and their respective AWS SDKs, such as Python (with Boto3), C++.

See the DynamoDB SDK references by language:

Invoke DynamoDB-Compatible API on your Autonomous AI Database

The following code demonstrates how to create a DynamoDB-compatible table movie and perform basic operations: describe, list, insert, update, and delete items using the Java AWS SDK v2 with a custom endpoint.

import software.amazon.awssdk.services.dynamodb.DynamoDbClient;
import software.amazon.awssdk.services.dynamodb.model.*;
import software.amazon.awssdk.regions.Region;
import software.amazon.awssdk.services.dynamodb.model.AttributeValue;
import java.net.URI;
import java.util.Map;

public class DynamoDBMovieExample {
    public static void main(String[] args) {
        // Set the region and endpoint
        //Region name is optional and will be overridden by the region value specified in the REST API endpoint.
        Region region = Region.US_WEST_1;
        String endpoint = "https://region.us-phoenix-1.adb.oraclecloud.com";

        // Build the DynamoDB client using a custom endpoint
        DynamoDbClient ddb = DynamoDbClient.builder()
            .region(region)
            .endpointOverride(URI.create(endpoint))
            .build();

        // Create table
        CreateTableRequest createTableRequest = CreateTableRequest.builder()
            .tableName("movie")
            .keySchema(
                KeySchemaElement.builder().attributeName("PK").keyType(KeyType.HASH).build(),
                KeySchemaElement.builder().attributeName("SK").keyType(KeyType.RANGE).build()
            )
            .attributeDefinitions(
                AttributeDefinition.builder().attributeName("PK").attributeType(ScalarAttributeType.S).build(),
                AttributeDefinition.builder().attributeName("SK").attributeType(ScalarAttributeType.S).build()
            )
            .provisionedThroughput(
                ProvisionedThroughput.builder().readCapacityUnits(5L).writeCapacityUnits(5L).build()
            )
            .build();
        ddb.createTable(createTableRequest);

        // Describe the table
        DescribeTableRequest descRequest = DescribeTableRequest.builder().tableName("movie").build();
        DescribeTableResponse descResponse = ddb.describeTable(descRequest);

        // List all tables
        ListTablesRequest listRequest = ListTablesRequest.builder().build();
        ListTablesResponse listResponse = ddb.listTables(listRequest);

        // Insert (PutItem)
        ddb.putItem(PutItemRequest.builder()
            .tableName("movie")
            .item(Map.of(
                "PK", AttributeValue.builder().s("001").build(),
                "SK", AttributeValue.builder().s("MOVIE").build(),
                "Title", AttributeValue.builder().s("Inception").build()))
            .build()
        );

        // Update (UpdateItem)
        ddb.updateItem(UpdateItemRequest.builder()
            .tableName("movie")
            .key(Map.of(
                "PK", AttributeValue.builder().s("001").build(),
                "SK", AttributeValue.builder().s("MOVIE").build()))
            .updateExpression("SET #T = :t")
            .expressionAttributeNames(Map.of("#T", "Title"))
            .expressionAttributeValues(Map.of(":t", AttributeValue.builder().s("Inception (2010)").build()))
            .build()
        );

        // Delete (DeleteItem)
        ddb.deleteItem(DeleteItemRequest.builder()
            .tableName("movie")
            .key(Map.of(
                "PK", AttributeValue.builder().s("001").build(),
                "SK", AttributeValue.builder().s("MOVIE").build()))
            .build()
        );
    }
}

Usage notes

Disable Autonomous AI Database API for DynamoDB on Autonomous AI Database

Shows the steps to disable the DynamoDB API for your Autonomous AI Database.

Perform the following prerequisite steps as necessary:

Follow these steps to disable DynamoDB APIs on an Autonomous AI Database instance:

  1. On the More actions drop-down list, select Manage tags.

    This shows the Add Tags page.

  2. Provide the following values to assign tags to Autonomous AI Database.

    • Namespace: To add a free-from tag, leave the value blank.

    • Key: adb$feature

    • Value: {"name":"DynamoDB_API","enable": false}

    Click Add to add the tag.

    After you click Add, the Lifecycle state field shows Updating and Autonomous AI Database generates an Update Autonomous AI Database Tags work request. To view the request, on the details page, select the Work requests tab.

Notes and Limitations for using Oracle AI Database API for DynamoDB on Autonomous AI Database

Lists notes and limitations for using Oracle AI Database API for DynamoDB on Autonomous AI Database.

Note the following when using Oracle AI Database API for DynamoDB on Autonomous AI Database:

Usage notes

Limitations

Import and Export Data into Autonomous AI Database DynamoDBTable

You can import data into an Autonomous AI Database DynamoDBTable from an existing Amazon DynamoDB table and export data from an Autonomous AI Database DynamoDBTable for use in other systems.

Required OCI policies for import and export

Before performing import or export operations, create a dynamic group and IAM policies that allow the Autonomous AI Database Key Value Store service to access the OCI Object Storage bucket used for data transfer.

Create a Dynamic Group

Create a dynamic group that specifies the resource ID of the Key Value Store leader database:

resource.id = '<leader-pdb-ocid>'

Create IAM Policies

Create policies that allow the dynamic group to access the OCI Object Storage bucket used for import and export operations:

allow dynamic-group <dynamic-group> to use buckets in compartment <bucket-compartment> where target.resource.id = <bucket-ocid>

allow dynamic-group <dynamic-group> to use objects in compartment <bucket-compartment> where target.resource.id = <bucket-ocid>

See Use Resource Principal to Access Oracle Cloud Infrastructure Resources for more information.

Import

The ImportTable operation helps existing Amazon DynamoDB customers migrate data from an Amazon DynamoDB table into an Autonomous AI Database DynamoDBTable.

The import process consists of the following steps:

  1. Export data from the existing Amazon DynamoDB table to an Amazon S3 bucket. See DynamoDB data export to Amazon S3 for more information.

  2. Copy the exported data from the Amazon S3 bucket to an OCI Object Storage bucket.

  3. Import the data from the OCI Object Storage bucket into an Autonomous AI Database DynamoDBTable by using the ImportTable API.

    Example ImportTable Request

    {
  "TableCreationParameters": {
    "TableName": "importExampleTable",
    "AttributeDefinitions": [
      {
        "AttributeName": "p",
        "AttributeType": "S"
      }
    ],
    "KeySchema": [
      {
        "AttributeName": "p",
        "KeyType": "HASH"
      }
    ],
    "ProvisionedThroughput": {
      "ReadCapacityUnits": 200,
      "WriteCapacityUnits": 200
    }
  },
  "S3BucketSource": {
    "S3Bucket": "<object-storage-private-bucket-url>"
  },
  "InputFormat": "JSON"
}

The following input formats are supported:

Export

The ExportTable operation enables you to export data from an Autonomous AI Database DynamoDBTable for use in other systems.

Exported data is written to an OCI Object Storage bucket that you specify in the request.

{
  "ClientToken"  : "anewone5",
  "ExportFormat" : "JSON",
  "TableArn"     : "<table-arn>",
  "S3Bucket"     : "<object-storage-private-bucket-url>"
}

The following formats are supported: