dynamodb

package
v1.2.4 Latest Latest
Warning

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

 Go to latest Published: Dec 4, 2021 License: Apache-2.0 Imports: 19 Imported by: 3

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type DynamoDB 

type DynamoDB struct {
	// define the AWS region that dynamodb is serviced from
	AwsRegion awsregion.AWSRegion

	// custom http2 client options
	HttpOptions *awshttp2.HttpClientSettings

	// define the Dax Endpoint (required if using DAX)
	DaxEndpoint string

	// if dax is enabled, skip dax will skip dax and route direct to DynamoDB
	// if dax is not enabled, skip dax true or not will always route to DynamoDB
	SkipDax bool

	// operating table
	TableName string
	PKName    string
	SKName    string

	// last execute param string
	LastExecuteParamsPayload string
	// contains filtered or unexported fields
}

DynamoDB struct encapsulates the AWS DynamoDB access functionality

Notes:

  1. to use dax, must be within vpc with dax cluster subnet pointing to private ip subnet of the vpc
  2. dax is not accessible outside of vpc
  3. on ec2 or container within vpc, also need aws credential via aws cli too = aws configure

func (*DynamoDB) BatchDeleteItemsWithRetry added in v1.1.4 

func (d *DynamoDB) BatchDeleteItemsWithRetry(maxRetries uint,
	timeOutDuration *time.Duration,
	deleteKeys ...*DynamoDBTableKeys) (deleteFailKeys []*DynamoDBTableKeys, err error)

BatchDeleteItemsWithRetry will attempt to delete one or more table records by on deleteKeys input, will auto retry delete if temporarily failed, if there are deleteFailKeys, its returned, if all succeeded, nil is returned

func (*DynamoDB) BatchGetItems 

func (d *DynamoDB) BatchGetItems(resultItemsPtr interface{},
	searchKeys []DynamoDBTableKeys,
	timeOutDuration *time.Duration,
	consistentRead *bool,
	projectedAttributes ...string) (notFound bool, err *DynamoDBError)

BatchGetItems accepts a slice of search keys (of DynamoDBSearchKeys struct object), optionally define attribute projections, and return found result items;

important 

if dynamodb table is defined as PK and SK together, then to search, MUST use PK and SK together or error will trigger

parameters: 

resultItemsPtr = required, pointer to items list struct to contain queried result; i.e. []Item{} where Item is struct; if projected attributes less than struct fields, unmatched is defaulted
searchKeys = required, slice of DynamoDBTableKeys struct objects to perform search against
timeOutDuration = optional, timeout duration sent via context to scan method; nil if not using timeout duration
consistentRead = optional, indicates if the read operation requires consistent read status
projectedAttributes = optional; ATTRIBUTES ARE CASE SENSITIVE; variadic list of attribute names that this query will project into result items;
				      attribute names must match struct field name or struct tag's json / dynamodbav tag values

return values: 

notFound = true if no items found; if error encountered, this field returns false with error field filled
err = if error is encountered, this field will be filled; otherwise nil

notes: 

item struct tags
	use `json:"" dynamodbav:""`
		json = sets the name used in json
		dynamodbav = sets the name used in dynamodb
	reference child element
		if struct has field with complex type (another struct), to reference it in code, use the parent struct field dot child field notation
			Info in parent struct with struct tag as info; to reach child element: info.xyz

func (*DynamoDB) BatchGetItemsWithRetry added in v1.1.4 

func (d *DynamoDB) BatchGetItemsWithRetry(maxRetries uint,
	resultItemsPtr interface{},
	searchKeys []DynamoDBTableKeys,
	timeOutDuration *time.Duration,
	consistentRead *bool,
	projectedAttributes ...string) (notFound bool, err *DynamoDBError)

BatchGetItemsWithRetry handles dynamodb retries in case action temporarily fails

func (*DynamoDB) BatchWriteItems 

func (d *DynamoDB) BatchWriteItems(putItems interface{},
	deleteKeys []DynamoDBTableKeys,
	timeOutDuration *time.Duration) (successCount int, unprocessedItems *DynamoDBUnprocessedItemsAndKeys, err *DynamoDBError)

BatchWriteItems will group up to 25 put and delete items in a single batch, and perform actions in parallel against dynamodb for better write efficiency， To update items, use UpdateItem instead for each item needing to be updated instead, BatchWriteItems does not support update items

important 

if dynamodb table is defined as PK and SK together, then to search, MUST use PK and SK together or error will trigger

parameters: 

putItems = slice of item struct objects to add to table (combine of putItems and deleteItems cannot exceed 25)
	1) Each element of slice is an struct object to be added, struct object must have PK, SK or another named primary key for example, and other attributes as needed
	2) putItems interface{} = Expects SLICE of STRUCT OBJECTS

deleteKeys = slice of search keys (as defined by DynamoDBTableKeys struct) to remove from table (combine of putItems and deleteKeys cannot exceed 25)
	1) Each element of slice is an struct object of DynamoDBTableKeys

timeOutDuration = optional, timeout duration sent via context to scan method; nil if not using timeout duration

return values: 

successCount = total number of item actions succeeded
unprocessedItems = any item actions did not succeed is returned; nil means all processed
err = if method call failed, error is returned

notes: 

item struct tags
	use `json:"" dynamodbav:""`
		json = sets the name used in json
		dynamodbav = sets the name used in dynamodb
	reference child element
		if struct has field with complex type (another struct), to reference it in code, use the parent struct field dot child field notation
			Info in parent struct with struct tag as info; to reach child element: info.xyz

