dynamoql

package module
v0.0.3 Latest Latest
Warning

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

 Go to latest Published: Aug 24, 2022 License: Apache-2.0 Imports: 11 Imported by: 0

README

DynamoQL for Amazon DynamoDB

An ORM-like lightweight toolkit for Go applications interacting with Amazon DynamoDB.

Documentation

Overview

Package dynamoql is a toolkit for Go applications using Amazon DynamoDB.

Index

Constants

View Source 
const (
	Equals             ConditionalOperator = "="
	GreaterThan        ConditionalOperator = ">"
	GreaterOrEqualThan ConditionalOperator = ">="
	LessThan           ConditionalOperator = "<"
	LessOrEqualThan    ConditionalOperator = "<="
	GreaterOrLess      ConditionalOperator = "<>"
	In                 ConditionalOperator = "IN"
	Between            ConditionalOperator = "BETWEEN"
	Contains           ConditionalOperator = "contains"
	BeginsWith         ConditionalOperator = "begins_with"
	AttributeType      ConditionalOperator = "attribute_type"
	AttributeExists    ConditionalOperator = "attribute_exists"
	AttributeNotExists ConditionalOperator = "attribute_not_exists"
	Size               ConditionalOperator = "size"

	And LogicalOperator = "AND"
	Or  LogicalOperator = "OR"

	Ascend  Ordering = "ASC"
	Descend Ordering = "DESC"
)

Variables

View Source 
var CompositeKeySeparator = "#"

CompositeKeySeparator a pattern to subdivide a key name and its value.

View Source 
var DefaultQueryLimit int32 = 10
View Source 
var DefaultSchemaField = "schema_name"

DefaultSchemaField base attribute name for schema name field in an Amazon DynamoDB table. Used by query hydration mechanisms.

View Source 
var DefaultTimeFormat = time.RFC3339

DefaultTimeFormat used by parsers and formatters algorithms to handle time.

View Source 
var ErrCannotCastAttribute = errors.New("dynamoql: Cannot cast attribute")

ErrCannotCastAttribute casting Amazon DynamoDB attribute failed.

View Source 
var ErrReaderEOF = errors.New("dynamoql: Reader has reached end of file")

ErrReaderEOF reader has reached the end of the file.

Functions

func FormatAttribute 

func FormatAttribute(v interface{}) types.AttributeValue

FormatAttribute converts a Go primitive type into a DynamoDB type.

Returns nil if unknown value is received.

func MustParseBinary 

func MustParseBinary(v types.AttributeValue) []byte

MustParseBinary converts the given Amazon DynamoDB attribute into a slice of bytes.

If fails to parse attribute, returns nil or zero-value.

func MustParseBinarySet 

func MustParseBinarySet(v types.AttributeValue) [][]byte

MustParseBinarySet converts the given Amazon DynamoDB attribute into a binary slice (matrix byte).

If fails to parse attribute, returns nil or zero-value.

func MustParseBool 

func MustParseBool(v types.AttributeValue) bool

MustParseBool converts the given Amazon DynamoDB attribute into boolean.

If fails to parse attribute, returns nil or zero-value.

func MustParseFloat32 

func MustParseFloat32(v types.AttributeValue) float32

MustParseFloat32 converts the given Amazon DynamoDB attribute into 32-bit floating point.

If fails to parse attribute, returns nil or zero-value.

func MustParseFloat32Set 

func MustParseFloat32Set(v types.AttributeValue) []float32

MustParseFloat32Set converts the given Amazon DynamoDB attribute into a float32 set.

If fails to parse attribute, returns nil or zero-value.

func MustParseFloat64 

func MustParseFloat64(v types.AttributeValue) float64

MustParseFloat64 converts the given Amazon DynamoDB attribute into 64-bit floating point.

If fails to parse attribute, returns nil or zero-value.

func MustParseFloat64Set 

func MustParseFloat64Set(v types.AttributeValue) []float64

MustParseFloat64Set converts the given Amazon DynamoDB attribute into a float64 set.

If fails to parse attribute, returns nil or zero-value.

