tablestorage

package
v0.5.0 Latest Latest
Warning

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

Go to latest
Published: Jan 12, 2019 License: MPL-2.0 Imports: 7 Imported by: 0

Documentation

Overview

Package tablestorage contains an implementation of the `gokv.Store` interface for Azure Table Storage.

Index

Constants

This section is empty.

Variables

View Source
var DefaultOptions = Options{
	TableName:            "gokv",
	PartitionKeySupplier: EmptyPartitionKeySupplier,
	Codec:                encoding.JSON,
}

DefaultOptions is an Options object with default values. TableName: "gokv", PartitionKeySupplier: tablestorage.EmptyPartitionKeySupplier, Codec: encoding.JSON.

Functions

func CreateSyntheticPartitionKeySupplier

func CreateSyntheticPartitionKeySupplier(partitionCount uint16) func(string) string

CreateSyntheticPartitionKeySupplier creates a PartitionKeySupplier that calculates synthetic "partition keys" from the given key-value pair keys.

Attention! It's experimental, so we might change or remove this in future releases.

The amount of distinct partition keys can be configured via the partitionCount parameter. They're evenly distributed to avoid "hot spot" partitions. Automatic tests assert a hit count deviation below 20% across all partition keys. It's a "synthetic" partition key, similar to the description in the official documentation: https://github.com/MicrosoftDocs/azure-docs/blob/f3ffbfd3258ee1132f710cfefaf33d92c4f096f2/articles/cosmos-db/synthetic-partition-keys.md.

The documentation suggests to use several hundred to several thousand distinct values. A high value ensures scalability and evenly distributed workload across the physical storage partitions. Maximum value (as enforced by uint16) is 65535.

func EmptyPartitionKeySupplier

func EmptyPartitionKeySupplier(_ string) string

EmptyPartitionKeySupplier returns an empty string as partition key for any given value.

Types

type Client

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

Client is a gokv.Store implementation for Table Storage.

func NewClient

func NewClient(options Options) (Client, error)

NewClient creates a new Table Storage client.

func (Client) Close

func (c Client) Close() error

Close closes the client. In the Table Storage implementation this doesn't have any effect.

func (Client) Delete

func (c Client) Delete(k string) error

Delete deletes the stored value for the given key. Deleting a non-existing key-value pair does NOT lead to an error. The key must not be "".

func (Client) Get

func (c Client) Get(k string, v interface{}) (found bool, err error)

Get retrieves the stored value for the given key. You need to pass a pointer to the value, so in case of a struct the automatic unmarshalling can populate the fields of the object that v points to with the values of the retrieved object's values. If no value is found it returns (false, nil). The key must not be "" and the pointer must not be nil.

func (Client) Set

func (c Client) Set(k string, v interface{}) error

Set stores the given value for the given key. Values are automatically marshalled to JSON or gob (depending on the configuration). The key must not be "" and the value must not be nil.

type Options

type Options struct {
	// Connection string.
	// Can be either a normal connection string like this:
	// "DefaultEndpointsProtocol=https;AccountName=foo;AccountKey=abc123==;EndpointSuffix=core.windows.net".
	// Or a "shared access signature". In this case it must not contain "BlobEndpoint", "FileEndpoint" or "QueueEndpoint".
	// Example: "TableEndpoint=https://foo.table.core.windows.net/;SharedAccessSignature=sv=2017-11-09&ss=t&srt=sco&sp=rwdlacu&se=2018-01-01T00:00:00Z&st=2018-01-02T00:00:00Z&spr=https&sig=abc123"
	ConnectionString string
	// Name of the table.
	// If the table doesn't exist yet, it's created automatically.
	// Optional ("gokv" by default).
	TableName string
	// PartitionKeySupplier is a function for supplying a "partition key" for a given key.
	//
	// The partition key is used to split the storage into logical partitions,
	// which is required to scale and evenly distribute workload across physical Table Storage partitions.
	// The Table Storage documentation suggests to use several hundred to several thousand distinct values.
	//
	// When using Table Storage as key-value store WITHOUT QUERIES though, partition keys can be as fine grained as possible,
	// up to using NO partition key at all, which leads to a new partition for each entity.
	// This only has a disadvantage when the keys that are being inserted are ordered
	// (e.g. you have 5 key-value pairs, with the keys being in the order 123, 124, 125, 126, 127),
	// because Azure then creates "range partitions", which can lead to bad scalability for inserts.
	//
	// gokv's default PartitionKeySupplier returns an empty partition key,
	// 1) for maximum scalability and 2) to not force a partition key generation algorithm on you,
	// which then leads to the key-value pairs not being accessible without using the same algorithm in the future.
	//
	// For a synthetic partition key generator you can create one using tablestorage.CreateSyntheticPartitionKeySupplier().
	// It's experimental though, so we might change or remove it in future releases.
	//
	// If you want to create your own PartitionKeySupplier, you should read the documentation about how to choose a PartitonKey.
	// See https://github.com/MicrosoftDocs/azure-docs/blob/984bcf2b5adf9340004603539d47fa94e13e4568/articles/cosmos-db/partitioning-overview.md#choosing-a-partition-key.
	// And https://docs.microsoft.com/en-us/rest/api/storageservices/designing-a-scalable-partitioning-strategy-for-azure-table-storage.
	// And https://github.com/MicrosoftDocs/azure-docs/blob/f3ffbfd3258ee1132f710cfefaf33d92c4f096f2/articles/cosmos-db/synthetic-partition-keys.md.
	//
	// When you decided on a way to supply partition keys, you should never change it,
	// because already stored key-value pairs cannot be retrieved with a partition key
	// that's different from the one that was used when storing the key-value pair.
	//
	// Optional (tablestorage.EmptyPartitionKeySupplier is used, leading to NO partition keys).
	PartitionKeySupplier func(k string) string
	// Encoding format.
	// Optional (encoding.JSON by default).
	Codec encoding.Codec
}

Options are the options for the Table Storage client.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL