com.amazonaws.services.dynamodbv2.AmazonDynamoDB Maven / Gradle / Ivy
/*
* Copyright 2010-2016 Amazon.com, Inc. or its affiliates. All Rights Reserved.
*
* Licensed under the Apache License, Version 2.0 (the "License").
* You may not use this file except in compliance with the License.
* A copy of the License is located at
*
* http://aws.amazon.com/apache2.0
*
* or in the "license" file accompanying this file. This file is distributed
* on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either
* express or implied. See the License for the specific language governing
* permissions and limitations under the License.
*/
package com.amazonaws.services.dynamodbv2;
import com.amazonaws.*;
import com.amazonaws.regions.*;
import com.amazonaws.services.dynamodbv2.model.*;
/**
* Interface for accessing AmazonDynamoDBv2.
* Amazon DynamoDB
* This is the Amazon DynamoDB API Reference. This guide provides
* descriptions of the low-level DynamoDB API.
*
*
* This guide is intended for use with the following DynamoDB
* documentation:
*
*
*
* -
*
* Amazon DynamoDB Getting Started Guide
* - provides hands-on exercises that help you learn the basics of
* working with DynamoDB. If you are new to DynamoDB, we recommend
* that you begin with the Getting Started Guide.
*
*
* -
*
* Amazon DynamoDB Developer Guide
* - contains detailed information about DynamoDB concepts, usage, and
* best practices.
*
*
* -
*
* Amazon DynamoDB Streams API Reference - provides descriptions and samples of the DynamoDB Streams API. (For more information, see Capturing Table Activity with DynamoDB Streams
* in the Amazon DynamoDB Developer Guide.)
*
*
*
*
*
* Instead of making the requests to the low-level DynamoDB API directly
* from your application, we recommend that you use the AWS Software
* Development Kits (SDKs). The easy-to-use libraries in the AWS SDKs
* make it unnecessary to call the low-level DynamoDB API directly from
* your application. The libraries take care of request authentication,
* serialization, and connection management. For more information, see
* Using the AWS SDKs with DynamoDB
* in the Amazon DynamoDB Developer Guide.
*
*
* If you decide to code against the low-level DynamoDB API directly, you
* will need to write the necessary code to authenticate your requests.
* For more information on signing your requests, see
* Using the DynamoDB API
* in the Amazon DynamoDB Developer Guide .
*
*
* The following are short descriptions of each low-level API action,
* organized by function.
*
*
* Managing Tables
*
*
*
* -
* CreateTable - Creates a table with user-specified provisioned
* throughput settings. You must define a primary key for the table -
* either a simple primary key (partition key), or a composite primary
* key (partition key and sort key). Optionally, you can create one or
* more secondary indexes, which provide fast data access using non-key
* attributes.
*
*
* -
* DescribeTable - Returns metadata for a table, such as table
* size, status, and index information.
*
*
* -
* UpdateTable - Modifies the provisioned throughput settings for
* a table. Optionally, you can modify the provisioned throughput
* settings for global secondary indexes on the table.
*
*
* -
* ListTables - Returns a list of all tables associated with the
* current AWS account and endpoint.
*
*
* -
* DeleteTable - Deletes a table and all of its indexes.
*
*
*
*
*
* For conceptual information about managing tables, see
* Working with Tables
* in the Amazon DynamoDB Developer Guide .
*
*
* Reading Data
*
*
*
* -
* GetItem - Returns a set of attributes for the item that has a
* given primary key. By default, GetItem performs an eventually
* consistent read; however, applications can request a strongly
* consistent read instead.
*
*
* -
* BatchGetItem - Performs multiple GetItem requests for
* data items using their primary keys, from one table or multiple
* tables. The response from BatchGetItem has a size limit of 16
* MB and returns a maximum of 100 items. Both eventually consistent and
* strongly consistent reads can be used.
*
*
* -
* Query - Returns one or more items from a table or a secondary
* index. You must provide a specific value for the partition key. You
* can narrow the scope of the query using comparison operators against a
* sort key value, or on the index key. Query supports either
* eventual or strong consistency. A single response has a size limit of
* 1 MB.
*
*
* -
* Scan - Reads every item in a table; the result set is
* eventually consistent. You can limit the number of items returned by
* filtering the data attributes, using conditional expressions.
* Scan can be used to enable ad-hoc querying of a table against
* non-key attributes; however, since this is a full table scan without
* using an index, Scan should not be used for any application
* query use case that requires predictable performance.
*
*
*
*
*
* For conceptual information about reading data, see
* Working with Items and Query and Scan Operations
* in the Amazon DynamoDB Developer Guide .
*
*
* Modifying Data
*
*
*
* -
* PutItem - Creates a new item, or replaces an existing item
* with a new item (including all the attributes). By default, if an item
* in the table already exists with the same primary key, the new item
* completely replaces the existing item. You can use conditional
* operators to replace an item only if its attribute values match
* certain conditions, or to insert a new item only if that item doesn't
* already exist.
*
*
* -
* UpdateItem - Modifies the attributes of an existing item. You
* can also use conditional operators to perform an update only if the
* item's attribute values match certain conditions.
*
*
* -
* DeleteItem - Deletes an item in a table by primary key. You
* can use conditional operators to perform a delete an item only if the
* item's attribute values match certain conditions.
*
*
* -
* BatchWriteItem - Performs multiple PutItem and
* DeleteItem requests across multiple tables in a single request.
* A failure of any request(s) in the batch will not cause the entire
* BatchWriteItem operation to fail. Supports batches of up to 25
* items to put or delete, with a maximum total request size of 16 MB.
*
*
*
*
*
* For conceptual information about modifying data, see
* Working with Items and Query and Scan Operations
* in the Amazon DynamoDB Developer Guide .
*
*/
public interface AmazonDynamoDB {
/**
* Overrides the default endpoint for this client ("http://dynamodb.us-east-1.amazonaws.com/").
* Callers can use this method to control which AWS region they want to work with.
*
* Callers can pass in just the endpoint (ex: "dynamodb.us-east-1.amazonaws.com/") or a full
* URL, including the protocol (ex: "http://dynamodb.us-east-1.amazonaws.com/"). If the
* protocol is not specified here, the default protocol from this client's
* {@link ClientConfiguration} will be used, which by default is HTTPS.
*
* For more information on using AWS regions with the AWS SDK for Java, and
* a complete list of all available endpoints for all AWS services, see:
*
* http://developer.amazonwebservices.com/connect/entry.jspa?externalID=3912
*
* This method is not threadsafe. An endpoint should be configured when the
* client is created and before any service requests are made. Changing it
* afterwards creates inevitable race conditions for any service requests in
* transit or retrying.
*
* @param endpoint
* The endpoint (ex: "dynamodb.us-east-1.amazonaws.com/") or a full URL,
* including the protocol (ex: "http://dynamodb.us-east-1.amazonaws.com/") of
* the region specific AWS endpoint this client will communicate
* with.
*
* @throws IllegalArgumentException
* If any problems are detected with the specified endpoint.
*/
public void setEndpoint(String endpoint) throws java.lang.IllegalArgumentException;
/**
* An alternative to {@link AmazonDynamoDB#setEndpoint(String)}, sets the
* regional endpoint for this client's service calls. Callers can use this
* method to control which AWS region they want to work with.
*
* By default, all service endpoints in all regions use the https protocol.
* To use http instead, specify it in the {@link ClientConfiguration}
* supplied at construction.
*
* This method is not threadsafe. A region should be configured when the
* client is created and before any service requests are made. Changing it
* afterwards creates inevitable race conditions for any service requests in
* transit or retrying.
*
* @param region
* The region this client will communicate with. See
* {@link Region#getRegion(com.amazonaws.regions.Regions)} for
* accessing a given region.
* @throws java.lang.IllegalArgumentException
* If the given region is null, or if this service isn't
* available in the given region. See
* {@link Region#isServiceSupported(String)}
* @see Region#getRegion(com.amazonaws.regions.Regions)
* @see Region#createClient(Class, com.amazonaws.auth.AWSCredentialsProvider, ClientConfiguration)
*/
public void setRegion(Region region) throws java.lang.IllegalArgumentException;
/**
*
* The CreateTable operation adds a new table to your account. In
* an AWS account, table names must be unique within each region. That
* is, you can have two tables with same name if you create the tables in
* different regions.
*
*
* CreateTable is an asynchronous operation. Upon receiving a
* CreateTable request, DynamoDB immediately returns a response
* with a TableStatus of CREATING . After the table
* is created, DynamoDB sets the TableStatus to
* ACTIVE . You can perform read and write operations only
* on an ACTIVE table.
*
*
* You can optionally define secondary indexes on the new table, as part
* of the CreateTable operation. If you want to create multiple
* tables with secondary indexes on them, you must create the tables
* sequentially. Only one table with secondary indexes can be in the
* CREATING state at any given time.
*
*
* You can use the DescribeTable API to check the table status.
*
*
* @param createTableRequest Container for the necessary parameters to
* execute the CreateTable service method on AmazonDynamoDBv2.
*
* @return The response from the CreateTable service method, as returned
* by AmazonDynamoDBv2.
*
* @throws LimitExceededException
* @throws ResourceInUseException
* @throws InternalServerErrorException
*
* @throws AmazonClientException
* If any internal errors are encountered inside the client while
* attempting to make the request or handle the response. For example
* if a network connection is not available.
* @throws AmazonServiceException
* If an error response is returned by AmazonDynamoDBv2 indicating
* either a problem with the data in the request, or a server side issue.
*/
public CreateTableResult createTable(CreateTableRequest createTableRequest)
throws AmazonServiceException, AmazonClientException;
/**
*
* The Scan operation returns one or more items and item
* attributes by accessing every item in a table or a secondary index. To
* have DynamoDB return fewer items, you can provide a ScanFilter
* operation.
*
*
* If the total number of scanned items exceeds the maximum data set
* size limit of 1 MB, the scan stops and results are returned to the
* user as a LastEvaluatedKey value to continue the scan in a
* subsequent operation. The results also include the number of items
* exceeding the limit. A scan can result in no table data meeting the
* filter criteria.
*
*
* By default, Scan operations proceed sequentially; however, for
* faster performance on a large table or secondary index, applications
* can request a parallel Scan operation by providing the
* Segment and TotalSegments parameters. For more
* information, see
* Parallel Scan
* in the Amazon DynamoDB Developer Guide .
*
*
* By default, Scan uses eventually consistent reads when
* accessing the data in a table; therefore, the result set might not
* include the changes to data in the table immediately before the
* operation began. If you need a consistent copy of the data, as of the
* time that the Scan begins, you can set the ConsistentRead
* parameter to true .
*
*
* @param scanRequest Container for the necessary parameters to execute
* the Scan service method on AmazonDynamoDBv2.
*
* @return The response from the Scan service method, as returned by
* AmazonDynamoDBv2.
*
* @throws InternalServerErrorException
* @throws ProvisionedThroughputExceededException
* @throws ResourceNotFoundException
*
* @throws AmazonClientException
* If any internal errors are encountered inside the client while
* attempting to make the request or handle the response. For example
* if a network connection is not available.
* @throws AmazonServiceException
* If an error response is returned by AmazonDynamoDBv2 indicating
* either a problem with the data in the request, or a server side issue.
*/
public ScanResult scan(ScanRequest scanRequest)
throws AmazonServiceException, AmazonClientException;
/**
*
* Returns the current provisioned-capacity limits for your AWS account
* in a region, both for the region as a whole and for any one DynamoDB
* table that you create there.
*
*
* When you establish an AWS account, the account has initial limits on
* the maximum read capacity units and write capacity units that you can
* provision across all of your DynamoDB tables in a given region. Also,
* there are per-table limits that apply when you create a table there.
* For more information, see
* Limits
* page in the Amazon DynamoDB Developer Guide .
*
*
* Although you can increase these limits by filing a case at
* AWS Support Center
* , obtaining the increase is not instantaneous. The
* DescribeLimits API lets you write code to compare the capacity
* you are currently using to those limits imposed by your account so
* that you have enough time to apply for an increase before you hit a
* limit.
*
*
* For example, you could use one of the AWS SDKs to do the following:
*
* - Call DescribeLimits for a particular region to obtain
* your current account limits on provisioned capacity there.
* - Create a variable to hold the aggregate read capacity units
* provisioned for all your tables in that region, and one to hold the
* aggregate write capacity units. Zero them both.
* - Call ListTables to obtain a list of all your DynamoDB
* tables.
* -
* For each table name listed by ListTables , do the following:
*
*
*
* - Call DescribeTable with the table name.
* - Use the data returned by DescribeTable to add the read
* capacity units and write capacity units provisioned for the table
* itself to your variables.
* - If the table has one or more global secondary indexes (GSIs),
* loop over these GSIs and add their provisioned capacity values to your
* variables as well.
*
*
*
* - Report the account limits for that region returned by
* DescribeLimits , along with the total current provisioned
* capacity levels you have calculated.
*
* This will let you see whether you are getting close to your
* account-level limits.
*
*
* The per-table limits apply only when you are creating a new table.
* They restrict the sum of the provisioned capacity of the new table
* itself and all its global secondary indexes.
*
*
* For existing tables and their GSIs, DynamoDB will not let you
* increase provisioned capacity extremely rapidly, but the only upper
* limit that applies is that the aggregate provisioned capacity over all
* your tables and GSIs cannot exceed either of the per-account limits.
*
*
* NOTE: DescribeLimits should only be called periodically. You
* can expect throttling errors if you call it more than once in a
* minute.
*
*
* The DescribeLimits Request element has no content.
*
*
* @param describeLimitsRequest Container for the necessary parameters to
* execute the DescribeLimits service method on AmazonDynamoDBv2.
*
* @return The response from the DescribeLimits service method, as
* returned by AmazonDynamoDBv2.
*
* @throws InternalServerErrorException
*
* @throws AmazonClientException
* If any internal errors are encountered inside the client while
* attempting to make the request or handle the response. For example
* if a network connection is not available.
* @throws AmazonServiceException
* If an error response is returned by AmazonDynamoDBv2 indicating
* either a problem with the data in the request, or a server side issue.
*/
public DescribeLimitsResult describeLimits(DescribeLimitsRequest describeLimitsRequest)
throws AmazonServiceException, AmazonClientException;
/**
*
* The BatchGetItem operation returns the attributes of one or
* more items from one or more tables. You identify requested items by
* primary key.
*
*
* A single operation can retrieve up to 16 MB of data, which can
* contain as many as 100 items. BatchGetItem will return a
* partial result if the response size limit is exceeded, the table's
* provisioned throughput is exceeded, or an internal processing failure
* occurs. If a partial result is returned, the operation returns a value
* for UnprocessedKeys . You can use this value to retry the
* operation starting with the next item to get.
*
*
* IMPORTANT: If you request more than 100 items BatchGetItem
* will return a ValidationException with the message "Too many items
* requested for the BatchGetItem call".
*
*
* For example, if you ask to retrieve 100 items, but each individual
* item is 300 KB in size, the system returns 52 items (so as not to
* exceed the 16 MB limit). It also returns an appropriate
* UnprocessedKeys value so you can get the next page of results.
* If desired, your application can include its own logic to assemble the
* pages of results into one data set.
*
*
* If none of the items can be processed due to insufficient
* provisioned throughput on all of the tables in the request, then
* BatchGetItem will return a
* ProvisionedThroughputExceededException . If at least one
* of the items is successfully processed, then BatchGetItem
* completes successfully, while returning the keys of the unread items
* in UnprocessedKeys .
*
*
* IMPORTANT: If DynamoDB returns any unprocessed items, you
* should retry the batch operation on those items. However, we strongly
* recommend that you use an exponential backoff algorithm. If you retry
* the batch operation immediately, the underlying read or write requests
* can still fail due to throttling on the individual tables. If you
* delay the batch operation using exponential backoff, the individual
* requests in the batch are much more likely to succeed. For more
* information, see Batch Operations and Error Handling in the Amazon
* DynamoDB Developer Guide.
*
*
* By default, BatchGetItem performs eventually consistent reads
* on every table in the request. If you want strongly consistent reads
* instead, you can set ConsistentRead to true for
* any or all tables.
*
*
* In order to minimize response latency, BatchGetItem retrieves
* items in parallel.
*
*
* When designing your application, keep in mind that DynamoDB does not
* return attributes in any particular order. To help parse the response
* by item, include the primary key values for the items in your request
* in the AttributesToGet parameter.
*
*
* If a requested item does not exist, it is not returned in the result.
* Requests for nonexistent items consume the minimum read capacity units
* according to the type of read. For more information, see
* Capacity Units Calculations
* in the Amazon DynamoDB Developer Guide .
*
*
* @param batchGetItemRequest Container for the necessary parameters to
* execute the BatchGetItem service method on AmazonDynamoDBv2.
*
* @return The response from the BatchGetItem service method, as returned
* by AmazonDynamoDBv2.
*
* @throws InternalServerErrorException
* @throws ProvisionedThroughputExceededException
* @throws ResourceNotFoundException
*
* @throws AmazonClientException
* If any internal errors are encountered inside the client while
* attempting to make the request or handle the response. For example
* if a network connection is not available.
* @throws AmazonServiceException
* If an error response is returned by AmazonDynamoDBv2 indicating
* either a problem with the data in the request, or a server side issue.
*/
public BatchGetItemResult batchGetItem(BatchGetItemRequest batchGetItemRequest)
throws AmazonServiceException, AmazonClientException;
/**
*
* The GetItem operation returns a set of attributes for the item
* with the given primary key. If there is no matching item,
* GetItem does not return any data.
*
*
* GetItem provides an eventually consistent read by default. If
* your application requires a strongly consistent read, set
* ConsistentRead to true . Although a strongly
* consistent read might take more time than an eventually consistent
* read, it always returns the last updated value.
*
*
* @param getItemRequest Container for the necessary parameters to
* execute the GetItem service method on AmazonDynamoDBv2.
*
* @return The response from the GetItem service method, as returned by
* AmazonDynamoDBv2.
*
* @throws InternalServerErrorException
* @throws ProvisionedThroughputExceededException
* @throws ResourceNotFoundException
*
* @throws AmazonClientException
* If any internal errors are encountered inside the client while
* attempting to make the request or handle the response. For example
* if a network connection is not available.
* @throws AmazonServiceException
* If an error response is returned by AmazonDynamoDBv2 indicating
* either a problem with the data in the request, or a server side issue.
*/
public GetItemResult getItem(GetItemRequest getItemRequest)
throws AmazonServiceException, AmazonClientException;
/**
*
* Returns an array of table names associated with the current account
* and endpoint. The output from ListTables is paginated, with
* each page returning a maximum of 100 table names.
*
*
* @param listTablesRequest Container for the necessary parameters to
* execute the ListTables service method on AmazonDynamoDBv2.
*
* @return The response from the ListTables service method, as returned
* by AmazonDynamoDBv2.
*
* @throws InternalServerErrorException
*
* @throws AmazonClientException
* If any internal errors are encountered inside the client while
* attempting to make the request or handle the response. For example
* if a network connection is not available.
* @throws AmazonServiceException
* If an error response is returned by AmazonDynamoDBv2 indicating
* either a problem with the data in the request, or a server side issue.
*/
public ListTablesResult listTables(ListTablesRequest listTablesRequest)
throws AmazonServiceException, AmazonClientException;
/**
*
* The BatchWriteItem operation puts or deletes multiple items in
* one or more tables. A single call to BatchWriteItem can write
* up to 16 MB of data, which can comprise as many as 25 put or delete
* requests. Individual items to be written can be as large as 400 KB.
*
*
* NOTE: BatchWriteItem cannot update items. To update items, use
* the UpdateItem API.
*
*
* The individual PutItem and DeleteItem operations
* specified in BatchWriteItem are atomic; however
* BatchWriteItem as a whole is not. If any requested operations
* fail because the table's provisioned throughput is exceeded or an
* internal processing failure occurs, the failed operations are returned
* in the UnprocessedItems response parameter. You can investigate
* and optionally resend the requests. Typically, you would call
* BatchWriteItem in a loop. Each iteration would check for
* unprocessed items and submit a new BatchWriteItem request with
* those unprocessed items until all items have been processed.
*
*
* Note that if none of the items can be processed due to
* insufficient provisioned throughput on all of the tables in the
* request, then BatchWriteItem will return a
* ProvisionedThroughputExceededException .
*
*
* IMPORTANT: If DynamoDB returns any unprocessed items, you
* should retry the batch operation on those items. However, we strongly
* recommend that you use an exponential backoff algorithm. If you retry
* the batch operation immediately, the underlying read or write requests
* can still fail due to throttling on the individual tables. If you
* delay the batch operation using exponential backoff, the individual
* requests in the batch are much more likely to succeed. For more
* information, see Batch Operations and Error Handling in the Amazon
* DynamoDB Developer Guide.
*
*
* With BatchWriteItem , you can efficiently write or delete
* large amounts of data, such as from Amazon Elastic MapReduce (EMR), or
* copy data from another database into DynamoDB. In order to improve
* performance with these large-scale operations, BatchWriteItem
* does not behave in the same way as individual PutItem and
* DeleteItem calls would. For example, you cannot specify
* conditions on individual put and delete requests, and
* BatchWriteItem does not return deleted items in the response.
*
*
* If you use a programming language that supports concurrency, you can
* use threads to write items in parallel. Your application must include
* the necessary logic to manage the threads. With languages that don't
* support threading, you must update or delete the specified items one
* at a time. In both situations, BatchWriteItem provides an
* alternative where the API performs the specified put and delete
* operations in parallel, giving you the power of the thread pool
* approach without having to introduce complexity into your application.
*
*
* Parallel processing reduces latency, but each specified put and
* delete request consumes the same number of write capacity units
* whether it is processed in parallel or not. Delete operations on
* nonexistent items consume one write capacity unit.
*
*
* If one or more of the following is true, DynamoDB rejects the entire
* batch write operation:
*
*
*
* -
* One or more tables specified in the BatchWriteItem request
* does not exist.
*
*
* -
* Primary key attributes specified on an item in the request do not
* match those in the corresponding table's primary key schema.
*
*
* -
* You try to perform multiple operations on the same item in the same
* BatchWriteItem request. For example, you cannot put and delete
* the same item in the same BatchWriteItem request.
*
*
* -
* There are more than 25 requests in the batch.
*
*
* -
* Any individual item in a batch exceeds 400 KB.
*
*
* -
* The total request size exceeds 16 MB.
*
*
*
*
*
* @param batchWriteItemRequest Container for the necessary parameters to
* execute the BatchWriteItem service method on AmazonDynamoDBv2.
*
* @return The response from the BatchWriteItem service method, as
* returned by AmazonDynamoDBv2.
*
* @throws ItemCollectionSizeLimitExceededException
* @throws InternalServerErrorException
* @throws ProvisionedThroughputExceededException
* @throws ResourceNotFoundException
*
* @throws AmazonClientException
* If any internal errors are encountered inside the client while
* attempting to make the request or handle the response. For example
* if a network connection is not available.
* @throws AmazonServiceException
* If an error response is returned by AmazonDynamoDBv2 indicating
* either a problem with the data in the request, or a server side issue.
*/
public BatchWriteItemResult batchWriteItem(BatchWriteItemRequest batchWriteItemRequest)
throws AmazonServiceException, AmazonClientException;
/**
*
* The DeleteTable operation deletes a table and all of its
* items. After a DeleteTable request, the specified table is in
* the DELETING state until DynamoDB completes the deletion.
* If the table is in the ACTIVE state, you can delete it.
* If a table is in CREATING or UPDATING
* states, then DynamoDB returns a ResourceInUseException . If the
* specified table does not exist, DynamoDB returns a
* ResourceNotFoundException . If table is already in the
* DELETING state, no error is returned.
*
*
* NOTE: DynamoDB might continue to accept data read and write
* operations, such as GetItem and PutItem, on a table in the DELETING
* state until the table deletion is complete.
*
*
* When you delete a table, any indexes on that table are also deleted.
*
*
* If you have DynamoDB Streams enabled on the table, then the
* corresponding stream on that table goes into the DISABLED
* state, and the stream is automatically deleted after 24 hours.
*
*
* Use the DescribeTable API to check the status of the table.
*
*
* @param deleteTableRequest Container for the necessary parameters to
* execute the DeleteTable service method on AmazonDynamoDBv2.
*
* @return The response from the DeleteTable service method, as returned
* by AmazonDynamoDBv2.
*
* @throws LimitExceededException
* @throws ResourceInUseException
* @throws InternalServerErrorException
* @throws ResourceNotFoundException
*
* @throws AmazonClientException
* If any internal errors are encountered inside the client while
* attempting to make the request or handle the response. For example
* if a network connection is not available.
* @throws AmazonServiceException
* If an error response is returned by AmazonDynamoDBv2 indicating
* either a problem with the data in the request, or a server side issue.
*/
public DeleteTableResult deleteTable(DeleteTableRequest deleteTableRequest)
throws AmazonServiceException, AmazonClientException;
/**
*
* Deletes a single item in a table by primary key. You can perform a
* conditional delete operation that deletes the item if it exists, or if
* it has an expected attribute value.
*
*
* In addition to deleting an item, you can also return the item's
* attribute values in the same operation, using the ReturnValues
* parameter.
*
*
* Unless you specify conditions, the DeleteItem is an idempotent
* operation; running it multiple times on the same item or attribute
* does not result in an error response.
*
*
* Conditional deletes are useful for deleting items only if specific
* conditions are met. If those conditions are met, DynamoDB performs the
* delete. Otherwise, the item is not deleted.
*
*
* @param deleteItemRequest Container for the necessary parameters to
* execute the DeleteItem service method on AmazonDynamoDBv2.
*
* @return The response from the DeleteItem service method, as returned
* by AmazonDynamoDBv2.
*
* @throws ConditionalCheckFailedException
* @throws ItemCollectionSizeLimitExceededException
* @throws InternalServerErrorException
* @throws ProvisionedThroughputExceededException
* @throws ResourceNotFoundException
*
* @throws AmazonClientException
* If any internal errors are encountered inside the client while
* attempting to make the request or handle the response. For example
* if a network connection is not available.
* @throws AmazonServiceException
* If an error response is returned by AmazonDynamoDBv2 indicating
* either a problem with the data in the request, or a server side issue.
*/
public DeleteItemResult deleteItem(DeleteItemRequest deleteItemRequest)
throws AmazonServiceException, AmazonClientException;
/**
*
* Modifies the provisioned throughput settings, global secondary
* indexes, or DynamoDB Streams settings for a given table.
*
*
* You can only perform one of the following operations at once:
*
*
*
* -
* Modify the provisioned throughput settings of the table.
*
*
* -
* Enable or disable Streams on the table.
*
*
* -
* Remove a global secondary index from the table.
*
*
* -
* Create a new global secondary index on the table. Once the index
* begins backfilling, you can use UpdateTable to perform other
* operations.
*
*
*
*
*
* UpdateTable is an asynchronous operation; while it is
* executing, the table status changes from ACTIVE to
* UPDATING . While it is UPDATING , you cannot
* issue another UpdateTable request. When the table returns to
* the ACTIVE state, the UpdateTable operation is
* complete.
*
*
* @param updateTableRequest Container for the necessary parameters to
* execute the UpdateTable service method on AmazonDynamoDBv2.
*
* @return The response from the UpdateTable service method, as returned
* by AmazonDynamoDBv2.
*
* @throws LimitExceededException
* @throws ResourceInUseException
* @throws InternalServerErrorException
* @throws ResourceNotFoundException
*
* @throws AmazonClientException
* If any internal errors are encountered inside the client while
* attempting to make the request or handle the response. For example
* if a network connection is not available.
* @throws AmazonServiceException
* If an error response is returned by AmazonDynamoDBv2 indicating
* either a problem with the data in the request, or a server side issue.
*/
public UpdateTableResult updateTable(UpdateTableRequest updateTableRequest)
throws AmazonServiceException, AmazonClientException;
/**
*
* Edits an existing item's attributes, or adds a new item to the table
* if it does not already exist. You can put, delete, or add attribute
* values. You can also perform a conditional update on an existing item
* (insert a new attribute name-value pair if it doesn't exist, or
* replace an existing name-value pair if it has certain expected
* attribute values).
*
*
* You can also return the item's attribute values in the same
* UpdateItem operation using the ReturnValues parameter.
*
*
* @param updateItemRequest Container for the necessary parameters to
* execute the UpdateItem service method on AmazonDynamoDBv2.
*
* @return The response from the UpdateItem service method, as returned
* by AmazonDynamoDBv2.
*
* @throws ConditionalCheckFailedException
* @throws ItemCollectionSizeLimitExceededException
* @throws InternalServerErrorException
* @throws ProvisionedThroughputExceededException
* @throws ResourceNotFoundException
*
* @throws AmazonClientException
* If any internal errors are encountered inside the client while
* attempting to make the request or handle the response. For example
* if a network connection is not available.
* @throws AmazonServiceException
* If an error response is returned by AmazonDynamoDBv2 indicating
* either a problem with the data in the request, or a server side issue.
*/
public UpdateItemResult updateItem(UpdateItemRequest updateItemRequest)
throws AmazonServiceException, AmazonClientException;
/**
*
* Returns information about the table, including the current status of
* the table, when it was created, the primary key schema, and any
* indexes on the table.
*
*
* NOTE: If you issue a DescribeTable request immediately after a
* CreateTable request, DynamoDB might return a
* ResourceNotFoundException. This is because DescribeTable uses an
* eventually consistent query, and the metadata for your table might not
* be available at that moment. Wait for a few seconds, and then try the
* DescribeTable request again.
*
*
* @param describeTableRequest Container for the necessary parameters to
* execute the DescribeTable service method on AmazonDynamoDBv2.
*
* @return The response from the DescribeTable service method, as
* returned by AmazonDynamoDBv2.
*
* @throws InternalServerErrorException
* @throws ResourceNotFoundException
*
* @throws AmazonClientException
* If any internal errors are encountered inside the client while
* attempting to make the request or handle the response. For example
* if a network connection is not available.
* @throws AmazonServiceException
* If an error response is returned by AmazonDynamoDBv2 indicating
* either a problem with the data in the request, or a server side issue.
*/
public DescribeTableResult describeTable(DescribeTableRequest describeTableRequest)
throws AmazonServiceException, AmazonClientException;
/**
*
* A Query operation uses the primary key of a table or a
* secondary index to directly access items from that table or index.
*
*
* Use the KeyConditionExpression parameter to provide a specific
* value for the partition key. The Query operation will return
* all of the items from the table or index with that partition key
* value. You can optionally narrow the scope of the Query
* operation by specifying a sort key value and a comparison operator in
* KeyConditionExpression . You can use the
* ScanIndexForward parameter to get results in forward or reverse
* order, by sort key.
*
*
* Queries that do not return results consume the minimum number of read
* capacity units for that type of read operation.
*
*
* If the total number of items meeting the query criteria exceeds the
* result set size limit of 1 MB, the query stops and results are
* returned to the user with the LastEvaluatedKey element to
* continue the query in a subsequent operation. Unlike a Scan
* operation, a Query operation never returns both an empty result
* set and a LastEvaluatedKey value. LastEvaluatedKey is
* only provided if the results exceed 1 MB, or if you have used the
* Limit parameter.
*
*
* You can query a table, a local secondary index, or a global secondary
* index. For a query on a table or on a local secondary index, you can
* set the ConsistentRead parameter to true and
* obtain a strongly consistent result. Global secondary indexes support
* eventually consistent reads only, so do not specify
* ConsistentRead when querying a global secondary index.
*
*
* @param queryRequest Container for the necessary parameters to execute
* the Query service method on AmazonDynamoDBv2.
*
* @return The response from the Query service method, as returned by
* AmazonDynamoDBv2.
*
* @throws InternalServerErrorException
* @throws ProvisionedThroughputExceededException
* @throws ResourceNotFoundException
*
* @throws AmazonClientException
* If any internal errors are encountered inside the client while
* attempting to make the request or handle the response. For example
* if a network connection is not available.
* @throws AmazonServiceException
* If an error response is returned by AmazonDynamoDBv2 indicating
* either a problem with the data in the request, or a server side issue.
*/
public QueryResult query(QueryRequest queryRequest)
throws AmazonServiceException, AmazonClientException;
/**
*
* Creates a new item, or replaces an old item with a new item. If an
* item that has the same primary key as the new item already exists in
* the specified table, the new item completely replaces the existing
* item. You can perform a conditional put operation (add a new item if
* one with the specified primary key doesn't exist), or replace an
* existing item if it has certain attribute values.
*
*
* In addition to putting an item, you can also return the item's
* attribute values in the same operation, using the ReturnValues
* parameter.
*
*
* When you add an item, the primary key attribute(s) are the only
* required attributes. Attribute values cannot be null. String and
* Binary type attributes must have lengths greater than zero. Set type
* attributes cannot be empty. Requests with empty values will be
* rejected with a ValidationException exception.
*
*
* You can request that PutItem return either a copy of the
* original item (before the update) or a copy of the updated item (after
* the update). For more information, see the ReturnValues
* description below.
*
*
* NOTE: To prevent a new item from replacing an existing item,
* use a conditional expression that contains the attribute_not_exists
* function with the name of the attribute being used as the partition
* key for the table. Since every record must contain that attribute,
* the attribute_not_exists function will only succeed if no matching
* item exists.
*
*
* For more information about using this API, see
* Working with Items
* in the Amazon DynamoDB Developer Guide .
*
*
* @param putItemRequest Container for the necessary parameters to
* execute the PutItem service method on AmazonDynamoDBv2.
*
* @return The response from the PutItem service method, as returned by
* AmazonDynamoDBv2.
*
* @throws ConditionalCheckFailedException
* @throws ItemCollectionSizeLimitExceededException
* @throws InternalServerErrorException
* @throws ProvisionedThroughputExceededException
* @throws ResourceNotFoundException
*
* @throws AmazonClientException
* If any internal errors are encountered inside the client while
* attempting to make the request or handle the response. For example
* if a network connection is not available.
* @throws AmazonServiceException
* If an error response is returned by AmazonDynamoDBv2 indicating
* either a problem with the data in the request, or a server side issue.
*/
public PutItemResult putItem(PutItemRequest putItemRequest)
throws AmazonServiceException, AmazonClientException;
/**
*
* Returns the current provisioned-capacity limits for your AWS account
* in a region, both for the region as a whole and for any one DynamoDB
* table that you create there.
*
*
* When you establish an AWS account, the account has initial limits on
* the maximum read capacity units and write capacity units that you can
* provision across all of your DynamoDB tables in a given region. Also,
* there are per-table limits that apply when you create a table there.
* For more information, see
* Limits
* page in the Amazon DynamoDB Developer Guide .
*
*
* Although you can increase these limits by filing a case at
* AWS Support Center
* , obtaining the increase is not instantaneous. The
* DescribeLimits API lets you write code to compare the capacity
* you are currently using to those limits imposed by your account so
* that you have enough time to apply for an increase before you hit a
* limit.
*
*
* For example, you could use one of the AWS SDKs to do the following:
*
* - Call DescribeLimits for a particular region to obtain
* your current account limits on provisioned capacity there.
* - Create a variable to hold the aggregate read capacity units
* provisioned for all your tables in that region, and one to hold the
* aggregate write capacity units. Zero them both.
* - Call ListTables to obtain a list of all your DynamoDB
* tables.
* -
* For each table name listed by ListTables , do the following:
*
*
*
* - Call DescribeTable with the table name.
* - Use the data returned by DescribeTable to add the read
* capacity units and write capacity units provisioned for the table
* itself to your variables.
* - If the table has one or more global secondary indexes (GSIs),
* loop over these GSIs and add their provisioned capacity values to your
* variables as well.
*
*
*
* - Report the account limits for that region returned by
* DescribeLimits , along with the total current provisioned
* capacity levels you have calculated.
*
* This will let you see whether you are getting close to your
* account-level limits.
*
*
* The per-table limits apply only when you are creating a new table.
* They restrict the sum of the provisioned capacity of the new table
* itself and all its global secondary indexes.
*
*
* For existing tables and their GSIs, DynamoDB will not let you
* increase provisioned capacity extremely rapidly, but the only upper
* limit that applies is that the aggregate provisioned capacity over all
* your tables and GSIs cannot exceed either of the per-account limits.
*
*
* NOTE: DescribeLimits should only be called periodically. You
* can expect throttling errors if you call it more than once in a
* minute.
*
*
* The DescribeLimits Request element has no content.
*
*
* @return The response from the DescribeLimits service method, as
* returned by AmazonDynamoDBv2.
*
* @throws InternalServerErrorException
*
* @throws AmazonClientException
* If any internal errors are encountered inside the client while
* attempting to make the request or handle the response. For example
* if a network connection is not available.
* @throws AmazonServiceException
* If an error response is returned by AmazonDynamoDBv2 indicating
* either a problem with the data in the request, or a server side issue.
*/
public DescribeLimitsResult describeLimits() throws AmazonServiceException, AmazonClientException;
/**
*
* Returns an array of table names associated with the current account
* and endpoint. The output from ListTables is paginated, with
* each page returning a maximum of 100 table names.
*
*
* @return The response from the ListTables service method, as returned
* by AmazonDynamoDBv2.
*
* @throws InternalServerErrorException
*
* @throws AmazonClientException
* If any internal errors are encountered inside the client while
* attempting to make the request or handle the response. For example
* if a network connection is not available.
* @throws AmazonServiceException
* If an error response is returned by AmazonDynamoDBv2 indicating
* either a problem with the data in the request, or a server side issue.
*/
public ListTablesResult listTables() throws AmazonServiceException, AmazonClientException;
/**
*
* The CreateTable operation adds a new table to your account. In
* an AWS account, table names must be unique within each region. That
* is, you can have two tables with same name if you create the tables in
* different regions.
*
*
* CreateTable is an asynchronous operation. Upon receiving a
* CreateTable request, DynamoDB immediately returns a response
* with a TableStatus of CREATING . After the table
* is created, DynamoDB sets the TableStatus to
* ACTIVE . You can perform read and write operations only
* on an ACTIVE table.
*
*
* You can optionally define secondary indexes on the new table, as part
* of the CreateTable operation. If you want to create multiple
* tables with secondary indexes on them, you must create the tables
* sequentially. Only one table with secondary indexes can be in the
* CREATING state at any given time.
*
*
* You can use the DescribeTable API to check the table status.
*
*
* @param attributeDefinitions An array of attributes that describe the
* key schema for the table and indexes.
* @param tableName The name of the table to create.
* @param keySchema Specifies the attributes that make up the primary key
* for a table or an index. The attributes in KeySchema must also
* be defined in the AttributeDefinitions array. For more
* information, see Data
* Model in the Amazon DynamoDB Developer Guide. Each
* KeySchemaElement in the array is composed of:
-
*
AttributeName - The name of this key attribute.
-
*
KeyType - The role that the key attribute will assume:
* HASH - partition key
RANGE - sort key
* The partition key of an item is also known as its hash
* attribute. The term "hash attribute" derives from DynamoDB' usage
* of an internal hash function to evenly distribute data items across
* partitions, based on their partition key values.
The sort key of an
* item is also known as its range attribute. The term "range
* attribute" derives from the way DynamoDB stores items with the same
* partition key physically close together, in sorted order by the sort
* key value.
For a simple primary key (partition key), you
* must provide exactly one element with a KeyType of
* HASH.
For a composite primary key (partition key and
* sort key), you must provide exactly two elements, in this order: The
* first element must have a KeyType of HASH, and the
* second element must have a KeyType of RANGE.
*
For more information, see Specifying
* the Primary Key in the Amazon DynamoDB Developer Guide.
* @param provisionedThroughput Represents the provisioned throughput
* settings for a specified table or index. The settings can be modified
* using the UpdateTable operation.
For current minimum and
* maximum provisioned throughput values, see Limits
* in the Amazon DynamoDB Developer Guide.
*
* @return The response from the CreateTable service method, as returned
* by AmazonDynamoDBv2.
*
* @throws LimitExceededException
* @throws ResourceInUseException
* @throws InternalServerErrorException
*
* @throws AmazonClientException
* If any internal errors are encountered inside the client while
* attempting to make the request or handle the response. For example
* if a network connection is not available.
* @throws AmazonServiceException
* If an error response is returned by AmazonDynamoDBv2 indicating
* either a problem with the data in the request, or a server side issue.
*/
public CreateTableResult createTable(java.util.List attributeDefinitions, String tableName, java.util.List keySchema, ProvisionedThroughput provisionedThroughput)
throws AmazonServiceException, AmazonClientException;
/**
*
* The Scan operation returns one or more items and item
* attributes by accessing every item in a table or a secondary index. To
* have DynamoDB return fewer items, you can provide a ScanFilter
* operation.
*
*
* If the total number of scanned items exceeds the maximum data set
* size limit of 1 MB, the scan stops and results are returned to the
* user as a LastEvaluatedKey value to continue the scan in a
* subsequent operation. The results also include the number of items
* exceeding the limit. A scan can result in no table data meeting the
* filter criteria.
*
*
* By default, Scan operations proceed sequentially; however, for
* faster performance on a large table or secondary index, applications
* can request a parallel Scan operation by providing the
* Segment and TotalSegments parameters. For more
* information, see
* Parallel Scan
* in the Amazon DynamoDB Developer Guide .
*
*
* By default, Scan uses eventually consistent reads when
* accessing the data in a table; therefore, the result set might not
* include the changes to data in the table immediately before the
* operation began. If you need a consistent copy of the data, as of the
* time that the Scan begins, you can set the ConsistentRead
* parameter to true .
*
*
* @param tableName The name of the table containing the requested items;
* or, if you provide IndexName, the name of the table to
* which that index belongs.
* @param attributesToGet This is a legacy parameter, for
* backward compatibility. New applications should use
* ProjectionExpression instead. Do not combine legacy parameters
* and expression parameters in a single API call; otherwise, DynamoDB
* will return a ValidationException exception.
This parameter
* allows you to retrieve attributes of type List or Map; however, it
* cannot retrieve individual elements within a List or a
* Map.
The names of one or more attributes to retrieve.
* If no attribute names are provided, then all attributes will be
* returned. If any of the requested attributes are not found, they will
* not appear in the result.
Note that AttributesToGet has no
* effect on provisioned throughput consumption. DynamoDB determines
* capacity units consumed based on item size, not on the amount of data
* that is returned to an application.
*
* @return The response from the Scan service method, as returned by
* AmazonDynamoDBv2.
*
* @throws InternalServerErrorException
* @throws ProvisionedThroughputExceededException
* @throws ResourceNotFoundException
*
* @throws AmazonClientException
* If any internal errors are encountered inside the client while
* attempting to make the request or handle the response. For example
* if a network connection is not available.
* @throws AmazonServiceException
* If an error response is returned by AmazonDynamoDBv2 indicating
* either a problem with the data in the request, or a server side issue.
*/
public ScanResult scan(String tableName, java.util.List attributesToGet)
throws AmazonServiceException, AmazonClientException;
/**
*
* The Scan operation returns one or more items and item
* attributes by accessing every item in a table or a secondary index. To
* have DynamoDB return fewer items, you can provide a ScanFilter
* operation.
*
*
* If the total number of scanned items exceeds the maximum data set
* size limit of 1 MB, the scan stops and results are returned to the
* user as a LastEvaluatedKey value to continue the scan in a
* subsequent operation. The results also include the number of items
* exceeding the limit. A scan can result in no table data meeting the
* filter criteria.
*
*
* By default, Scan operations proceed sequentially; however, for
* faster performance on a large table or secondary index, applications
* can request a parallel Scan operation by providing the
* Segment and TotalSegments parameters. For more
* information, see
* Parallel Scan
* in the Amazon DynamoDB Developer Guide .
*
*
* By default, Scan uses eventually consistent reads when
* accessing the data in a table; therefore, the result set might not
* include the changes to data in the table immediately before the
* operation began. If you need a consistent copy of the data, as of the
* time that the Scan begins, you can set the ConsistentRead
* parameter to true .
*
*
* @param tableName The name of the table containing the requested items;
* or, if you provide IndexName, the name of the table to
* which that index belongs.
* @param scanFilter This is a legacy parameter, for
* backward compatibility. New applications should use
* FilterExpression instead. Do not combine legacy parameters and
* expression parameters in a single API call; otherwise, DynamoDB will
* return a ValidationException exception.
A
* condition that evaluates the scan results and returns only the desired
* values. This parameter does not support attributes of type
* List or Map.
If you specify more than one condition in the
* ScanFilter map, then by default all of the conditions must
* evaluate to true. In other words, the conditions are ANDed together.
* (You can use the ConditionalOperator parameter to OR the
* conditions instead. If you do this, then at least one of the
* conditions must evaluate to true, rather than all of them.)
Each
* ScanFilter element consists of an attribute name to compare,
* along with the following:
-
AttributeValueList - One
* or more values to evaluate against the supplied attribute. The number
* of values in the list depends on the operator specified in
* ComparisonOperator .
For type Number, value comparisons are
* numeric.
String value comparisons for greater than, equals, or less
* than are based on ASCII character code values. For example,
* a is greater than A, and a is
* greater than B. For a list of code values, see http://en.wikipedia.org/wiki/ASCII#ASCII_printable_characters.
*
For Binary, DynamoDB treats each byte of the binary data as
* unsigned when it compares binary values.
For information on
* specifying data types in JSON, see JSON
* Data Format in the Amazon DynamoDB Developer Guide.
* ComparisonOperator - A comparator for evaluating
* attributes. For example, equals, greater than, less than, etc.
The
* following comparison operators are available:
EQ | NE | LE |
* LT | GE | GT | NOT_NULL | NULL | CONTAINS | NOT_CONTAINS | BEGINS_WITH
* | IN | BETWEEN
For complete descriptions of all comparison
* operators, see Condition.
*
*
* @return The response from the Scan service method, as returned by
* AmazonDynamoDBv2.
*
* @throws InternalServerErrorException
* @throws ProvisionedThroughputExceededException
* @throws ResourceNotFoundException
*
* @throws AmazonClientException
* If any internal errors are encountered inside the client while
* attempting to make the request or handle the response. For example
* if a network connection is not available.
* @throws AmazonServiceException
* If an error response is returned by AmazonDynamoDBv2 indicating
* either a problem with the data in the request, or a server side issue.
*/
public ScanResult scan(String tableName, java.util.Map scanFilter)
throws AmazonServiceException, AmazonClientException;
/**
*
* The Scan operation returns one or more items and item
* attributes by accessing every item in a table or a secondary index. To
* have DynamoDB return fewer items, you can provide a ScanFilter
* operation.
*
*
* If the total number of scanned items exceeds the maximum data set
* size limit of 1 MB, the scan stops and results are returned to the
* user as a LastEvaluatedKey value to continue the scan in a
* subsequent operation. The results also include the number of items
* exceeding the limit. A scan can result in no table data meeting the
* filter criteria.
*
*
* By default, Scan operations proceed sequentially; however, for
* faster performance on a large table or secondary index, applications
* can request a parallel Scan operation by providing the
* Segment and TotalSegments parameters. For more
* information, see
* Parallel Scan
* in the Amazon DynamoDB Developer Guide .
*
*
* By default, Scan uses eventually consistent reads when
* accessing the data in a table; therefore, the result set might not
* include the changes to data in the table immediately before the
* operation began. If you need a consistent copy of the data, as of the
* time that the Scan begins, you can set the ConsistentRead
* parameter to true .
*
*
* @param tableName The name of the table containing the requested items;
* or, if you provide IndexName, the name of the table to
* which that index belongs.
* @param attributesToGet This is a legacy parameter, for
* backward compatibility. New applications should use
* ProjectionExpression instead. Do not combine legacy parameters
* and expression parameters in a single API call; otherwise, DynamoDB
* will return a ValidationException exception.
This parameter
* allows you to retrieve attributes of type List or Map; however, it
* cannot retrieve individual elements within a List or a
* Map.
The names of one or more attributes to retrieve.
* If no attribute names are provided, then all attributes will be
* returned. If any of the requested attributes are not found, they will
* not appear in the result.
Note that AttributesToGet has no
* effect on provisioned throughput consumption. DynamoDB determines
* capacity units consumed based on item size, not on the amount of data
* that is returned to an application.
* @param scanFilter This is a legacy parameter, for
* backward compatibility. New applications should use
* FilterExpression instead. Do not combine legacy parameters and
* expression parameters in a single API call; otherwise, DynamoDB will
* return a ValidationException exception.
A
* condition that evaluates the scan results and returns only the desired
* values. This parameter does not support attributes of type
* List or Map.
If you specify more than one condition in the
* ScanFilter map, then by default all of the conditions must
* evaluate to true. In other words, the conditions are ANDed together.
* (You can use the ConditionalOperator parameter to OR the
* conditions instead. If you do this, then at least one of the
* conditions must evaluate to true, rather than all of them.)
Each
* ScanFilter element consists of an attribute name to compare,
* along with the following:
-
AttributeValueList - One
* or more values to evaluate against the supplied attribute. The number
* of values in the list depends on the operator specified in
* ComparisonOperator .
For type Number, value comparisons are
* numeric.
String value comparisons for greater than, equals, or less
* than are based on ASCII character code values. For example,
* a is greater than A, and a is
* greater than B. For a list of code values, see http://en.wikipedia.org/wiki/ASCII#ASCII_printable_characters.
*
For Binary, DynamoDB treats each byte of the binary data as
* unsigned when it compares binary values.
For information on
* specifying data types in JSON, see JSON
* Data Format in the Amazon DynamoDB Developer Guide.
* ComparisonOperator - A comparator for evaluating
* attributes. For example, equals, greater than, less than, etc.
The
* following comparison operators are available:
EQ | NE | LE |
* LT | GE | GT | NOT_NULL | NULL | CONTAINS | NOT_CONTAINS | BEGINS_WITH
* | IN | BETWEEN
For complete descriptions of all comparison
* operators, see Condition.
*
*
* @return The response from the Scan service method, as returned by
* AmazonDynamoDBv2.
*
* @throws InternalServerErrorException
* @throws ProvisionedThroughputExceededException
* @throws ResourceNotFoundException
*
* @throws AmazonClientException
* If any internal errors are encountered inside the client while
* attempting to make the request or handle the response. For example
* if a network connection is not available.
* @throws AmazonServiceException
* If an error response is returned by AmazonDynamoDBv2 indicating
* either a problem with the data in the request, or a server side issue.
*/
public ScanResult scan(String tableName, java.util.List attributesToGet, java.util.Map scanFilter)
throws AmazonServiceException, AmazonClientException;
/**
*
* The BatchGetItem operation returns the attributes of one or
* more items from one or more tables. You identify requested items by
* primary key.
*
*
* A single operation can retrieve up to 16 MB of data, which can
* contain as many as 100 items. BatchGetItem will return a
* partial result if the response size limit is exceeded, the table's
* provisioned throughput is exceeded, or an internal processing failure
* occurs. If a partial result is returned, the operation returns a value
* for UnprocessedKeys . You can use this value to retry the
* operation starting with the next item to get.
*
*
* IMPORTANT: If you request more than 100 items BatchGetItem
* will return a ValidationException with the message "Too many items
* requested for the BatchGetItem call".
*
*
* For example, if you ask to retrieve 100 items, but each individual
* item is 300 KB in size, the system returns 52 items (so as not to
* exceed the 16 MB limit). It also returns an appropriate
* UnprocessedKeys value so you can get the next page of results.
* If desired, your application can include its own logic to assemble the
* pages of results into one data set.
*
*
* If none of the items can be processed due to insufficient
* provisioned throughput on all of the tables in the request, then
* BatchGetItem will return a
* ProvisionedThroughputExceededException . If at least one
* of the items is successfully processed, then BatchGetItem
* completes successfully, while returning the keys of the unread items
* in UnprocessedKeys .
*
*
* IMPORTANT: If DynamoDB returns any unprocessed items, you
* should retry the batch operation on those items. However, we strongly
* recommend that you use an exponential backoff algorithm. If you retry
* the batch operation immediately, the underlying read or write requests
* can still fail due to throttling on the individual tables. If you
* delay the batch operation using exponential backoff, the individual
* requests in the batch are much more likely to succeed. For more
* information, see Batch Operations and Error Handling in the Amazon
* DynamoDB Developer Guide.
*
*
* By default, BatchGetItem performs eventually consistent reads
* on every table in the request. If you want strongly consistent reads
* instead, you can set ConsistentRead to true for
* any or all tables.
*
*
* In order to minimize response latency, BatchGetItem retrieves
* items in parallel.
*
*
* When designing your application, keep in mind that DynamoDB does not
* return attributes in any particular order. To help parse the response
* by item, include the primary key values for the items in your request
* in the AttributesToGet parameter.
*
*
* If a requested item does not exist, it is not returned in the result.
* Requests for nonexistent items consume the minimum read capacity units
* according to the type of read. For more information, see
* Capacity Units Calculations
* in the Amazon DynamoDB Developer Guide .
*
*
* @param requestItems A map of one or more table names and, for each
* table, a map that describes one or more items to retrieve from that
* table. Each table name can be used only once per BatchGetItem
* request. Each element in the map of items to retrieve consists of
* the following:
-
ConsistentRead - If
* true, a strongly consistent read is used; if
* false (the default), an eventually consistent read is
* used.
-
ExpressionAttributeNames - One or more
* substitution tokens for attribute names in the
* ProjectionExpression parameter. The following are some use
* cases for using ExpressionAttributeNames:
-
To
* access an attribute whose name conflicts with a DynamoDB reserved
* word.
-
To create a placeholder for repeating occurrences
* of an attribute name in an expression.
-
To prevent
* special characters in an attribute name from being misinterpreted in
* an expression.
Use the # character in an
* expression to dereference an attribute name. For example, consider the
* following attribute name:
Percentile
* The name of this attribute conflicts with a reserved word, so it
* cannot be used directly in an expression. (For the complete list of
* reserved words, see Reserved
* Words in the Amazon DynamoDB Developer Guide). To work
* around this, you could specify the following for
* ExpressionAttributeNames:
*
{"#P":"Percentile"}
You could
* then use this substitution in an expression, as in this example:
*
#P = :val
Tokens that begin
* with the : character are expression attribute values,
* which are placeholders for the actual value at runtime.
For
* more information on expression attribute names, see Accessing
* Item Attributes in the Amazon DynamoDB Developer Guide.
*
-
Keys - An array of primary key attribute values
* that define specific items in the table. For each primary key, you
* must provide all of the key attributes. For example, with a
* simple primary key, you only need to provide the partition key value.
* For a composite key, you must provide both the partition key
* value and the sort key value.
-
*
ProjectionExpression - A string that identifies one or more
* attributes to retrieve from the table. These attributes can include
* scalars, sets, or elements of a JSON document. The attributes in the
* expression must be separated by commas.
If no attribute names are
* specified, then all attributes will be returned. If any of the
* requested attributes are not found, they will not appear in the
* result.
For more information, see Accessing
* Item Attributes in the Amazon DynamoDB Developer Guide.
*
-
AttributesToGet - This is a
* legacy parameter, for backward compatibility. New applications should
* use ProjectionExpression instead. Do not combine legacy
* parameters and expression parameters in a single API call; otherwise,
* DynamoDB will return a ValidationException exception.
This
* parameter allows you to retrieve attributes of type List or Map;
* however, it cannot retrieve individual elements within a List or a
* Map.
The names of one or more attributes to retrieve.
* If no attribute names are provided, then all attributes will be
* returned. If any of the requested attributes are not found, they will
* not appear in the result.
Note that AttributesToGet has no
* effect on provisioned throughput consumption. DynamoDB determines
* capacity units consumed based on item size, not on the amount of data
* that is returned to an application.
* @param returnConsumedCapacity Determines the level of detail about
* provisioned throughput consumption that is returned in the response:
* INDEXES - The response includes the aggregate
* ConsumedCapacity for the operation, together with
* ConsumedCapacity for each table and secondary index that was
* accessed.
Note that some operations, such as GetItem and
* BatchGetItem, do not access any indexes at all. In these cases,
* specifying INDEXES will only return ConsumedCapacity
* information for table(s).
TOTAL - The response
* includes only the aggregate ConsumedCapacity for the
* operation.
NONE - No ConsumedCapacity
* details are included in the response.
*
* @return The response from the BatchGetItem service method, as returned
* by AmazonDynamoDBv2.
*
* @throws InternalServerErrorException
* @throws ProvisionedThroughputExceededException
* @throws ResourceNotFoundException
*
* @throws AmazonClientException
* If any internal errors are encountered inside the client while
* attempting to make the request or handle the response. For example
* if a network connection is not available.
* @throws AmazonServiceException
* If an error response is returned by AmazonDynamoDBv2 indicating
* either a problem with the data in the request, or a server side issue.
*/
public BatchGetItemResult batchGetItem(java.util.Map requestItems, String returnConsumedCapacity)
throws AmazonServiceException, AmazonClientException;
/**
*
* The BatchGetItem operation returns the attributes of one or
* more items from one or more tables. You identify requested items by
* primary key.
*
*
* A single operation can retrieve up to 16 MB of data, which can
* contain as many as 100 items. BatchGetItem will return a
* partial result if the response size limit is exceeded, the table's
* provisioned throughput is exceeded, or an internal processing failure
* occurs. If a partial result is returned, the operation returns a value
* for UnprocessedKeys . You can use this value to retry the
* operation starting with the next item to get.
*
*
* IMPORTANT: If you request more than 100 items BatchGetItem
* will return a ValidationException with the message "Too many items
* requested for the BatchGetItem call".
*
*
* For example, if you ask to retrieve 100 items, but each individual
* item is 300 KB in size, the system returns 52 items (so as not to
* exceed the 16 MB limit). It also returns an appropriate
* UnprocessedKeys value so you can get the next page of results.
* If desired, your application can include its own logic to assemble the
* pages of results into one data set.
*
*
* If none of the items can be processed due to insufficient
* provisioned throughput on all of the tables in the request, then
* BatchGetItem will return a
* ProvisionedThroughputExceededException . If at least one
* of the items is successfully processed, then BatchGetItem
* completes successfully, while returning the keys of the unread items
* in UnprocessedKeys .
*
*
* IMPORTANT: If DynamoDB returns any unprocessed items, you
* should retry the batch operation on those items. However, we strongly
* recommend that you use an exponential backoff algorithm. If you retry
* the batch operation immediately, the underlying read or write requests
* can still fail due to throttling on the individual tables. If you
* delay the batch operation using exponential backoff, the individual
* requests in the batch are much more likely to succeed. For more
* information, see Batch Operations and Error Handling in the Amazon
* DynamoDB Developer Guide.
*
*
* By default, BatchGetItem performs eventually consistent reads
* on every table in the request. If you want strongly consistent reads
* instead, you can set ConsistentRead to true for
* any or all tables.
*
*
* In order to minimize response latency, BatchGetItem retrieves
* items in parallel.
*
*
* When designing your application, keep in mind that DynamoDB does not
* return attributes in any particular order. To help parse the response
* by item, include the primary key values for the items in your request
* in the AttributesToGet parameter.
*
*
* If a requested item does not exist, it is not returned in the result.
* Requests for nonexistent items consume the minimum read capacity units
* according to the type of read. For more information, see
* Capacity Units Calculations
* in the Amazon DynamoDB Developer Guide .
*
*
* @param requestItems A map of one or more table names and, for each
* table, a map that describes one or more items to retrieve from that
* table. Each table name can be used only once per BatchGetItem
* request. Each element in the map of items to retrieve consists of
* the following:
-
ConsistentRead - If
* true, a strongly consistent read is used; if
* false (the default), an eventually consistent read is
* used.
-
ExpressionAttributeNames - One or more
* substitution tokens for attribute names in the
* ProjectionExpression parameter. The following are some use
* cases for using ExpressionAttributeNames:
-
To
* access an attribute whose name conflicts with a DynamoDB reserved
* word.
-
To create a placeholder for repeating occurrences
* of an attribute name in an expression.
-
To prevent
* special characters in an attribute name from being misinterpreted in
* an expression.
Use the # character in an
* expression to dereference an attribute name. For example, consider the
* following attribute name:
Percentile
* The name of this attribute conflicts with a reserved word, so it
* cannot be used directly in an expression. (For the complete list of
* reserved words, see Reserved
* Words in the Amazon DynamoDB Developer Guide). To work
* around this, you could specify the following for
* ExpressionAttributeNames:
*
{"#P":"Percentile"}
You could
* then use this substitution in an expression, as in this example:
*
#P = :val
Tokens that begin
* with the : character are expression attribute values,
* which are placeholders for the actual value at runtime.
For
* more information on expression attribute names, see Accessing
* Item Attributes in the Amazon DynamoDB Developer Guide.
*
-
Keys - An array of primary key attribute values
* that define specific items in the table. For each primary key, you
* must provide all of the key attributes. For example, with a
* simple primary key, you only need to provide the partition key value.
* For a composite key, you must provide both the partition key
* value and the sort key value.
-
*
ProjectionExpression - A string that identifies one or more
* attributes to retrieve from the table. These attributes can include
* scalars, sets, or elements of a JSON document. The attributes in the
* expression must be separated by commas.
If no attribute names are
* specified, then all attributes will be returned. If any of the
* requested attributes are not found, they will not appear in the
* result.
For more information, see Accessing
* Item Attributes in the Amazon DynamoDB Developer Guide.
*
-
AttributesToGet - This is a
* legacy parameter, for backward compatibility. New applications should
* use ProjectionExpression instead. Do not combine legacy
* parameters and expression parameters in a single API call; otherwise,
* DynamoDB will return a ValidationException exception.
This
* parameter allows you to retrieve attributes of type List or Map;
* however, it cannot retrieve individual elements within a List or a
* Map.
The names of one or more attributes to retrieve.
* If no attribute names are provided, then all attributes will be
* returned. If any of the requested attributes are not found, they will
* not appear in the result.
Note that AttributesToGet has no
* effect on provisioned throughput consumption. DynamoDB determines
* capacity units consumed based on item size, not on the amount of data
* that is returned to an application.
*
* @return The response from the BatchGetItem service method, as returned
* by AmazonDynamoDBv2.
*
* @throws InternalServerErrorException
* @throws ProvisionedThroughputExceededException
* @throws ResourceNotFoundException
*
* @throws AmazonClientException
* If any internal errors are encountered inside the client while
* attempting to make the request or handle the response. For example
* if a network connection is not available.
* @throws AmazonServiceException
* If an error response is returned by AmazonDynamoDBv2 indicating
* either a problem with the data in the request, or a server side issue.
*/
public BatchGetItemResult batchGetItem(java.util.Map requestItems)
throws AmazonServiceException, AmazonClientException;
/**
*
* The GetItem operation returns a set of attributes for the item
* with the given primary key. If there is no matching item,
* GetItem does not return any data.
*
*
* GetItem provides an eventually consistent read by default. If
* your application requires a strongly consistent read, set
* ConsistentRead to true . Although a strongly
* consistent read might take more time than an eventually consistent
* read, it always returns the last updated value.
*
*
* @param tableName The name of the table containing the requested item.
* @param key A map of attribute names to AttributeValue objects,
* representing the primary key of the item to retrieve. For the
* primary key, you must provide all of the attributes. For example, with
* a simple primary key, you only need to provide a value for the
* partition key. For a composite primary key, you must provide values
* for both the partition key and the sort key.
*
* @return The response from the GetItem service method, as returned by
* AmazonDynamoDBv2.
*
* @throws InternalServerErrorException
* @throws ProvisionedThroughputExceededException
* @throws ResourceNotFoundException
*
* @throws AmazonClientException
* If any internal errors are encountered inside the client while
* attempting to make the request or handle the response. For example
* if a network connection is not available.
* @throws AmazonServiceException
* If an error response is returned by AmazonDynamoDBv2 indicating
* either a problem with the data in the request, or a server side issue.
*/
public GetItemResult getItem(String tableName, java.util.Map key)
throws AmazonServiceException, AmazonClientException;
/**
*
* The GetItem operation returns a set of attributes for the item
* with the given primary key. If there is no matching item,
* GetItem does not return any data.
*
*
* GetItem provides an eventually consistent read by default. If
* your application requires a strongly consistent read, set
* ConsistentRead to true . Although a strongly
* consistent read might take more time than an eventually consistent
* read, it always returns the last updated value.
*
*
* @param tableName The name of the table containing the requested item.
* @param key A map of attribute names to AttributeValue objects,
* representing the primary key of the item to retrieve. For the
* primary key, you must provide all of the attributes. For example, with
* a simple primary key, you only need to provide a value for the
* partition key. For a composite primary key, you must provide values
* for both the partition key and the sort key.
* @param consistentRead Determines the read consistency model: If set to
* true, then the operation uses strongly consistent reads;
* otherwise, the operation uses eventually consistent reads.
*
* @return The response from the GetItem service method, as returned by
* AmazonDynamoDBv2.
*
* @throws InternalServerErrorException
* @throws ProvisionedThroughputExceededException
* @throws ResourceNotFoundException
*
* @throws AmazonClientException
* If any internal errors are encountered inside the client while
* attempting to make the request or handle the response. For example
* if a network connection is not available.
* @throws AmazonServiceException
* If an error response is returned by AmazonDynamoDBv2 indicating
* either a problem with the data in the request, or a server side issue.
*/
public GetItemResult getItem(String tableName, java.util.Map key, Boolean consistentRead)
throws AmazonServiceException, AmazonClientException;
/**
*
* Returns an array of table names associated with the current account
* and endpoint. The output from ListTables is paginated, with
* each page returning a maximum of 100 table names.
*
*
* @param exclusiveStartTableName The first table name that this
* operation will evaluate. Use the value that was returned for
* LastEvaluatedTableName in a previous operation, so that you can
* obtain the next page of results.
*
* @return The response from the ListTables service method, as returned
* by AmazonDynamoDBv2.
*
* @throws InternalServerErrorException
*
* @throws AmazonClientException
* If any internal errors are encountered inside the client while
* attempting to make the request or handle the response. For example
* if a network connection is not available.
* @throws AmazonServiceException
* If an error response is returned by AmazonDynamoDBv2 indicating
* either a problem with the data in the request, or a server side issue.
*/
public ListTablesResult listTables(String exclusiveStartTableName)
throws AmazonServiceException, AmazonClientException;
/**
*
* Returns an array of table names associated with the current account
* and endpoint. The output from ListTables is paginated, with
* each page returning a maximum of 100 table names.
*
*
* @param exclusiveStartTableName The first table name that this
* operation will evaluate. Use the value that was returned for
* LastEvaluatedTableName in a previous operation, so that you can
* obtain the next page of results.
* @param limit A maximum number of table names to return. If this
* parameter is not specified, the limit is 100.
*
* @return The response from the ListTables service method, as returned
* by AmazonDynamoDBv2.
*
* @throws InternalServerErrorException
*
* @throws AmazonClientException
* If any internal errors are encountered inside the client while
* attempting to make the request or handle the response. For example
* if a network connection is not available.
* @throws AmazonServiceException
* If an error response is returned by AmazonDynamoDBv2 indicating
* either a problem with the data in the request, or a server side issue.
*/
public ListTablesResult listTables(String exclusiveStartTableName, Integer limit)
throws AmazonServiceException, AmazonClientException;
/**
*
* Returns an array of table names associated with the current account
* and endpoint. The output from ListTables is paginated, with
* each page returning a maximum of 100 table names.
*
*
* @param limit A maximum number of table names to return. If this
* parameter is not specified, the limit is 100.
*
* @return The response from the ListTables service method, as returned
* by AmazonDynamoDBv2.
*
* @throws InternalServerErrorException
*
* @throws AmazonClientException
* If any internal errors are encountered inside the client while
* attempting to make the request or handle the response. For example
* if a network connection is not available.
* @throws AmazonServiceException
* If an error response is returned by AmazonDynamoDBv2 indicating
* either a problem with the data in the request, or a server side issue.
*/
public ListTablesResult listTables(Integer limit)
throws AmazonServiceException, AmazonClientException;
/**
*
* The BatchWriteItem operation puts or deletes multiple items in
* one or more tables. A single call to BatchWriteItem can write
* up to 16 MB of data, which can comprise as many as 25 put or delete
* requests. Individual items to be written can be as large as 400 KB.
*
*
* NOTE: BatchWriteItem cannot update items. To update items, use
* the UpdateItem API.
*
*
* The individual PutItem and DeleteItem operations
* specified in BatchWriteItem are atomic; however
* BatchWriteItem as a whole is not. If any requested operations
* fail because the table's provisioned throughput is exceeded or an
* internal processing failure occurs, the failed operations are returned
* in the UnprocessedItems response parameter. You can investigate
* and optionally resend the requests. Typically, you would call
* BatchWriteItem in a loop. Each iteration would check for
* unprocessed items and submit a new BatchWriteItem request with
* those unprocessed items until all items have been processed.
*
*
* Note that if none of the items can be processed due to
* insufficient provisioned throughput on all of the tables in the
* request, then BatchWriteItem will return a
* ProvisionedThroughputExceededException .
*
*
* IMPORTANT: If DynamoDB returns any unprocessed items, you
* should retry the batch operation on those items. However, we strongly
* recommend that you use an exponential backoff algorithm. If you retry
* the batch operation immediately, the underlying read or write requests
* can still fail due to throttling on the individual tables. If you
* delay the batch operation using exponential backoff, the individual
* requests in the batch are much more likely to succeed. For more
* information, see Batch Operations and Error Handling in the Amazon
* DynamoDB Developer Guide.
*
*
* With BatchWriteItem , you can efficiently write or delete
* large amounts of data, such as from Amazon Elastic MapReduce (EMR), or
* copy data from another database into DynamoDB. In order to improve
* performance with these large-scale operations, BatchWriteItem
* does not behave in the same way as individual PutItem and
* DeleteItem calls would. For example, you cannot specify
* conditions on individual put and delete requests, and
* BatchWriteItem does not return deleted items in the response.
*
*
* If you use a programming language that supports concurrency, you can
* use threads to write items in parallel. Your application must include
* the necessary logic to manage the threads. With languages that don't
* support threading, you must update or delete the specified items one
* at a time. In both situations, BatchWriteItem provides an
* alternative where the API performs the specified put and delete
* operations in parallel, giving you the power of the thread pool
* approach without having to introduce complexity into your application.
*
*
* Parallel processing reduces latency, but each specified put and
* delete request consumes the same number of write capacity units
* whether it is processed in parallel or not. Delete operations on
* nonexistent items consume one write capacity unit.
*
*
* If one or more of the following is true, DynamoDB rejects the entire
* batch write operation:
*
*
*
* -
* One or more tables specified in the BatchWriteItem request
* does not exist.
*
*
* -
* Primary key attributes specified on an item in the request do not
* match those in the corresponding table's primary key schema.
*
*
* -
* You try to perform multiple operations on the same item in the same
* BatchWriteItem request. For example, you cannot put and delete
* the same item in the same BatchWriteItem request.
*
*
* -
* There are more than 25 requests in the batch.
*
*
* -
* Any individual item in a batch exceeds 400 KB.
*
*
* -
* The total request size exceeds 16 MB.
*
*
*
*
*
* @param requestItems A map of one or more table names and, for each
* table, a list of operations to be performed (DeleteRequest or
* PutRequest). Each element in the map consists of the following:
* -
DeleteRequest - Perform a DeleteItem
* operation on the specified item. The item to be deleted is identified
* by a Key subelement:
-
Key - A map of primary
* key attribute values that uniquely identify the ! item. Each entry in
* this map consists of an attribute name and an attribute value. For
* each primary key, you must provide all of the key attributes.
* For example, with a simple primary key, you only need to provide a
* value for the partition key. For a composite primary key, you must
* provide values for both the partition key and the sort key.
*
-
PutRequest - Perform a PutItem
* operation on the specified item. The item to be put is identified by
* an Item subelement:
-
Item - A map of
* attributes and their values. Each entry in this map consists of an
* attribute name and an attribute value. Attribute values must not be
* null; string and binary type attributes must have lengths greater than
* zero; and set type attributes must not be empty. Requests that contain
* empty values will be rejected with a ValidationException
* exception.
If you specify any attributes that are part of an index
* key, then the data types for those attributes must match those of the
* schema in the table's attribute definition.
*
* @return The response from the BatchWriteItem service method, as
* returned by AmazonDynamoDBv2.
*
* @throws ItemCollectionSizeLimitExceededException
* @throws InternalServerErrorException
* @throws ProvisionedThroughputExceededException
* @throws ResourceNotFoundException
*
* @throws AmazonClientException
* If any internal errors are encountered inside the client while
* attempting to make the request or handle the response. For example
* if a network connection is not available.
* @throws AmazonServiceException
* If an error response is returned by AmazonDynamoDBv2 indicating
* either a problem with the data in the request, or a server side issue.
*/
public BatchWriteItemResult batchWriteItem(java.util.Map> requestItems)
throws AmazonServiceException, AmazonClientException;
/**
*
* The DeleteTable operation deletes a table and all of its
* items. After a DeleteTable request, the specified table is in
* the DELETING state until DynamoDB completes the deletion.
* If the table is in the ACTIVE state, you can delete it.
* If a table is in CREATING or UPDATING
* states, then DynamoDB returns a ResourceInUseException . If the
* specified table does not exist, DynamoDB returns a
* ResourceNotFoundException . If table is already in the
* DELETING state, no error is returned.
*
*
* NOTE: DynamoDB might continue to accept data read and write
* operations, such as GetItem and PutItem, on a table in the DELETING
* state until the table deletion is complete.
*
*
* When you delete a table, any indexes on that table are also deleted.
*
*
* If you have DynamoDB Streams enabled on the table, then the
* corresponding stream on that table goes into the DISABLED
* state, and the stream is automatically deleted after 24 hours.
*
*
* Use the DescribeTable API to check the status of the table.
*
*
* @param tableName The name of the table to delete.
*
* @return The response from the DeleteTable service method, as returned
* by AmazonDynamoDBv2.
*
* @throws LimitExceededException
* @throws ResourceInUseException
* @throws InternalServerErrorException
* @throws ResourceNotFoundException
*
* @throws AmazonClientException
* If any internal errors are encountered inside the client while
* attempting to make the request or handle the response. For example
* if a network connection is not available.
* @throws AmazonServiceException
* If an error response is returned by AmazonDynamoDBv2 indicating
* either a problem with the data in the request, or a server side issue.
*/
public DeleteTableResult deleteTable(String tableName)
throws AmazonServiceException, AmazonClientException;
/**
*
* Deletes a single item in a table by primary key. You can perform a
* conditional delete operation that deletes the item if it exists, or if
* it has an expected attribute value.
*
*
* In addition to deleting an item, you can also return the item's
* attribute values in the same operation, using the ReturnValues
* parameter.
*
*
* Unless you specify conditions, the DeleteItem is an idempotent
* operation; running it multiple times on the same item or attribute
* does not result in an error response.
*
*
* Conditional deletes are useful for deleting items only if specific
* conditions are met. If those conditions are met, DynamoDB performs the
* delete. Otherwise, the item is not deleted.
*
*
* @param tableName The name of the table from which to delete the item.
* @param key A map of attribute names to AttributeValue objects,
* representing the primary key of the item to delete. For the primary
* key, you must provide all of the attributes. For example, with a
* simple primary key, you only need to provide a value for the partition
* key. For a composite primary key, you must provide values for both the
* partition key and the sort key.
*
* @return The response from the DeleteItem service method, as returned
* by AmazonDynamoDBv2.
*
* @throws ConditionalCheckFailedException
* @throws ItemCollectionSizeLimitExceededException
* @throws InternalServerErrorException
* @throws ProvisionedThroughputExceededException
* @throws ResourceNotFoundException
*
* @throws AmazonClientException
* If any internal errors are encountered inside the client while
* attempting to make the request or handle the response. For example
* if a network connection is not available.
* @throws AmazonServiceException
* If an error response is returned by AmazonDynamoDBv2 indicating
* either a problem with the data in the request, or a server side issue.
*/
public DeleteItemResult deleteItem(String tableName, java.util.Map key)
throws AmazonServiceException, AmazonClientException;
/**
*
* Deletes a single item in a table by primary key. You can perform a
* conditional delete operation that deletes the item if it exists, or if
* it has an expected attribute value.
*
*
* In addition to deleting an item, you can also return the item's
* attribute values in the same operation, using the ReturnValues
* parameter.
*
*
* Unless you specify conditions, the DeleteItem is an idempotent
* operation; running it multiple times on the same item or attribute
* does not result in an error response.
*
*
* Conditional deletes are useful for deleting items only if specific
* conditions are met. If those conditions are met, DynamoDB performs the
* delete. Otherwise, the item is not deleted.
*
*
* @param tableName The name of the table from which to delete the item.
* @param key A map of attribute names to AttributeValue objects,
* representing the primary key of the item to delete. For the primary
* key, you must provide all of the attributes. For example, with a
* simple primary key, you only need to provide a value for the partition
* key. For a composite primary key, you must provide values for both the
* partition key and the sort key.
* @param returnValues Use ReturnValues if you want to get the
* item attributes as they appeared before they were deleted. For
* DeleteItem, the valid values are:
-
*
NONE - If ReturnValues is not specified, or if
* its value is NONE, then nothing is returned. (This
* setting is the default for ReturnValues.)
-
*
ALL_OLD - The content of the old item is returned.
*
*
* @return The response from the DeleteItem service method, as returned
* by AmazonDynamoDBv2.
*
* @throws ConditionalCheckFailedException
* @throws ItemCollectionSizeLimitExceededException
* @throws InternalServerErrorException
* @throws ProvisionedThroughputExceededException
* @throws ResourceNotFoundException
*
* @throws AmazonClientException
* If any internal errors are encountered inside the client while
* attempting to make the request or handle the response. For example
* if a network connection is not available.
* @throws AmazonServiceException
* If an error response is returned by AmazonDynamoDBv2 indicating
* either a problem with the data in the request, or a server side issue.
*/
public DeleteItemResult deleteItem(String tableName, java.util.Map key, String returnValues)
throws AmazonServiceException, AmazonClientException;
/**
*
* Modifies the provisioned throughput settings, global secondary
* indexes, or DynamoDB Streams settings for a given table.
*
*
* You can only perform one of the following operations at once:
*
*
*
* -
* Modify the provisioned throughput settings of the table.
*
*
* -
* Enable or disable Streams on the table.
*
*
* -
* Remove a global secondary index from the table.
*
*
* -
* Create a new global secondary index on the table. Once the index
* begins backfilling, you can use UpdateTable to perform other
* operations.
*
*
*
*
*
* UpdateTable is an asynchronous operation; while it is
* executing, the table status changes from ACTIVE to
* UPDATING . While it is UPDATING , you cannot
* issue another UpdateTable request. When the table returns to
* the ACTIVE state, the UpdateTable operation is
* complete.
*
*
* @param tableName The name of the table to be updated.
* @param provisionedThroughput Represents the provisioned throughput
* settings for a specified table or index. The settings can be modified
* using the UpdateTable operation. For current minimum and
* maximum provisioned throughput values, see Limits
* in the Amazon DynamoDB Developer Guide.
*
* @return The response from the UpdateTable service method, as returned
* by AmazonDynamoDBv2.
*
* @throws LimitExceededException
* @throws ResourceInUseException
* @throws InternalServerErrorException
* @throws ResourceNotFoundException
*
* @throws AmazonClientException
* If any internal errors are encountered inside the client while
* attempting to make the request or handle the response. For example
* if a network connection is not available.
* @throws AmazonServiceException
* If an error response is returned by AmazonDynamoDBv2 indicating
* either a problem with the data in the request, or a server side issue.
*/
public UpdateTableResult updateTable(String tableName, ProvisionedThroughput provisionedThroughput)
throws AmazonServiceException, AmazonClientException;
/**
*
* Edits an existing item's attributes, or adds a new item to the table
* if it does not already exist. You can put, delete, or add attribute
* values. You can also perform a conditional update on an existing item
* (insert a new attribute name-value pair if it doesn't exist, or
* replace an existing name-value pair if it has certain expected
* attribute values).
*
*
* You can also return the item's attribute values in the same
* UpdateItem operation using the ReturnValues parameter.
*
*
* @param tableName The name of the table containing the item to update.
* @param key The primary key of the item to be updated. Each element
* consists of an attribute name and a value for that attribute. For
* the primary key, you must provide all of the attributes. For example,
* with a simple primary key, you only need to provide a value for the
* partition key. For a composite primary key, you must provide values
* for both the partition key and the sort key.
* @param attributeUpdates This is a legacy parameter, for
* backward compatibility. New applications should use
* UpdateExpression instead. Do not combine legacy parameters and
* expression parameters in a single API call; otherwise, DynamoDB will
* return a ValidationException exception.
This parameter can
* be used for modifying top-level attributes; however, it does not
* support individual list or map elements.
The names of
* attributes to be modified, the action to perform on each, and the new
* value for each. If you are updating an attribute that is an index key
* attribute for any indexes on that table, the attribute type must match
* the index key type defined in the AttributesDefinition of the
* table description. You can use UpdateItem to update any non-key
* attributes.
Attribute values cannot be null. String and Binary type
* attributes must have lengths greater than zero. Set type attributes
* must not be empty. Requests with empty values will be rejected with a
* ValidationException exception.
Each AttributeUpdates
* element consists of an attribute name to modify, along with the
* following:
-
Value - The new value, if applicable,
* for this attribute.
-
Action - A value that
* specifies how to perform the update. This action is only valid for an
* existing attribute whose data type is Number or is a set; do not use
* ADD for other data types.
If an item with the
* specified primary key is found in the table, the following values
* perform the following actions:
-
PUT - Adds
* the specified attribute to the item. If the attribute already exists,
* it is replaced by the new value.
-
DELETE -
* Removes the attribute and its value, if no value is specified for
* DELETE. The data type of the specified value must match
* the existing value's data type.
If a set of values is specified,
* then those values are subtracted from the old set. For example, if the
* attribute value was the set [a,b,c] and the
* DELETE action specifies [a,c], then the
* final attribute value is [b]. Specifying an empty set is
* an error.
-
ADD - Adds the specified value to
* the item, if the attribute does not already exist. If the attribute
* does exist, then the behavior of ADD depends on the data
* type of the attribute:
-
If the existing attribute is a
* number, and if Value is also a number, then Value is
* mathematically added to the existing attribute. If Value is a
* negative number, then it is subtracted from the existing attribute.
* If you use ADD to increment or decrement a
* number value for an item that doesn't exist before the update,
* DynamoDB uses 0 as the initial value.
Similarly, if you use
* ADD for an existing item to increment or decrement an
* attribute value that doesn't exist before the update, DynamoDB uses
* 0 as the initial value. For example, suppose that the
* item you want to update doesn't have an attribute named
* itemcount, but you decide to ADD the number
* 3 to this attribute anyway. DynamoDB will create the
* itemcount attribute, set its initial value to 0,
* and finally add 3 to it. The result will be a new
* itemcount attribute, with a value of 3.
*
-
If the existing data type is a set, and if Value
* is also a set, then Value is appended to the existing set. For
* example, if the attribute value is the set [1,2], and the
* ADD action specified [3], then the final
* attribute value is [1,2,3]. An error occurs if an
* ADD action is specified for a set attribute and the
* attribute type specified does not match the existing set type.
Both
* sets must have the same primitive data type. For example, if the
* existing data type is a set of strings, Value must also be a
* set of strings.
If no item with the
* specified key is found in the table, the following values perform the
* following actions:
-
PUT - Causes DynamoDB to
* create a new item with the specified primary key, and then adds the
* attribute.
-
DELETE - Nothing happens,
* because attributes cannot be deleted from a nonexistent item. The
* operation succeeds, but DynamoDB does not create a new item.
* -
ADD - Causes DynamoDB to create an item with the
* supplied primary key and number (or set of numbers) for the attribute
* value. The only data types allowed are Number and Number Set.
*
If you provide any attributes that are part of an
* index key, then the data types for those attributes must match those
* of the schema in the table's attribute definition.
*
* @return The response from the UpdateItem service method, as returned
* by AmazonDynamoDBv2.
*
* @throws ConditionalCheckFailedException
* @throws ItemCollectionSizeLimitExceededException
* @throws InternalServerErrorException
* @throws ProvisionedThroughputExceededException
* @throws ResourceNotFoundException
*
* @throws AmazonClientException
* If any internal errors are encountered inside the client while
* attempting to make the request or handle the response. For example
* if a network connection is not available.
* @throws AmazonServiceException
* If an error response is returned by AmazonDynamoDBv2 indicating
* either a problem with the data in the request, or a server side issue.
*/
public UpdateItemResult updateItem(String tableName, java.util.Map key, java.util.Map attributeUpdates)
throws AmazonServiceException, AmazonClientException;
/**
*
* Edits an existing item's attributes, or adds a new item to the table
* if it does not already exist. You can put, delete, or add attribute
* values. You can also perform a conditional update on an existing item
* (insert a new attribute name-value pair if it doesn't exist, or
* replace an existing name-value pair if it has certain expected
* attribute values).
*
*
* You can also return the item's attribute values in the same
* UpdateItem operation using the ReturnValues parameter.
*
*
* @param tableName The name of the table containing the item to update.
* @param key The primary key of the item to be updated. Each element
* consists of an attribute name and a value for that attribute. For
* the primary key, you must provide all of the attributes. For example,
* with a simple primary key, you only need to provide a value for the
* partition key. For a composite primary key, you must provide values
* for both the partition key and the sort key.
* @param attributeUpdates This is a legacy parameter, for
* backward compatibility. New applications should use
* UpdateExpression instead. Do not combine legacy parameters and
* expression parameters in a single API call; otherwise, DynamoDB will
* return a ValidationException exception.
This parameter can
* be used for modifying top-level attributes; however, it does not
* support individual list or map elements.
The names of
* attributes to be modified, the action to perform on each, and the new
* value for each. If you are updating an attribute that is an index key
* attribute for any indexes on that table, the attribute type must match
* the index key type defined in the AttributesDefinition of the
* table description. You can use UpdateItem to update any non-key
* attributes.
Attribute values cannot be null. String and Binary type
* attributes must have lengths greater than zero. Set type attributes
* must not be empty. Requests with empty values will be rejected with a
* ValidationException exception.
Each AttributeUpdates
* element consists of an attribute name to modify, along with the
* following:
-
Value - The new value, if applicable,
* for this attribute.
-
Action - A value that
* specifies how to perform the update. This action is only valid for an
* existing attribute whose data type is Number or is a set; do not use
* ADD for other data types.
If an item with the
* specified primary key is found in the table, the following values
* perform the following actions:
-
PUT - Adds
* the specified attribute to the item. If the attribute already exists,
* it is replaced by the new value.
-
DELETE -
* Removes the attribute and its value, if no value is specified for
* DELETE. The data type of the specified value must match
* the existing value's data type.
If a set of values is specified,
* then those values are subtracted from the old set. For example, if the
* attribute value was the set [a,b,c] and the
* DELETE action specifies [a,c], then the
* final attribute value is [b]. Specifying an empty set is
* an error.
-
ADD - Adds the specified value to
* the item, if the attribute does not already exist. If the attribute
* does exist, then the behavior of ADD depends on the data
* type of the attribute:
-
If the existing attribute is a
* number, and if Value is also a number, then Value is
* mathematically added to the existing attribute. If Value is a
* negative number, then it is subtracted from the existing attribute.
* If you use ADD to increment or decrement a
* number value for an item that doesn't exist before the update,
* DynamoDB uses 0 as the initial value.
Similarly, if you use
* ADD for an existing item to increment or decrement an
* attribute value that doesn't exist before the update, DynamoDB uses
* 0 as the initial value. For example, suppose that the
* item you want to update doesn't have an attribute named
* itemcount, but you decide to ADD the number
* 3 to this attribute anyway. DynamoDB will create the
* itemcount attribute, set its initial value to 0,
* and finally add 3 to it. The result will be a new
* itemcount attribute, with a value of 3.
*
-
If the existing data type is a set, and if Value
* is also a set, then Value is appended to the existing set. For
* example, if the attribute value is the set [1,2], and the
* ADD action specified [3], then the final
* attribute value is [1,2,3]. An error occurs if an
* ADD action is specified for a set attribute and the
* attribute type specified does not match the existing set type.
Both
* sets must have the same primitive data type. For example, if the
* existing data type is a set of strings, Value must also be a
* set of strings.
If no item with the
* specified key is found in the table, the following values perform the
* following actions:
-
PUT - Causes DynamoDB to
* create a new item with the specified primary key, and then adds the
* attribute.
-
DELETE - Nothing happens,
* because attributes cannot be deleted from a nonexistent item. The
* operation succeeds, but DynamoDB does not create a new item.
* -
ADD - Causes DynamoDB to create an item with the
* supplied primary key and number (or set of numbers) for the attribute
* value. The only data types allowed are Number and Number Set.
*
If you provide any attributes that are part of an
* index key, then the data types for those attributes must match those
* of the schema in the table's attribute definition.
* @param returnValues Use ReturnValues if you want to get the
* item attributes as they appeared either before or after they were
* updated. For UpdateItem, the valid values are:
-
*
NONE - If ReturnValues is not specified, or if
* its value is NONE, then nothing is returned. (This
* setting is the default for ReturnValues.)
-
*
ALL_OLD - If UpdateItem overwrote an attribute
* name-value pair, then the content of the old item is returned.
* -
UPDATED_OLD - The old versions of only the
* updated attributes are returned.
-
ALL_NEW -
* All of the attributes of the new version of the item are returned.
*
-
UPDATED_NEW - The new versions of only the
* updated attributes are returned.
There is no additional
* cost associated with requesting a return value aside from the small
* network and processing overhead of receiving a larger response. No
* Read Capacity Units are consumed.
Values returned are strongly
* consistent
*
* @return The response from the UpdateItem service method, as returned
* by AmazonDynamoDBv2.
*
* @throws ConditionalCheckFailedException
* @throws ItemCollectionSizeLimitExceededException
* @throws InternalServerErrorException
* @throws ProvisionedThroughputExceededException
* @throws ResourceNotFoundException
*
* @throws AmazonClientException
* If any internal errors are encountered inside the client while
* attempting to make the request or handle the response. For example
* if a network connection is not available.
* @throws AmazonServiceException
* If an error response is returned by AmazonDynamoDBv2 indicating
* either a problem with the data in the request, or a server side issue.
*/
public UpdateItemResult updateItem(String tableName, java.util.Map key, java.util.Map attributeUpdates, String returnValues)
throws AmazonServiceException, AmazonClientException;
/**
*
* Returns information about the table, including the current status of
* the table, when it was created, the primary key schema, and any
* indexes on the table.
*
*
* NOTE: If you issue a DescribeTable request immediately after a
* CreateTable request, DynamoDB might return a
* ResourceNotFoundException. This is because DescribeTable uses an
* eventually consistent query, and the metadata for your table might not
* be available at that moment. Wait for a few seconds, and then try the
* DescribeTable request again.
*
*
* @param tableName The name of the table to describe.
*
* @return The response from the DescribeTable service method, as
* returned by AmazonDynamoDBv2.
*
* @throws InternalServerErrorException
* @throws ResourceNotFoundException
*
* @throws AmazonClientException
* If any internal errors are encountered inside the client while
* attempting to make the request or handle the response. For example
* if a network connection is not available.
* @throws AmazonServiceException
* If an error response is returned by AmazonDynamoDBv2 indicating
* either a problem with the data in the request, or a server side issue.
*/
public DescribeTableResult describeTable(String tableName)
throws AmazonServiceException, AmazonClientException;
/**
*
* Creates a new item, or replaces an old item with a new item. If an
* item that has the same primary key as the new item already exists in
* the specified table, the new item completely replaces the existing
* item. You can perform a conditional put operation (add a new item if
* one with the specified primary key doesn't exist), or replace an
* existing item if it has certain attribute values.
*
*
* In addition to putting an item, you can also return the item's
* attribute values in the same operation, using the ReturnValues
* parameter.
*
*
* When you add an item, the primary key attribute(s) are the only
* required attributes. Attribute values cannot be null. String and
* Binary type attributes must have lengths greater than zero. Set type
* attributes cannot be empty. Requests with empty values will be
* rejected with a ValidationException exception.
*
*
* You can request that PutItem return either a copy of the
* original item (before the update) or a copy of the updated item (after
* the update). For more information, see the ReturnValues
* description below.
*
*
* NOTE: To prevent a new item from replacing an existing item,
* use a conditional expression that contains the attribute_not_exists
* function with the name of the attribute being used as the partition
* key for the table. Since every record must contain that attribute,
* the attribute_not_exists function will only succeed if no matching
* item exists.
*
*
* For more information about using this API, see
* Working with Items
* in the Amazon DynamoDB Developer Guide .
*
*
* @param tableName The name of the table to contain the item.
* @param item A map of attribute name/value pairs, one for each
* attribute. Only the primary key attributes are required; you can
* optionally provide other attribute name-value pairs for the item.
* You must provide all of the attributes for the primary key. For
* example, with a simple primary key, you only need to provide a value
* for the partition key. For a composite primary key, you must provide
* both values for both the partition key and the sort key.
If you
* specify any attributes that are part of an index key, then the data
* types for those attributes must match those of the schema in the
* table's attribute definition.
For more information about primary
* keys, see Primary
* Key in the Amazon DynamoDB Developer Guide.
Each element
* in the Item map is an AttributeValue object.
*
* @return The response from the PutItem service method, as returned by
* AmazonDynamoDBv2.
*
* @throws ConditionalCheckFailedException
* @throws ItemCollectionSizeLimitExceededException
* @throws InternalServerErrorException
* @throws ProvisionedThroughputExceededException
* @throws ResourceNotFoundException
*
* @throws AmazonClientException
* If any internal errors are encountered inside the client while
* attempting to make the request or handle the response. For example
* if a network connection is not available.
* @throws AmazonServiceException
* If an error response is returned by AmazonDynamoDBv2 indicating
* either a problem with the data in the request, or a server side issue.
*/
public PutItemResult putItem(String tableName, java.util.Map item)
throws AmazonServiceException, AmazonClientException;
/**
*
* Creates a new item, or replaces an old item with a new item. If an
* item that has the same primary key as the new item already exists in
* the specified table, the new item completely replaces the existing
* item. You can perform a conditional put operation (add a new item if
* one with the specified primary key doesn't exist), or replace an
* existing item if it has certain attribute values.
*
*
* In addition to putting an item, you can also return the item's
* attribute values in the same operation, using the ReturnValues
* parameter.
*
*
* When you add an item, the primary key attribute(s) are the only
* required attributes. Attribute values cannot be null. String and
* Binary type attributes must have lengths greater than zero. Set type
* attributes cannot be empty. Requests with empty values will be
* rejected with a ValidationException exception.
*
*
* You can request that PutItem return either a copy of the
* original item (before the update) or a copy of the updated item (after
* the update). For more information, see the ReturnValues
* description below.
*
*
* NOTE: To prevent a new item from replacing an existing item,
* use a conditional expression that contains the attribute_not_exists
* function with the name of the attribute being used as the partition
* key for the table. Since every record must contain that attribute,
* the attribute_not_exists function will only succeed if no matching
* item exists.
*
*
* For more information about using this API, see
* Working with Items
* in the Amazon DynamoDB Developer Guide .
*
*
* @param tableName The name of the table to contain the item.
* @param item A map of attribute name/value pairs, one for each
* attribute. Only the primary key attributes are required; you can
* optionally provide other attribute name-value pairs for the item.
* You must provide all of the attributes for the primary key. For
* example, with a simple primary key, you only need to provide a value
* for the partition key. For a composite primary key, you must provide
* both values for both the partition key and the sort key.
If you
* specify any attributes that are part of an index key, then the data
* types for those attributes must match those of the schema in the
* table's attribute definition.
For more information about primary
* keys, see Primary
* Key in the Amazon DynamoDB Developer Guide.
Each element
* in the Item map is an AttributeValue object.
* @param returnValues Use ReturnValues if you want to get the
* item attributes as they appeared before they were updated with the
* PutItem request. For PutItem, the valid values are:
* -
NONE - If ReturnValues is not specified,
* or if its value is NONE, then nothing is returned. (This
* setting is the default for ReturnValues.)
-
*
ALL_OLD - If PutItem overwrote an attribute
* name-value pair, then the content of the old item is returned.
*
*
* @return The response from the PutItem service method, as returned by
* AmazonDynamoDBv2.
*
* @throws ConditionalCheckFailedException
* @throws ItemCollectionSizeLimitExceededException
* @throws InternalServerErrorException
* @throws ProvisionedThroughputExceededException
* @throws ResourceNotFoundException
*
* @throws AmazonClientException
* If any internal errors are encountered inside the client while
* attempting to make the request or handle the response. For example
* if a network connection is not available.
* @throws AmazonServiceException
* If an error response is returned by AmazonDynamoDBv2 indicating
* either a problem with the data in the request, or a server side issue.
*/
public PutItemResult putItem(String tableName, java.util.Map item, String returnValues)
throws AmazonServiceException, AmazonClientException;
/**
* Shuts down this client object, releasing any resources that might be held
* open. This is an optional method, and callers are not expected to call
* it, but can if they want to explicitly release any open resources. Once a
* client has been shutdown, it should not be used to make any more
* requests.
*/
public void shutdown();
/**
* Returns additional metadata for a previously executed successful request, typically used for
* debugging issues where a service isn't acting as expected. This data isn't considered part
* of the result data returned by an operation, so it's available through this separate,
* diagnostic interface.
*
* Response metadata is only cached for a limited period of time, so if you need to access
* this extra diagnostic information for an executed request, you should use this method
* to retrieve it as soon as possible after executing a request.
*
* @param request
* The originally executed request.
*
* @return The response metadata for the specified request, or null if none
* is available.
*/
public ResponseMetadata getCachedResponseMetadata(AmazonWebServiceRequest request);
}