func MustParseInt 

func MustParseInt(v types.AttributeValue) int

MustParseInt converts the given Amazon DynamoDB attribute into a signed integer.

If fails to parse attribute, returns nil or zero-value.

func MustParseInt16 

func MustParseInt16(v types.AttributeValue) int16

MustParseInt16 converts the given Amazon DynamoDB attribute into an 16-bit signed integer.

If fails to parse attribute, returns nil or zero-value.

func MustParseInt32 

func MustParseInt32(v types.AttributeValue) int32

MustParseInt32 converts the given Amazon DynamoDB attribute into an 32-bit signed integer.

If fails to parse attribute, returns nil or zero-value.

func MustParseInt64 

func MustParseInt64(v types.AttributeValue) int64

MustParseInt64 converts the given Amazon DynamoDB attribute into an 64-bit signed integer.

If fails to parse attribute, returns nil or zero-value.

func MustParseInt8 

func MustParseInt8(v types.AttributeValue) int8

MustParseInt8 converts the given Amazon DynamoDB attribute into an 8-bit signed integer.

If fails to parse attribute, returns nil or zero-value.

func MustParseIntSet 

func MustParseIntSet(v types.AttributeValue) []int

MustParseIntSet converts the given Amazon DynamoDB attribute into a signed integer set.

If fails to parse attribute, returns nil or zero-value.

func MustParseString 

func MustParseString(v types.AttributeValue) string

MustParseString converts the given Amazon DynamoDB attribute into string.

If fails to parse attribute, returns nil or zero-value.

func MustParseStringSet 

func MustParseStringSet(v types.AttributeValue) []string

MustParseStringSet converts the given Amazon DynamoDB attribute into a string set.

If fails to parse attribute, returns nil or zero-value.

func MustParseTime 

func MustParseTime(v types.AttributeValue) time.Time

MustParseTime converts the given Amazon DynamoDB attribute into time.Time.

If fails to parse attribute, returns nil or zero-value.

func MustParseUint 

func MustParseUint(v types.AttributeValue) uint

MustParseUint converts the given Amazon DynamoDB attribute into an unsigned integer.

If fails to parse attribute, returns nil or zero-value.

func MustParseUint16 

func MustParseUint16(v types.AttributeValue) uint16

MustParseUint16 converts the given Amazon DynamoDB attribute into an 16-bit unsigned integer.

If fails to parse attribute, returns nil or zero-value.

func MustParseUint32 

func MustParseUint32(v types.AttributeValue) uint32

MustParseUint32 converts the given Amazon DynamoDB attribute into an 32-bit unsigned integer.

If fails to parse attribute, returns nil or zero-value.

func MustParseUint64 

func MustParseUint64(v types.AttributeValue) uint64

MustParseUint64 converts the given Amazon DynamoDB attribute into an 64-bit unsigned integer.

If fails to parse attribute, returns nil or zero-value.

func MustParseUint8 

func MustParseUint8(v types.AttributeValue) uint8

MustParseUint8 converts the given Amazon DynamoDB attribute into an 8-bit unsigned integer.

If fails to parse attribute, returns nil or zero-value.

func MustParseUintSet 

func MustParseUintSet(v types.AttributeValue) []uint

MustParseUintSet converts the given Amazon DynamoDB attribute into an unsigned integer set.

If fails to parse attribute, returns nil or zero-value.

func NewCompositeKey 

func NewCompositeKey(prefix, v string) string

NewCompositeKey creates a key composed by the key itself, a separator (CompositeKeySeparator) and the actual key value; ready to be used by graph database implementations (e.g. Amazon DynamoDB with adjacency list graph pattern).

The nomenclature is the following: {PREFIX}{SEPARATOR}{VALUE}.

e.g. USER#123

func NewGetInput 

func NewGetInput(q *QueryBuilder) dynamodb.GetItemInput

NewGetInput builds a dynamodb.GetItemInput using current QueryBuilder instance values.

func NewOverloadedKey 

func NewOverloadedKey(sep string, v ...string) string