func (*DynamoDB) BatchWriteItemsWithRetry added in v1.1.4 

func (d *DynamoDB) BatchWriteItemsWithRetry(maxRetries uint,
	putItems interface{}, deleteKeys []DynamoDBTableKeys,
	timeOutDuration *time.Duration) (successCount int, unprocessedItems *DynamoDBUnprocessedItemsAndKeys, err *DynamoDBError)

BatchWriteItemsWithRetry handles dynamodb retries in case action temporarily fails

func (*DynamoDB) Connect 

func (d *DynamoDB) Connect(parentSegment ...*xray.XRayParentSegment) (err error)

Connect will establish a connection to the dynamodb service

func (*DynamoDB) DeleteItem 

func (d *DynamoDB) DeleteItem(pkValue string, skValue string, timeOutDuration *time.Duration) (ddbErr *DynamoDBError)

DeleteItem will delete an existing item from dynamodb table, using primary key values (PK and SK)

important 

if dynamodb table is defined as PK and SK together, then to search, MUST use PK and SK together or error will trigger

parameters: 

pkValue = required, value of partition key to seek
skValue = optional, value of sort key to seek; set to blank if value not provided
timeOutDuration = optional, timeout duration sent via context to scan method; nil if not using timeout duration

func (*DynamoDB) DeleteItemWithRetry added in v1.1.4 

func (d *DynamoDB) DeleteItemWithRetry(maxRetries uint, pkValue string, skValue string, timeOutDuration *time.Duration) *DynamoDBError

DeleteItemWithRetry handles dynamodb retries in case action temporarily fails

func (*DynamoDB) DisableDax 

func (d *DynamoDB) DisableDax()

DisableDax will disable dax service for this dynamodb session

func (*DynamoDB) EnableDax 

func (d *DynamoDB) EnableDax() (err error)

EnableDax will enable dax service for this dynamodb session

func (*DynamoDB) GetItem 

func (d *DynamoDB) GetItem(resultItemPtr interface{},
	pkValue string, skValue string,
	timeOutDuration *time.Duration, consistentRead *bool, projectedAttributes ...string) (ddbErr *DynamoDBError)

GetItem will find an existing item from dynamodb table

important 

if dynamodb table is defined as PK and SK together, then to search, MUST use PK and SK together or error will trigger

parameters: 

resultItemPtr = required, pointer to item object for return value to unmarshal into; if projected attributes less than struct fields, unmatched is defaulted
	a) MUST BE STRUCT OBJECT; NEVER A SLICE
pkValue = required, value of partition key to seek
skValue = optional, value of sort key to seek; set to blank if value not provided
timeOutDuration = optional, timeout duration sent via context to scan method; nil if not using timeout duration
consistentRead = optional, scan uses consistent read or eventual consistent read, default is eventual consistent read
projectedAttributes = optional; ATTRIBUTES ARE CASE SENSITIVE; variadic list of attribute names that this query will project into result items;
				      attribute names must match struct field name or struct tag's json / dynamodbav tag values

notes: 

item struct tags
	use `json:"" dynamodbav:""`
		json = sets the name used in json
		dynamodbav = sets the name used in dynamodb
	reference child element
		if struct has field with complex type (another struct), to reference it in code, use the parent struct field dot child field notation
			Info in parent struct with struct tag as info; to reach child element: info.xyz

func (*DynamoDB) GetItemWithRetry added in v1.1.4 

func (d *DynamoDB) GetItemWithRetry(maxRetries uint,
	resultItemPtr interface{}, pkValue string, skValue string,
	timeOutDuration *time.Duration, consistentRead *bool, projectedAttributes ...string) *DynamoDBError

GetItemWithRetry handles dynamodb retries in case action temporarily fails

func (*DynamoDB) PutItem 

func (d *DynamoDB) PutItem(item interface{}, timeOutDuration *time.Duration) (ddbErr *DynamoDBError)

PutItem will add or update a new item into dynamodb table

parameters: 

item = required, must be a struct object; ALWAYS SINGLE STRUCT OBJECT, NEVER SLICE
	   must start with fields 'pk string', 'sk string', and 'data string' before any other attributes
timeOutDuration = optional, timeout duration sent via context to scan method; nil if not using timeout duration

notes: 

item struct tags
	use `json:"" dynamodbav:""`
		json = sets the name used in json
		dynamodbav = sets the name used in dynamodb
	reference child element
		if struct has field with complex type (another struct), to reference it in code, use the parent struct field dot child field notation
			Info in parent struct with struct tag as info; to reach child element: info.xyz

func (*DynamoDB) PutItemWithRetry added in v1.1.4 

func (d *DynamoDB) PutItemWithRetry(maxRetries uint, item interface{}, timeOutDuration *time.Duration) *DynamoDBError

PutItemWithRetry add or updates, and handles dynamodb retries in case action temporarily fails

func (*DynamoDB) QueryItems 

func (d *DynamoDB) QueryItems(resultItemsPtr interface{},
	timeOutDuration *time.Duration,
	consistentRead *bool,
	indexName *string,
	pageLimit *int64,
	pagedQuery bool,
	pagedQueryPageCountLimit *int64,
	exclusiveStartKey map[string]*dynamodb.AttributeValue,
	keyConditionExpression string,
	expressionAttributeNames map[string]*string,
	expressionAttributeValues map[string]*dynamodb.AttributeValue,
	filterConditionExpression *expression.ConditionBuilder,
	projectedAttributes ...string) (prevEvalKey map[string]*dynamodb.AttributeValue, ddbErr *DynamoDBError)

