attributevalue

package module
v1.15.22 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Dec 19, 2024 License: Apache-2.0 Imports: 10 Imported by: 671

Documentation

Overview

Package attributevalue provides marshaling and unmarshaling utilities to convert between Go types and Amazon DynamoDB AttributeValues.

These utilities allow you to marshal slices, maps, structs, and scalar values to and from AttributeValue type. These utilities make it easier to convert between AttributeValue and Go types when working with DynamoDB resources.

This package only converts between Go types and DynamoDB AttributeValue. See the feature/dynamodbstreams/attributevalue package for converting to DynamoDBStreams AttributeValue types.

Converting AttributeValue between DynamoDB and DynamoDBStreams

The FromDynamoStreamsDBMap, FromDynamoStreamsDBList, and FromDynamoDBStreams functions provide the conversion utilities to convert a DynamoDBStreams AttributeValue type to a DynamoDB AttributeValue type. Use these utilities when you need to convert the AttributeValue type between the two APIs.

AttributeValue Marshaling

To marshal a Go type to an AttributeValue you can use the Marshal, MarshalList, and MarshalMap functions. The List and Map functions are specialized versions of the Marshal for serializing slices and maps of Attributevalues.

The following example uses MarshalMap to convert a Go struct, Record to a AttributeValue. The AttributeValue value is then used as input to the PutItem operation call. 

type Record struct {
    ID     string
    URLs   []string
}

//...

r := Record{
    ID:   "ABC123",
    URLs: []string{
        "https://example.com/first/link",
        "https://example.com/second/url",
    },
}
av, err := attributevalue.MarshalMap(r)
if err != nil {
    return fmt.Errorf("failed to marshal Record, %w", err)
}

_, err = client.PutItem(context.TODO(), &dynamodb.PutItemInput{
    TableName: aws.String(myTableName),
    Item:      av,
})
if err != nil {
    return fmt.Errorf("failed to put Record, %w", err)
}

AttributeValue Unmarshaling

To unmarshal an AttributeValue to a Go type you can use the Unmarshal, UnmarshalList, UnmarshalMap, and UnmarshalListOfMaps functions. The List and Map functions are specialized versions of the Unmarshal function for unmarshal slices and maps of Attributevalues.

The following example will unmarshal Items result from the DynamoDB's Scan API operation. The Items returned will be unmarshaled into the slice of the Records struct. 

type Record struct {
    ID     string
    URLs   []string
}

//...

result, err := client.Scan(context.Context(), &dynamodb.ScanInput{
    TableName: aws.String(myTableName),
})
if err != nil {
    return fmt.Errorf("failed to scan  table, %w", err)
}

var records []Record
err := attributevalue.UnmarshalListOfMaps(results.Items, &records)
if err != nil {
     return fmt.Errorf("failed to unmarshal Items, %w", err)
}

Struct tags

The AttributeValue Marshal and Unmarshal functions support the `dynamodbav` struct tag by default. Additional tags can be enabled with the EncoderOptions and DecoderOptions, TagKey option.

See the Marshal and Unmarshal function for information on how struct tags and fields are marshaled and unmarshaled.

Index

Examples

Constants

This section is empty.

Variables

This section is empty.

Functions

func FromDynamoDBStreams 

func FromDynamoDBStreams(from streams.AttributeValue) (ddb.AttributeValue, error)

FromDynamoDBStreams converts an Amazon DynamoDB Streams AttributeValue, and all nested members.

func FromDynamoDBStreamsList 

func FromDynamoDBStreamsList(from []streams.AttributeValue) (to []ddb.AttributeValue, err error)

FromDynamoDBStreamsList converts a slice of Amazon DynamoDB Streams AttributeValues, and all nested members.

func FromDynamoDBStreamsMap 

func FromDynamoDBStreamsMap(from map[string]streams.AttributeValue) (to map[string]ddb.AttributeValue, err error)

FromDynamoDBStreamsMap converts a map of Amazon DynamoDB Streams AttributeValues, and all nested members.

func Marshal 

