kdb

README

Go driver for kdb+

This is an implementation of kdb+ driver native in Go. It implements Q IPC protocol.

Can be used both as a client(Go program connects to kdb+ process) and as a server(kdb+ connects to Go program). In server mode no execution capabilities are available.

For documentations and examples see godoc

Documentation

Overview

Package kdb implements encoding and decoding of q ipc message format

Index

• Constants
• Variables
• func Compress(b []byte) (dst []byte)
• func Decode(src *bufio.Reader) (data *K, msgtype ReqType, e error)
• func Encode(w io.Writer, msgtype ReqType, data *K) error
• func HandleClientConnection(conn net.Conn)
• func Uncompress(b []byte) (dst []byte)
• func UnmarshalDict(t Dict, v interface{}) error
• func UnmarshalDictToMap(t Dict, v interface{}) error
• func UnmarshalTable(t Table, v interface{}) (interface{}, error)
• type Attr
• type Dict
  • func (d Dict) String() string
• type Function
• type K
  • func Atom(t int8, x interface{}) *K
  • func Date(x time.Time) *K
  • func DateV(x []time.Time) *K
  • func Error(x error) *K
  • func Float(x float64) *K
  • func FloatV(x []float64) *K
  • func Int(x int32) *K
  • func IntV(x []int32) *K
  • func Long(x int64) *K
  • func LongV(x []int64) *K
  • func NewDict(k, v *K) *K
  • func NewFunc(ctx, body string) *K
  • func NewList(x ...*K) *K
  • func NewTable(cols []string, data []*K) *K
  • func Real(x float32) *K
  • func RealV(x []float32) *K
  • func Symbol(x string) *K
  • func SymbolV(x []string) *K
  • func (k *K) Index(i int) interface{}
  • func (k *K) Len() int
  • func (k K) String() string
• type KDBConn
  • func DialKDB(host string, port int, auth string) (*KDBConn, error)
  • func DialKDBTimeout(host string, port int, auth string, timeout time.Duration) (*KDBConn, error)
  • func DialTLS(host string, port int, auth string, cfg *tls.Config) (*KDBConn, error)
  • func DialUnix(host string, port int, auth string) (*KDBConn, error)
  • func (c *KDBConn) AsyncCall(cmd string, args ...*K) (err error)
  • func (c *KDBConn) Call(cmd string, args ...*K) (data *K, err error)
  • func (c *KDBConn) Close() error
  • func (c *KDBConn) ReadMessage() (data *K, msgtype ReqType, e error)
  • func (c *KDBConn) Response(data *K) (err error)
  • func (c *KDBConn) WriteMessage(msgtype ReqType, data *K) (err error)
• type Minute
  • func (m Minute) String() string
• type Month
  • func (m Month) String() string
• type ReqType
• type Second
  • func (s Second) String() string
• type Table
  • func (tbl *Table) Index(i int) Dict
  • func (tbl Table) String() string
• type Time
  • func (t Time) String() string

Examples

• DialKDB

Constants

const (
	ASYNC    ReqType = 0
	SYNC             = 1
	RESPONSE         = 2
)

Constants for recognised request types

const (
	K0 int8 = 0 // generic type
	//      type bytes qtype     ctype
	KB int8 = 1  // 1 boolean   char
	UU int8 = 2  // 16 guid     U
	KG int8 = 4  // 1 byte      char
	KH int8 = 5  // 2 short     short
	KI int8 = 6  // 4 int       int
	KJ int8 = 7  // 8 long      long
	KE int8 = 8  // 4 real      float
	KF int8 = 9  // 8 float     double
	KC int8 = 10 // 1 char      char
	KS int8 = 11 // * symbol    char*

	KP int8 = 12 // 8 timestamp long    nanoseconds from 2000.01.01
	KM int8 = 13 // 4 month     int     months from 2000.01.01
	KD int8 = 14 // 4 date      int     days from 2000.01.01
	KZ int8 = 15 // 8 datetime  double  deprecated - DO NOT USE
	KN int8 = 16 // 8 timespan  long    nanoseconds
	KU int8 = 17 // 4 minute    int
	KV int8 = 18 // 4 second    int
	KT int8 = 19 // 4 time      int     millisecond

	// table,dict
	XT int8 = 98  //   pointer to dictionary containing string keys(column names) and values
	XD int8 = 99  //   2 element generic list with 0 as keys and 1 as values
	SD int8 = 127 // 	 sorted dict - acts as a step function

	// function types
	KFUNC      int8 = 100
	KFUNCUP    int8 = 101 // unary primitive
	KFUNCBP    int8 = 102 // binary primitive
	KFUNCTR    int8 = 103 // ternary (operator)
	KPROJ      int8 = 104 // projection
	KCOMP      int8 = 105 // composition
	KEACH      int8 = 106 // f'
	KOVER      int8 = 107 //	f/
	KSCAN      int8 = 108 // f\
	KPRIOR     int8 = 109 // f':
	KEACHRIGHT int8 = 110 // f/:
	KEACHLEFT  int8 = 111 // f\:
	KDYNLOAD   int8 = 112 // dynamic loaded libraries - not available in IPC

	// error type
	KERR int8 = -128 // indicates error with 0 terminated string as a text
)

