Actions

The AWS SimpleDB connector exposes the following clients:

Available clients:

Client	Purpose
Client	Manage SimpleDB domains and perform item attribute reads, writes, queries, and deletes

---

Client

Provides access to all Amazon SimpleDB domain management and item attribute operations through a single authenticated client.

Configuration

ConnectionConfig

Field	Type	Default	Description
auth	auth:AuthConfig	Required	Authentication configuration: static credentials, AWS profile, STS assume-role, web identity (OIDC), IAM Identity Center (SSO), external credential process, or the default provider chain
region	aws:Region|string	Required	AWS region: an aws:Region enum member or a plain region string (e.g., "us-east-1") for regions not yet in the enum
endpoint	aws:EndpointConfig	Optional	Optional endpoint options: FIPS/dualstack variants, or a custom endpoint override (e.g. VPC interface endpoints)

The client also accepts the standard Ballerina HTTP client options (timeout, retryConfig, secureSocket, proxy, and the rest of http:ClientConfiguration), which are omitted here.

Initializing the client

import ballerinax/aws;
import ballerinax/aws.simpledb;

simpledb:ConnectionConfig config = {
    auth: {
        accessKeyId: "<AWS_ACCESS_KEY_ID>",
        secretAccessKey: "<AWS_SECRET_ACCESS_KEY>"
    },
    region: aws:US_EAST_1
};
simpledb:Client simpleDb = check new (config);

Operations

Domain management

createDomain

Create a domain.

Parameters:

Name	Type	Required	Description
domainName	string	Yes	Name of domain

Returns: CreateDomainResponse|xml|error

Sample code:

simpledb:CreateDomainResponse|xml result = check simpleDb->createDomain("inventory");

Sample response:

{
  "responseMetadata": {
    "requestId": "b1e3e6fb-7c79-4d64-9b81-b54d7b023e40",
    "boxUsage": "0.0055590278"
  }
}

listDomains

List available domains.

Parameters:

Name	Type	Required	Description

This operation takes no parameters.

Returns: ListDomainsResponse|xml|error

Sample code:

simpledb:ListDomainsResponse|xml result = check simpleDb->listDomains();

Sample response:

{
  "listDomainsResult": {
    "domainNames": "inventory products orders",
    "nextToken": ""
  },
  "responseMetadata": {
    "requestId": "d3e5b9c0-1f2a-4b6c-8d7e-b9c0d1e2f3a4",
    "boxUsage": "0.0000219907"
  }
}

getDomainMetaData

Get information about the domain, including when the domain was created, the number of items and attributes, and the size of attribute names and values.

Parameters:

Name	Type	Required	Description
domainName	string	Yes	Name of domain

Returns: DomainMetaDataResponse|xml|error

Sample code:

simpledb:DomainMetaDataResponse|xml result = check simpleDb->getDomainMetaData("inventory");

Sample response:

{
  "domainMetadataResult": {
    "itemCount": "4",
    "itemNamesSizeBytes": "48",
    "attributeNameCount": "3",
    "attributeNamesSizeBytes": "36",
    "attributeValueCount": "12",
    "attributeValuesSizeBytes": "120",
    "timestamp": "1735689600"
  },
  "responseMetadata": {
    "requestId": "c2f4a7b8-0e1d-4c5a-9f2e-a8b3c4d5e6f7",
    "boxUsage": "0.0000219907"
  }
}

deleteDomain

Delete a domain.

Parameters:

Name	Type	Required	Description
domainName	string	Yes	Name of domain

Returns: DeleteDomainResponse|xml|error

Sample code:

simpledb:DeleteDomainResponse|xml result = check simpleDb->deleteDomain("inventory");

Sample response:

{
  "responseMetadata": {
    "requestId": "e4f6c0d1-2a3b-4c7d-9e8f-c0d1e2f3a4b5",
    "boxUsage": "0.0055590278"
  }
}

Item operations

putAttributes

Creates an attribute in an item. The value is added to the attribute rather than replacing any value it already has.

Parameters:

Name	Type	Required	Description
domainName	string	Yes	Name of domain
itemName	string	Yes	Name of item
attributes	Attribute[]	Yes	Attributes to create; each Attribute has a name (string) and a value (string)

Returns: PutAttributesResponse|xml|error

Sample code:

simpledb:PutAttributesResponse|xml result = check simpleDb->putAttributes(
    "inventory",
    "sku-1024",
    [{name: "colour", value: "blue"}]
);

Sample response:

{
  "responseMetadata": {
    "requestId": "a6b8e2f3-4c5d-4e9f-1a0b-e2f3a4b5c6d7",
    "boxUsage": "0.0000219907"
  }
}

getAttributes

Get all of the attributes associated with the item.

Parameters:

Name	Type	Required	Description
domainName	string	Yes	Name of domain
itemName	string	Yes	Name of item
consistentRead	boolean	Yes	True if consistent reads are to be accepted

Returns: GetAttributesResponse|xml|error

Sample code:

simpledb:GetAttributesResponse|xml result = check simpleDb->getAttributes("inventory", "sku-1024", true);

Sample response:

{
  "getAttributesResult": {
    "attributes": "colour=blue size=medium"
  },
  "responseMetadata": {
    "requestId": "f5a7d1e2-3b4c-4d8e-0f9a-d1e2f3a4b5c6",
    "boxUsage": "0.0000219907"
  }
}

deleteAttributes

Delete attributes in an item. When attributes is empty, the whole item is deleted.

Parameters:

Name	Type	Required	Description
domainName	string	Yes	Name of domain
itemName	string	Yes	Name of item
attributes	Attribute[]	Yes	Attributes to delete; pass an empty array to delete the entire item. Each Attribute has a name (string) and a value (string)

Returns: DeleteAttributesResponse|xml|error

Sample code:

simpledb:DeleteAttributesResponse|xml result = check simpleDb->deleteAttributes(
    "inventory",
    "sku-1024",
    [{name: "colour", value: "blue"}]
);

Sample response:

{
  "responseMetadata": {
    "requestId": "b7c9f3a4-5d6e-4f0a-2b1c-f3a4b5c6d7e8",
    "boxUsage": "0.0000219907"
  }
}

select

Select set of attributes that match the select expression.

Parameters:

Name	Type	Required	Description
selectExpression	string	Yes	SQL-like select expression to retrieve attributes (e.g., select * from \domainName` where colour = 'blue'`)
consistentRead	boolean	Yes	True if consistent reads are to be accepted

Returns: SelectResponse|xml|error

Sample code:

string selectExpression = "select * from `inventory` where colour = 'blue'";
simpledb:SelectResponse|xml result = check simpleDb->'select(selectExpression, true);

Sample response:

{
  "selectResult": {
    "items": "sku-1024"
  },
  "responseMetadata": {
    "requestId": "c8d0a4b5-6e7f-4a1b-3c2d-a4b5c6d7e8f9",
    "boxUsage": "0.0000219907"
  }
}