func Marshal(in interface{}) (types.AttributeValue, error)

Marshal will serialize the passed in Go value type into a AttributeValue type. This value can be used in API operations to simplify marshaling your Go value types into AttributeValues.

Marshal will recursively transverse the passed in value marshaling its contents into a AttributeValue. Marshal supports basic scalars (int,uint,float,bool,string), maps, slices, and structs. Anonymous nested types are flattened based on Go anonymous type visibility.

Marshaling slices to AttributeValue will default to a List for all types except for []byte and [][]byte. []byte will be marshaled as Binary data (B), and [][]byte will be marshaled as binary data set (BS).

The `time.Time` type is marshaled as `time.RFC3339Nano` format.

`dynamodbav` struct tag can be used to control how the value will be marshaled into a AttributeValue. 

// Field is ignored
Field int `dynamodbav:"-"`

// Field AttributeValue map key "myName"
Field int `dynamodbav:"myName"`

// Field AttributeValue map key "myName", and
// Field is omitted if the field is a zero value for the type.
Field int `dynamodbav:"myName,omitempty"`

// Field AttributeValue map key "Field", and
// Field is omitted if the field is a zero value for the type.
Field int `dynamodbav:",omitempty"`

// Field's elems will be omitted if the elem's value is empty.
// only valid for slices, and maps.
Field []string `dynamodbav:",omitemptyelem"`

// Field AttributeValue map key "Field", and
// Field is sent as NULL if the field is a zero value for the type.
Field int `dynamodbav:",nullempty"`

// Field's elems will be sent as NULL if the elem's value a zero value
// for the type. Only valid for slices, and maps.
Field []string `dynamodbav:",nullemptyelem"`

// Field will be marshaled as a AttributeValue string
// only value for number types, (int,uint,float)
Field int `dynamodbav:",string"`

// Field will be marshaled as a binary set
Field [][]byte `dynamodbav:",binaryset"`

// Field will be marshaled as a number set
Field []int `dynamodbav:",numberset"`

// Field will be marshaled as a string set
Field []string `dynamodbav:",stringset"`

// Field will be marshaled as Unix time number in seconds.
// This tag is only valid with time.Time typed struct fields.
// Important to note that zero value time as unixtime is not 0 seconds
// from January 1, 1970 UTC, but -62135596800. Which is seconds between
// January 1, 0001 UTC, and January 1, 0001 UTC.
Field time.Time `dynamodbav:",unixtime"`

The omitempty tag is only used during Marshaling and is ignored for Unmarshal. omitempty will skip any member if the Go value of the member is zero. The omitemptyelem tag works the same as omitempty except it applies to the elements of maps and slices instead of struct fields, and will not be included in the marshaled AttributeValue Map, List, or Set.

The nullempty tag is only used during Marshaling and is ignored for Unmarshal. nullempty will serialize a AttributeValueMemberNULL for the member if the Go value of the member is zero. nullemptyelem tag works the same as nullempty except it applies to the elements of maps and slices instead of struct fields, and will not be included in the marshaled AttributeValue Map, List, or Set.

All struct fields and with anonymous fields, are marshaled unless the any of the following conditions are meet.

  • the field is not exported
  • json or dynamodbav field tag is "-"
  • json or dynamodbav field tag specifies "omitempty", and is a zero value.

Pointer and interfaces values are encoded as the value pointed to or contained in the interface. A nil value encodes as the AttributeValue NULL value unless `omitempty` struct tag is provided.

Channel, complex, and function values are not encoded and will be skipped when walking the value to be marshaled.

Error that occurs when marshaling will stop the marshal, and return the error.

Marshal cannot represent cyclic data structures and will not handle them. Passing cyclic structures to Marshal will result in an infinite recursion.

Example 
package main

import (
	"fmt"

	"github.com/aws/aws-sdk-go-v2/feature/dynamodb/attributevalue"
	"github.com/aws/aws-sdk-go-v2/internal/awsutil"
	"github.com/aws/aws-sdk-go-v2/service/dynamodb/types"
)