QueryItems will query dynamodb items in given table using primary key (PK, SK for example), or one of Global/Local Secondary Keys (indexName must be defined if using GSI) To query against non-key attributes, use Scan (bad for performance however) QueryItems requires using Key attributes, and limited to TWO key attributes in condition maximum;

important 

if dynamodb table is defined as PK and SK together, then to search without GSI/LSI, MUST use PK and SK together or error will trigger

parameters: 

resultItemsPtr = required, pointer to items list struct to contain queried result; i.e. []Item{} where Item is struct; if projected attributes less than struct fields, unmatched is defaulted
timeOutDuration = optional, timeout duration sent via context to scan method; nil if not using timeout duration
consistentRead = optional, scan uses consistent read or eventual consistent read, default is eventual consistent read
indexName = optional, global secondary index or local secondary index name to help in query operation
pageLimit = optional, scan page limit if set, this limits number of items examined per page during scan operation, allowing scan to work better for RCU
pagedQuery = optional, indicates if query is page based or not; if true, query will be performed via pages, this helps overcome 1 MB limit of each query result
pagedQueryPageCountLimit = optional, indicates how many pages to query during paged query action
exclusiveStartKey = optional, if using pagedQuery and starting the query from prior results

keyConditionExpression = required, ATTRIBUTES ARE CASE SENSITIVE; either the primary key (PK SK for example) or global secondary index (SK Data for example) or another secondary index (secondary index must be named)
	Usage Syntax:
		1) Max 2 Attribute Fields
		2) First Field must be Partition Key (Must Evaluate to True or False)
			a) = ONLY
		3) Second Field is Sort Key (May Evaluate to True or False or Range)
			a) =, <, <=, >, >=, BETWEEN, begins_with()
		4) Combine Two Fields with AND
		5) When Attribute Name is Reserved Keyword, Use ExpressionAttributeNames to Define #xyz to Alias
			a) Use the #xyz in the KeyConditionExpression such as #yr = :year (:year is Defined ExpressionAttributeValue)
		6) Example
			a) partitionKeyName = :partitionKeyVal
			b) partitionKeyName = :partitionKeyVal AND sortKeyName = :sortKeyVal
			c) #yr = :year
		7) If Using GSI / Local Index
			a) When Using, Must Specify the IndexName
			b) First Field is the GSI's Partition Key, such as SK (Evals to True/False), While Second Field is the GSI's SortKey (Range)

expressionAttributeNames = optional, ATTRIBUTES ARE CASE SENSITIVE; set nil if not used, must define for attribute names that are reserved keywords such as year, data etc. using #xyz
	Usage Syntax:
		1) map[string]*string: where string is the #xyz, and *string is the original xyz attribute name
			a) map[string]*string { "#xyz": aws.String("Xyz"), }
		2) Add to Map
			a) m := make(map[string]*string)
			b) m["#xyz"] = aws.String("Xyz")

expressionAttributeValues = required, ATTRIBUTES ARE CASE SENSITIVE; sets the value token and value actual to be used within the keyConditionExpression; this sets both compare token and compare value
	Usage Syntax:
		1) map[string]*dynamodb.AttributeValue: where string is the :xyz, and *dynamodb.AttributeValue is { S: aws.String("abc"), },
			a) map[string]*dynamodb.AttributeValue { ":xyz" : { S: aws.String("abc"), }, ":xyy" : { N: aws.String("123"), }, }
		2) Add to Map
			a) m := make(map[string]*dynamodb.AttributeValue)
			b) m[":xyz"] = &dynamodb.AttributeValue{ S: aws.String("xyz") }
		3) Slice of Strings -> CONVERT To Slice of *dynamodb.AttributeValue = []string -> []*dynamodb.AttributeValue
			a) av, err := dynamodbattribute.MarshalList(xyzSlice)
			b) ExpressionAttributeValue, Use 'L' To Represent the List for av defined in 3.a above

filterConditionExpression = optional; ATTRIBUTES ARE CASE SENSITIVE; once query on key conditions returned, this filter condition further restricts return data before output to caller;
	Usage Syntax:
		1) &expression.Name(xyz).Equals(expression.Value(abc))
		2) &expression.Name(xyz).Equals(expression.Value(abc)).And(...)

projectedAttributes = optional; ATTRIBUTES ARE CASE SENSITIVE; variadic list of attribute names that this query will project into result items;
				      attribute names must match struct field name or struct tag's json / dynamodbav tag values

Return Values: 

prevEvalKey = if paged query, the last evaluate key returned, to be used in subsequent query via exclusiveStartKey; otherwise always nil is returned
			  prevEvalkey map is set into exclusiveStartKey field if more data to load

notes: 

item struct tags
	use `json:"" dynamodbav:""`
		json = sets the name used in json
		dynamodbav = sets the name used in dynamodb
	reference child element
		if struct has field with complex type (another struct), to reference it in code, use the parent struct field dot child field notation
			Info in parent struct with struct tag as info; to reach child element: info.xyz

func (*DynamoDB) QueryItemsWithRetry added in v1.1.4 

