redis_bloom_go

README

redisbloom-go

Go client for RedisBloom (https://github.com/RedisBloom/redisbloom), based on redigo.

Installing

$ go get github.com/RedisBloom/redisbloom-go

Running tests

A simple test suite is provided, and can be run with:

$ RedisBloom_TEST_PASSWORD="" go test

The tests expect a Redis server with the RedisBloom module loaded to be available at localhost:6379

Example Code

package main 

import (
        "fmt"
        redisbloom "github.com/RedisBloom/redisbloom-go"
)

func main() {
		// Connect to localhost with no password
    var client = redisbloom.NewClient("localhost:6379", "nohelp", nil)
       
    // BF.ADD mytest item 
    _, err := client.Add("mytest", "myItem")
    if err != nil {
        fmt.Println("Error:", err)
    }
    
    exists, err := client.Exists("mytest", "myItem")
    if err != nil {
        fmt.Println("Error:", err)
    }
    fmt.Println("myItem exists in mytest: ", exists)
}

Supported RedisBloom Commands

Bloom Filter

Command	Recommended API and godoc
BF.RESERVE	Reserve
BF.ADD	Add
BF.MADD	N/A
BF.INSERT	N/A
BF.EXISTS	Exists
BF.MEXISTS	N/A
BF.SCANDUMP	N/A
BF.LOADCHUNK	N/A
BF.INFO	Info

Cuckoo Filter

Command	Recommended API and godoc
CF.RESERVE	N/A
CF.ADD	N/A
CF.ADDNX	N/A
CF.INSERT	N/A
CF.INSERTNX	N/A
CF.EXISTS	N/A
CF.DEL	N/A
CF.COUNT	N/A
CF.SCANDUMP	N/A
CF.LOADCHUNK	N/A
CF.INFO	N/A

Count-Min Sketch

Command	Recommended API and godoc
CMS.INITBYDIM	N/A
CMS.INITBYPROB	N/A
CMS.INCRBY	N/A
CMS.QUERY	N/A
CMS.MERGE	N/A
CMS.INFO	N/A

TopK Filter

Command	Recommended API and godoc
TOPK.RESERVE	TopkReserve
TOPK.ADD	TopkAdd
TOPK.INCRBY	TopkIncrby
TOPK.QUERY	TopkQuery
TOPK.COUNT	TopkCount
TOPK.LIST	TopkList
TOPK.INFO	TopkInfo

License

redisbloom-go is distributed under the BSD 3-Clause license - see LICENSE

Documentation

Index

• type Client
  • func NewClient(addr, name string, authPass *string) *Client
  • func NewClientFromPool(pool *redis.Pool, name string) *Client
  • func (client *Client) Add(key string, item string) (exists bool, err error)
  • func (client *Client) BfAddMulti(key string, items []string) ([]int64, error)
  • func (client *Client) BfExistsMulti(key string, items []string) ([]int64, error)
  • func (client *Client) Exists(key string, item string) (exists bool, err error)
  • func (client *Client) Info(key string) (info map[string]int64, err error)
  • func (client *Client) Reserve(key string, error_rate float64, capacity uint64) (err error)
  • func (client *Client) TopkAdd(key string, items []string) ([]string, error)
  • func (client *Client) TopkCount(key string, items []string) ([]string, error)
  • func (client *Client) TopkIncrBy(key string, itemIncrements map[string]int64) ([]string, error)
  • func (client *Client) TopkInfo(key string) (map[string]string, error)
  • func (client *Client) TopkList(key string) ([]string, error)
  • func (client *Client) TopkQuery(key string, items []string) ([]int64, error)
  • func (client *Client) TopkReserve(key string, topk int64, width int64, depth int64, decay float64) (string, error)
• type ConnPool
• type MultiHostPool
  • func NewMultiHostPool(hosts []string, authPass *string) *MultiHostPool
  • func (p *MultiHostPool) Close() (err error)
  • func (p *MultiHostPool) Get() redis.Conn
• type SingleHostPool
  • func NewSingleHostPool(host string, authPass *string) *SingleHostPool

Examples

• NewClient
• NewClientFromPool

Types

type Client

type Client struct {
	Pool ConnPool
	Name string
}

Client is an interface to time series redis commands

func NewClient

func NewClient(addr, name string, authPass *string) *Client

NewClient creates a new client connecting to the redis host, and using the given name as key prefix. Addr can be a single host:port pair, or a comma separated list of host:port,host:port... In the case of multiple hosts we create a multi-pool and select connections at random

Example

exemplifies the NewClient function

package main

import (
	"fmt"
	redisbloom "github.com/RedisBloom/redisbloom-go"
)

func main() {
	host := "localhost:6379"
	var client = redisbloom.NewClient(host, "nohelp", nil)

	// BF.ADD mytest item
	_, err := client.Add("mytest", "myItem")
	if err != nil {
		fmt.Println("Error:", err)
	}

	exists, err := client.Exists("mytest", "myItem")
	if err != nil {
		fmt.Println("Error:", err)
	}
	fmt.Println("myItem exists in mytest: ", exists)
}

Output:

myItem exists in mytest:  true

func NewClientFromPool

func NewClientFromPool(pool *redis.Pool, name string) *Client

NewClientFromPool creates a new Client with the given pool and client name

Example

exemplifies the NewClientFromPool function

package main

import (
	"fmt"
	redisbloom "github.com/RedisBloom/redisbloom-go"
	"github.com/gomodule/redigo/redis"
	"log"
)

func main() {
	host := "localhost:6379"
	password := ""
	pool := &redis.Pool{Dial: func() (redis.Conn, error) {
		return redis.Dial("tcp", host, redis.DialPassword(password))
	}}
	client := redisbloom.NewClientFromPool(pool, "bloom-client-1")

	// BF.ADD mytest item
	_, err := client.Add("mytest", "myItem")
	if err != nil {
		log.Fatalf("Error: %v", err)
	}

	exists, err := client.Exists("mytest", "myItem")
	if err != nil {
		log.Fatalf("Error: %v", err)
	}
	fmt.Println("myItem exists in mytest: ", exists)
}

Output:

myItem exists in mytest:  true

func (*Client) Add

func (client *Client) Add(key string, item string) (exists bool, err error)

Add - Add (or create and add) a new value to the filter args: key - the name of the filter item - the item to add

func (*Client) BfAddMulti

func (client *Client) BfAddMulti(key string, items []string) ([]int64, error)

BfAddMulti - Adds one or more items to the Bloom Filter, creating the filter if it does not yet exist. args: key - the name of the filter item - One or more items to add

func (*Client) BfExistsMulti

func (client *Client) BfExistsMulti(key string, items []string) ([]int64, error)

BfExistsMulti - Determines if one or more items may exist in the filter or not. args: key - the name of the filter item - one or more items to check

func (*Client) Exists

func (client *Client) Exists(key string, item string) (exists bool, err error)

Exists - Determines whether an item may exist in the Bloom Filter or not. args: key - the name of the filter item - the item to check for

func (*Client) Info

func (client *Client) Info(key string) (info map[string]int64, err error)

Info - Return information about key args: key - the name of the filter

func (*Client) Reserve

func (client *Client) Reserve(key string, error_rate float64, capacity uint64) (err error)

Reserve - Creates an empty Bloom Filter with a given desired error ratio and initial capacity. args: key - the name of the filter error_rate - the desired probability for false positives capacity - the number of entries you intend to add to the filter

func (*Client) TopkAdd

func (client *Client) TopkAdd(key string, items []string) ([]string, error)

Adds an item to the data structure.

func (*Client) TopkCount

func (client *Client) TopkCount(key string, items []string) ([]string, error)

Returns count for an item.

func (*Client) TopkIncrBy

func (client *Client) TopkIncrBy(key string, itemIncrements map[string]int64) ([]string, error)

Increase the score of an item in the data structure by increment.

func (*Client) TopkInfo

func (client *Client) TopkInfo(key string) (map[string]string, error)

Returns number of required items (k), width, depth and decay values.

func (*Client) TopkList

func (client *Client) TopkList(key string) ([]string, error)

Return full list of items in Top K list.

func (*Client) TopkQuery

func (client *Client) TopkQuery(key string, items []string) ([]int64, error)

Checks whether an item is one of Top-K items.

func (*Client) TopkReserve

func (client *Client) TopkReserve(key string, topk int64, width int64, depth int64, decay float64) (string, error)

Initializes a TopK with specified parameters.

type ConnPool

type ConnPool interface {
	Get() redis.Conn
	Close() error
}

type MultiHostPool

type MultiHostPool struct {
	sync.Mutex
	// contains filtered or unexported fields
}

func NewMultiHostPool

func NewMultiHostPool(hosts []string, authPass *string) *MultiHostPool

func (*MultiHostPool) Close

func (p *MultiHostPool) Close() (err error)

func (*MultiHostPool) Get

func (p *MultiHostPool) Get() redis.Conn

type SingleHostPool

type SingleHostPool struct {
	*redis.Pool
}

func NewSingleHostPool

func NewSingleHostPool(host string, authPass *string) *SingleHostPool