Query a DynamoDB table using an AWS SDK - AWS SDK Code Examples

There are more AWS SDK examples available in the AWS Doc SDK Examples GitHub repo.

Query a DynamoDB table using an AWS SDK

The following code examples show how to query a DynamoDB table.

.NET
AWS SDK for .NET
Note

There's more on GitHub. Find the complete example and learn how to set up and run in the AWS Code Examples Repository.

/// <summary> /// Queries the table for movies released in a particular year and /// then displays the information for the movies returned. /// </summary> /// <param name="client">The initialized DynamoDB client object.</param> /// <param name="tableName">The name of the table to query.</param> /// <param name="year">The release year for which we want to /// view movies.</param> /// <returns>The number of movies that match the query.</returns> public static async Task<int> QueryMoviesAsync(AmazonDynamoDBClient client, string tableName, int year) { var movieTable = Table.LoadTable(client, tableName); var filter = new QueryFilter("year", QueryOperator.Equal, year); Console.WriteLine("\nFind movies released in: {year}:"); var config = new QueryOperationConfig() { Limit = 10, // 10 items per page. Select = SelectValues.SpecificAttributes, AttributesToGet = new List<string> { "title", "year", }, ConsistentRead = true, Filter = filter, }; // Value used to track how many movies match the // supplied criteria. var moviesFound = 0; Search search = movieTable.Query(config); do { var movieList = await search.GetNextSetAsync(); moviesFound += movieList.Count; foreach (var movie in movieList) { DisplayDocument(movie); } } while (!search.IsDone); return moviesFound; }
  • For API details, see Query in AWS SDK for .NET API Reference.

C++
SDK for C++
Note

There's more on GitHub. Find the complete example and learn how to set up and run in the AWS Code Examples Repository.

//! Perform a query on an Amazon DynamoDB Table and retrieve items. /*! \sa queryItem() \param tableName: The table name. \param partitionKey: The partition key. \param partitionValue: The value for the partition key. \param projectionExpression: The projections expression, which is ignored if empty. \param clientConfiguration: AWS client configuration. \return bool: Function succeeded. */ /* * The partition key attribute is searched with the specified value. By default, all fields and values * contained in the item are returned. If an optional projection expression is * specified on the command line, only the specified fields and values are * returned. */ bool AwsDoc::DynamoDB::queryItems(const Aws::String &tableName, const Aws::String &partitionKey, const Aws::String &partitionValue, const Aws::String &projectionExpression, const Aws::Client::ClientConfiguration &clientConfiguration) { Aws::DynamoDB::DynamoDBClient dynamoClient(clientConfiguration); Aws::DynamoDB::Model::QueryRequest request; request.SetTableName(tableName); if (!projectionExpression.empty()) { request.SetProjectionExpression(projectionExpression); } // Set query key condition expression. request.SetKeyConditionExpression(partitionKey + "= :valueToMatch"); // Set Expression AttributeValues. Aws::Map<Aws::String, Aws::DynamoDB::Model::AttributeValue> attributeValues; attributeValues.emplace(":valueToMatch", partitionValue); request.SetExpressionAttributeValues(attributeValues); bool result = true; // "exclusiveStartKey" is used for pagination. Aws::Map<Aws::String, Aws::DynamoDB::Model::AttributeValue> exclusiveStartKey; do { if (!exclusiveStartKey.empty()) { request.SetExclusiveStartKey(exclusiveStartKey); exclusiveStartKey.clear(); } // Perform Query operation. const Aws::DynamoDB::Model::QueryOutcome &outcome = dynamoClient.Query(request); if (outcome.IsSuccess()) { // Reference the retrieved items. const Aws::Vector<Aws::Map<Aws::String, Aws::DynamoDB::Model::AttributeValue>> &items = outcome.GetResult().GetItems(); if (!items.empty()) { std::cout << "Number of items retrieved from Query: " << items.size() << std::endl; // Iterate each item and print. for (const auto &item: items) { std::cout << "******************************************************" << std::endl; // Output each retrieved field and its value. for (const auto &i: item) std::cout << i.first << ": " << i.second.GetS() << std::endl; } } else { std::cout << "No item found in table: " << tableName << std::endl; } exclusiveStartKey = outcome.GetResult().GetLastEvaluatedKey(); } else { std::cerr << "Failed to Query items: " << outcome.GetError().GetMessage(); result = false; break; } } while (!exclusiveStartKey.empty()); return result; }
  • For API details, see Query in AWS SDK for C++ API Reference.