func (d *DynamoDB) QueryItemsWithRetry(maxRetries uint,
	resultItemsPtr interface{},
	timeOutDuration *time.Duration,
	consistentRead *bool,
	indexName *string,
	pageLimit *int64,
	pagedQuery bool,
	pagedQueryPageCountLimit *int64,
	exclusiveStartKey map[string]*dynamodb.AttributeValue,
	keyConditionExpression string,
	expressionAttributeNames map[string]*string,
	expressionAttributeValues map[string]*dynamodb.AttributeValue,
	filterConditionExpression *expression.ConditionBuilder,
	projectedAttributes ...string) (prevEvalKey map[string]*dynamodb.AttributeValue, ddbErr *DynamoDBError)

QueryItemsWithRetry handles dynamodb retries in case action temporarily fails

func (*DynamoDB) QueryPagedItemsWithRetry added in v1.1.4 

func (d *DynamoDB) QueryPagedItemsWithRetry(maxRetries uint,
	pagedSlicePtr interface{},
	resultSlicePtr interface{},
	timeOutDuration *time.Duration,
	indexName string,
	keyConditionExpression string,
	expressionAttributeValues map[string]*dynamodb.AttributeValue,
	filterConditionExpression *expression.ConditionBuilder) (returnItemsList interface{}, err error)

QueryPagedItemsWithRetry will query dynamodb items in given table using primary key (PK, SK for example), or one of Global/Local Secondary Keys (indexName must be defined if using GSI)

To query against non-key attributes, use Scan (bad for performance however) QueryItems requires using Key attributes, and limited to TWO key attributes in condition maximum;

important 

if dynamodb table is defined as PK and SK together, then to search without GSI/LSI, MUST use PK and SK together or error will trigger

parameters: 

pagedSlicePtr = required, identifies the actual slice pointer for use during paged query
				(this parameter is not the output of result, actual result is returned via return variable returnItemsList)
resultSlicePtr = required, pointer to working items list struct to contain queried result;
				 i.e. []Item{} where Item is struct; if projected attributes less than struct fields, unmatched is defaulted;
				 (this parameter is not the output of result, actual result is returned via return variable returnItemsList)
timeOutDuration = optional, timeout duration sent via context to scan method; nil if not using timeout duration
consistentRead = (always set to false for paged query internally)
indexName = optional, global secondary index or local secondary index name to help in query operation
pageLimit = (always set to 100 internally)
pagedQuery = (always set to true internally)
pagedQueryPageCountLimit = (always set to 25 internally)
exclusiveStartKey = (set internally by the paged query loop if any exists)
keyConditionExpression = required, ATTRIBUTES ARE CASE SENSITIVE; either the primary key (PK SK for example) or global secondary index (SK Data for example) or another secondary index (secondary index must be named)
	Usage Syntax:
		1) Max 2 Attribute Fields
		2) First Field must be Partition Key (Must Evaluate to True or False)
			a) = ONLY
		3) Second Field is Sort Key (May Evaluate to True or False or Range)
			a) =, <, <=, >, >=, BETWEEN, begins_with()
		4) Combine Two Fields with AND
		5) When Attribute Name is Reserved Keyword, Use ExpressionAttributeNames to Define #xyz to Alias
			a) Use the #xyz in the KeyConditionExpression such as #yr = :year (:year is Defined ExpressionAttributeValue)
		6) Example
			a) partitionKeyName = :partitionKeyVal
			b) partitionKeyName = :partitionKeyVal AND sortKeyName = :sortKeyVal
			c) #yr = :year
		7) If Using GSI / Local Index
			a) When Using, Must Specify the IndexName
			b) First Field is the GSI's Partition Key, such as SK (Evals to True/False), While Second Field is the GSI's SortKey (Range)
expressionAttributeNames = (always nil internally, not used in paged query)
expressionAttributeValues = required, ATTRIBUTES ARE CASE SENSITIVE; sets the value token and value actual to be used within the keyConditionExpression; this sets both compare token and compare value
	Usage Syntax:
		1) map[string]*dynamodb.AttributeValue: where string is the :xyz, and *dynamodb.AttributeValue is { S: aws.String("abc"), },
			a) map[string]*dynamodb.AttributeValue { ":xyz" : { S: aws.String("abc"), }, ":xyy" : { N: aws.String("123"), }, }
		2) Add to Map
			a) m := make(map[string]*dynamodb.AttributeValue)
			b) m[":xyz"] = &dynamodb.AttributeValue{ S: aws.String("xyz") }
		3) Slice of Strings -> CONVERT To Slice of *dynamodb.AttributeValue = []string -> []*dynamodb.AttributeValue
			a) av, err := dynamodbattribute.MarshalList(xyzSlice)
			b) ExpressionAttributeValue, Use 'L' To Represent the List for av defined in 3.a above
filterConditionExpression = optional; ATTRIBUTES ARE CASE SENSITIVE; once query on key conditions returned, this filter condition further restricts return data before output to caller;
	Usage Syntax:
		1) &expression.Name(xyz).Equals(expression.Value(abc))
		2) &expression.Name(xyz).Equals(expression.Value(abc)).And(...)
projectedAttributes = (always nil internally for paged query)

Return Values: 

returnItemsList = interface{} of return slice, use assert to cast to target type
err = error info if error is encountered

notes: 

item struct tags
	use `json:"" dynamodbav:""`
		json = sets the name used in json
		dynamodbav = sets the name used in dynamodb
	reference child element
		if struct has field with complex type (another struct), to reference it in code, use the parent struct field dot child field notation
			Info in parent struct with struct tag as info; to reach child element: info.xyz