NewOverloadedKey creates a key composed by N values and a separator between values. This key crafting technique is used for advanced search queries using the sort key with BeginsWith or Between operators mostly.

The nomenclature is the following: {VALUE_0}{SEPARATOR}{VALUE_N}.

e.g. London:Westminster:Downing St:10

func NewQueryInput 

func NewQueryInput(q *QueryBuilder) dynamodb.QueryInput

NewQueryInput builds a dynamodb.QueryInput using current QueryBuilder instance values.

func NewScanInput 

func NewScanInput(q *QueryBuilder) dynamodb.ScanInput

NewScanInput builds a dynamodb.ScanInput using current QueryBuilder instance values.

func ParseBinary 

func ParseBinary(v types.AttributeValue) ([]byte, error)

ParseBinary converts the given Amazon DynamoDB attribute into a slice of bytes.

func ParseBinarySet 

func ParseBinarySet(v types.AttributeValue) ([][]byte, error)

ParseBinarySet converts the given Amazon DynamoDB attribute into a binary slice (matrix byte).

func ParseBool 

func ParseBool(v types.AttributeValue) (bool, error)

ParseBool converts the given Amazon DynamoDB attribute into boolean.

func ParseCompositeKey 

func ParseCompositeKey(k string) string

ParseCompositeKey removes prefix and separator (CompositeKeySeparator). If no separator found, returns k.

func ParseFloat32 

func ParseFloat32(v types.AttributeValue) (float32, error)

ParseFloat32 converts the given Amazon DynamoDB attribute into 32-bit floating point.

func ParseFloat32Set 

func ParseFloat32Set(v types.AttributeValue) ([]float32, error)

ParseFloat32Set converts the given Amazon DynamoDB attribute into a float32 set.

func ParseFloat64 

func ParseFloat64(v types.AttributeValue) (float64, error)

ParseFloat64 converts the given Amazon DynamoDB attribute into 64-bit floating point.

func ParseFloat64Set 

func ParseFloat64Set(v types.AttributeValue) ([]float64, error)

ParseFloat64Set converts the given Amazon DynamoDB attribute into a float64 set.

func ParseInt 

func ParseInt(v types.AttributeValue) (int, error)

ParseInt converts the given Amazon DynamoDB attribute into a signed integer.

func ParseInt16 

func ParseInt16(v types.AttributeValue) (int16, error)

ParseInt16 converts the given Amazon DynamoDB attribute into an 16-bit signed integer.

func ParseInt32 

func ParseInt32(v types.AttributeValue) (int32, error)

ParseInt32 converts the given Amazon DynamoDB attribute into an 32-bit signed integer.

func ParseInt64 

func ParseInt64(v types.AttributeValue) (int64, error)

ParseInt64 converts the given Amazon DynamoDB attribute into an 64-bit signed integer.

func ParseInt8 

func ParseInt8(v types.AttributeValue) (int8, error)

ParseInt8 converts the given Amazon DynamoDB attribute into an 8-bit signed integer.

func ParseIntSet 

func ParseIntSet(v types.AttributeValue) ([]int, error)

ParseIntSet converts the given Amazon DynamoDB attribute into a signed integer set.

func ParseString 

func ParseString(v types.AttributeValue) (string, error)

ParseString converts the given Amazon DynamoDB attribute into string.

func ParseStringSet 

func ParseStringSet(v types.AttributeValue) ([]string, error)

ParseStringSet converts the given Amazon DynamoDB attribute into a string set.

func ParseTime 

func ParseTime(v types.AttributeValue) (time.Time, error)

ParseTime converts the given Amazon DynamoDB attribute into time.Time.

func ParseUint 

func ParseUint(v types.AttributeValue) (uint, error)

ParseUint converts the given Amazon DynamoDB attribute into an unsigned integer.

func ParseUint16 

func ParseUint16(v types.AttributeValue) (uint16, error)

ParseUint16 converts the given Amazon DynamoDB attribute into an 16-bit unsigned integer.

func ParseUint32 

func ParseUint32(v types.AttributeValue) (uint32, error)