func main() {
	type Record struct {
		Bytes   []byte
		MyField string
		Letters []string
		Numbers []int
	}

	r := Record{
		Bytes:   []byte{48, 49},
		MyField: "MyFieldValue",
		Letters: []string{"a", "b", "c", "d"},
		Numbers: []int{1, 2, 3},
	}
	av, err := attributevalue.Marshal(r)
	m := av.(*types.AttributeValueMemberM)
	fmt.Println("err", err)
	fmt.Println("Bytes", awsutil.Prettify(m.Value["Bytes"]))
	fmt.Println("MyField", awsutil.Prettify(m.Value["MyField"]))
	fmt.Println("Letters", awsutil.Prettify(m.Value["Letters"]))
	fmt.Println("Numbers", awsutil.Prettify(m.Value["Numbers"]))

}

Output:

err <nil>
Bytes &{
  Value: <binary> len 2
}
MyField &{
  Value: "MyFieldValue"
}
Letters &{
  Value: [
    &{
      Value: "a"
    },
    &{
      Value: "b"
    },
    &{
      Value: "c"
    },
    &{
      Value: "d"
    }
  ]
}
Numbers &{
  Value: [
    &{
      Value: "1"
    },
    &{
      Value: "2"
    },
    &{
      Value: "3"
    }
  ]
}

func MarshalList 

func MarshalList(in interface{}) ([]types.AttributeValue, error)

MarshalList is an alias for Marshal func which marshals Go value type to a slice of AttributeValues. If the in parameter does not serialize to a slice, an empty AttributeValue slice will be returned.

func MarshalListWithOptions added in v1.6.0 

func MarshalListWithOptions(in interface{}, optFns ...func(*EncoderOptions)) ([]types.AttributeValue, error)

MarshalListWithOptions is an alias for MarshalWithOptions func which marshals Go value type to a slice of AttributeValues. If the in parameter does not serialize to a slice, an empty AttributeValue slice will be returned.

Use the `optsFns` functional options to override the default configuration.

func MarshalMap 

func MarshalMap(in interface{}) (map[string]types.AttributeValue, error)

MarshalMap is an alias for Marshal func which marshals Go value type to a map of AttributeValues. If the in parameter does not serialize to a map, an empty AttributeValue map will be returned.

Use the `optsFns` functional options to override the default configuration.

This is useful for APIs such as PutItem.

func MarshalMapWithOptions added in v1.6.0 

func MarshalMapWithOptions(in interface{}, optFns ...func(*EncoderOptions)) (map[string]types.AttributeValue, error)

MarshalMapWithOptions is an alias for MarshalWithOptions func which marshals Go value type to a map of AttributeValues. If the in parameter does not serialize to a map, an empty AttributeValue map will be returned.

Use the `optsFns` functional options to override the default configuration.

This is useful for APIs such as PutItem.

func MarshalWithOptions added in v1.6.0 

func MarshalWithOptions(in interface{}, optFns ...func(*EncoderOptions)) (types.AttributeValue, error)

MarshalWithOptions will serialize the passed in Go value type into a AttributeValue type, by using . This value can be used in API operations to simplify marshaling your Go value types into AttributeValues.

Use the `optsFns` functional options to override the default configuration.

MarshalWithOptions will recursively transverse the passed in value marshaling its contents into a AttributeValue. Marshal supports basic scalars (int,uint,float,bool,string), maps, slices, and structs. Anonymous nested types are flattened based on Go anonymous type visibility.

Marshaling slices to AttributeValue will default to a List for all types except for []byte and [][]byte. []byte will be marshaled as Binary data (B), and [][]byte will be marshaled as binary data set (BS).

The `time.Time` type is marshaled as `time.RFC3339Nano` format.

`dynamodbav` struct tag can be used to control how the value will be marshaled into a AttributeValue. 

// Field is ignored
Field int `dynamodbav:"-"`

// Field AttributeValue map key "myName"
Field int `dynamodbav:"myName"`

// Field AttributeValue map key "myName", and
// Field is omitted if the field is a zero value for the type.
Field int `dynamodbav:"myName,omitempty"`

