dyngeo

package module
v0.1.2 Latest Latest
Warning

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

 Go to latest Published: Jan 23, 2023 License: MIT Imports: 13 Imported by: 0

README

DynG(e)o

Unofficial Go port of the Geo Library for Amazon DynamoDB using geohash to easily create and query geospatial data. The library takes care of managing the geohash indexes and storing item with latitude/longitude pairs.

Install

Fetch the package with

go get github.com/crolly/dyngeo

And import it into your programs with

import "github.com/crolly/dyngeo"

Usage

DynG(e)o Configuration
type DynGeoConfig struct {
	TableName             string
	ConsistentRead        bool
	HashKeyAttributeName  string
	RangeKeyAttributeName string
	GeoHashAttributeName  string
	GeoJSONAttributeName  string
	GeoHashIndexName      string
	HashKeyLength         int8
	LongitudeFirst        bool

	DynamoDBClient  *dynamodb.DynamoDB
}

Defines, how DynG(e)o manages the geospatial data, e.g. what the db attribute and index names are as well as setting the geohash key length. The geohash key length will determine the size of the tiles the planet will be seperated into:

Length Tile Size
1 5,009.4km x 4,992.6km
2 1,252.3km x 624.1km
3 156.5km x 156km
4 39.1km x 19.5km
5 4.9km x 4.9km
6 1.2km x 609.4m
7 152.9m x 152.4m
8 38.2m x 19m
9 4.8m x 4.8m
10 1.2m x 59.5cm
11 14.9cm x 14.9cm
12 3.7cm x 1.9cm

Setting DynamoDBClient *dynamodb.DynamoDB and TableName string is required.

DynG(e)o Instance
func New
func New(config DynGeoConfig) (*DynGeo, error)

Returns a new instance of DynG(e)o managing the geohashing and geospatial db operations.

func PutPoint
func (dg DynGeo) PutPoint(input PutPointInput) (*PutPointOutput, error)

Put a point into the Amazon DynamoDB table. Once put, you cannot update attributes specified in GeoDataManagerConfiguration: hash key, range key, geohash and geoJson. If you want to update these columns, you need to insert a new record and delete the old record.

func BatchWritePoints
func (dg DynGeo) BatchWritePoints(inputs []PutPointInput) (*BatchWritePointOutput, error)

Put a list of points into the Amazon DynamoDB table. Once put, you cannot update attributes specified in GeoDataManagerConfiguration: hash key, range key, geohash and geoJson. If you want to update these columns, you need to insert a new record and delete the old record.

func GetPoint
func (dg DynGeo) GetPoint(input GetPointInput) (*GetPointOutput, error)

Get a point from the Amazon DynamoDB table.

func UpdatePoint
func (dg DynGeo) UpdatePoint(input UpdatePointInput) (*UpdatePointOutput, error)

Update a point data in Amazon DynamoDB table. You cannot update attributes specified in GeoDataManagerConfiguration: hash key, range key, geohash and geoJson. If you want to update these columns, you need to insert a new record and delete the old record.

func DeletePoint
func (dg DynGeo) DeletePoint(input DeletePointInput) (*DeletePointOutput, error)

Delete a point from the Amazon DynamoDB table.

func QueryRadius
func (dg DynGeo) QueryRadius(input QueryRadiusInput, out interface{}) error

Query a circular area constructed by a center point and its radius.

func QueryRectangle
func (dg DynGeo) QueryRectangle(input QueryRectangleInput, out interface{}) error

Query a rectangular area constructed by two points and return all points within the area. Two points need to construct a rectangle from minimum and maximum latitudes and longitudes. If minPoint.Longitude > maxPoint.Longitude, the rectangle spans the 180 degree longitude line.

Getting Started Example

This repository contains a Getting Started example in the folder starbucks-example inspired by James Beswick's very good blog post about Location-based search results with DynamoDB and Geohash

It uses the US Starbucks locations, loads them into DynamoDB in batches of 25 and then retrieves the the locations of all Starbucks in the radius of 5000 meters surrounding Latitude: 40.7769099, Longitude: -73.9822532.

