dynamodb

package
v1.5.3 Latest Latest
Warning

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

 Go to latest Published: Nov 9, 2024 License: Apache-2.0 Imports: 22 Imported by: 3

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type AttributeValue added in v1.2.5 

type AttributeValue struct {
	Name string

	Value     string   // string value or string value representing number
	IsN       bool     // treats Value as number, and ListValue as number slice
	IsBool    bool     // treats Value as boolean, does not work with ListValue
	ListValue []string // honors IsN to treat ListValue as either list of string or list of numbers

	ComplexMap    interface{} // for map of custom type or custom type slice
	ComplexList   interface{} // for custom type slice
	ComplexObject interface{} // for custom type object
}

type ConnectionConfig added in v1.2.5 

type ConnectionConfig struct {
	Region    string
	TableName string
	UseDax    bool
	DaxUrl    string

	TimeoutSeconds uint
	ActionRetries  uint
}

type Crud added in v1.2.5 

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

func (*Crud) BatchDelete added in v1.2.5 

func (c *Crud) BatchDelete(deleteKeys ...PkSkValuePair) (successCount int, failedDeletes []PkSkValuePair, err error)

BatchDelete removes one or more record from dynamodb table based on the PK SK pairs

func (*Crud) BatchGet added in v1.2.5 

func (c *Crud) BatchGet(searchKeys []PkSkValuePair, resultDataSlicePtr interface{}, consistentRead bool, projectedAttributes ...string) (found bool, err error)

BatchGet executes get against up to 100 PK SK search keys, results populated into resultDataSlicePtr (each slice element is struct of underlying dynamodb table record attributes definition)

warning: projectedAttributes = if specified, MUST include PartitionKey (Hash Key) typically "PK" as the first projected attribute, regardless if used or not

func (*Crud) BatchSet added in v1.2.5 

func (c *Crud) BatchSet(putDataSlice interface{}, deleteKeys []PkSkValuePair) (successCount int, failedPuts []PkSkValuePair, failedDeletes []PkSkValuePair, err error)

BatchSet executes put and delete against up to 25 grouped records combined, putDataSlice = []dataStruct for the put items (make sure not passing in as Ptr) deleteKeys = PK SK pairs slice to delete against failedPuts & failedDeletes = PK SK pairs slices for the failed action attempts

func (*Crud) Close added in v1.2.5 

func (c *Crud) Close()

Close will reset and clean up connection to dynamodb table

func (*Crud) CreateBackup added in v1.2.8 

func (c *Crud) CreateBackup(tableName string, backupName string) (backupArn string, err error)

CreateBackup creates dynamodb backup based on the given input parameter

func (*Crud) CreateGlobalTable added in v1.2.8 

func (c *Crud) CreateGlobalTable(tableName string,
	sse *ddb.SSESpecification,
	lsi []*ddb.LocalSecondaryIndex,
	gsi []*ddb.GlobalSecondaryIndex,
	attributes []*ddb.AttributeDefinition,
	replicaRegions []awsregion.AWSRegion) error

CreateGlobalTable will create a new dynamodb global table based on input parameter values， this function first creates the primary table in the current default region, then this function creates the same table on replicaRegions identified.

billing = default to PAY_PER_REQUEST (onDemand) stream = enabled, with old and new images

global table supported regions: 

us-east-1 (nvirginia), us-east-2 (ohio), us-west-1 (california), us-west-2 (oregon)
eu-west-2 (london), eu-central-1 (frankfurt), eu-west-1 (ireland)
ap-southeast-1 (singapore), ap-southeast-2 (sydney), ap-northeast-1 (tokyo), ap-northeast-2 (seoul)

warning: do not first create the original table, this function creates the primary automatically

func (*Crud) CreatePKValue added in v1.2.5 

func (c *Crud) CreatePKValue(pkApp string, pkService string, pkScope string, pkIdentifier string, values ...string) (pkValue string, err error)

CreatePKValue generates composite pk values from configured app and service name, along with parameterized pk values

func (*Crud) CreateTable added in v1.2.8 

func (c *Crud) CreateTable(tableName string,
	onDemand bool,
	rcu int64, wcu int64,
	sse *ddb.SSESpecification,
	enableStream bool,
	lsi []*ddb.LocalSecondaryIndex,
	gsi []*ddb.GlobalSecondaryIndex,
	attributes []*ddb.AttributeDefinition,
	customDynamoDBConnection ...*DynamoDB) error