Q type constants

const Nh int16 = math.MinInt16

Nh is a short nil

const Ni int32 = math.MinInt32

Ni is an int nil

const Nj int64 = math.MinInt64

Nj is a long nil

const Wh int16 = math.MaxInt16

Wh is a short infinity

const Wi int32 = math.MaxInt32

Wi is an int infinity

const Wj int64 = math.MaxInt64

Wj is a long infinity

Variables

var ErrBadHeader = errors.New("Bad header")

ErrBadHeader to indicate invalid header

var ErrBadMsg = errors.New("Bad Message")

ErrBadMsg to indicate malformed or invalid message

var ErrSyncRequest = errors.New("nosyncrequest")

ErrSyncRequest cannot process sync requests

var Ne = float32(math.NaN())

Ne is a real nil

var Nf = math.NaN()

Nf is a double nil

var We = float32(math.Inf(+1))

We is a real infinity

var Wf = math.Inf(+1)

Wf is a double infinity

Functions

func Compress

func Compress(b []byte) (dst []byte)

Compress b using Q IPC compression

func Decode

func Decode(src *bufio.Reader) (data *K, msgtype ReqType, e error)

Decode deserialises data from src in q ipc format.

func Encode

func Encode(w io.Writer, msgtype ReqType, data *K) error

Encode data to ipc format as msgtype(sync/async/response) to specified writer

func HandleClientConnection

func HandleClientConnection(conn net.Conn)

process clients requests

func Uncompress

func Uncompress(b []byte) (dst []byte)

Uncompress byte array compressed with Q IPC compression

func UnmarshalDict

func UnmarshalDict(t Dict, v interface{}) error

UnmarshalDict decodes dict to a struct

func UnmarshalDictToMap

func UnmarshalDictToMap(t Dict, v interface{}) error

UnmarshalDictToMap decodes dict into map[string]{}interface

func UnmarshalTable

func UnmarshalTable(t Table, v interface{}) (interface{}, error)

UnmarshalTable decodes table to array of structs

Types

type Attr

type Attr int8

Attr denotes attribute set on a non-scalar object

const (
	NONE Attr = iota
	SORTED
	UNIQUE
	PARTED
	GROUPED
)

Constants for recognised attributes

type Dict

type Dict struct {
	Key   *K
	Value *K
}

Dict represents ordered key->value mapping. Key and Value must be slices of the same length

func (Dict) String

func (d Dict) String() string

String

type Function

type Function struct {
	Namespace string
	Body      string
}

Function represents function in kdb+

type K

type K struct {
	Type int8
	Attr Attr
	Data interface{}
}

K structure

func Atom

func Atom(t int8, x interface{}) *K

Atom constructs generic K atom with given type

func Date

func Date(x time.Time) *K

Date wraps time.Time as K

func DateV

func DateV(x []time.Time) *K

DateV wraps time.Time slice as K

func Error

func Error(x error) *K

Error constructs K error object from Go error

func Float

func Float(x float64) *K

Float wraps float64 as K

func FloatV

func FloatV(x []float64) *K

FloatV wraps float64 as K

func Int

func Int(x int32) *K

Int wraps int32 as K