Go
SDK for Go V2
Note

There's more on GitHub. Find the complete example and learn how to set up and run in the AWS Code Examples Repository.

// TableBasics encapsulates the Amazon DynamoDB service actions used in the examples. // It contains a DynamoDB service client that is used to act on the specified table. type TableBasics struct { DynamoDbClient *dynamodb.Client TableName string } // Query gets all movies in the DynamoDB table that were released in the specified year. // The function uses the `expression` package to build the key condition expression // that is used in the query. func (basics TableBasics) Query(releaseYear int) ([]Movie, error) { var err error var response *dynamodb.QueryOutput var movies []Movie keyEx := expression.Key("year").Equal(expression.Value(releaseYear)) expr, err := expression.NewBuilder().WithKeyCondition(keyEx).Build() if err != nil { log.Printf("Couldn't build epxression for query. Here's why: %v\n", err) } else { response, err = basics.DynamoDbClient.Query(context.TODO(), &dynamodb.QueryInput{ TableName: aws.String(basics.TableName), ExpressionAttributeNames: expr.Names(), ExpressionAttributeValues: expr.Values(), KeyConditionExpression: expr.KeyCondition(), }) if err != nil { log.Printf("Couldn't query for movies released in %v. Here's why: %v\n", releaseYear, err) } else { err = attributevalue.UnmarshalListOfMaps(response.Items, &movies) if err != nil { log.Printf("Couldn't unmarshal query response. Here's why: %v\n", err) } } } return movies, err }
  • For API details, see Query in AWS SDK for Go API Reference.

Java
SDK for Java 2.x
Note

There's more on GitHub. Find the complete example and learn how to set up and run in the AWS Code Examples Repository.

Queries a table by using the enhanced client.