// Field AttributeValue map key "Field", and
// Field is omitted if the field is a zero value for the type.
Field int `dynamodbav:",omitempty"`

// Field's elems will be omitted if the elem's value is empty.
// only valid for slices, and maps.
Field []string `dynamodbav:",omitemptyelem"`

// Field AttributeValue map key "Field", and
// Field is sent as NULL if the field is a zero value for the type.
Field int `dynamodbav:",nullempty"`

// Field's elems will be sent as NULL if the elem's value a zero value
// for the type. Only valid for slices, and maps.
Field []string `dynamodbav:",nullemptyelem"`

// Field will be marshaled as a AttributeValue string
// only value for number types, (int,uint,float)
Field int `dynamodbav:",string"`

// Field will be marshaled as a binary set
Field [][]byte `dynamodbav:",binaryset"`

// Field will be marshaled as a number set
Field []int `dynamodbav:",numberset"`

// Field will be marshaled as a string set
Field []string `dynamodbav:",stringset"`

// Field will be marshaled as Unix time number in seconds.
// This tag is only valid with time.Time typed struct fields.
// Important to note that zero value time as unixtime is not 0 seconds
// from January 1, 1970 UTC, but -62135596800. Which is seconds between
// January 1, 0001 UTC, and January 1, 0001 UTC.
Field time.Time `dynamodbav:",unixtime"`

The omitempty tag is only used during Marshaling and is ignored for Unmarshal. omitempty will skip any member if the Go value of the member is zero. The omitemptyelem tag works the same as omitempty except it applies to the elements of maps and slices instead of struct fields, and will not be included in the marshaled AttributeValue Map, List, or Set.

The nullempty tag is only used during Marshaling and is ignored for Unmarshal. nullempty will serialize a AttributeValueMemberNULL for the member if the Go value of the member is zero. nullemptyelem tag works the same as nullempty except it applies to the elements of maps and slices instead of struct fields, and will not be included in the marshaled AttributeValue Map, List, or Set.

All struct fields and with anonymous fields, are marshaled unless the any of the following conditions are meet.

  • the field is not exported
  • json or dynamodbav field tag is "-"
  • json or dynamodbav field tag specifies "omitempty", and is a zero value.

Pointer and interfaces values are encoded as the value pointed to or contained in the interface. A nil value encodes as the AttributeValue NULL value unless `omitempty` struct tag is provided.

Channel, complex, and function values are not encoded and will be skipped when walking the value to be marshaled.

Error that occurs when marshaling will stop the marshal, and return the error.

MarshalWithOptions cannot represent cyclic data structures and will not handle them. Passing cyclic structures to Marshal will result in an infinite recursion.

func Unmarshal 

func Unmarshal(av types.AttributeValue, out interface{}) error

Unmarshal will unmarshal AttributeValues to Go value types. Both generic interface{} and concrete types are valid unmarshal destination types.

Unmarshal will allocate maps, slices, and pointers as needed to unmarshal the AttributeValue into the provided type value.

When unmarshaling AttributeValues into structs Unmarshal matches the field names of the struct to the AttributeValue Map keys. Initially it will look for exact field name matching, but will fall back to case insensitive if not exact match is found.

With the exception of omitempty, omitemptyelem, binaryset, numberset and stringset all struct tags used by Marshal are also used by Unmarshal.

When decoding AttributeValues to interfaces Unmarshal will use the following types. 

[]byte,                 AV Binary (B)
[][]byte,               AV Binary Set (BS)
bool,                   AV Boolean (BOOL)
[]interface{},          AV List (L)
map[string]interface{}, AV Map (M)
float64,                AV Number (N)
Number,                 AV Number (N) with UseNumber set
[]float64,              AV Number Set (NS)
[]Number,               AV Number Set (NS) with UseNumber set
string,                 AV String (S)
[]string,               AV String Set (SS)

If the Decoder option, UseNumber is set numbers will be unmarshaled as Number values instead of float64. Use this to maintain the original string formating of the number as it was represented in the AttributeValue. In addition provides additional opportunities to parse the number string based on individual use cases.