ParseUint32 converts the given Amazon DynamoDB attribute into an 32-bit unsigned integer.

func ParseUint64 

func ParseUint64(v types.AttributeValue) (uint64, error)

ParseUint64 converts the given Amazon DynamoDB attribute into an 64-bit unsigned integer.

func ParseUint8 

func ParseUint8(v types.AttributeValue) (uint8, error)

ParseUint8 converts the given Amazon DynamoDB attribute into an 8-bit unsigned integer.

func ParseUintSet 

func ParseUintSet(v types.AttributeValue) ([]uint, error)

ParseUintSet converts the given Amazon DynamoDB attribute into an unsigned integer set.

Types

type Condition 

type Condition struct {
	// Negate sets an opposite value of the statement original output.
	Negate bool
	// IsKey sets the given statement as a Key comparison.
	IsKey bool
	// Operator statement comparison operator.
	Operator ConditionalOperator
	// SecondaryOperator an additional comparison operator.
	// Used by Size operator only.
	SecondaryOperator ConditionalOperator
	// Field attribute name used by the comparison statement.
	Field string
	// Value attribute actual value used by the comparison statement.
	Value interface{}
	// ExtraValues additional attribute values.
	// Used by Between and In operators only
	ExtraValues []interface{}
}

Condition a comparison statement used by queries (QueryBuilder).

type ConditionalOperator 

type ConditionalOperator string

ConditionalOperator Used to compare an operand against a range of values or an enumerated list of values.

type EdgeSchema 

type EdgeSchema interface {
	Schema
	GetLeftKeys() map[string]types.AttributeValue
	GetRightKeys() map[string]types.AttributeValue
}

EdgeSchema an Amazon DynamoDB Many-To-Many model. Stores the keys from each side of the relation and additional attributes if desired.

type ItemBuffer 

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

ItemBuffer efficiently hold and interact with collections of Amazon DynamoDB items.

func NewItemBuffer 

func NewItemBuffer(size int) *ItemBuffer

NewItemBuffer allocates a new ItemBuffer with the given size.

func (*ItemBuffer) Cap 

func (b *ItemBuffer) Cap() int

Cap retrieves internal buffer capacity.

func (*ItemBuffer) Grow 

func (b *ItemBuffer) Grow(n int)

Grow increases the memory allocation (malloc) of the internal buffer.

func (*ItemBuffer) IsFull 

func (b *ItemBuffer) IsFull() bool

IsFull checks if the internal buffer is full.

func (*ItemBuffer) ItemAt 

func (b *ItemBuffer) ItemAt(n int) map[string]types.AttributeValue

ItemAt retrieves a specific item using its position.

func (*ItemBuffer) Items 

func (b *ItemBuffer) Items() []map[string]types.AttributeValue

Items retrieves the current collection of items.

func (*ItemBuffer) Len 

func (b *ItemBuffer) Len() int

Len retrieves internal buffer length.

func (*ItemBuffer) PeekAt 

func (b *ItemBuffer) PeekAt(n int) bool

PeekAt checks if an item is present on the given position.

func (*ItemBuffer) Reset 

func (b *ItemBuffer) Reset()

Reset removes all items from the internal buffer, retaining the original capacity.

func (*ItemBuffer) Write 

func (b *ItemBuffer) Write(v map[string]types.AttributeValue)

Write stores the given value into the buffer.

func (*ItemBuffer) WriteItems 

func (b *ItemBuffer) WriteItems(v []map[string]types.AttributeValue)

WriteItems stores the given set of values into the buffer.

type LogicalOperator 

type LogicalOperator string

LogicalOperator Used to perform logical evaluations (AND, OR & NOT).

type Marshaler 

type Marshaler interface {
	MarshalDynamoDB() (map[string]types.AttributeValue, error)
}

Marshaler converts an Amazon DynamoDB model into a primitive map.

type NodeSchema 

type NodeSchema interface {
	Schema
	GetName() string
	GetKeys() map[string]types.AttributeValue
}

NodeSchema an Amazon DynamoDB entity. Not necessarily a table.

type Ordering 