public static String queryTable(DynamoDbEnhancedClient enhancedClient) { try{ DynamoDbTable<Customer> mappedTable = enhancedClient.table("Customer", TableSchema.fromBean(Customer.class)); QueryConditional queryConditional = QueryConditional.keyEqualTo(Key.builder() .partitionValue("id101") .build()); // Get items in the table and write out the ID value. Iterator<Customer> results = mappedTable.query(queryConditional).items().iterator(); String result=""; while (results.hasNext()) { Customer rec = results.next(); result = rec.getId(); System.out.println("The record id is "+result); } return result; } catch (DynamoDbException e) { System.err.println(e.getMessage()); System.exit(1); } return ""; }

Queries a table by using the enhanced client and a secondary index.

public static void queryIndex(DynamoDbClient ddb, String tableName) { try { // Create a DynamoDbEnhancedClient and use the DynamoDbClient object. DynamoDbEnhancedClient enhancedClient = DynamoDbEnhancedClient.builder() .dynamoDbClient(ddb) .build(); //Create a DynamoDbTable object based on Movies. DynamoDbTable<Movies> table = enhancedClient.table("Movies", TableSchema.fromBean(Movies.class)); String dateVal = "2013"; DynamoDbIndex<Movies> secIndex = enhancedClient.table("Movies", TableSchema.fromBean(Movies.class)) .index("year-index"); AttributeValue attVal = AttributeValue.builder() .n(dateVal) .build(); // Create a QueryConditional object that's used in the query operation. QueryConditional queryConditional = QueryConditional .keyEqualTo(Key.builder().partitionValue(attVal) .build()); // Get items in the table. SdkIterable<Page<Movies>> results = secIndex.query(QueryEnhancedRequest.builder() .queryConditional(queryConditional) .limit(300) .build()); // Display the results. results.forEach(page -> { List<Movies> allMovies = page.items(); for (Movies myMovies: allMovies) { System.out.println("The movie title is " + myMovies.getTitle() + ". The year is " + myMovies.getYear()); } }); } catch (DynamoDbException e) { System.err.println(e.getMessage()); System.exit(1); } }

Queries a table by using the DynamoDbClient.

public static int queryTable(DynamoDbClient ddb, String tableName, String partitionKeyName, String partitionKeyVal, String partitionAlias) { // Set up an alias for the partition key name in case it's a reserved word. HashMap<String,String> attrNameAlias = new HashMap<String,String>(); attrNameAlias.put(partitionAlias, partitionKeyName); // Set up mapping of the partition name with the value. HashMap<String, AttributeValue> attrValues = new HashMap<>(); attrValues.put(":"+partitionKeyName, AttributeValue.builder() .s(partitionKeyVal) .build()); QueryRequest queryReq = QueryRequest.builder() .tableName(tableName) .keyConditionExpression(partitionAlias + " = :" + partitionKeyName) .expressionAttributeNames(attrNameAlias) .expressionAttributeValues(attrValues) .build(); try { QueryResponse response = ddb.query(queryReq); return response.count(); } catch (DynamoDbException e) { System.err.println(e.getMessage()); System.exit(1); } return -1; }

Queries a table by using the DynamoDbClient and a secondary index.

public static void queryIndex(DynamoDbClient ddb, String tableName) { try { Map<String, String> expressionAttributesNames = new HashMap<>(); expressionAttributesNames.put("#year", "year"); Map<String, AttributeValue> expressionAttributeValues = new HashMap<>(); expressionAttributeValues.put(":yearValue", AttributeValue.builder().n("2013").build()); QueryRequest request = QueryRequest.builder() .tableName(tableName) .indexName("year-index") .keyConditionExpression("#year = :yearValue") .expressionAttributeNames(expressionAttributesNames) .expressionAttributeValues(expressionAttributeValues) .build(); System.out.println("=== Movie Titles ==="); QueryResponse response = ddb.query(request); response.items() .forEach(movie -> System.out.println(movie.get("title").s())); } catch (DynamoDbException e) { System.err.println(e.getMessage()); System.exit(1); } }
  • For API details, see Query in AWS SDK for Java 2.x API Reference.

JavaScript
SDK for JavaScript V3
Note

There's more on GitHub. Find the complete example and learn how to set up and run in the AWS Code Examples Repository.

Create the client.

// Create service client module using ES6 syntax. import { DynamoDBClient } from "@aws-sdk/client-dynamodb"; // Set the AWS Region. const REGION = "REGION"; //e.g. "us-east-1" // Create an Amazon DynamoDB service client object. const ddbClient = new DynamoDBClient({ region: REGION }); export { ddbClient };

Query the table.

// Import required AWS SDK clients and commands for Node.js import { QueryCommand } from "@aws-sdk/client-dynamodb"; import { ddbClient } from "./libs/ddbClient.js"; // Set the parameters export const params = { KeyConditionExpression: "Season = :s and Episode > :e", FilterExpression: "contains (Subtitle, :topic)", ExpressionAttributeValues: { ":s": { N: "1" }, ":e": { N: "2" }, ":topic": { S: "SubTitle" }, }, ProjectionExpression: "Episode, Title, Subtitle", TableName: "EPISODES_TABLE", }; export const run = async () => { try { const data = await ddbClient.send(new QueryCommand(params)); data.Items.forEach(function (element) { console.log(element.Title.S + " (" + element.Subtitle.S + ")"); }); return data; } catch (err) { console.error(err); } }; run();

Create the client for the DynamoDB document client.

// Create service client module using ES6 syntax. import { DynamoDBDocumentClient} from "@aws-sdk/lib-dynamodb"; import {ddbClient} from "./ddbClient"; const marshallOptions = { // Whether to automatically convert empty strings, blobs, and sets to `null`. convertEmptyValues: false, // false, by default. // Whether to remove undefined values while marshalling. removeUndefinedValues: false, // false, by default. // Whether to convert typeof object to map attribute. convertClassInstanceToMap: false, // false, by default. }; const unmarshallOptions = { // Whether to return numbers as a string instead of converting them to native JavaScript numbers. wrapNumbers: false, // false, by default. }; const translateConfig = { marshallOptions, unmarshallOptions }; // Create the DynamoDB Document client. const ddbDocClient = DynamoDBDocumentClient.from(ddbClient, translateConfig); export { ddbDocClient };

Query the table using the DynamoDB document client.

import { QueryCommand } from "@aws-sdk/lib-dynamodb"; import { ddbDocClient } from "../libs/ddbDocClient.js"; // Set the parameters. export const params = { ExpressionAttributeNames: { "#r": "rank", "#y": "year" }, ProjectionExpression: "#r, #y, title", TableName: "TABLE_NAME", ExpressionAttributeValues: { ":t": "MOVIE_NAME", ":y": "MOVIE_YEAR", ":r": "MOVIE_RANK", }, KeyConditionExpression: "title = :t and #y = :y", FilterExpression: "info.#r = :r", }; export const queryTable = async () => { try { const data = await ddbDocClient.send(new QueryCommand(params)); for (let i = 0; i < data.Items.length; i++) { console.log( "Success. Items with rank of " + "MOVIE_RANK" + " include\n" + "Year = " + data.Items[i].year + " Title = " + data.Items[i].title ); } } catch (err) { console.log("Error", err); } }; queryTable();
SDK for JavaScript V2
Note

There's more on GitHub. Find the complete example and learn how to set up and run in the AWS Code Examples Repository.

// Load the AWS SDK for Node.js var AWS = require('aws-sdk'); // Set the region AWS.config.update({region: 'REGION'}); // Create DynamoDB document client var docClient = new AWS.DynamoDB.DocumentClient({apiVersion: '2012-08-10'}); var params = { ExpressionAttributeValues: { ':s': 2, ':e': 9, ':topic': 'PHRASE' }, KeyConditionExpression: 'Season = :s and Episode > :e', FilterExpression: 'contains (Subtitle, :topic)', TableName: 'EPISODES_TABLE' }; docClient.query(params, function(err, data) { if (err) { console.log("Error", err); } else { console.log("Success", data.Items); } });
Kotlin
SDK for Kotlin
Note

This is prerelease documentation for a feature in preview release. It is subject to change.

Note

There's more on GitHub. Find the complete example and learn how to set up and run in the AWS Code Examples Repository.

suspend fun queryDynTable( tableNameVal: String, partitionKeyName: String, partitionKeyVal: String, partitionAlias: String ): Int { val attrNameAlias = mutableMapOf<String, String>() attrNameAlias[partitionAlias] = partitionKeyName // Set up mapping of the partition name with the value. val attrValues = mutableMapOf<String, AttributeValue>() attrValues[":$partitionKeyName"] = AttributeValue.S(partitionKeyVal) val request = QueryRequest { tableName = tableNameVal keyConditionExpression = "$partitionAlias = :$partitionKeyName" expressionAttributeNames = attrNameAlias this.expressionAttributeValues = attrValues } DynamoDbClient { region = "us-east-1" }.use { ddb -> val response = ddb.query(request) return response.count } }
  • For API details, see Query in AWS SDK for Kotlin API reference.

PHP
SDK for PHP
Note

There's more on GitHub. Find the complete example and learn how to set up and run in the AWS Code Examples Repository.

$birthKey = [ 'Key' => [ 'year' => [ 'N' => "$birthYear", ], ], ]; $result = $service->query($tableName, $birthKey); public function query(string $tableName, $key) { $expressionAttributeValues = []; $expressionAttributeNames = []; $keyConditionExpression = ""; $index = 1; foreach ($key as $name => $value) { $keyConditionExpression .= "#" . array_key_first($value) . " = :v$index,"; $expressionAttributeNames["#" . array_key_first($value)] = array_key_first($value); $hold = array_pop($value); $expressionAttributeValues[":v$index"] = [ array_key_first($hold) => array_pop($hold), ]; } $keyConditionExpression = substr($keyConditionExpression, 0, -1); $query = [ 'ExpressionAttributeValues' => $expressionAttributeValues, 'ExpressionAttributeNames' => $expressionAttributeNames, 'KeyConditionExpression' => $keyConditionExpression, 'TableName' => $tableName, ]; return $this->dynamoDbClient->query($query); }
  • For API details, see Query in AWS SDK for PHP API Reference.

Python
SDK for Python (Boto3)
Note

There's more on GitHub. Find the complete example and learn how to set up and run in the AWS Code Examples Repository.

Query items by using a key condition expression.

class Movies: """Encapsulates an Amazon DynamoDB table of movie data.""" def __init__(self, dyn_resource): """ :param dyn_resource: A Boto3 DynamoDB resource. """ self.dyn_resource = dyn_resource self.table = None def query_movies(self, year): """ Queries for movies that were released in the specified year. :param year: The year to query. :return: The list of movies that were released in the specified year. """ try: response = self.table.query(KeyConditionExpression=Key('year').eq(year)) except ClientError as err: logger.error( "Couldn't query for movies released in %s. Here's why: %s: %s", year, err.response['Error']['Code'], err.response['Error']['Message']) raise else: return response['Items']

Query items and project them to return a subset of data.

class UpdateQueryWrapper: def __init__(self, table): self.table = table def query_and_project_movies(self, year, title_bounds): """ Query for movies that were released in a specified year and that have titles that start within a range of letters. A projection expression is used to return a subset of data for each movie. :param year: The release year to query. :param title_bounds: The range of starting letters to query. :return: The list of movies. """ try: response = self.table.query( ProjectionExpression="#yr, title, info.genres, info.actors[0]", ExpressionAttributeNames={"#yr": "year"}, KeyConditionExpression=( Key('year').eq(year) & Key('title').between(title_bounds['first'], title_bounds['second']))) except ClientError as err: if err.response['Error']['Code'] == "ValidationException": logger.warning( "There's a validation error. Here's the message: %s: %s", err.response['Error']['Code'], err.response['Error']['Message']) else: logger.error( "Couldn't query for movies. Here's why: %s: %s", err.response['Error']['Code'], err.response['Error']['Message']) raise else: return response['Items']
  • For API details, see Query in AWS SDK for Python (Boto3) API Reference.

Ruby
SDK for Ruby
Note

There's more on GitHub. Find the complete example and learn how to set up and run in the AWS Code Examples Repository.

# Queries for movies that were released in the specified year. # # @param year [Integer] The year to query. # @return [Array] The list of movies that were released in the specified year. def query_movies(year) response = @table.query( key_condition_expression: "#yr = :year", expression_attribute_names: {"#yr" => "year"}, expression_attribute_values: {":year" => year}) rescue Aws::Errors::ServiceError => e puts("Couldn't query for movies released in #{year}. Here's why:") puts("\t#{e.code}: #{e.message}") raise else response.items end
  • For API details, see Query in AWS SDK for Ruby API Reference.

Rust
SDK for Rust
Note

This documentation is for an SDK in preview release. The SDK is subject to change and should not be used in production.

Note

There's more on GitHub. Find the complete example and learn how to set up and run in the AWS Code Examples Repository.

Find the movies made in the specified year.

pub async fn movies_in_year( client: &Client, table_name: &str, year: u16, ) -> Result<Vec<Movie>, MovieError> { let results = client .query() .table_name(table_name) .key_condition_expression("#yr = :yyyy") .expression_attribute_names("#yr", "year") .expression_attribute_values(":yyyy", AttributeValue::N(year.to_string())) .send() .await?; if let Some(items) = results.items { let movies = items.iter().map(|v| v.into()).collect(); Ok(movies) } else { Ok(vec![]) } }
  • For API details, see Query in AWS SDK for Rust API reference.