When unmarshaling any error that occurs will halt the unmarshal and return the error.

The output value provided must be a non-nil pointer

Example 
package main

import (
	"fmt"
	"reflect"

	"github.com/aws/aws-sdk-go-v2/feature/dynamodb/attributevalue"
	"github.com/aws/aws-sdk-go-v2/service/dynamodb/types"
)

func main() {
	type Record struct {
		Bytes   []byte
		MyField string
		Letters []string
		A2Num   map[string]int
	}

	expect := Record{
		Bytes:   []byte{48, 49},
		MyField: "MyFieldValue",
		Letters: []string{"a", "b", "c", "d"},
		A2Num:   map[string]int{"a": 1, "b": 2, "c": 3},
	}

	av := &types.AttributeValueMemberM{
		Value: map[string]types.AttributeValue{
			"Bytes":   &types.AttributeValueMemberB{Value: []byte{48, 49}},
			"MyField": &types.AttributeValueMemberS{Value: "MyFieldValue"},
			"Letters": &types.AttributeValueMemberL{Value: []types.AttributeValue{
				&types.AttributeValueMemberS{Value: "a"},
				&types.AttributeValueMemberS{Value: "b"},
				&types.AttributeValueMemberS{Value: "c"},
				&types.AttributeValueMemberS{Value: "d"},
			}},
			"A2Num": &types.AttributeValueMemberM{Value: map[string]types.AttributeValue{
				"a": &types.AttributeValueMemberN{Value: "1"},
				"b": &types.AttributeValueMemberN{Value: "2"},
				"c": &types.AttributeValueMemberN{Value: "3"},
			}},
		},
	}

	actual := Record{}
	err := attributevalue.Unmarshal(av, &actual)
	fmt.Println(err, reflect.DeepEqual(expect, actual))

}

Output:

<nil> true

func UnmarshalList 

func UnmarshalList(l []types.AttributeValue, out interface{}) error

UnmarshalList is an alias for Unmarshal func which unmarshals a slice of AttributeValues.

The output value provided must be a non-nil pointer

func UnmarshalListOfMaps 

func UnmarshalListOfMaps(l []map[string]types.AttributeValue, out interface{}) error

UnmarshalListOfMaps is an alias for Unmarshal func which unmarshals a slice of maps of attribute values.

This is useful for when you need to unmarshal the Items from a Query API call.

The output value provided must be a non-nil pointer

func UnmarshalListOfMapsWithOptions added in v1.6.0 

func UnmarshalListOfMapsWithOptions(l []map[string]types.AttributeValue, out interface{}, optFns ...func(options *DecoderOptions)) error

UnmarshalListOfMapsWithOptions is an alias for UnmarshalWithOptions func which unmarshals a slice of maps of attribute values.

Use the `optsFns` functional options to override the default configuration.

This is useful for when you need to unmarshal the Items from a Query API call.

The output value provided must be a non-nil pointer

func UnmarshalListWithOptions added in v1.6.0 

func UnmarshalListWithOptions(l []types.AttributeValue, out interface{}, optFns ...func(options *DecoderOptions)) error

UnmarshalListWithOptions is an alias for UnmarshalWithOptions func which unmarshals a slice of AttributeValues.

Use the `optsFns` functional options to override the default configuration.

The output value provided must be a non-nil pointer

func UnmarshalMap 

func UnmarshalMap(m map[string]types.AttributeValue, out interface{}) error

UnmarshalMap is an alias for Unmarshal which unmarshals from a map of AttributeValues.

The output value provided must be a non-nil pointer

func UnmarshalMapWithOptions added in v1.6.0 

func UnmarshalMapWithOptions(m map[string]types.AttributeValue, out interface{}, optFns ...func(options *DecoderOptions)) error

UnmarshalMapWithOptions is an alias for UnmarshalWithOptions which unmarshals from a map of AttributeValues.

Use the `optsFns` functional options to override the default configuration.

The output value provided must be a non-nil pointer

func UnmarshalWithOptions added in v1.6.0 