type Ordering string

Ordering Used to set the traversing order while iterating items in a DynamoDB table.

type PageToken 

type PageToken map[string]types.AttributeValue

PageToken is a DynamoDB Last Evaluate Key(s) from Query and Scan APIs. This is a base64-based custom type used to represent the Last Evaluate Key(s) as URL-safe string to be used by clients (if developing a HTTP/gRPC/... API).

Note: Last Evaluate Key(s) is the primary key of a DynamoDB table. Primary keys accept String, Binary and Number DynamoDB types and have a maximum length of 2 keys (Partition Key and Sort Key, which compose a composite key if both present).

See ref: https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/HowItWorks.CoreComponents.html

func NewPageToken 

func NewPageToken(rawStr string) (PageToken, error)

NewPageToken converts the given base64-coded string into a PageToken.

func NewPageTokenString 

func NewPageTokenString(rawStr string) PageToken

NewPageTokenString converts the given base64-coded string into a PageToken.

It will panic if fails to decode base64 string.

func (PageToken) Decode 

func (t PageToken) Decode(encodedRaw string) error

Decode converts given base64 URL-safe string into a PageToken.

func (PageToken) Encode 

func (t PageToken) Encode() string

Encode transforms the current PageToken into a base64 URL-safe string.

func (PageToken) String 

func (t PageToken) String() string

String transforms the current PageToken into a base64 URL-safe string.

Wraps PageToken.Encode().

type QueryBuilder 

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

QueryBuilder crafts an Amazon DynamoDB query statement ready to be used by Query, GetItem and Scan APIs.

Moreover, it integrates with Paginator and Reader instances for seamless API usability.

func NewQueryBuilder 

func NewQueryBuilder() *QueryBuilder

NewQueryBuilder builds a QueryBuilder instance.

func Select 

func Select(projectedFields ...string) *QueryBuilder

Select builds a new QueryBuilder instance and sets attributes to be projected by the query.

func (*QueryBuilder) And 

func (q *QueryBuilder) And() *QueryBuilder

And concatenates Condition(s) with an And operator.

func (*QueryBuilder) DegreeOfParallelism 

func (q *QueryBuilder) DegreeOfParallelism(d int32) *QueryBuilder

DegreeOfParallelism sets the number of segments to be scanned in parallel.

Note: Only available for Scan operations.

func (*QueryBuilder) ExecGet 

func (q *QueryBuilder) ExecGet(ctx context.Context, c *dynamodb.Client) (dynamodb.GetItemOutput, error)

ExecGet executes a GetItem API operation.

func (*QueryBuilder) ExecQuery 

func (q *QueryBuilder) ExecQuery(ctx context.Context, c *dynamodb.Client) (dynamodb.QueryOutput, error)

ExecQuery executes a Query API operation.

func (*QueryBuilder) ExecScan 

func (q *QueryBuilder) ExecScan(ctx context.Context, c *dynamodb.Client) (dynamodb.ScanOutput, error)

ExecScan executes a Scan API operation.

func (*QueryBuilder) From 

func (q *QueryBuilder) From(table string) *QueryBuilder

From sets the table to query from.

func (*QueryBuilder) GetQueryPaginator 

func (q *QueryBuilder) GetQueryPaginator(c *dynamodb.Client) *QueryPaginator

GetQueryPaginator builds a QueryPaginator using current QueryBuilder instance values.

func (*QueryBuilder) GetQueryReader 

func (q *QueryBuilder) GetQueryReader(c *dynamodb.Client) *QueryReader

GetQueryReader builds a *QueryReader using current QueryBuilder instance values.

func (*QueryBuilder) Index 

func (q *QueryBuilder) Index(i string) *QueryBuilder

Index sets the Global Secondary Index to query from.

func (*QueryBuilder) Limit 

func (q *QueryBuilder) Limit(l int32) *QueryBuilder

Limit sets the length of the items to be returned by the query operation.

func (*QueryBuilder) Metrics 

func (q *QueryBuilder) Metrics(v types.ReturnConsumedCapacity) *QueryBuilder