func (*DynamoDB) ScanItems 

func (d *DynamoDB) ScanItems(resultItemsPtr interface{},
	timeOutDuration *time.Duration,
	consistentRead *bool,
	indexName *string,
	pageLimit *int64,
	pagedQuery bool,
	pagedQueryPageCountLimit *int64,
	exclusiveStartKey map[string]*dynamodb.AttributeValue,
	filterConditionExpression expression.ConditionBuilder, projectedAttributes ...string) (prevEvalKey map[string]*dynamodb.AttributeValue, ddbErr *DynamoDBError)

ScanItems will scan dynamodb items in given table, project results, using filter expression >>> DO NOT USE SCAN IF POSSIBLE - SCAN IS NOT EFFICIENT ON RCU <<<

parameters: 

resultItemsPtr = required, pointer to items list struct to contain queried result; i.e. []Item{} where Item is struct; if projected attributes less than struct fields, unmatched is defaulted
timeOutDuration = optional, timeout duration sent via context to scan method; nil if not using timeout duration
consistentRead = optional, scan uses consistent read or eventual consistent read, default is eventual consistent read
indexName = optional, global secondary index or local secondary index name to help in scan operation
pageLimit = optional, scan page limit if set, this limits number of items examined per page during scan operation, allowing scan to work better for RCU
pagedQuery = optional, indicates if query is page based or not; if true, query will be performed via pages, this helps overcome 1 MB limit of each query result
pagedQueryPageCountLimit = optional, indicates how many pages to query during paged query action
exclusiveStartKey = optional, if using pagedQuery and starting the query from prior results

filterConditionExpression = required; ATTRIBUTES ARE CASE SENSITIVE; sets the scan filter condition;
	Usage Syntax:
		1) expFilter := expression.Name(xyz).Equals(expression.Value(abc))
		2) expFilter := expression.Name(xyz).Equals(expression.Value(abc)).And(...)
		3) Assign expFilter into filterConditionExpression

projectedAttributes = optional; ATTRIBUTES ARE CASE SENSITIVE; variadic list of attribute names that this query will project into result items;
				      attribute names must match struct field name or struct tag's json / dynamodbav tag values

Return Values: 

prevEvalKey = if paged query, the last evaluate key returned, to be used in subsequent query via exclusiveStartKey; otherwise always nil is returned

notes: 

item struct tags
	use `json:"" dynamodbav:""`
		json = sets the name used in json
		dynamodbav = sets the name used in dynamodb
	reference child element
		if struct has field with complex type (another struct), to reference it in code, use the parent struct field dot child field notation
			Info in parent struct with struct tag as info; to reach child element: info.xyz

func (*DynamoDB) ScanItemsWithRetry added in v1.1.4 

func (d *DynamoDB) ScanItemsWithRetry(maxRetries uint,
	resultItemsPtr interface{},
	timeOutDuration *time.Duration,
	consistentRead *bool,
	indexName *string,
	pageLimit *int64,
	pagedQuery bool,
	pagedQueryPageCountLimit *int64,
	exclusiveStartKey map[string]*dynamodb.AttributeValue,
	filterConditionExpression expression.ConditionBuilder, projectedAttributes ...string) (prevEvalKey map[string]*dynamodb.AttributeValue, ddbErr *DynamoDBError)

ScanItemsWithRetry handles dynamodb retries in case action temporarily fails

func (*DynamoDB) ScanPagedItemsWithRetry added in v1.1.4 

func (d *DynamoDB) ScanPagedItemsWithRetry(maxRetries uint,
	pagedSlicePtr interface{},
	resultSlicePtr interface{},
	timeOutDuration *time.Duration,
	indexName string,
	filterConditionExpression expression.ConditionBuilder) (returnItemsList interface{}, err error)

ScanPagedItemsWithRetry will scan dynamodb items in given table using paged mode with retry, project results, using filter expression >>> DO NOT USE SCAN IF POSSIBLE - SCAN IS NOT EFFICIENT ON RCU <<<

parameters: 

maxRetries = required, max number of auto retries per paged query
pagedSlicePtr = required, working variable to store paged query (actual return items list is via return variable)
resultSlicePtr = required, pointer to items list struct to contain queried result; i.e. []Item{} where Item is struct; if projected attributes less than struct fields, unmatched is defaulted
timeOutDuration = optional, timeout duration sent via context to scan method; nil if not using timeout duration
consistentRead = (always false)
indexName = optional, global secondary index or local secondary index name to help in scan operation
pageLimit = (always 100)
pagedQuery = (always true)
pagedQueryPageCountLimit = (always 25)
exclusiveStartKey = (always internally controlled during paged query)

filterConditionExpression = required; ATTRIBUTES ARE CASE SENSITIVE; sets the scan filter condition;
	Usage Syntax:
		1) expFilter := expression.Name(xyz).Equals(expression.Value(abc))
		2) expFilter := expression.Name(xyz).Equals(expression.Value(abc)).And(...)
		3) Assign expFilter into filterConditionExpression

projectedAttributes = (always project all attributes)

Return Values: 

returnItemsList = interface of slice returned, representing the items found during scan
err = error if encountered

notes: 

item struct tags
	use `json:"" dynamodbav:""`
		json = sets the name used in json
		dynamodbav = sets the name used in dynamodb
	reference child element
		if struct has field with complex type (another struct), to reference it in code, use the parent struct field dot child field notation
			Info in parent struct with struct tag as info; to reach child element: info.xyz