func UnmarshalWithOptions(av types.AttributeValue, out interface{}, optFns ...func(options *DecoderOptions)) error

UnmarshalWithOptions will unmarshal AttributeValues to Go value types. Both generic interface{} and concrete types are valid unmarshal destination types.

Use the `optsFns` functional options to override the default configuration.

UnmarshalWithOptions will allocate maps, slices, and pointers as needed to unmarshal the AttributeValue into the provided type value.

When unmarshaling AttributeValues into structs Unmarshal matches the field names of the struct to the AttributeValue Map keys. Initially it will look for exact field name matching, but will fall back to case insensitive if not exact match is found.

With the exception of omitempty, omitemptyelem, binaryset, numberset and stringset all struct tags used by Marshal are also used by UnmarshalWithOptions.

When decoding AttributeValues to interfaces Unmarshal will use the following types. 

[]byte,                 AV Binary (B)
[][]byte,               AV Binary Set (BS)
bool,                   AV Boolean (BOOL)
[]interface{},          AV List (L)
map[string]interface{}, AV Map (M)
float64,                AV Number (N)
Number,                 AV Number (N) with UseNumber set
[]float64,              AV Number Set (NS)
[]Number,               AV Number Set (NS) with UseNumber set
string,                 AV String (S)
[]string,               AV String Set (SS)

If the Decoder option, UseNumber is set numbers will be unmarshaled as Number values instead of float64. Use this to maintain the original string formating of the number as it was represented in the AttributeValue. In addition provides additional opportunities to parse the number string based on individual use cases.

When unmarshaling any error that occurs will halt the unmarshal and return the error.

The output value provided must be a non-nil pointer

Types

type DecodeTimeAttributes added in v1.9.0 

type DecodeTimeAttributes struct {
	// Will decode S attribute values and SS attribute value elements into time.Time
	//
	// Default string parsing format is time.RFC3339
	S func(string) (time.Time, error)
	// Will decode N attribute values and NS attribute value elements into time.Time
	//
	// Default number parsing format is seconds since January 1, 1970 UTC
	N func(string) (time.Time, error)
}

DecodeTimeAttributes is the set of time decoding functions for different AttributeValues.

type Decoder 

type Decoder struct {
	// contains filtered or unexported fields
}

A Decoder provides unmarshaling AttributeValues to Go value types.

func NewDecoder 

func NewDecoder(optFns ...func(*DecoderOptions)) *Decoder

NewDecoder creates a new Decoder with default configuration. Use the `opts` functional options to override the default configuration.

func (*Decoder) Decode 

func (d *Decoder) Decode(av types.AttributeValue, out interface{}, opts ...func(*Decoder)) error

Decode will unmarshal an AttributeValue into a Go value type. An error will be return if the decoder is unable to unmarshal the AttributeValue to the provide Go value type.

The output value provided must be a non-nil pointer

type DecoderOptions 

type DecoderOptions struct {
	// Support other custom struct tag keys, such as `yaml`, `json`, or `toml`.
	// Note that values provided with a custom TagKey must also be supported
	// by the (un)marshalers in this package.
	//
	// Tag key `dynamodbav` will always be read, but if custom tag key
	// conflicts with `dynamodbav` the custom tag key value will be used.
	TagKey string

	// Instructs the decoder to decode AttributeValue Numbers as
	// Number type instead of float64 when the destination type
	// is interface{}. Similar to encoding/json.Number
	UseNumber bool

	// Contains the time decoding functions for different AttributeValues
	//
	// Default string parsing format is time.RFC3339
	// Default number parsing format is seconds since January 1, 1970 UTC
	DecodeTime DecodeTimeAttributes

	// When enabled, the decoder will use implementations of
	// encoding.TextUnmarshaler and encoding.BinaryUnmarshaler when present on
	// unmarshaling targets.
	//
	// If a target implements [Unmarshaler], encoding unmarshaler
	// implementations are ignored.
	//
	// If the attributevalue is a string, its underlying value will be used to
	// call UnmarshalText on the target. If the attributevalue is a binary, its
	// value will be used to call UnmarshalBinary.
	UseEncodingUnmarshalers bool
}

