github.com/aavshr/aws-sdk-go@v1.41.3/example/service/dynamodb/expression/readme.md (about)

     1  # Example
     2  
     3  `scan` is an example how to use Amazon DynamoDB's `expression` package to fill
     4  the member fields of Amazon DynamoDB's Operation input types.
     5  
     6  ## Representing DynamoDB Expressions
     7  
     8  In the example, the variable `filt` represents a `FilterExpression`. Note that
     9  DynamoDB item attributes are represented using the function `Name()` and
    10  DynamoDB item values are similarly represented using the function `Value()`. In
    11  this context, the string `"Artist"` represents the name of the item attribute
    12  that we want to evaluate and the string `"No One You Know"` represents the value
    13  we 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)
    15  are specified using the method `Equal()`.
    16  
    17  Similarly, the variable `proj` represents a `ProjectionExpression`. The list of
    18  item attribute names comprising the `ProjectionExpression` are specified as
    19  arguments to the function `NamesList()`. The `expression` package utilizes the
    20  type safety of Go and if an item value were to be used as an argument to the
    21  function `NamesList()`, a compile time error is returned. The pattern of
    22  representing DynamoDB Expressions by indicating relationships between `operands`
    23  with functions is consistent throughout the whole `expression` package.
    24  
    25  ```go
    26  filt := 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  
    30  proj := expression.NamesList(expression.Name("SongTitle"), expression.Name("AlbumTitle"))
    31  // equivalent ProjectionExpression: "SongTitle, AlbumTitle"
    32  ```
    33  
    34  ## Creating an `Expression`
    35  
    36  In 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
    38  initialized by the `NewBuilder()` function. Then, types representing DynamoDB
    39  Expressions are added to the `Builder` by methods `WithFilter()` and
    40  `WithProjection()`. The `Build()` method returns an instance of an `Expression`
    41  and an error. The error will be either an `InvalidParameterError` or an
    42  `UnsetParameterError`.
    43  
    44  ```go
    45  filt := expression.Name("Artist").Equal(expression.Value("No One You Know"))
    46  proj := expression.NamesList(expression.Name("SongTitle"), expression.Name("AlbumTitle"))
    47  
    48  expr, err := expression.NewBuilder().WithFilter(filt).WithProjection(proj).Build()
    49  if err != nil {
    50    fmt.Println(err)
    51  }
    52  ```
    53  
    54  ## Filling in the fields of a DynamoDB `Scan` API
    55  
    56  In the example, the getter methods of the `Expression` type is used to get the
    57  formatted DynamoDB Expression strings. The `ExpressionAttributeNames` and
    58  `ExpressionAttributeValues` member field of the DynamoDB API must always be
    59  assigned when using an `Expression` since all item attribute names and values
    60  are 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
    63  error.
    64  
    65  ```go
    66  filt := expression.Name("Artist").Equal(expression.Value("No One You Know"))
    67  proj := expression.NamesList(expression.Name("SongTitle"), expression.Name("AlbumTitle"))
    68  expr, err := expression.NewBuilder().WithFilter(filt).WithProjection(proj).Build()
    69  if err != nil {
    70    fmt.Println(err)
    71  }
    72  
    73  input := &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  ```