func (*DynamoDB) TimeOutDuration added in v1.1.4 

func (d *DynamoDB) TimeOutDuration(timeOutSeconds uint) *time.Duration

func (*DynamoDB) TransactionGetItems 

func (d *DynamoDB) TransactionGetItems(timeOutDuration *time.Duration, tranKeys ...*DynamoDBTransactionReads) (successCount int, err *DynamoDBError)

TransactionGetItems receives parameters via tranKeys variadic objects of type DynamoDBTransactionReads; each object has TableName override in case querying against other tables Each tranKeys struct object can contain one or more DynamoDBTableKeys struct, which contains PK, SK fields, and ResultItemPtr, The PK (required) and SK (optional) is used for search, while ResultItemPtr interface{} receives pointer to the output object, so that once query completes the appropriate item data will unmarshal into object

important 

if dynamodb table is defined as PK and SK together, then to search, MUST use PK and SK together or error will trigger

setting result item ptr info

  1. Each DynamoDBTableKeys struct object must set pointer of output struct object to ResultItemPtr
  2. In the external calling code, must define slice of struct object pointers to receive such unmarshaled results a) output := []*MID{ &MID{}, &MID{}, } b) Usage Passing each element of output to ResultItemPtr within DynamoDBTableKeys struct object

notes:

  1. transKeys' must contain at laest one object
  2. within transKeys object, at least one object of DynamoDBTableKeys must exist for search
  3. no more than total of 25 search keys allowed across all variadic objects
  4. the ResultItemPtr in all DynamoDBTableKeys objects within all variadic objects MUST BE SET

func (*DynamoDB) TransactionGetItemsWithRetry added in v1.1.4 

func (d *DynamoDB) TransactionGetItemsWithRetry(maxRetries uint,
	timeOutDuration *time.Duration,
	tranKeys ...*DynamoDBTransactionReads) (successCount int, err *DynamoDBError)

TransactionGetItemsWithRetry handles dynamodb retries in case action temporarily fails

func (*DynamoDB) TransactionWriteItems 

func (d *DynamoDB) TransactionWriteItems(timeOutDuration *time.Duration, tranItems ...*DynamoDBTransactionWrites) (success bool, err *DynamoDBError)

TransactionWriteItems performs a transaction write action for one or more DynamoDBTransactionWrites struct objects, Either all success or all fail, Total Items Count in a Single Transaction for All transItems combined (inner elements) cannot exceed 25

important 

if dynamodb table is defined as PK and SK together, then to search, MUST use PK and SK together or error will trigger

func (*DynamoDB) TransactionWriteItemsWithRetry added in v1.1.4 

func (d *DynamoDB) TransactionWriteItemsWithRetry(maxRetries uint,
	timeOutDuration *time.Duration,
	tranItems ...*DynamoDBTransactionWrites) (success bool, err *DynamoDBError)

TransactionWriteItemsWithRetry handles dynamodb retries in case action temporarily fails

func (*DynamoDB) UpdateItem 

func (d *DynamoDB) UpdateItem(pkValue string, skValue string,
	updateExpression string,
	conditionExpression string,
	expressionAttributeNames map[string]*string,
	expressionAttributeValues map[string]*dynamodb.AttributeValue,
	timeOutDuration *time.Duration) (ddbErr *DynamoDBError)

UpdateItem will update dynamodb item in given table using primary key (PK, SK), and set specific attributes with new value and persists UpdateItem requires using Primary Key attributes, and limited to TWO key attributes in condition maximum;

important 

if dynamodb table is defined as PK and SK together, then to search, MUST use PK and SK together or error will trigger

parameters: 

pkValue = required, value of partition key to seek
skValue = optional, value of sort key to seek; set to blank if value not provided

updateExpression = required, ATTRIBUTES ARE CASE SENSITIVE; set remove add or delete action expression, see Rules URL for full detail
	Rules:
		1) https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.UpdateExpressions.html
	Usage Syntax:
		1) Action Keywords are: set, add, remove, delete
		2) Each Action Keyword May Appear in UpdateExpression Only Once
		3) Each Action Keyword Grouping May Contain One or More Actions, Such as 'set price=:p, age=:age, etc' (each action separated by comma)
		4) Each Action Keyword Always Begin with Action Keyword itself, such as 'set ...', 'add ...', etc
		5) If Attribute is Numeric, Action Can Perform + or - Operation in Expression, such as 'set age=age-:newAge, price=price+:price, etc'
		6) If Attribute is Slice, Action Can Perform Slice Element Operation in Expression, such as 'set age[2]=:newData, etc'
		7) When Attribute Name is Reserved Keyword, Use ExpressionAttributeNames to Define #xyz to Alias
			a) Use the #xyz in the KeyConditionExpression such as #yr = :year (:year is Defined ExpressionAttributeValue)
		8) When Attribute is a List, Use list_append(a, b, ...) in Expression to append elements (list_append() is case sensitive)
			a) set #ri = list_append(#ri, :vals) where :vals represents one or more of elements to add as in L
		9) if_not_exists(path, value)
			a) Avoids existing attribute if already exists
			b) set price = if_not_exists(price, :p)
			c) if_not_exists is case sensitive; path is the existing attribute to check
		10) Action Type Purposes
			a) SET = add one or more attributes to an item; overrides existing attributes in item with new values; if attribute is number, able to perform + or - operations
			b) REMOVE = remove one or more attributes from an item, to remove multiple attributes, separate by comma; remove element from list use xyz[1] index notation
			c) ADD = adds a new attribute and its values to an item; if attribute is number and already exists, value will add up or subtract
			d) DELETE = supports only on set data types; deletes one or more elements from a set, such as 'delete color :c'
		11) Example
			a) set age=:age, name=:name, etc
			b) set age=age-:age, num=num+:num, etc