DecoderOptions is a collection of options to configure how the decoder unmarshals the value.

type Encoder 

type Encoder struct {
	// contains filtered or unexported fields
}

An Encoder provides marshaling Go value types to AttributeValues.

func NewEncoder 

func NewEncoder(optFns ...func(*EncoderOptions)) *Encoder

NewEncoder creates a new Encoder with default configuration. Use the `opts` functional options to override the default configuration.

func (*Encoder) Encode 

func (e *Encoder) Encode(in interface{}) (types.AttributeValue, error)

Encode will marshal a Go value type to an AttributeValue. Returning the AttributeValue constructed or error.

type EncoderOptions 

type EncoderOptions struct {
	// Support other custom struct tag keys, such as `yaml`, `json`, or `toml`.
	// Note that values provided with a custom TagKey must also be supported
	// by the (un)marshalers in this package.
	//
	// Tag key `dynamodbav` will always be read, but if custom tag key
	// conflicts with `dynamodbav` the custom tag key value will be used.
	TagKey string

	// Will encode any slice being encoded as a set (SS, NS, and BS) as a NULL
	// AttributeValue if the slice is not nil, but is empty but contains no
	// elements.
	//
	// If a type implements the Marshal interface, and returns empty set
	// slices, this option will not modify the returned value.
	//
	// Defaults to enabled, because AttributeValue sets cannot currently be
	// empty lists.
	NullEmptySets bool

	// Will encode time.Time fields
	//
	// Default encoding is time.RFC3339Nano in a DynamoDB String (S) data type.
	EncodeTime func(time.Time) (types.AttributeValue, error)

	// When enabled, the encoder will use implementations of
	// encoding.TextMarshaler and encoding.BinaryMarshaler when present on
	// marshaled values.
	//
	// Implementations are checked in the following order:
	//   - [Marshaler]
	//   - encoding.TextMarshaler
	//   - encoding.BinaryMarshaler
	//
	// The results of a MarshalText call will convert to string (S), results
	// from a MarshalBinary call will convert to binary (B).
	UseEncodingMarshalers bool

	// When enabled, the encoder will omit null (NULL) attribute values
	// returned from custom marshalers tagged with `omitempty`.
	//
	// NULL attribute values returned from the standard marshaling routine will
	// always respect omitempty regardless of this setting.
	OmitNullAttributeValues bool
}

EncoderOptions is a collection of options used by the marshaler.

type InvalidMarshalError 

type InvalidMarshalError struct {
	// contains filtered or unexported fields
}

An InvalidMarshalError is an error type representing an error occurring when marshaling a Go value type to an AttributeValue.

func (*InvalidMarshalError) Error 

func (e *InvalidMarshalError) Error() string

Error returns the string representation of the error. satisfying the error interface

type InvalidUnmarshalError 

type InvalidUnmarshalError struct {
	Type reflect.Type
}

An InvalidUnmarshalError is an error type representing an invalid type encountered while unmarshaling a AttributeValue to a Go value type.

func (*InvalidUnmarshalError) Error 

func (e *InvalidUnmarshalError) Error() string

Error returns the string representation of the error. satisfying the error interface

type Marshaler 

type Marshaler interface {
	MarshalDynamoDBAttributeValue() (types.AttributeValue, error)
}

A Marshaler is an interface to provide custom marshaling of Go value types to AttributeValues. Use this to provide custom logic determining how a Go Value type should be marshaled. 

type CustomIntType struct {
	Value Int
}
func (m *CustomIntType) MarshalDynamoDBAttributeValue() (types.AttributeValue, error) {
	return &types.AttributeValueMemberN{
		Value: strconv.Itoa(m.Value),
	}, nil
}

type Number 

type Number string

A Number represents a Attributevalue number literal.

func (Number) Float64 

func (n Number) Float64() (float64, error)

Float64 attempts to cast the number to a float64, returning the result of the case or error if the case failed.