CreateTable will create a new dynamodb table based on input parameter values

onDemand = sets billing to "PAY_PER_REQUEST", required if creating global table rcu / wcu = defaults to 2 if value is 0 attributes = PK and SK are inserted automatically, only need to specify non PK SK attributes

func (*Crud) Delete added in v1.2.5 

func (c *Crud) Delete(pkValue string, skValue string) (err error)

Delete removes data from dynamodb table with given pk and sk values

func (*Crud) DeleteBackup added in v1.2.8 

func (c *Crud) DeleteBackup(backupArn string) error

DeleteBackup deletes dynamodb backup based on the given input parameter

func (*Crud) DeleteTable added in v1.2.8 

func (c *Crud) DeleteTable(tableName string, region awsregion.AWSRegion) error

DeleteTable will delete the target dynamodb table given by input parameter values

func (*Crud) DescribeBackup added in v1.2.8 

func (c *Crud) DescribeBackup(backupArn string) (*ddb.BackupDescription, error)

DescribeBackup describes a given dynamodb backup info

func (*Crud) DescribeGlobalTable added in v1.2.8 

func (c *Crud) DescribeGlobalTable(tableName string) (*ddb.GlobalTableDescription, error)

DescribeGlobalTable will describe the dynamodb global table info based on input parameter values

func (*Crud) DescribeTable added in v1.2.8 

func (c *Crud) DescribeTable(tableName string) (*ddb.TableDescription, error)

DescribeTable will describe the dynamodb table info based on input parameter values

func (*Crud) Get added in v1.2.5 

func (c *Crud) Get(pkValue string, skValue string, resultDataPtr interface{}, consistentRead bool, projectedAttributes ...string) (err error)

Get retrieves data from dynamodb table with given pk and sk values, resultDataPtr refers to pointer to struct of the target dynamodb table record 

result struct contains PK, SK, and attributes, with struct tags for json and dynamodbav

warning: projectedAttributes = if specified, MUST include PartitionKey (Hash Key) typically "PK" as the first projected attribute, regardless if used or not

func (*Crud) ListBackups added in v1.2.8 

func (c *Crud) ListBackups(tableNameFilter string, fromTime *time.Time, toTime *time.Time) ([]*ddb.BackupSummary, error)

ListBackups lists dynamodb backups based on the given input parameter

func (*Crud) ListGlobalTables added in v1.2.8 

func (c *Crud) ListGlobalTables(filterRegion ...awsregion.AWSRegion) ([]*GlobalTableInfo, error)

ListGlobalTables will return list of all dynamodb global table names

global table supported regions: 

us-east-1 (nvirginia), us-east-2 (ohio), us-west-1 (california), us-west-2 (oregon)
eu-west-2 (london), eu-central-1 (frankfurt), eu-west-1 (ireland)
ap-southeast-1 (singapore), ap-southeast-2 (sydney), ap-northeast-1 (tokyo), ap-northeast-2 (seoul)

func (*Crud) ListTables added in v1.2.8 

func (c *Crud) ListTables() ([]string, error)

ListTables will return list of all dynamodb table names

func (*Crud) Open added in v1.2.5 

func (c *Crud) Open(cfg *ConnectionConfig) error

Open will establish connection to the target dynamodb table as defined in config.yaml

func (*Crud) Query added in v1.2.5 

func (c *Crud) Query(keyExpression *QueryExpression, pagedDataPtrSlice interface{}, resultDataPtrSlice interface{}) (responseDataPtrSlice interface{}, err error)

Query retrieves data from dynamodb table with given pk and sk values, or via LSI / GSI using index name, pagedDataPtrSlice refers to pointer slice of data struct pointers for use during paged query, that each data struct represents the underlying dynamodb table record, 

&[]*xyz{}

resultDataPtrSlice refers to pointer slice of data struct pointers to contain the paged query results (this is the working variable, not the returning result), 

&[]*xyz{}

both pagedDataPtrSlice and resultDataPtrSlice have the same data types, but they will be contained in separate slice ptr vars, 

data struct contains PK, SK, and attributes, with struct tags for json and dynamodbav, ie: &[]*exampleDataStruct

responseDataPtrSlice, is the slice ptr result to caller, expects caller to assert to target slice ptr objects, ie: results.([]*xyz)

func (*Crud) QueryByPage added in v1.3.6 