conditionExpress = optional, ATTRIBUTES ARE CASE SENSITIVE; sets conditions for this condition expression, set to blank if not used
		Usage Syntax:
			1) "size(info.actors) >= :num"
				a) When Length of Actors Attribute Value is Equal or Greater Than :num, ONLY THEN UpdateExpression is Performed
			2) ExpressionAttributeName and ExpressionAttributeValue is Still Defined within ExpressionAttributeNames and ExpressionAttributeValues Where Applicable

expressionAttributeNames = optional, ATTRIBUTES ARE CASE SENSITIVE; set nil if not used, must define for attribute names that are reserved keywords such as year, data etc. using #xyz
	Usage Syntax:
		1) map[string]*string: where string is the #xyz, and *string is the original xyz attribute name
			a) map[string]*string { "#xyz": aws.String("Xyz"), }
		2) Add to Map
			a) m := make(map[string]*string)
			b) m["#xyz"] = aws.String("Xyz")

expressionAttributeValues = required, ATTRIBUTES ARE CASE SENSITIVE; sets the value token and value actual to be used within the keyConditionExpression; this sets both compare token and compare value
	Usage Syntax:
		1) map[string]*dynamodb.AttributeValue: where string is the :xyz, and *dynamodb.AttributeValue is { S: aws.String("abc"), },
			a) map[string]*dynamodb.AttributeValue { ":xyz" : { S: aws.String("abc"), }, ":xyy" : { N: aws.String("123"), }, }
		2) Add to Map
			a) m := make(map[string]*dynamodb.AttributeValue)
			b) m[":xyz"] = &dynamodb.AttributeValue{ S: aws.String("xyz") }
		3) Slice of Strings -> CONVERT To Slice of *dynamodb.AttributeValue = []string -> []*dynamodb.AttributeValue
			a) av, err := dynamodbattribute.MarshalList(xyzSlice)
			b) ExpressionAttributeValue, Use 'L' To Represent the List for av defined in 3.a above

timeOutDuration = optional, timeout duration sent via context to scan method; nil if not using timeout duration

notes: 

item struct tags
	use `json:"" dynamodbav:""`
		json = sets the name used in json
		dynamodbav = sets the name used in dynamodb
	reference child element
		if struct has field with complex type (another struct), to reference it in code, use the parent struct field dot child field notation
			Info in parent struct with struct tag as info; to reach child element: info.xyz

func (*DynamoDB) UpdateItemWithRetry added in v1.1.4 

func (d *DynamoDB) UpdateItemWithRetry(maxRetries uint,
	pkValue string, skValue string,
	updateExpression string,
	conditionExpression string,
	expressionAttributeNames map[string]*string,
	expressionAttributeValues map[string]*dynamodb.AttributeValue,
	timeOutDuration *time.Duration) *DynamoDBError

UpdateItemWithRetry handles dynamodb retries in case action temporarily fails

func (*DynamoDB) UpdateParentSegment added in v1.1.4 

func (d *DynamoDB) UpdateParentSegment(parentSegment *xray.XRayParentSegment)

UpdateParentSegment updates this struct's xray parent segment, if no parent segment, set nil

type DynamoDBError 

type DynamoDBError struct {
	ErrorMessage  string
	SuppressError bool

	AllowRetry        bool
	RetryNeedsBackOff bool
}

DynamoDBError struct contains special status info including error and retry advise

func (*DynamoDBError) Error 

func (e *DynamoDBError) Error() string

Error returns error string of the struct object

type DynamoDBTableKeys 

type DynamoDBTableKeys struct {
	PK string
	SK string

	ResultItemPtr interface{} `dynamodbav:"-"`
	ResultError   error       `dynamodbav:"-"`
	// contains filtered or unexported fields
}

DynamoDBTableKeys struct defines the PK and SK fields to be used in key search (Always PK and SK)

important 

if dynamodb table is defined as PK and SK together, then to search, MUST use PK and SK together or error will trigger

ResultItemPtr = optional, used with TransactionGetItems() to denote output unmarshal object target

type DynamoDBTransactionReads 

type DynamoDBTransactionReads struct {
	Keys              []*DynamoDBTableKeys
	TableNameOverride string
}

DynamoDBTransactionReads defines one or more items to get by PK / SK

type DynamoDBTransactionWrites 

type DynamoDBTransactionWrites struct {
	PutItems          interface{}
	UpdateItems       []*DynamoDBUpdateItemInput
	DeleteItems       []*DynamoDBTableKeys
	TableNameOverride string
}

DynamoDBTransactionWrites defines one or more items to put, update or delete

notes 

PutItems interface{} = is Slice of PutItems: []Xyz
	a) We use interface{} because []interface{} will require each element conversion (instead we will handle conversion by internal code)
	b) PutItems ALWAYS Slice of Struct (Value), NOT pointers to Structs

func (*DynamoDBTransactionWrites) MarshalPutItems 

func (w *DynamoDBTransactionWrites) MarshalPutItems() (result []map[string]*dynamodb.AttributeValue, err error)