func (Number) Int64 

func (n Number) Int64() (int64, error)

Int64 attempts to cast the number to a int64, returning the result of the case or error if the case failed.

func (Number) String 

func (n Number) String() string

String returns the raw number represented as a string

func (Number) Uint64 

func (n Number) Uint64() (uint64, error)

Uint64 attempts to cast the number to a uint64, returning the result of the case or error if the case failed.

type UnixTime 

type UnixTime time.Time

An UnixTime provides aliasing of time.Time into a type that when marshaled and unmarshaled with AttributeValues it will be done so as number instead of string in seconds since January 1, 1970 UTC.

This type is useful as an alternative to the struct tag `unixtime` when you want to have your time value marshaled as Unix time in seconds into a number attribute type instead of the default time.RFC3339Nano.

Important to note that zero value time as unixtime is not 0 seconds from January 1, 1970 UTC, but -62135596800. Which is seconds between January 1, 0001 UTC, and January 1, 0001 UTC.

Also, important to note: the default UnixTime implementation of the Marshaler interface will marshal into an attribute of type of number; therefore, it may not be used as a sort key if the attribute value is of type string. Further, the time.RFC3339Nano format removes trailing zeros from the seconds field and thus may not sort correctly once formatted.

func (UnixTime) MarshalDynamoDBAttributeValue 

func (e UnixTime) MarshalDynamoDBAttributeValue() (types.AttributeValue, error)

MarshalDynamoDBAttributeValue implements the Marshaler interface so that the UnixTime can be marshaled from to a AttributeValue number value encoded in the number of seconds since January 1, 1970 UTC.

func (UnixTime) String added in v1.10.0 

func (e UnixTime) String() string

String calls the underlying time.Time.String to return a human readable representation.

func (*UnixTime) UnmarshalDynamoDBAttributeValue 

func (e *UnixTime) UnmarshalDynamoDBAttributeValue(av types.AttributeValue) error

UnmarshalDynamoDBAttributeValue implements the Unmarshaler interface so that the UnixTime can be unmarshaled from a AttributeValue number representing the number of seconds since January 1, 1970 UTC.

If an error parsing the AttributeValue number occurs UnmarshalError will be returned.

type UnmarshalError 

type UnmarshalError struct {
	Err   error
	Value string
	Type  reflect.Type
}

An UnmarshalError wraps an error that occurred while unmarshaling a AttributeValue element into a Go type. This is different from UnmarshalTypeError in that it wraps the underlying error that occurred.

func (*UnmarshalError) Error 

func (e *UnmarshalError) Error() string

Error returns the string representation of the error satisfying the error interface.

func (*UnmarshalError) Unwrap 

func (e *UnmarshalError) Unwrap() error

type UnmarshalTypeError 

type UnmarshalTypeError struct {
	Value string
	Type  reflect.Type
	Err   error
}

An UnmarshalTypeError is an error type representing a error unmarshaling the AttributeValue's element to a Go value type. Includes details about the AttributeValue type and Go value type.

func (*UnmarshalTypeError) Error 

func (e *UnmarshalTypeError) Error() string

Error returns the string representation of the error. satisfying the error interface

func (*UnmarshalTypeError) Unwrap added in v1.7.0 

func (e *UnmarshalTypeError) Unwrap() error

Unwrap returns the underlying error if any.

type Unmarshaler 

type Unmarshaler interface {
	UnmarshalDynamoDBAttributeValue(types.AttributeValue) error
}

An Unmarshaler is an interface to provide custom unmarshaling of AttributeValues. Use this to provide custom logic determining how AttributeValues should be unmarshaled. 

		type ExampleUnmarshaler struct {
			Value int
		}

		func (u *ExampleUnmarshaler) UnmarshalDynamoDBAttributeValue(av types.AttributeValue) error {
         avN, ok := av.(*types.AttributeValueMemberN)
			if !ok {
				return nil
			}

			n, err := strconv.ParseInt(avN.Value, 10, 0)
			if err != nil {
				return err
			}

			u.Value = int(n)
			return nil
		}

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.