func (c *Crud) QueryByPage(itemsPerPage int64, exclusiveStartKey string, keyExpression *QueryExpression, pagedDataPtrSlice interface{}) (responseDataPtrSlice interface{}, prevEvalKey string, err error)

QueryByPage retrieves data from dynamodb table with given pk and sk values, or via LSI / GSI using index name on per page basis

Parameters: 

	itemsPerPage = indicates total number of items per page to return in query, defaults to 10 if set to 0; max limit is 500
	exclusiveStartKey = if this is new query, set to ""; if this is continuation query (pagination), set the prior query's prevEvalKey in base64 string format
	keyExpression = query expression object
	pagedDataPtrSlice = refers to pointer slice of data struct pointers for use during paged query, that each data struct represents the underlying dynamodb table record

&[]*xyz{}

data struct contains PK, SK, and attributes, with struct tags for json and dynamodbav, ie: &[]*exampleDataStruct

responseDataPtrSlice, is the slice ptr result to caller, expects caller to assert to target slice ptr objects, ie: results.([]*xyz)

func (*Crud) QueryPaginationData added in v1.3.7 

func (c *Crud) QueryPaginationData(itemsPerPage int64, keyExpression *QueryExpression) (paginationData []string, err error)

QueryPaginationData returns pagination slice to be used for paging

if paginationData is nil or zero length, then this is single page

if paginationData is 1 or more elements, then element 0 (first element) is always page 1 and value is nil, page 2 will be on element 1 and contains the exclusiveStartKey, and so on.

each element contains base64 encoded value of exclusiveStartkey, therefore page 1 exclusiveStartKey is nil.

for page 1 use exclusiveStartKey as nil for page 2 and more use the exclusiveStartKey from paginationData slice

func (*Crud) Set added in v1.2.5 

func (c *Crud) Set(dataPtr interface{}) (err error)

Set persists data to dynamodb table with given pointer struct that represents the target dynamodb table record, pk value within pointer struct is created using CreatePKValue func dataPtr refers to pointer to struct of the target dynamodb table record 

data struct contains PK, SK, and attributes, with struct tags for json and dynamodbav

func (*Crud) TransactionGet added in v1.2.5 

func (c *Crud) TransactionGet(transReads ...*DynamoDBTransactionReads) (successCount int, err error)

TransactionGet retrieves records from dynamodb table(s), based on given PK SK, action results will be passed to caller via transReads' ResultItemPtr and ResultError fields

func (*Crud) TransactionSet added in v1.2.5 

func (c *Crud) TransactionSet(transWrites ...*DynamoDBTransactionWrites) (success bool, err error)

TransactionSet puts, updates, deletes records against dynamodb table, with option to override table name,

func (*Crud) Update added in v1.2.5 

func (c *Crud) Update(pkValue string, skValue string, updateExpression string, conditionExpression string, attributeValues []*AttributeValue) (err error)

Update will update a specific dynamodb record based on PK and SK, with given update expression, condition, and attribute values, attribute values controls the actual values going to be updated into the record 

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

func (*Crud) UpdateGlobalTable added in v1.2.8 

func (c *Crud) UpdateGlobalTable(tableName string, createRegions []awsregion.AWSRegion, deleteRegions []awsregion.AWSRegion) error

UpdateGlobalTable creates or deletes global table replicas

if update is to create new global table regional replicas, the regional tables will auto create based on given table name, then associate to global table

if update is to delete existing global table regional replicas, the regional table will be removed from global replication, and actual table deleted

global table supported regions: 

us-east-1 (nvirginia), us-east-2 (ohio), us-west-1 (california), us-west-2 (oregon)
eu-west-2 (london), eu-central-1 (frankfurt), eu-west-1 (ireland)
ap-southeast-1 (singapore), ap-southeast-2 (sydney), ap-northeast-1 (tokyo), ap-northeast-2 (seoul)

warning: do not first create the new replica table when adding to global table, this function creates all the new replica tables automatically

func (*Crud) UpdatePointInTimeBackup added in v1.2.8 

func (c *Crud) UpdatePointInTimeBackup(tableName string, pointInTimeRecoveryEnabled bool) error

UpdatePointInTimeBackup updates dynamodb continuous backup options (point in time recovery) based on the given input parameter

func (*Crud) UpdateTable added in v1.2.8 

func (c *Crud) UpdateTable(tableName string, rcu int64, wcu int64,
	gsi []*ddb.GlobalSecondaryIndexUpdate,
	attributes []*ddb.AttributeDefinition) error

