Use Autonomous AI 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 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.

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 API for DynamoDB on Autonomous AI Database

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

Perform the following prerequisite steps as necessary:

Follow these steps to enable the API for DynamoDB 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 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 API for DynamoDB, 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 API for DynamoDB 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 Autonomous AI Database API for DynamoDB

This section provides the steps to create and manage access keys required to authenticate and use the API for DynamoDB 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 to use the API 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.

Note: Access key information is stored in the Oracle-managed DATA_ACCESS_COMMON schema in your database. You cannot access this schema.

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 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 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 ctables associated with the Autonomous AI Database.
READ <Table(s)> Access to perform table and items read operations on specific DynamoDB table(s) 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 table(s) 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 table(s) 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 table(s) associated with Autonomous AI Database.

Create an access key

To create an Access Key and Secret Key in your Autonomous AI 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 the API for DynamoDB

After enabling the API for DynamoDB 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 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:

Use the API for DynamoDB on your Autonomous AI Database

The following code demonstrates how to create a DynamoDB 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

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 API for DynamoDB 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

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

Transaction Compatibility with Amazon DynamoDB

Amazon DynamoDB and Autonomous AI Database API for DynamoDB both support atomic transactions. However, they use different methods to manage concurrent operations on the same items. Review these differences when migrating an application that uses transaction conflicts or related exceptions to coordinate concurrent work.

Amazon DynamoDB Transaction Behavior

The TransactWriteItems and TransactGetItems operations group up to 100 items, with an aggregate size of up to 4 MB, into a single all-or-nothing operation. Amazon DynamoDB uses a two-phase, server-side protocol to process each transaction. The transaction succeeds only if both phases succeed, and the client application does not control either phase.

Amazon DynamoDB uses optimistic concurrency control. It does not hold locks for the duration of a transaction. Instead, it detects conflicting concurrent operations and cancels an affected request rather than waiting for the other operation to complete.

The following points describe how Amazon DynamoDB handles concurrent transactions:

Condition expressions, all-or-nothing atomicity, cancellation reasons, and optional idempotency through ClientRequestToken remain part of the DynamoDB API contract. However, concurrency-related cancellations differ between Amazon DynamoDB and Autonomous AI Database API for DynamoDB.

Autonomous AI Database API for DynamoDB Transaction Behavior

Autonomous AI Database API for DynamoDB runs transaction operations using the Oracle AI Database default READ COMMITTED isolation level. This preserves transaction atomicity and prevents dirty reads.

The main difference is the concurrency model. Oracle AI Database uses row-level locks and pessimistic concurrency control. When concurrent operations modify the same items, a later operation generally waits for the earlier operation to complete and then proceeds. The operation is not normally canceled because of the conflict.

As a result, concurrent operations on the same items are more likely to complete instead of being rejected. However, an operation can wait for a lock. In the uncommon case of a cyclic lock dependency, Oracle AI Database detects a deadlock, selects one transaction as the victim, and rolls it back.

READ COMMITTED is the compatibility default because an Amazon DynamoDB application cannot rely on which of two concurrent transactions commits first or on a particular conflict result. Amazon DynamoDB determines transaction ordering internally. An application that does not depend on that ordering remains compatible when concurrent operations serialize and complete in Autonomous AI Database.

Transaction Behavior Comparison

Concurrent operations on the same items Amazon DynamoDB Autonomous AI Database API for DynamoDB Migration consideration
TransactWriteItems and another conflicting TransactWriteItems Optimistic conflict detection cancels the affected transaction with TransactionCanceledException. One or both transactions can be canceled, and the client must retry the request. Row-level locks serialize the transactions. Both transactions generally complete in commit order. A cyclic dependency can cause a deadlock, in which case one transaction is rolled back. Do not rely on a transaction conflict to reject or coordinate work.
TransactWriteItems and PutItem, UpdateItem, or DeleteItem The standard write is rejected with TransactionConflictException. The transaction continues. The standard write waits for the row lock and generally completes after the transaction. It is not rejected as a transaction conflict. Review application logic that treats a rejected standard write as a signal that another transaction is in progress.
TransactGetItems and an in-progress TransactWriteItems The read transaction can be canceled with TransactionCanceledException. A single GetItem request is not canceled; both operations can succeed. The read generally completes using read-committed isolation instead of failing because of an isolation conflict. Review readers that interpret cancellation as an indication that data is locked.
Multi-item nontransactional read during an in-progress transaction Query, Scan, BatchGetItem, or multiple GetItem requests use read-committed isolation. The result can contain a combination of item states from before and after the transaction. Use TransactGetItems when an atomic view is required. Reads use READ COMMITTED isolation and do not return uncommitted data. Oracle AI Database also provides a consistent view for each statement as of the time the statement begins. Both implementations prevent dirty reads. Use TransactGetItems when the application requires an atomic multi-item view.
TransactWriteItems and BatchWriteItem A batch is not a single serializable operation. Its individual writes are serializable with the transaction and can partially succeed. The individual batch writes serialize on row locks and generally complete. Validate the final state and ensure that the application handles partial batch failures.
Condition expressions and all-or-nothing atomicity Conditions are enforced. A failed condition is reported in the transaction cancellation reasons. Conditions are enforced and remain part of the API contract. Continue to test condition expressions, cancellation reasons, and protection against partial results.

For both implementations, the effective order is the order in which the database executes the operations, which might differ from the order in which the API receives the requests. Applications should not assume which concurrent request wins or determines the committed result.

Review Transaction Behavior Before Migration

Before migrating an application, review any logic that uses Amazon DynamoDB conflict responses to coordinate work. This includes optimistic locking, job claiming, inventory reservation, uniqueness enforcement, and retry decisions based on TransactionConflictException or TransactionCanceledException.

With Autonomous AI Database API for DynamoDB, concurrent operations on the same items generally wait and then complete instead of being rejected. Test the following concurrent operations:

Verify that the application:

Import and Export Data into Autonomous AI Database DynamoDB Tables

You can import data into an Autonomous AI Database DynamoDB table from an existing Amazon DynamoDB table and export data from an Autonomous AI Database DynamoDB table 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 API for DynamoDB 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 managing Autonomous AI Database:

resource.id = '<database-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 DynamoDB tables

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

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 DynamoDB tables

The ExportTable operation enables you to export data from an Autonomous AI Database DynamoDB table 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: