Swift basic scenario example for DynamoDB (#4403)

* Readme skeleton for Swift DynamoDB samples

* WIP: Basic scenario for DDB on Swift

* Readme skeleton for Swift DynamoDB samples

* WIP: Basic scenario for DDB on Swift

* Checkpoint

* Final tweaks before PR

* Readme update for DynamoDB

* Fix incorrect SoS tags

* Metadata for Swift DynamoDB scenario

Add metadata for the DynamoDB scenario for Swift, and fix a couple of
validation issues that have cropped up.

* SoS metadata and tag fixes for Swift

* Fix mis-paste of pathnames

* More SoS cleanup

* Add file left out of last commit

* Typo fix

* Update SDK metadata to fix validation error

* Remove commented-out lines

* Remove more commented out code

* Text review feedback for DDB scenario for Swift

* Update metadata and README for code review stage

* Updated metadata for Swift DynamoDB

---------

Co-authored-by: Eric Shepherd <[email protected]>

Author: shepazon

.doc_gen/metadata/dynamodb_metadata.yaml

@@ -104,6 +104,14 @@ dynamodb_CreateTable:
             - description:
               snippet_tags:
                 - dynamodb.JavaScript.table.createTable
+    Swift:
+      versions:
+        - sdk_version: 1
+          github: swift/example_code/ddb
+          excerpts:
+            - description:
+              snippet_tags:
+                - ddb.swift.basics.createtable
   services:
     dynamodb: {CreateTable}
 dynamodb_BatchGetItem:
@@ -329,6 +337,14 @@ dynamodb_BatchWriteItem:
             - description:
               snippet_tags:
                 - cpp.example_code.dynamodb.batch_write_item
+    Swift:
+      versions:
+        - sdk_version: 1
+          github: swift/example_code/ddb/
+          excerpts:
+            - description:
+              snippet_tags:
+                - ddb.swift.basics.populate
   services:
     dynamodb: {BatchWriteItem}
 dynamodb_DeleteTable:
@@ -434,6 +450,14 @@ dynamodb_DeleteTable:
             - description:
               snippet_tags:
                 - dynamodb.JavaScript.table.deleteTable
+    Swift:
+      versions:
+        - sdk_version: 1
+          github: swift/example_code/ddb
+          excerpts:
+            - description:
+              snippet_tags:
+                - ddb.swift.basics.deletetable
   services:
     dynamodb: {DeleteTable}
 dynamodb_PutItem:
@@ -552,6 +576,15 @@ dynamodb_PutItem:
             - description: Put an item in a table using the &DDB; document client.
               snippet_tags:
                 - dynamodb.JavaScript.docClient.put
+    Swift:
+      versions:
+        - sdk_version: 1
+          github: swift/example_code/ddb
+          excerpts:
+            - description:
+              snippet_tags:
+                - ddb.swift.basics.add-movie
+                - ddb.swift.basics.movie.getasitem
   services:
     dynamodb: {PutItem}
 dynamodb_GetItem:
@@ -662,6 +695,14 @@ dynamodb_GetItem:
             - description: Get an item from a table using the &DDB; document client.
               snippet_tags:
                 - dynamodb.JavaScript.docClient.get
+    Swift:
+      versions:
+        - sdk_version: 1
+          github: swift/example_code/ddb
+          excerpts:
+            - description:
+              snippet_tags:
+                - ddb.swift.basics.get
   services:
     dynamodb: {GetItem}
 dynamodb_UpdateItem:
@@ -772,6 +813,14 @@ dynamodb_UpdateItem:
             - description: Update items by batch in a table using PartiQL.
               snippet_tags:
                 - dynamodb.JavaScript.partiQL.updateItemsV3
+    Swift:
+      versions:
+        - sdk_version: 1
+          github: swift/example_code/ddb
+          excerpts:
+            - description:
+              snippet_tags:
+                - ddb.swift.basics.update
   services:
     dynamodb: {UpdateItem}
 dynamodb_DeleteItem:
@@ -898,6 +947,14 @@ dynamodb_DeleteItem:
             - description:
               snippet_tags:
                 - cpp.example_code.dynamodb.delete_item
+    Swift:
+      versions:
+        - sdk_version: 1
+          github: swift/example_code/ddb
+          excerpts:
+            - description:
+              snippet_tags:
+                - ddb.swift.basics.delete
   services:
     dynamodb: {DeleteItem}
 dynamodb_ListTables:
@@ -1128,6 +1185,14 @@ dynamodb_Query:
             - description:
               snippet_tags:
                 - dynamodb.JavaScript.docClient.query
+    Swift:
+      versions:
+        - sdk_version: 1
+          github: swift/example_code/ddb
+          excerpts:
+            - description:
+              snippet_tags:
+                - ddb.swift.basics.getMovies-year
   services:
     dynamodb: {Query}
 dynamodb_Scan:
@@ -1237,6 +1302,14 @@ dynamodb_Scan:
             - description:
               snippet_tags:
                 - dynamodb.JavaScript.table.scan
+    Swift:
+      versions:
+        - sdk_version: 1
+          github: swift/example_code/ddb
+          excerpts:
+            - description:
+              snippet_tags:
+                - ddb.swift.basics.getmovies-range
   services:
     dynamodb: {Scan}
 dynamodb_ExecuteStatement:
@@ -1701,6 +1774,23 @@ dynamodb_Scenario_GettingStartedMovies:
                 - cpp.example_code.dynamodb.scenario.createMoviesDynamoDBTable
                 - cpp.example_code.dynamodb.scenario.deleteMoviesDynamoDBTable
                 - cpp.example_code.dynamodb.scenario.waitTableActive
+    Swift:
+      versions:
+        - sdk_version: 1
+          github: swift/example_code/ddb
+          excerpts:
+            - description:
+                A Swift class that handles &DDB; calls to the &Swift;.
+              snippet_tags:
+                - ddb.swift.basics.movietable
+            - description: The structures used by the MovieTable class to
+                represent movies.
+              snippet_tags:
+                - ddb.swift.basics.movie
+            - description: A program that uses the MovieTable class to access
+                a &DDB; database.
+              snippet_tags:
+                - ddb.swift.basics
   services:
     dynamodb:
       {

swift/example_code/ddb/README.md

@@ -0,0 +1,72 @@
+# DynamoDB code examples for the SDK for Swift
+## Overview
+This folder contains code examples demonstrating how to use the AWS SDK for
+Swift to use Amazon DynamoDB. This README discusses how to run these examples.
+
+Amazon DynamoDB is a fully managed NoSQL database service that provides fast
+and predictable performance with seamless scalability. DynamoDB lets you
+offload the administrative burdens of operating and scaling a distributed
+database so that you don't have to worry about hardware provisioning, setup
+and configuration, replication, software patching, or cluster scaling.
+
+## ⚠️ Important
+* Running this code might result in charges to your AWS account. 
+* Running the tests might result in charges to your AWS account.
+* We recommend that you grant your code least privilege. At most, grant only the minimum permissions required to perform the task. For more information, see [Grant least privilege](https://docs.aws.amazon.com/DynamoDB/latest/UserGuide/best-practices.html#grant-least-privilege). 
+* This code is not tested in every AWS Region. For more information, see [AWS Regional Services](https://aws.amazon.com/about-aws/global-infrastructure/regional-product-services).
+
+## Code examples
+
+### Single actions
+Code excerpts that show you how to call individual service functions.
+* [Create a table](./basics/MovieList/MovieTable.swift)
+  (`CreateTable`)
+* [Add an item to a table](./basics/MovieList/MovieTable.swift) (`PutItem`)
+* [Update an item](./basics/MovieList/MovieTable.swift) (`UpdateItem`)
+* [Add the contents of a JSON file to a table](./basics/MovieList/MovieTable.swift) (`BatchWriteItem`)
+* [Get an item by key](./basics/MovieList/MovieTable.swift) (`GetItem`)
+* [Delete an item by key](./basics/MovieList/MovieTable.swift) (`DeleteItem`)
+* [Query a table](./basics/MovieList/MovieTable.swift) (`Query`)
+* [Scan a table with pagination](./basics/MovieList/MovieTable.swift) (`Scan`)
+* [Delete a table](./basics/MovieList/MovieTable.swift) (`DeleteTable`)
+
+### Scenarios
+Code examples that show you how to accomplish a specific task by calling multiple functions within the same service.
+
+* [DynamoDB Basics](./basics/Sources/basics.swift). Demonstrates a common
+  series of actions to create and perform common actions on a movie list
+  database. (`Basics`)
+
+<!-- ### Cross-service examples
+Sample applications that work across multiple AWS services.
+* [*Title of code example*](*relative link to code example*) --->
+
+## Run the examples
+To build any of these examples from a terminal window, navigate into its
+directory, then use the following command:
+
+```
+$ swift build
+```
+
+To build one of these examples in Xcode, navigate to the example's directory
+(such as the `basics` directory, to build that example). Then type `xed.`
+to open the example directory in Xcode. You can then use standard Xcode build
+and run commands.
+
+### Prerequisites
+See the [Prerequisites](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/swift#Prerequisites) section in the README for the AWS SDK for Swift examples repository.
+
+## Tests
+⚠️ Running the tests might result in charges to your AWS account.
+
+To run the tests for an example, use the command `swift test` in the example's directory.
+
+## Additional resources
+* [DynamoDB Developer Guide](https://docs.aws.amazon.com/dynamodb/index.html)
+* [DynamoDB API Reference](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/)
+* [DynamoDB Developer Guide for Swift](https://docs.aws.amazon.com/sdk-for-swift/latest/developer-guide/examples-ddb.html)
+* [DynamoDB API Reference for Swift](https://awslabs.github.io/aws-sdk-swift/reference/0.x/AWSDynamoDB/Home)
+* [Security best practices for DynamoDB](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/best-practices-security.html)
+
+_Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved. SPDX-License-Identifier: Apache-2.0_

swift/example_code/ddb/basics/MovieList/Movie.swift

@@ -0,0 +1,157 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+// snippet-start:[ddb.swift.basics.movie]
+import Foundation
+import AWSDynamoDB
+
+// snippet-start:[ddb.swift.basics.details]
+/// 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?
+}
+// snippet-end:[ddb.swift.basics.details]
+
+/// 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
+
+    // snippet-start:[ddb.swift.basics.init]
+    /// 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)
+    }
+    // snippet-end:[ddb.swift.basics.init]
+
+    // snippet-start:[ddb.swift.basics.init-info]
+    /// 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)
+        }
+    }
+    // snippet-end:[ddb.swift.basics.init-info]
+
+    // snippet-start:[ddb.swift.basics.init-withitem]
+    ///
+    /// 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)
+    }
+    // snippet-end:[ddb.swift.basics.init-withitem]
+
+    // snippet-start:[ddb.swift.basics.movie.getasitem]
+    ///
+    /// 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
+    }
+    // snippet-end:[ddb.swift.basics.movie.getasitem]
+ }
+ // snippet-end:[ddb.swift.basics.movie]