UpdateTable will update an existing dynamodb table based on input parameter values

tableName = (required) the name of dynamodb table to be updated rcu / wcu = if > 0, corresponding update is affected to the provisioned throughput; if to be updated, both must be set gsi = contains slice of global secondary index updates (create / delete / update ... of gsi) attributes = attributes involved for the table (does not pre-load PK or SK in this function call)

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

warning 

projectedAttributes = if specified, must include PartitionKey (Hash key) typically "PK" as the first attribute in projected attributes

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

warning 

projectedAttributes = if specified, must include PartitionKey (Hash key) typically "PK" as the first attribute in projected attributes

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) CreateBackup added in v1.2.8 

func (d *DynamoDB) CreateBackup(input *dynamodb.CreateBackupInput, ctx ...aws.Context) (*dynamodb.CreateBackupOutput, error)

CreateBackup creates dynamodb table backup

func (*DynamoDB) CreateGlobalTable added in v1.2.8 

func (d *DynamoDB) CreateGlobalTable(input *dynamodb.CreateGlobalTableInput, ctx ...aws.Context) (*dynamodb.CreateGlobalTableOutput, error)

CreateGlobalTable creates a dynamodb global table

func (*DynamoDB) CreateTable added in v1.2.8 

func (d *DynamoDB) CreateTable(input *dynamodb.CreateTableInput, ctx ...aws.Context) (*dynamodb.CreateTableOutput, error)

CreateTable creates a new dynamodb table to the default aws region (as configured by aws cli)

func (*DynamoDB) DeleteBackup added in v1.2.8 

func (d *DynamoDB) DeleteBackup(input *dynamodb.DeleteBackupInput, ctx ...aws.Context) (*dynamodb.DeleteBackupOutput, error)

DeleteBackup deletes an existing dynamodb table backup

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) DeleteTable added in v1.2.8 

func (d *DynamoDB) DeleteTable(input *dynamodb.DeleteTableInput, ctx ...aws.Context) (*dynamodb.DeleteTableOutput, error)

DeleteTable deletes an existing dynamodb table

func (*DynamoDB) DescribeBackup added in v1.2.8 

func (d *DynamoDB) DescribeBackup(input *dynamodb.DescribeBackupInput, ctx ...aws.Context) (*dynamodb.DescribeBackupOutput, error)

DescribeBackup describes dynamodb table backup

func (*DynamoDB) DescribeGlobalTable added in v1.2.8 

func (d *DynamoDB) DescribeGlobalTable(input *dynamodb.DescribeGlobalTableInput, ctx ...aws.Context) (*dynamodb.DescribeGlobalTableOutput, error)

DescribeGlobalTable describes dynamodb global table

func (*DynamoDB) DescribeTable added in v1.2.8 

func (d *DynamoDB) DescribeTable(input *dynamodb.DescribeTableInput, ctx ...aws.Context) (*dynamodb.DescribeTableOutput, error)

DescribeTable describes the dynamodb table info for target identified in input parameter

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

warning 

projectedAttributes = if specified, must include PartitionKey (Hash key) typically "PK" as the first attribute in projected attributes

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,
					  if specified, must include PartitionKey (Hash key) typically "PK" as the first attribute in projected attributes

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

warning 

projectedAttributes = if specified, must include PartitionKey (Hash key) typically "PK" as the first attribute in projected attributes

func (*DynamoDB) ListBackups added in v1.2.8 

func (d *DynamoDB) ListBackups(input *dynamodb.ListBackupsInput, ctx ...aws.Context) (*dynamodb.ListBackupsOutput, error)

ListBackups lists dynamodb table backup

func (*DynamoDB) ListGlobalTables added in v1.2.8 

func (d *DynamoDB) ListGlobalTables(input *dynamodb.ListGlobalTablesInput, ctx ...aws.Context) (*dynamodb.ListGlobalTablesOutput, error)

ListGlobalTables lists dynamodb global tables

func (*DynamoDB) ListTables added in v1.2.8 

func (d *DynamoDB) ListTables(input *dynamodb.ListTablesInput, ctx ...aws.Context) (*dynamodb.ListTablesOutput, error)

ListTables queries dynamodb tables list and returns found tables info

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

warning 

projectedAttributes = if specified, must include PartitionKey (Hash key) typically "PK" as the first attribute in projected attributes

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

warning 