The example illustrates the general usage as well as a hint of the performance. The radius search constantly needs about 20-30ms with the given dataset (approximately 6500 Starbucks coffee shops in the US).

Documentation

Index

Constants

View Source 
const EARTH_RADIUS_METERS = 6367000.0

S2 Util

Variables

This section is empty.

Functions

func GetCreateTableRequest 

func GetCreateTableRequest(config Config) *dynamodb.CreateTableInput

Types

type BatchWritePointOutput 

type BatchWritePointOutput struct {
	*dynamodb.BatchWriteItemOutput
}

type Config added in v0.1.2 

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

func MakeConfig added in v0.1.2 

func MakeConfig(opts ...GeoOptions) *Config

func (Config) Valid added in v0.1.2 

func (cfg Config) Valid() error

type DeletePointInput 

type DeletePointInput struct {
	PointInput
	DeleteItemInput dynamodb.DeleteItemInput
}

type DeletePointOutput 

type DeletePointOutput struct {
	*dynamodb.DeleteItemOutput
}

type ErrFailedToConvertItemToGeoPoint added in v0.1.2 

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

func (ErrFailedToConvertItemToGeoPoint) Error added in v0.1.2 

func (e ErrFailedToConvertItemToGeoPoint) Error() string

type ErrMissingDynamoClient added in v0.1.2 

type ErrMissingDynamoClient struct{}

func (ErrMissingDynamoClient) Error added in v0.1.2 

func (ErrMissingDynamoClient) Error() string

type ErrMissingDynamoTableName added in v0.1.2 

type ErrMissingDynamoTableName struct{}

func (ErrMissingDynamoTableName) Error added in v0.1.2 

func (ErrMissingDynamoTableName) Error() string

type ErrPaginatedQueryInvalidLimit added in v0.1.2 

type ErrPaginatedQueryInvalidLimit struct{}

func (ErrPaginatedQueryInvalidLimit) Error added in v0.1.2 

func (ErrPaginatedQueryInvalidLimit) Error() string

type Geo added in v0.1.2 

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

func New 

func New(cfg *Config) (*Geo, error)

func (Geo) BatchWritePoints added in v0.1.2 

func (g Geo) BatchWritePoints(ctx context.Context, inputs []PutPointInput) (*BatchWritePointOutput, error)

func (Geo) DeletePoint added in v0.1.2 

func (g Geo) DeletePoint(ctx context.Context, input DeletePointInput) (*DeletePointOutput, error)

func (Geo) GetPoint added in v0.1.2 

func (g Geo) GetPoint(ctx context.Context, input GetPointInput) (*GetPointOutput, error)

func (Geo) PutPoint added in v0.1.2 

func (g Geo) PutPoint(ctx context.Context, input PutPointInput) (*PutPointOutput, error)

func (Geo) QueryRadius added in v0.1.2 

func (g Geo) QueryRadius(ctx context.Context, input QueryRadiusInput, out interface{}) error

func (Geo) QueryRadiusPaginated added in v0.1.2 

func (g Geo) QueryRadiusPaginated(ctx context.Context, input QueryRadiusInput, hashToLastEvaluatedEntry GeoHashToLastEvaluatedDBValue, limit uint, out interface{}) (GeoHashToLastEvaluatedDBValue, error)

func (Geo) QueryRectangle added in v0.1.2 

func (g Geo) QueryRectangle(ctx context.Context, input QueryRectangleInput, out interface{}) error

func (Geo) UpdatePoint added in v0.1.2 

func (g Geo) UpdatePoint(ctx context.Context, input UpdatePointInput) (*UpdatePointOutput, error)

type GeoHashToLastEvaluatedDBValue 

type GeoHashToLastEvaluatedDBValue map[uint64]map[string]types.AttributeValue

type GeoJSONAttribute 

type GeoJSONAttribute struct {
	Type        string    `json:"type"`
	Coordinates []float64 `json:"coordinates"`
}

type GeoOptions added in v0.1.2 

type GeoOptions func(c *Config)

func WithConsistentRead added in v0.1.2 

func WithConsistentRead(consistentRead bool) GeoOptions

func WithDynamoClient added in v0.1.2 

func WithDynamoClient(client *dynamodb.Client) GeoOptions

