1# Example
2
3`scan` is an example how to use Amazon DynamoDB's `expression` package to fill
4the member fields of Amazon DynamoDB's Operation input types.
5
6## Representing DynamoDB Expressions
7
8In the example, the variable `filt` represents a `FilterExpression`. Note that
9DynamoDB item attributes are represented using the function `Name()` and
10DynamoDB item values are similarly represented using the function `Value()`. In
11this context, the string `"Artist"` represents the name of the item attribute
12that we want to evaluate and the string `"No One You Know"` represents the value
13we want to evaluate the item attribute against. The relationship between the two
14[operands](http://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html#Expressions.OperatorsAndFunctions.Syntax)
15are specified using the method `Equal()`.
16
17Similarly, the variable `proj` represents a `ProjectionExpression`. The list of
18item attribute names comprising the `ProjectionExpression` are specified as
19arguments to the function `NamesList()`. The `expression` package utilizes the
20type safety of Go and if an item value were to be used as an argument to the
21function `NamesList()`, a compile time error is returned. The pattern of
22representing DynamoDB Expressions by indicating relationships between `operands`
23with functions is consistent throughout the whole `expression` package.
24
25```go
26filt := expression.Name("Artist").Equal(expression.Value("No One You Know"))
27// let :a be an ExpressionAttributeValue representing the string "No One You Know"
28// equivalent FilterExpression: "Artist = :a"
29
30proj := expression.NamesList(expression.Name("SongTitle"), expression.Name("AlbumTitle"))
31// equivalent ProjectionExpression: "SongTitle, AlbumTitle"
32```
33
34## Creating an `Expression`
35
36In the example, the variable `expr` is an instance of an `Expression` type. An
37`Expression` is built using a builder pattern. First, a new `Builder` is
38initialized by the `NewBuilder()` function. Then, types representing DynamoDB
39Expressions are added to the `Builder` by methods `WithFilter()` and
40`WithProjection()`. The `Build()` method returns an instance of an `Expression`
41and an error. The error will be either an `InvalidParameterError` or an
42`UnsetParameterError`.
43
44```go
45filt := expression.Name("Artist").Equal(expression.Value("No One You Know"))
46proj := expression.NamesList(expression.Name("SongTitle"), expression.Name("AlbumTitle"))
47
48expr, err := expression.NewBuilder().WithFilter(filt).WithProjection(proj).Build()
49if err != nil {
50  fmt.Println(err)
51}
52```
53
54## Filling in the fields of a DynamoDB `Scan` API
55
56In the example, the getter methods of the `Expression` type is used to get the
57formatted DynamoDB Expression strings. The `ExpressionAttributeNames` and
58`ExpressionAttributeValues` member field of the DynamoDB API must always be
59assigned when using an `Expression` since all item attribute names and values
60are aliased. That means that if the `ExpressionAttributeNames` and
61`ExpressionAttributeValues` member is not assigned with the corresponding
62`Names()` and `Values()` methods, the DynamoDB operation will run into a logic
63error.
64
65```go
66filt := expression.Name("Artist").Equal(expression.Value("No One You Know"))
67proj := expression.NamesList(expression.Name("SongTitle"), expression.Name("AlbumTitle"))
68expr, err := expression.NewBuilder().WithFilter(filt).WithProjection(proj).Build()
69if err != nil {
70  fmt.Println(err)
71}
72
73input := &dynamodb.ScanInput{
74  ExpressionAttributeNames:  expr.Names(),
75  ExpressionAttributeValues: expr.Values(),
76  FilterExpression:          expr.Filter(),
77  ProjectionExpression:      expr.Projection(),
78  TableName:                 aws.String("Music"),
79}
80```
81
82## Usage
83
84`go run -tags example scan.go -table "<table_name>" -region "<optional_region>"`
85
86## Output
87
88```
89{
90	Count: #SomeNumber,
91	Items: [{
92		AlbumTitle: {
93			#SomeAlbumTitle
94		},
95		SongTitle: {
96			#SomeSongTitle
97		}
98	}],
99	...
100	ScannedCount: #SomeNumber,
101}
102```
103