func IntV

func IntV(x []int32) *K

IntV wraps int32 slice as K

func Long

func Long(x int64) *K

Long wraps int64 as K

func LongV

func LongV(x []int64) *K

LongV wraps int64 slice as K

func NewDict

func NewDict(k, v *K) *K

NewDict constructs K dict from k,v slices.

func NewFunc

func NewFunc(ctx, body string) *K

NewFunc creates K function with body in ctx namespace

func NewList

func NewList(x ...*K) *K

NewList constructs generic list(type 0) from list of K arguments

func NewTable

func NewTable(cols []string, data []*K) *K

NewTable constructs table with cols as header and data as values

func Real

func Real(x float32) *K

Real wraps float32 as K

func RealV

func RealV(x []float32) *K

RealV wraps float32 slice as K

func Symbol

func Symbol(x string) *K

Symbol wraps string as K

func SymbolV

func SymbolV(x []string) *K

SymbolV wraps string slice as K

func (*K) Index

func (k *K) Index(i int) interface{}

Index returns i'th element of K structure

func (*K) Len

func (k *K) Len() int

Len returns number of elements in K structure Special cases: Atoms and functions = 1 Dictionaries = number of keys Tables = number of rows

func (K) String

func (k K) String() string

String converts K structure to string

type KDBConn

type KDBConn struct {
	Host string
	Port string
	// contains filtered or unexported fields
}

KDBConn establishes connection and communicates using Q IPC protocol

func DialKDB

func DialKDB(host string, port int, auth string) (*KDBConn, error)

DialKDB connects to host:port using supplied user:password. Wait until connected

Example

con, err := kdb.DialKDB("localhost", 1234, "")
if err != nil {
	fmt.Println("Failed to connect:", err)
	return
}

res, err := con.Call("til", kdb.Int(10))
if err != nil {
	fmt.Println("Query failed:", err)
}
fmt.Println("Result:", res)

func DialKDBTimeout

func DialKDBTimeout(host string, port int, auth string, timeout time.Duration) (*KDBConn, error)

DialKDBTimeout connects to host:port using supplied user:password. Wait timeout for connection

func DialTLS

func DialTLS(host string, port int, auth string, cfg *tls.Config) (*KDBConn, error)

DialTLS connects to host:port using TLS with cfg provided

func DialUnix

func DialUnix(host string, port int, auth string) (*KDBConn, error)

DialUnix connects to port using unix domain sockets. host parameter is ignored.

func (*KDBConn) AsyncCall

func (c *KDBConn) AsyncCall(cmd string, args ...*K) (err error)

AsyncCall performs asynchronous call to kdb+

func (*KDBConn) Call

func (c *KDBConn) Call(cmd string, args ...*K) (data *K, err error)

Call performs synchronous call to kdb+ similar to h(func;arg1;arg2;...)

func (*KDBConn) Close

func (c *KDBConn) Close() error

Close connection to the server

func (*KDBConn) ReadMessage

func (c *KDBConn) ReadMessage() (data *K, msgtype ReqType, e error)

ReadMessage reads complete message from connection

func (*KDBConn) Response

func (c *KDBConn) Response(data *K) (err error)

Response sends response to asynchronous call

func (*KDBConn) WriteMessage

func (c *KDBConn) WriteMessage(msgtype ReqType, data *K) (err error)

WriteMessage sends data in Q IPC format

type Minute

type Minute time.Time

Minute represents a minute type in kdb

func (Minute) String

func (m Minute) String() string

type Month

type Month int32

Month represents a month type in kdb

func (Month) String

func (m Month) String() string

type ReqType

type ReqType int8

ReqType represents type of message sent or recieved via ipc

type Second

type Second time.Time

Second represents a second type in kdb - hh:mm:ss

func (Second) String

func (s Second) String() string

type Table

type Table struct {
	Columns []string
	Data    []*K
}

Table represents table type in kdb

func (*Table) Index

func (tbl *Table) Index(i int) Dict

Index returns i'th row of the table

func (Table) String

func (tbl Table) String() string

String prints table

type Time

type Time time.Time

Time represents time type in kdb - hh:mm:ss.SSS

func (Time) String

func (t Time) String() string