WithDynamoClient sets the dynamo client to be used

func WithGeoHashkey added in v0.1.2 

func WithGeoHashkey(attributeName string) GeoOptions

WithGeoHashkey sets a custom geo hashKey attribute name. When it's missing, the value is `geohash`

func WithGeoIndex added in v0.1.2 

func WithGeoIndex(name string) GeoOptions

WithGeoIndex sets a custom geo index name. When it's missing, the value is `geohash-index`

func WithGeoJSONKey added in v0.1.2 

func WithGeoJSONKey(attributeName string) GeoOptions

WithGeoJSONKey sets a custom geo JSON key attribute name. When it's missing, the value is `geoJson`

func WithHashkey added in v0.1.2 

func WithHashkey(attributeName string) GeoOptions

WithHashKey sets a custom hashKey attribute name. When it's missing, the value is `hashKey`

func WithHashkeyLen added in v0.1.2 

func WithHashkeyLen(len int8) GeoOptions

WithHashkeyLen sets a custom hashKey len. When it's missing, the value is `5`

func WithLongitudeFirst added in v0.1.2 

func WithLongitudeFirst(f bool) GeoOptions

WithLongitudeFirst sets the order of a geo coordinate to be readed, the default value is false.

func WithRangekey added in v0.1.2 

func WithRangekey(attributeName string) GeoOptions

WithHashKey sets a custom rangeKey attribute name. When it's missing, the value is `rangeKey`

func WithRetryOnFilterOfRadiusQuery added in v0.1.2 

func WithRetryOnFilterOfRadiusQuery(maxRetries, multiplier int) GeoOptions

WithRetryOnFilterOfRadiusQuery sets a max number of retries allowed for radius query; Important to mention, this retry will be applied when the algo is trying to find if the results from dynamo db are part of the created circle. When this is enabled, the algorithm will do 

radius = radius * multiplier; for each reach the maxRetries - do radius * multiplier

be aware that multipler has set 2 as default

func WithS2RegionCoverer added in v0.1.2 

func WithS2RegionCoverer(s2rc s2.RegionCoverer) GeoOptions

WithS2RegionCoverer sets the s2.RegionCoverer to be used

func WithTableName added in v0.1.2 

func WithTableName(name string) GeoOptions

WithTableName sets the table name expected to be queried

func WithUnmarshalAsJSON added in v0.1.2 

func WithUnmarshalAsJSON(f bool) GeoOptions

type GeoPoint 

type GeoPoint struct {
	Latitude  float64
	Longitude float64
}

type GeoQueryInput 

type GeoQueryInput struct {
	QueryInput dynamodb.QueryInput
}

type GeoQueryOutput 

type GeoQueryOutput struct {
	*dynamodb.QueryOutput
}

type GetPointInput 

type GetPointInput struct {
	PointInput
	GetItemInput dynamodb.GetItemInput
}

type GetPointOutput 

type GetPointOutput struct {
	*dynamodb.GetItemOutput
}

type PointInput 

type PointInput struct {
	RangeKeyValue types.AttributeValue
	GeoPoint      GeoPoint
}

type PutPointInput 

type PutPointInput struct {
	PointInput
	PutItemInput dynamodb.PutItemInput
}

type PutPointOutput 

type PutPointOutput struct {
	*dynamodb.PutItemOutput
}

type QueryRadiusInput 

type QueryRadiusInput struct {
	GeoQueryInput
	CenterPoint   GeoPoint
	RadiusInMeter int
}

type QueryRadiusOutput 

type QueryRadiusOutput struct {
	*GeoQueryOutput
}

type QueryRectangleInput 

type QueryRectangleInput struct {
	GeoQueryInput
	MinPoint *GeoPoint
	MaxPoint *GeoPoint
}

type QueryRectangleOutput 

type QueryRectangleOutput struct {
	*GeoQueryOutput
}

type UpdatePointInput 

type UpdatePointInput struct {
	PointInput
	UpdateItemInput dynamodb.UpdateItemInput
}

type UpdatePointOutput 

type UpdatePointOutput struct {
	*dynamodb.UpdateItemOutput
}

Source Files

View all Source files

Directories

Path Synopsis

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.