Metrics sets the desired metric data from consumed capacity outputs.

func (*QueryBuilder) Negate 

func (q *QueryBuilder) Negate() *QueryBuilder

Negate sets the returned output to be opposite.

func (*QueryBuilder) Or 

func (q *QueryBuilder) Or() *QueryBuilder

Or concatenates Condition(s) with an Or operator.

func (*QueryBuilder) OrderBy 

func (q *QueryBuilder) OrderBy(o Ordering) *QueryBuilder

OrderBy sets the ordering of the item list to be returned by the query operation.

func (*QueryBuilder) PageToken 

func (q *QueryBuilder) PageToken(t PageToken) *QueryBuilder

PageToken sets the next page token for pagination query operations.

func (*QueryBuilder) Select 

func (q *QueryBuilder) Select(projectedFields []string) *QueryBuilder

Select sets attributes to be projected by the query.

func (*QueryBuilder) StrongConsistency 

func (q *QueryBuilder) StrongConsistency() *QueryBuilder

StrongConsistency sets the desired replication consistency between Amazon DynamoDB internal nodes while querying data. Default is eventual consistency, as every distributed platform is due CAP theorem.

func (*QueryBuilder) Where 

func (q *QueryBuilder) Where(c ...Condition) *QueryBuilder

Where sets conditions statements.

type QueryPaginator 

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

func NewQueryPaginator 

func NewQueryPaginator(pageSize int32, c *dynamodb.Client, q dynamodb.QueryInput) *QueryPaginator

func (QueryPaginator) Count 

func (p QueryPaginator) Count() int32

func (*QueryPaginator) GetPage 

func (p *QueryPaginator) GetPage(ctx context.Context) (*dynamodb.QueryOutput, error)

func (QueryPaginator) Next 

func (p QueryPaginator) Next() bool

func (QueryPaginator) NextPageToken 

func (p QueryPaginator) NextPageToken() PageToken

func (QueryPaginator) ScannedPages 

func (p QueryPaginator) ScannedPages() uint32

type QueryReader 

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

QueryReader iterates for each item stored in an Amazon DynamoDB table using the Query API.

Uses a pre-fetching strategy, loading chunks of data (specified by the user, default is 10 items per-chunk) into an internal buffer before actual item iteration.

When a reader reaches last item from the local data chunk, it will automatically fetch the next chunk until no more chunks are left (if iteration is not stopped in the meanwhile).

Some example for using QueryReader: 

bills := make([]Bill, 0, 10)
for r.Next() {
	item, err := r.GetItem(ctx)
	if err != nil {
		break
	}

	bill := Bill{}
	if err = bill.UnmarshalDynamoDB(item); err != nil {
		break
	}

	bills = append(bills, bill)
	if r.Count() >= 10 {
		break
	}
}

func NewQueryReader 

func NewQueryReader(chunkSize int32, c *dynamodb.Client, q dynamodb.QueryInput) *QueryReader

NewQueryReader allocates a QueryReader with required internal components. Returns nil if a nil dynamodb.QueryInput is passed.

func (*QueryReader) Count 

func (q *QueryReader) Count() int

Count returns the count of each item retrieved by a QueryReader instance.

func (*QueryReader) GetItem 

func (q *QueryReader) GetItem(ctx context.Context) (map[string]types.AttributeValue, error)

GetItem retrieves an Item from an Amazon DynamoDB table.

func (*QueryReader) Next 

func (q *QueryReader) Next() bool

Next indicates if there is another item to get.

type Schema 

type Schema interface {
	Marshaler
	Unmarshaler
}

Schema an Amazon DynamoDB model. Not necessarily a table.

type Unmarshaler 

type Unmarshaler interface {
	UnmarshalDynamoDB(map[string]types.AttributeValue) error
}

Unmarshaler converts a primitive map into an Amazon DynamoDB model.

Source Files

View all Source files

Directories

Path Synopsis
Package transaction is a database-agnostic utility set of rich functionalities to perform transactions.
 Package transaction is a database-agnostic utility set of rich functionalities to perform transactions.

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.