projectedAttributes = if specified, must include PartitionKey (Hash key) typically "PK" as the first attribute in projected attributes

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) QueryPaginationDataWithRetry added in v1.3.7 

func (d *DynamoDB) QueryPaginationDataWithRetry(
	maxRetries uint,
	timeOutDuration *time.Duration,
	indexName *string,
	itemsPerPage int64,
	keyConditionExpression string,
	expressionAttributeNames map[string]*string,
	expressionAttributeValues map[string]*dynamodb.AttributeValue) (paginationData []map[string]*dynamodb.AttributeValue, ddbErr *DynamoDBError)

QueryPaginationDataWithRetry returns slice of ExclusiveStartKeys, with first element always a nil to represent no exclusiveStartKey, and each subsequent element starts from page 2 with its own exclusiveStartKey.

if slice is nil or zero element, then it also indicates single page, same as if slice is single element with nil indicating single page.

Caller can use this info to pre-build the pagination buttons, so that clicking page 1 simply query using no exclusiveStartKey, where as query page 2 uses the exclusiveStartKey from element 1 of the slice, and so on.

func (*DynamoDB) QueryPerPageItemsWithRetry added in v1.3.6 

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

QueryPerPageItemsWithRetry 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);

*** This Query is used for pagination where each query returns a specified set of items, along with the prevEvalKey, in the subsequent paged queries using this method, passing prevEvalKey to the exclusiveStartKey parameter will return next page of items from the exclusiveStartKey position ***

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: 

maxRetries = number of retries to attempt
itemsPerPage = query per page items count, if < 0 = 10; if > 500 = 500; defaults to 10 if 0
exclusiveStartKey = if query is continuation from prior pagination, then the prior query's prevEvalKey is passed into this field
pagedSlicePtr = required, identifies the actual slice pointer for use during paged query
				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
indexName = optional, global secondary index or local secondary index name to help in query operation
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)
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(...)

Return Values: 

returnItemsList = interface{} of return slice, use assert to cast to target type
prevEvalKey = map[string]*dynamodb.Attribute, if there are more pages, this value is then used in the subsequent query's exclusiveStartKey parameter
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) RemoveItemAttribute added in v1.4.0 

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

RemoveItemAttribute will remove attribute from dynamodb item in given table using primary key (PK, SK)

func (*DynamoDB) RemoveItemAttributeWithRetry added in v1.4.0 

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

RemoveItemAttributeWithRetry handles dynamodb retries in case action temporarily fails

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 <<<

warning 

projectedAttributes = if specified, must include PartitionKey (Hash key) typically "PK" as the first attribute in projected attributes

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

warning 

projectedAttributes = if specified, must include PartitionKey (Hash key) typically "PK" as the first attribute in projected attributes

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) UpdateGlobalTable added in v1.2.8 

func (d *DynamoDB) UpdateGlobalTable(input *dynamodb.UpdateGlobalTableInput, ctx ...aws.Context) (*dynamodb.UpdateGlobalTableOutput, error)

UpdateGlobalTable updates a dynamodb global table

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

func (*DynamoDB) UpdatePointInTimeBackup added in v1.2.8 

func (d *DynamoDB) UpdatePointInTimeBackup(input *dynamodb.UpdateContinuousBackupsInput, ctx ...aws.Context) (*dynamodb.UpdateContinuousBackupsOutput, error)

UpdatePointInTimeBackup updates dynamodb table point in time backup option

func (*DynamoDB) UpdateTable added in v1.2.8 

func (d *DynamoDB) UpdateTable(input *dynamodb.UpdateTableInput, ctx ...aws.Context) (*dynamodb.UpdateTableOutput, error)

UpdateTable updates an existing dynamodb table with provided input parameter

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

type GlobalTableInfo added in v1.2.8 

type GlobalTableInfo struct {
	TableName string
	Regions   []awsregion.AWSRegion
}

type PkSkValuePair added in v1.2.5 

type PkSkValuePair struct {
	PKValue string
	SKValue string
}

type QueryExpression added in v1.2.5 

type QueryExpression struct {
	PKName  string
	PKValue string

	UseSK           bool
	SKName          string
	SKIsNumber      bool
	SKCompareSymbol string // valid symbols: = <= >= < > BETWEEN begins_with (note = not equal symbol is not allowed)
	SKValue         string
	SKValue2        string // used only if SKComparerSymbol is BETWEEN

	IndexName string
}

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.