DynamoDB examples using SDK for Swift
The following code examples show you how to perform actions and implement common scenarios by using the AWS SDK for Swift with DynamoDB.
Basics are code examples that show you how to perform the essential operations within a service.
Actions are code excerpts from larger programs and must be run in context. While actions show you how to call individual service functions, you can see actions in context in their related scenarios.
Each example includes a link to the complete source code, where you can find instructions on how to set up and run the code in context.
Basics
The following code example shows how to:
Create a table that can hold movie data.
Put, get, and update a single movie in the table.
Write movie data to the table from a sample JSON file.
Query for movies that were released in a given year.
Scan for movies that were released in a range of years.
Delete a movie from the table, then delete the table.
- SDK for Swift
-
Note
This is prerelease documentation for an SDK 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
. A Swift class that handles DynamoDB calls to the SDK for Swift.
import Foundation import AWSDynamoDB /// An enumeration of error codes representing issues that can arise when using /// the `MovieTable` class. enum MoviesError: Error { /// The specified table wasn't found or couldn't be created. case TableNotFound /// The specified item wasn't found or couldn't be created. case ItemNotFound /// The Amazon DynamoDB client is not properly initialized. case UninitializedClient /// The table status reported by Amazon DynamoDB is not recognized. case StatusUnknown /// One or more specified attribute values are invalid or missing. case InvalidAttributes } /// A class representing an Amazon DynamoDB table containing movie /// information. public class MovieTable { var ddbClient: DynamoDBClient? = nil let tableName: String /// Create an object representing a movie table in an Amazon DynamoDB /// database. /// /// - Parameters: /// - region: The Amazon Region to create the database in. /// - tableName: The name to assign to the table. If not specified, a /// random table name is generated automatically. /// /// > Note: The table is not necessarily available when this function /// returns. Use `tableExists()` to check for its availability, or /// `awaitTableActive()` to wait until the table's status is reported as /// ready to use by Amazon DynamoDB. /// init(region: String = "us-east-2", tableName: String) async throws { ddbClient = try DynamoDBClient(region: region) self.tableName = tableName try await self.createTable() } /// /// Create a movie table in the Amazon DynamoDB data store. /// private func createTable() async throws { guard let client = self.ddbClient else { throw MoviesError.UninitializedClient } let input = CreateTableInput( attributeDefinitions: [ DynamoDBClientTypes.AttributeDefinition(attributeName: "year", attributeType: .n), DynamoDBClientTypes.AttributeDefinition(attributeName: "title", attributeType: .s), ], keySchema: [ DynamoDBClientTypes.KeySchemaElement(attributeName: "year", keyType: .hash), DynamoDBClientTypes.KeySchemaElement(attributeName: "title", keyType: .range) ], provisionedThroughput: DynamoDBClientTypes.ProvisionedThroughput( readCapacityUnits: 10, writeCapacityUnits: 10 ), tableName: self.tableName ) let output = try await client.createTable(input: input) if output.tableDescription == nil { throw MoviesError.TableNotFound } } /// Check to see if the table exists online yet. /// /// - Returns: `true` if the table exists, or `false` if not. /// func tableExists() async throws -> Bool { guard let client = self.ddbClient else { throw MoviesError.UninitializedClient } let input = DescribeTableInput( tableName: tableName ) let output = try await client.describeTable(input: input) guard let description = output.table else { throw MoviesError.TableNotFound } return (description.tableName == self.tableName) } /// /// Waits for the table to exist and for its status to be active. /// func awaitTableActive() async throws { while (try await tableExists() == false) { Thread.sleep(forTimeInterval: 0.25) } while (try await getTableStatus() != .active) { Thread.sleep(forTimeInterval: 0.25) } } /// /// Deletes the table from Amazon DynamoDB. /// func deleteTable() async throws { guard let client = self.ddbClient else { throw MoviesError.UninitializedClient } let input = DeleteTableInput( tableName: self.tableName ) _ = try await client.deleteTable(input: input) } /// Get the table's status. /// /// - Returns: The table status, as defined by the /// `DynamoDBClientTypes.TableStatus` enum. /// func getTableStatus() async throws -> DynamoDBClientTypes.TableStatus { guard let client = self.ddbClient else { throw MoviesError.UninitializedClient } let input = DescribeTableInput( tableName: self.tableName ) let output = try await client.describeTable(input: input) guard let description = output.table else { throw MoviesError.TableNotFound } guard let status = description.tableStatus else { throw MoviesError.StatusUnknown } return status } /// Populate the movie database from the specified JSON file. /// /// - Parameter jsonPath: Path to a JSON file containing movie data. /// func populate(jsonPath: String) async throws { guard let client = self.ddbClient else { throw MoviesError.UninitializedClient } // Create a Swift `URL` and use it to load the file into a `Data` // object. Then decode the JSON into an array of `Movie` objects. let fileUrl = URL(fileURLWithPath: jsonPath) let jsonData = try Data(contentsOf: fileUrl) var movieList = try JSONDecoder().decode([Movie].self, from: jsonData) // Truncate the list to the first 200 entries or so for this example. if movieList.count > 200 { movieList = Array(movieList[...199]) } // Before sending records to the database, break the movie list into // 25-entry chunks, which is the maximum size of a batch item request. let count = movieList.count let chunks = stride(from: 0, to: count, by: 25).map { Array(movieList[$0 ..< Swift.min($0 + 25, count)]) } // For each chunk, create a list of write request records and populate // them with `PutRequest` requests, each specifying one movie from the // chunk. Once the chunk's items are all in the `PutRequest` list, // send them to Amazon DynamoDB using the // `DynamoDBClient.batchWriteItem()` function. for chunk in chunks { var requestList: [DynamoDBClientTypes.WriteRequest] = [] for movie in chunk { let item = try await movie.getAsItem() let request = DynamoDBClientTypes.WriteRequest( putRequest: .init( item: item ) ) requestList.append(request) } let input = BatchWriteItemInput(requestItems: [tableName: requestList]) _ = try await client.batchWriteItem(input: input) } } /// Add a movie specified as a `Movie` structure to the Amazon DynamoDB /// table. /// /// - Parameter movie: The `Movie` to add to the table. /// func add(movie: Movie) async throws { guard let client = self.ddbClient else { throw MoviesError.UninitializedClient } // Get a DynamoDB item containing the movie data. let item = try await movie.getAsItem() // Send the `PutItem` request to Amazon DynamoDB. let input = PutItemInput( item: item, tableName: self.tableName ) _ = try await client.putItem(input: input) } /// Given a movie's details, add a movie to the Amazon DynamoDB table. /// /// - Parameters: /// - title: The movie's title as a `String`. /// - year: The release year of the movie (`Int`). /// - rating: The movie's rating if available (`Double`; default is /// `nil`). /// - plot: A summary of the movie's plot (`String`; default is `nil`, /// indicating no plot summary is available). /// func add(title: String, year: Int, rating: Double? = nil, plot: String? = nil) async throws { let movie = Movie(title: title, year: year, rating: rating, plot: plot) try await self.add(movie: movie) } /// Return a `Movie` record describing the specified movie from the Amazon /// DynamoDB table. /// /// - Parameters: /// - title: The movie's title (`String`). /// - year: The movie's release year (`Int`). /// /// - Throws: `MoviesError.ItemNotFound` if the movie isn't in the table. /// /// - Returns: A `Movie` record with the movie's details. func get(title: String, year: Int) async throws -> Movie { guard let client = self.ddbClient else { throw MoviesError.UninitializedClient } let input = GetItemInput( key: [ "year": .n(String(year)), "title": .s(title) ], tableName: self.tableName ) let output = try await client.getItem(input: input) guard let item = output.item else { throw MoviesError.ItemNotFound } let movie = try Movie(withItem: item) return movie } /// Get all the movies released in the specified year. /// /// - Parameter year: The release year of the movies to return. /// /// - Returns: An array of `Movie` objects describing each matching movie. /// func getMovies(fromYear year: Int) async throws -> [Movie] { guard let client = self.ddbClient else { throw MoviesError.UninitializedClient } let input = QueryInput( expressionAttributeNames: [ "#y": "year" ], expressionAttributeValues: [ ":y": .n(String(year)) ], keyConditionExpression: "#y = :y", tableName: self.tableName ) let output = try await client.query(input: input) guard let items = output.items else { throw MoviesError.ItemNotFound } // Convert the found movies into `Movie` objects and return an array // of them. var movieList: [Movie] = [] for item in items { let movie = try Movie(withItem: item) movieList.append(movie) } return movieList } /// Return an array of `Movie` objects released in the specified range of /// years. /// /// - Parameters: /// - firstYear: The first year of movies to return. /// - lastYear: The last year of movies to return. /// - startKey: A starting point to resume processing; always use `nil`. /// /// - Returns: An array of `Movie` objects describing the matching movies. /// /// > Note: The `startKey` parameter is used by this function when /// recursively calling itself, and should always be `nil` when calling /// directly. /// func getMovies(firstYear: Int, lastYear: Int, startKey: [Swift.String:DynamoDBClientTypes.AttributeValue]? = nil) async throws -> [Movie] { var movieList: [Movie] = [] guard let client = self.ddbClient else { throw MoviesError.UninitializedClient } let input = ScanInput( consistentRead: true, exclusiveStartKey: startKey, expressionAttributeNames: [ "#y": "year" // `year` is a reserved word, so use `#y` instead. ], expressionAttributeValues: [ ":y1": .n(String(firstYear)), ":y2": .n(String(lastYear)) ], filterExpression: "#y BETWEEN :y1 AND :y2", tableName: self.tableName ) let output = try await client.scan(input: input) guard let items = output.items else { return movieList } // Build an array of `Movie` objects for the returned items. for item in items { let movie = try Movie(withItem: item) movieList.append(movie) } // Call this function recursively to continue collecting matching // movies, if necessary. if output.lastEvaluatedKey != nil { let movies = try await self.getMovies(firstYear: firstYear, lastYear: lastYear, startKey: output.lastEvaluatedKey) movieList += movies } return movieList } /// Update the specified movie with new `rating` and `plot` information. /// /// - Parameters: /// - title: The title of the movie to update. /// - year: The release year of the movie to update. /// - rating: The new rating for the movie. /// - plot: The new plot summary string for the movie. /// /// - Returns: An array of mappings of attribute names to their new /// listing each item actually changed. Items that didn't need to change /// aren't included in this list. `nil` if no changes were made. /// func update(title: String, year: Int, rating: Double? = nil, plot: String? = nil) async throws -> [Swift.String:DynamoDBClientTypes.AttributeValue]? { guard let client = self.ddbClient else { throw MoviesError.UninitializedClient } // Build the update expression and the list of expression attribute // values. Include only the information that's changed. var expressionParts: [String] = [] var attrValues: [Swift.String:DynamoDBClientTypes.AttributeValue] = [:] if rating != nil { expressionParts.append("info.rating=:r") attrValues[":r"] = .n(String(rating!)) } if plot != nil { expressionParts.append("info.plot=:p") attrValues[":p"] = .s(plot!) } let expression: String = "set \(expressionParts.joined(separator: ", "))" let input = UpdateItemInput( // Create substitution tokens for the attribute values, to ensure // no conflicts in expression syntax. expressionAttributeValues: attrValues, // The key identifying the movie to update consists of the release // year and title. key: [ "year": .n(String(year)), "title": .s(title) ], returnValues: .updatedNew, tableName: self.tableName, updateExpression: expression ) let output = try await client.updateItem(input: input) guard let attributes: [Swift.String:DynamoDBClientTypes.AttributeValue] = output.attributes else { throw MoviesError.InvalidAttributes } return attributes } /// Delete a movie, given its title and release year. /// /// - Parameters: /// - title: The movie's title. /// - year: The movie's release year. /// func delete(title: String, year: Int) async throws { guard let client = self.ddbClient else { throw MoviesError.UninitializedClient } let input = DeleteItemInput( key: [ "year": .n(String(year)), "title": .s(title) ], tableName: self.tableName ) _ = try await client.deleteItem(input: input) } }
The structures used by the MovieTable class to represent movies.
import Foundation import AWSDynamoDB /// The optional details about a movie. public struct Details: Codable { /// The movie's rating, if available. var rating: Double? /// The movie's plot, if available. var plot: String? } /// A structure describing a movie. The `year` and `title` properties are /// required and are used as the key for Amazon DynamoDB operations. The /// `info` sub-structure's two properties, `rating` and `plot`, are optional. public struct Movie: Codable { /// The year in which the movie was released. var year: Int /// The movie's title. var title: String /// A `Details` object providing the optional movie rating and plot /// information. var info: Details /// Create a `Movie` object representing a movie, given the movie's /// details. /// /// - Parameters: /// - title: The movie's title (`String`). /// - year: The year in which the movie was released (`Int`). /// - rating: The movie's rating (optional `Double`). /// - plot: The movie's plot (optional `String`) init(title: String, year: Int, rating: Double? = nil, plot: String? = nil) { self.title = title self.year = year self.info = Details(rating: rating, plot: plot) } /// Create a `Movie` object representing a movie, given the movie's /// details. /// /// - Parameters: /// - title: The movie's title (`String`). /// - year: The year in which the movie was released (`Int`). /// - info: The optional rating and plot information for the movie in a /// `Details` object. init(title: String, year: Int, info: Details?){ self.title = title self.year = year if info != nil { self.info = info! } else { self.info = Details(rating: nil, plot: nil) } } /// /// Return a new `MovieTable` object, given an array mapping string to Amazon /// DynamoDB attribute values. /// /// - Parameter item: The item information provided to the form used by /// DynamoDB. This is an array of strings mapped to /// `DynamoDBClientTypes.AttributeValue` values. init(withItem item: [Swift.String:DynamoDBClientTypes.AttributeValue]) throws { // Read the attributes. guard let titleAttr = item["title"], let yearAttr = item["year"] else { throw MoviesError.ItemNotFound } let infoAttr = item["info"] ?? nil // Extract the values of the title and year attributes. if case .s(let titleVal) = titleAttr { self.title = titleVal } else { throw MoviesError.InvalidAttributes } if case .n(let yearVal) = yearAttr { self.year = Int(yearVal)! } else { throw MoviesError.InvalidAttributes } // Extract the rating and/or plot from the `info` attribute, if // they're present. var rating: Double? = nil var plot: String? = nil if infoAttr != nil, case .m(let infoVal) = infoAttr { let ratingAttr = infoVal["rating"] ?? nil let plotAttr = infoVal["plot"] ?? nil if ratingAttr != nil, case .n(let ratingVal) = ratingAttr { rating = Double(ratingVal) ?? nil } if plotAttr != nil, case .s(let plotVal) = plotAttr { plot = plotVal } } self.info = Details(rating: rating, plot: plot) } /// /// Return an array mapping attribute names to Amazon DynamoDB attribute /// values, representing the contents of the `Movie` record as a DynamoDB /// item. /// /// - Returns: The movie item as an array of type /// `[Swift.String:DynamoDBClientTypes.AttributeValue]`. /// func getAsItem() async throws -> [Swift.String:DynamoDBClientTypes.AttributeValue] { // Build the item record, starting with the year and title, which are // always present. var item: [Swift.String:DynamoDBClientTypes.AttributeValue] = [ "year": .n(String(self.year)), "title": .s(self.title) ] // Add the `info` field with the rating and/or plot if they're // available. var details: [Swift.String:DynamoDBClientTypes.AttributeValue] = [:] if (self.info.rating != nil || self.info.plot != nil) { if self.info.rating != nil { details["rating"] = .n(String(self.info.rating!)) } if self.info.plot != nil { details["plot"] = .s(self.info.plot!) } } item["info"] = .m(details) return item } }
A program that uses the MovieTable class to access a DynamoDB database.
import Foundation import ArgumentParser import AWSDynamoDB import ClientRuntime @testable import MovieList struct ExampleCommand: ParsableCommand { @Argument(help: "The path of the sample movie data JSON file.") var jsonPath: String = "../../../../resources/sample_files/movies.json" @Option(help: "The AWS Region to run AWS API calls in.") var awsRegion = "us-east-2" @Option( help: ArgumentHelp("The level of logging for the Swift SDK to perform."), completion: .list([ "critical", "debug", "error", "info", "notice", "trace", "warning" ]) ) var logLevel: String = "error" /// Configuration details for the command. static var configuration = CommandConfiguration( commandName: "basics", abstract: "A basic scenario demonstrating the usage of Amazon DynamoDB.", discussion: """ An example showing how to use Amazon DynamoDB to perform a series of common database activities on a simple movie database. """ ) /// Called by ``main()`` to asynchronously run the AWS example. func runAsync() async throws { print("Welcome to the AWS SDK for Swift basic scenario for Amazon DynamoDB!") SDKLoggingSystem.initialize(logLevel: .error) //===================================================================== // 1. Create the table. The Amazon DynamoDB table is represented by // the `MovieTable` class. //===================================================================== let tableName = "ddb-movies-sample-\(Int.random(in: 1...Int.max))" //let tableName = String.uniqueName(withPrefix: "ddb-movies-sample", maxDigits: 8) print("Creating table \"\(tableName)\"...") let movieDatabase = try await MovieTable(region: awsRegion, tableName: tableName) print("\nWaiting for table to be ready to use...") try await movieDatabase.awaitTableActive() //===================================================================== // 2. Add a movie to the table. //===================================================================== print("\nAdding a movie...") try await movieDatabase.add(title: "Avatar: The Way of Water", year: 2022) try await movieDatabase.add(title: "Not a Real Movie", year: 2023) //===================================================================== // 3. Update the plot and rating of the movie using an update // expression. //===================================================================== print("\nAdding details to the added movie...") _ = try await movieDatabase.update(title: "Avatar: The Way of Water", year: 2022, rating: 9.2, plot: "It's a sequel.") //===================================================================== // 4. Populate the table from the JSON file. //===================================================================== print("\nPopulating the movie database from JSON...") try await movieDatabase.populate(jsonPath: jsonPath) //===================================================================== // 5. Get a specific movie by key. In this example, the key is a // combination of `title` and `year`. //===================================================================== print("\nLooking for a movie in the table...") let gotMovie = try await movieDatabase.get(title: "This Is the End", year: 2013) print("Found the movie \"\(gotMovie.title)\", released in \(gotMovie.year).") print("Rating: \(gotMovie.info.rating ?? 0.0).") print("Plot summary: \(gotMovie.info.plot ?? "None.")") //===================================================================== // 6. Delete a movie. //===================================================================== print("\nDeleting the added movie...") try await movieDatabase.delete(title: "Avatar: The Way of Water", year: 2022) //===================================================================== // 7. Use a query with a key condition expression to return all movies // released in a given year. //===================================================================== print("\nGetting movies released in 1994...") let movieList = try await movieDatabase.getMovies(fromYear: 1994) for movie in movieList { print(" \(movie.title)") } //===================================================================== // 8. Use `scan()` to return movies released in a range of years. //===================================================================== print("\nGetting movies released between 1993 and 1997...") let scannedMovies = try await movieDatabase.getMovies(firstYear: 1993, lastYear: 1997) for movie in scannedMovies { print(" \(movie.title) (\(movie.year))") } //===================================================================== // 9. Delete the table. //===================================================================== print("\nDeleting the table...") try await movieDatabase.deleteTable() } } @main struct Main { static func main() async { let args = Array(CommandLine.arguments.dropFirst()) do { let command = try ExampleCommand.parse(args) try await command.runAsync() } catch { ExampleCommand.exit(withError: error) } } }
-
For API details, see the following topics in AWS SDK for Swift API reference.
-
Actions
The following code example shows how to use BatchGetItem
.
- SDK for Swift
-
Note
This is prerelease documentation for an SDK 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
. /// Gets an array of `Movie` objects describing all the movies in the /// specified list. Any movies that aren't found in the list have no /// corresponding entry in the resulting array. /// /// - Parameters /// - keys: An array of tuples, each of which specifies the title and /// release year of a movie to fetch from the table. /// /// - Returns: /// - An array of `Movie` objects describing each match found in the /// table. /// /// - Throws: /// - `MovieError.ClientUninitialized` if the DynamoDB client has not /// been initialized. /// - DynamoDB errors are thrown without change. func batchGet(keys: [(title: String, year: Int)]) async throws -> [Movie] { guard let client = self.ddbClient else { throw MovieError.ClientUninitialized } var movieList: [Movie] = [] var keyItems: [[Swift.String:DynamoDBClientTypes.AttributeValue]] = [] // Convert the list of keys into the form used by DynamoDB. for key in keys { let item: [Swift.String:DynamoDBClientTypes.AttributeValue] = [ "title": .s(key.title), "year": .n(String(key.year)) ] keyItems.append(item) } // Create the input record for `batchGetItem()`. The list of requested // items is in the `requestItems` property. This array contains one // entry for each table from which items are to be fetched. In this // example, there's only one table containing the movie data. // // If we wanted this program to also support searching for matches // in a table of book data, we could add a second `requestItem` // mapping the name of the book table to the list of items we want to // find in it. let input = BatchGetItemInput( requestItems: [ self.tableName: .init( consistentRead: true, keys: keyItems ) ] ) // Fetch the matching movies from the table. let output = try await client.batchGetItem(input: input) // Get the set of responses. If there aren't any, return the empty // movie list. guard let responses = output.responses else { return movieList } // Get the list of matching items for the table with the name // `tableName`. guard let responseList = responses[self.tableName] else { return movieList } // Create `Movie` items for each of the matching movies in the table // and add them to the `MovieList` array. for response in responseList { movieList.append(try Movie(withItem: response)) } return movieList }
-
For API details, see BatchGetItem
in AWS SDK for Swift API reference.
-
The following code example shows how to use BatchWriteItem
.
- SDK for Swift
-
Note
This is prerelease documentation for an SDK 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
. /// Populate the movie database from the specified JSON file. /// /// - Parameter jsonPath: Path to a JSON file containing movie data. /// func populate(jsonPath: String) async throws { guard let client = self.ddbClient else { throw MoviesError.UninitializedClient } // Create a Swift `URL` and use it to load the file into a `Data` // object. Then decode the JSON into an array of `Movie` objects. let fileUrl = URL(fileURLWithPath: jsonPath) let jsonData = try Data(contentsOf: fileUrl) var movieList = try JSONDecoder().decode([Movie].self, from: jsonData) // Truncate the list to the first 200 entries or so for this example. if movieList.count > 200 { movieList = Array(movieList[...199]) } // Before sending records to the database, break the movie list into // 25-entry chunks, which is the maximum size of a batch item request. let count = movieList.count let chunks = stride(from: 0, to: count, by: 25).map { Array(movieList[$0 ..< Swift.min($0 + 25, count)]) } // For each chunk, create a list of write request records and populate // them with `PutRequest` requests, each specifying one movie from the // chunk. Once the chunk's items are all in the `PutRequest` list, // send them to Amazon DynamoDB using the // `DynamoDBClient.batchWriteItem()` function. for chunk in chunks { var requestList: [DynamoDBClientTypes.WriteRequest] = [] for movie in chunk { let item = try await movie.getAsItem() let request = DynamoDBClientTypes.WriteRequest( putRequest: .init( item: item ) ) requestList.append(request) } let input = BatchWriteItemInput(requestItems: [tableName: requestList]) _ = try await client.batchWriteItem(input: input) } }
-
For API details, see BatchWriteItem
in AWS SDK for Swift API reference.
-
The following code example shows how to use CreateTable
.
- SDK for Swift
-
Note
This is prerelease documentation for an SDK 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
. /// /// Create a movie table in the Amazon DynamoDB data store. /// private func createTable() async throws { guard let client = self.ddbClient else { throw MoviesError.UninitializedClient } let input = CreateTableInput( attributeDefinitions: [ DynamoDBClientTypes.AttributeDefinition(attributeName: "year", attributeType: .n), DynamoDBClientTypes.AttributeDefinition(attributeName: "title", attributeType: .s), ], keySchema: [ DynamoDBClientTypes.KeySchemaElement(attributeName: "year", keyType: .hash), DynamoDBClientTypes.KeySchemaElement(attributeName: "title", keyType: .range) ], provisionedThroughput: DynamoDBClientTypes.ProvisionedThroughput( readCapacityUnits: 10, writeCapacityUnits: 10 ), tableName: self.tableName ) let output = try await client.createTable(input: input) if output.tableDescription == nil { throw MoviesError.TableNotFound } }
-
For API details, see CreateTable
in AWS SDK for Swift API reference.
-
The following code example shows how to use DeleteItem
.
- SDK for Swift
-
Note
This is prerelease documentation for an SDK 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
. /// Delete a movie, given its title and release year. /// /// - Parameters: /// - title: The movie's title. /// - year: The movie's release year. /// func delete(title: String, year: Int) async throws { guard let client = self.ddbClient else { throw MoviesError.UninitializedClient } let input = DeleteItemInput( key: [ "year": .n(String(year)), "title": .s(title) ], tableName: self.tableName ) _ = try await client.deleteItem(input: input) }
-
For API details, see DeleteItem
in AWS SDK for Swift API reference.
-
The following code example shows how to use DeleteTable
.
- SDK for Swift
-
Note
This is prerelease documentation for an SDK 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
. /// /// Deletes the table from Amazon DynamoDB. /// func deleteTable() async throws { guard let client = self.ddbClient else { throw MoviesError.UninitializedClient } let input = DeleteTableInput( tableName: self.tableName ) _ = try await client.deleteTable(input: input) }
-
For API details, see DeleteTable
in AWS SDK for Swift API reference.
-
The following code example shows how to use GetItem
.
- SDK for Swift
-
Note
This is prerelease documentation for an SDK 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
. /// Return a `Movie` record describing the specified movie from the Amazon /// DynamoDB table. /// /// - Parameters: /// - title: The movie's title (`String`). /// - year: The movie's release year (`Int`). /// /// - Throws: `MoviesError.ItemNotFound` if the movie isn't in the table. /// /// - Returns: A `Movie` record with the movie's details. func get(title: String, year: Int) async throws -> Movie { guard let client = self.ddbClient else { throw MoviesError.UninitializedClient } let input = GetItemInput( key: [ "year": .n(String(year)), "title": .s(title) ], tableName: self.tableName ) let output = try await client.getItem(input: input) guard let item = output.item else { throw MoviesError.ItemNotFound } let movie = try Movie(withItem: item) return movie }
-
For API details, see GetItem
in AWS SDK for Swift API reference.
-
The following code example shows how to use ListTables
.
- SDK for Swift
-
Note
This is prerelease documentation for an SDK 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
. /// Get a list of the DynamoDB tables available in the specified Region. /// /// - Returns: An array of strings listing all of the tables available /// in the Region specified when the session was created. public func getTableList() async throws -> [String] { var tableList: [String] = [] var lastEvaluated: String? = nil // Iterate over the list of tables, 25 at a time, until we have the // names of every table. Add each group to the `tableList` array. // Iteration is complete when `output.lastEvaluatedTableName` is `nil`. repeat { let input = ListTablesInput( exclusiveStartTableName: lastEvaluated, limit: 25 ) let output = try await self.session.listTables(input: input) guard let tableNames = output.tableNames else { return tableList } tableList.append(contentsOf: tableNames) lastEvaluated = output.lastEvaluatedTableName } while lastEvaluated != nil return tableList }
-
For API details, see ListTables
in AWS SDK for Swift API reference.
-
The following code example shows how to use PutItem
.
- SDK for Swift
-
Note
This is prerelease documentation for an SDK 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
. /// Add a movie specified as a `Movie` structure to the Amazon DynamoDB /// table. /// /// - Parameter movie: The `Movie` to add to the table. /// func add(movie: Movie) async throws { guard let client = self.ddbClient else { throw MoviesError.UninitializedClient } // Get a DynamoDB item containing the movie data. let item = try await movie.getAsItem() // Send the `PutItem` request to Amazon DynamoDB. let input = PutItemInput( item: item, tableName: self.tableName ) _ = try await client.putItem(input: input) } /// /// Return an array mapping attribute names to Amazon DynamoDB attribute /// values, representing the contents of the `Movie` record as a DynamoDB /// item. /// /// - Returns: The movie item as an array of type /// `[Swift.String:DynamoDBClientTypes.AttributeValue]`. /// func getAsItem() async throws -> [Swift.String:DynamoDBClientTypes.AttributeValue] { // Build the item record, starting with the year and title, which are // always present. var item: [Swift.String:DynamoDBClientTypes.AttributeValue] = [ "year": .n(String(self.year)), "title": .s(self.title) ] // Add the `info` field with the rating and/or plot if they're // available. var details: [Swift.String:DynamoDBClientTypes.AttributeValue] = [:] if (self.info.rating != nil || self.info.plot != nil) { if self.info.rating != nil { details["rating"] = .n(String(self.info.rating!)) } if self.info.plot != nil { details["plot"] = .s(self.info.plot!) } } item["info"] = .m(details) return item }
-
For API details, see PutItem
in AWS SDK for Swift API reference.
-
The following code example shows how to use Query
.
- SDK for Swift
-
Note
This is prerelease documentation for an SDK 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
. /// Get all the movies released in the specified year. /// /// - Parameter year: The release year of the movies to return. /// /// - Returns: An array of `Movie` objects describing each matching movie. /// func getMovies(fromYear year: Int) async throws -> [Movie] { guard let client = self.ddbClient else { throw MoviesError.UninitializedClient } let input = QueryInput( expressionAttributeNames: [ "#y": "year" ], expressionAttributeValues: [ ":y": .n(String(year)) ], keyConditionExpression: "#y = :y", tableName: self.tableName ) let output = try await client.query(input: input) guard let items = output.items else { throw MoviesError.ItemNotFound } // Convert the found movies into `Movie` objects and return an array // of them. var movieList: [Movie] = [] for item in items { let movie = try Movie(withItem: item) movieList.append(movie) } return movieList }
-
For API details, see Query
in AWS SDK for Swift API reference.
-
The following code example shows how to use Scan
.
- SDK for Swift
-
Note
This is prerelease documentation for an SDK 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
. /// Return an array of `Movie` objects released in the specified range of /// years. /// /// - Parameters: /// - firstYear: The first year of movies to return. /// - lastYear: The last year of movies to return. /// - startKey: A starting point to resume processing; always use `nil`. /// /// - Returns: An array of `Movie` objects describing the matching movies. /// /// > Note: The `startKey` parameter is used by this function when /// recursively calling itself, and should always be `nil` when calling /// directly. /// func getMovies(firstYear: Int, lastYear: Int, startKey: [Swift.String:DynamoDBClientTypes.AttributeValue]? = nil) async throws -> [Movie] { var movieList: [Movie] = [] guard let client = self.ddbClient else { throw MoviesError.UninitializedClient } let input = ScanInput( consistentRead: true, exclusiveStartKey: startKey, expressionAttributeNames: [ "#y": "year" // `year` is a reserved word, so use `#y` instead. ], expressionAttributeValues: [ ":y1": .n(String(firstYear)), ":y2": .n(String(lastYear)) ], filterExpression: "#y BETWEEN :y1 AND :y2", tableName: self.tableName ) let output = try await client.scan(input: input) guard let items = output.items else { return movieList } // Build an array of `Movie` objects for the returned items. for item in items { let movie = try Movie(withItem: item) movieList.append(movie) } // Call this function recursively to continue collecting matching // movies, if necessary. if output.lastEvaluatedKey != nil { let movies = try await self.getMovies(firstYear: firstYear, lastYear: lastYear, startKey: output.lastEvaluatedKey) movieList += movies } return movieList }
-
For API details, see Scan
in AWS SDK for Swift API reference.
-
The following code example shows how to use UpdateItem
.
- SDK for Swift
-
Note
This is prerelease documentation for an SDK 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
. /// Update the specified movie with new `rating` and `plot` information. /// /// - Parameters: /// - title: The title of the movie to update. /// - year: The release year of the movie to update. /// - rating: The new rating for the movie. /// - plot: The new plot summary string for the movie. /// /// - Returns: An array of mappings of attribute names to their new /// listing each item actually changed. Items that didn't need to change /// aren't included in this list. `nil` if no changes were made. /// func update(title: String, year: Int, rating: Double? = nil, plot: String? = nil) async throws -> [Swift.String:DynamoDBClientTypes.AttributeValue]? { guard let client = self.ddbClient else { throw MoviesError.UninitializedClient } // Build the update expression and the list of expression attribute // values. Include only the information that's changed. var expressionParts: [String] = [] var attrValues: [Swift.String:DynamoDBClientTypes.AttributeValue] = [:] if rating != nil { expressionParts.append("info.rating=:r") attrValues[":r"] = .n(String(rating!)) } if plot != nil { expressionParts.append("info.plot=:p") attrValues[":p"] = .s(plot!) } let expression: String = "set \(expressionParts.joined(separator: ", "))" let input = UpdateItemInput( // Create substitution tokens for the attribute values, to ensure // no conflicts in expression syntax. expressionAttributeValues: attrValues, // The key identifying the movie to update consists of the release // year and title. key: [ "year": .n(String(year)), "title": .s(title) ], returnValues: .updatedNew, tableName: self.tableName, updateExpression: expression ) let output = try await client.updateItem(input: input) guard let attributes: [Swift.String:DynamoDBClientTypes.AttributeValue] = output.attributes else { throw MoviesError.InvalidAttributes } return attributes }
-
For API details, see UpdateItem
in AWS SDK for Swift API reference.
-