MarshalPutItems will marshal dynamodb transaction writes' put items into []map[string]*dynamodb.AttributeValue

type DynamoDBUnprocessedItemsAndKeys 

type DynamoDBUnprocessedItemsAndKeys struct {
	PutItems   []map[string]*dynamodb.AttributeValue
	DeleteKeys []*DynamoDBTableKeys
}

DynamoDBUnprocessedItemsAndKeys defines struct to slices of items and keys

func (*DynamoDBUnprocessedItemsAndKeys) UnmarshalPutItems 

func (u *DynamoDBUnprocessedItemsAndKeys) UnmarshalPutItems(resultItemsPtr interface{}) error

UnmarshalPutItems will convert struct's PutItems into target slice of struct objects

notes: 

resultItemsPtr interface{} = Input is Slice of Actual Struct Objects

type DynamoDBUpdateItemInput 

type DynamoDBUpdateItemInput struct {
	PK                        string
	SK                        string
	UpdateExpression          string
	ConditionExpression       string
	ExpressionAttributeNames  map[string]*string
	ExpressionAttributeValues map[string]*dynamodb.AttributeValue
}

DynamoDBUpdateItemInput defines a single item update instruction

important 

if dynamodb table is defined as PK and SK together, then to search, MUST use PK and SK together or error will trigger

parameters: 

pkValue = required, value of partition key to seek
skValue = optional, value of sort key to seek; set to blank if value not provided

updateExpression = required, ATTRIBUTES ARE CASE SENSITIVE; set remove add or delete action expression, see Rules URL for full detail
	Rules:
		1) https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.UpdateExpressions.html
	Usage Syntax:
		1) Action Keywords are: set, add, remove, delete
		2) Each Action Keyword May Appear in UpdateExpression Only Once
		3) Each Action Keyword Grouping May Contain One or More Actions, Such as 'set price=:p, age=:age, etc' (each action separated by comma)
		4) Each Action Keyword Always Begin with Action Keyword itself, such as 'set ...', 'add ...', etc
		5) If Attribute is Numeric, Action Can Perform + or - Operation in Expression, such as 'set age=age-:newAge, price=price+:price, etc'
		6) If Attribute is Slice, Action Can Perform Slice Element Operation in Expression, such as 'set age[2]=:newData, etc'
		7) When Attribute Name is Reserved Keyword, Use ExpressionAttributeNames to Define #xyz to Alias
			a) Use the #xyz in the KeyConditionExpression such as #yr = :year (:year is Defined ExpressionAttributeValue)
		8) When Attribute is a List, Use list_append(a, b, ...) in Expression to append elements (list_append() is case sensitive)
			a) set #ri = list_append(#ri, :vals) where :vals represents one or more of elements to add as in L
		9) if_not_exists(path, value)
			a) Avoids existing attribute if already exists
			b) set price = if_not_exists(price, :p)
			c) if_not_exists is case sensitive; path is the existing attribute to check
		10) Action Type Purposes
			a) SET = add one or more attributes to an item; overrides existing attributes in item with new values; if attribute is number, able to perform + or - operations
			b) REMOVE = remove one or more attributes from an item, to remove multiple attributes, separate by comma; remove element from list use xyz[1] index notation
			c) ADD = adds a new attribute and its values to an item; if attribute is number and already exists, value will add up or subtract
			d) DELETE = supports only on set data types; deletes one or more elements from a set, such as 'delete color :c'
		11) Example
			a) set age=:age, name=:name, etc
			b) set age=age-:age, num=num+:num, etc

conditionExpress = optional, ATTRIBUTES ARE CASE SENSITIVE; sets conditions for this condition expression, set to blank if not used
		Usage Syntax:
			1) "size(info.actors) >= :num"
				a) When Length of Actors Attribute Value is Equal or Greater Than :num, ONLY THEN UpdateExpression is Performed
			2) ExpressionAttributeName and ExpressionAttributeValue is Still Defined within ExpressionAttributeNames and ExpressionAttributeValues Where Applicable

expressionAttributeNames = optional, ATTRIBUTES ARE CASE SENSITIVE; set nil if not used, must define for attribute names that are reserved keywords such as year, data etc. using #xyz
	Usage Syntax:
		1) map[string]*string: where string is the #xyz, and *string is the original xyz attribute name
			a) map[string]*string { "#xyz": aws.String("Xyz"), }
		2) Add to Map
			a) m := make(map[string]*string)
			b) m["#xyz"] = aws.String("Xyz")

expressionAttributeValues = required, ATTRIBUTES ARE CASE SENSITIVE; sets the value token and value actual to be used within the keyConditionExpression; this sets both compare token and compare value
	Usage Syntax:
		1) map[string]*dynamodb.AttributeValue: where string is the :xyz, and *dynamodb.AttributeValue is { S: aws.String("abc"), },
			a) map[string]*dynamodb.AttributeValue { ":xyz" : { S: aws.String("abc"), }, ":xyy" : { N: aws.String("123"), }, }
		2) Add to Map
			a) m := make(map[string]*dynamodb.AttributeValue)
			b) m[":xyz"] = &dynamodb.AttributeValue{ S: aws.String("xyz") }
		3) Slice of Strings -> CONVERT To Slice of *dynamodb.AttributeValue = []string -> []*dynamodb.AttributeValue
			a) av, err := dynamodbattribute.MarshalList(xyzSlice)
			b) ExpressionAttributeValue, Use 'L' To Represent the List for av defined in 3.a above

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.