planbuilder

Documentation

Index

• Constants
• func IsUnique(v Vindex) bool
• func Register(vindexType string, newVindexFunc NewVindexFunc)
• type ByCost
  • func (bc ByCost) Len() int
  • func (bc ByCost) Less(i, j int) bool
  • func (bc ByCost) Swap(i, j int)
• type ClassFormal
• type ColVindex
• type ColVindexFormal
• type Functional
• type FunctionalGenerator
• type Keyspace
• type KeyspaceFormal
• type Lookup
• type LookupGenerator
• type NewVindexFunc
• type NonUnique
• type Plan
  • func BuildPlan(query string, schema *Schema) *Plan
  • func (pln *Plan) IsMulti() bool
  • func (pln *Plan) MarshalJSON() ([]byte, error)
  • func (pln *Plan) Size() int
• type PlanID
  • func PlanByName(s string) (id PlanID, ok bool)
  • func (id PlanID) MarshalJSON() ([]byte, error)
  • func (id PlanID) String() string
• type Reversible
• type Schema
  • func BuildSchema(source *SchemaFormal) (schema *Schema, err error)
  • func LoadFile(filename string) (schema *Schema, err error)
  • func NewSchema(data []byte) (schema *Schema, err error)
  • func (schema *Schema) FindTable(tablename string) (table *Table, reason string)
• type SchemaFormal
• type Table
• type Unique
• type VCursor
• type Vindex
  • func CreateVindex(vindexType string, params map[string]interface{}) (Vindex, error)
• type VindexFormal

Constants

const (
	NoPlan = PlanID(iota)
	SelectUnsharded
	SelectEqual
	SelectIN
	SelectKeyrange
	SelectScatter
	UpdateUnsharded
	UpdateEqual
	DeleteUnsharded
	DeleteEqual
	InsertUnsharded
	InsertSharded
	NumPlans
)

The following constants define all the PlanID values.

const ListVarName = "_vals"

ListVarName is the bind var name used for plans that require VTGate to compute custom list values, like for IN clauses.

Functions

func IsUnique

func IsUnique(v Vindex) bool

IsUnique returns true if the Vindex is Unique.

func Register

func Register(vindexType string, newVindexFunc NewVindexFunc)

Register registers a vindex under the specified vindexType. A duplicate vindexType will generate a panic. New vindexes will be created using these functions at the time of schema loading.

Types

type ByCost

type ByCost []*ColVindex

ByCost provides the interface needed for ColVindexes to be sorted by cost order.

func (ByCost) Len

func (bc ByCost) Len() int

func (ByCost) Less

func (bc ByCost) Less(i, j int) bool

func (ByCost) Swap

func (bc ByCost) Swap(i, j int)

type ClassFormal

type ClassFormal struct {
	ColVindexes []ColVindexFormal
}

ClassFormal is the info for each table class as loaded from the source.

type ColVindex

type ColVindex struct {
	Col    string
	Type   string
	Name   string
	Owned  bool
	Vindex Vindex
}

ColVindex contains the index info for each index of a table.

type ColVindexFormal

type ColVindexFormal struct {
	Col  string
	Name string
}

ColVindexFormal is the info for each indexed column of a table as loaded from the source.

type Functional

type Functional interface {
	Create(VCursor, interface{}) error
	Delete(VCursor, []interface{}, []byte) error
	Unique
}

A Functional vindex is an index that can compute the keyspace id from the id without a lookup. This means that the creation of a functional vindex entry does not take the keyspace id as input. In general, the main reason to support creation functions for functional indexes is for auto-generating ids. A Functional vindex is also required to be Unique. If it's not unique, we cannot determine the target shard for an insert operation.

type FunctionalGenerator

type FunctionalGenerator interface {
	Functional
	Generate(cursor VCursor) (id int64, err error)
}

A FunctionalGenerator vindex is a Functional vindex that can generate new ids.

type Keyspace

type Keyspace struct {
	Name    string
	Sharded bool
}

Keyspace contains the keyspcae info for each Table.

type KeyspaceFormal

type KeyspaceFormal struct {
	Sharded  bool
	Vindexes map[string]VindexFormal
	Classes  map[string]ClassFormal
	Tables   map[string]string
}

KeyspaceFormal is the keyspace info for each keyspace as loaded from the source.

type Lookup

type Lookup interface {
	Create(VCursor, interface{}, []byte) error
	Delete(VCursor, []interface{}, []byte) error
}

A Lookup vindex is one that needs to lookup a previously stored map to compute the keyspace id from an id. This means that the creation of a lookup vindex entry requires a keyspace id as input. A Lookup vindex need not be unique because the keyspace_id, which must be supplied, can be used to determine the target shard for an insert operation.

type LookupGenerator

type LookupGenerator interface {
	Lookup
	Generate(VCursor, []byte) (id int64, err error)
}

A LookupGenerator vindex is a Lookup that can generate new ids.

type NewVindexFunc

type NewVindexFunc func(map[string]interface{}) (Vindex, error)

A NewVindexFunc is a function that creates a Vindex based on the properties specified in the input map. Every vindex must register a NewVindexFunc under a unique vindexType.

type NonUnique

type NonUnique interface {
	Map(cursor VCursor, ids []interface{}) ([][][]byte, error)
}

NonUnique defines the interface for a non-unique vindex. This means that an id can map to multiple keyspace ids.

type Plan

type Plan struct {
	ID PlanID
	// Reason usually contains a string describing the reason
	// for why a certain plan was (or not) chosen.
	Reason string
	Table  *Table
	// Original is the original query.
	Original string
	// Rewritten is the rewritten query. This is empty for
	// all Unsharded plans since the Original query is sufficient.
	Rewritten string
	// Subquery is used for DeleteUnsharded to fetch the column values
	// for owned vindexes so they can be deleted.
	Subquery  string
	ColVindex *ColVindex
	// Values is a single or a list of values that are used
	// for making routing decisions.
	Values interface{}
}

Plan represents the routing strategy for a given query.

func BuildPlan

func BuildPlan(query string, schema *Schema) *Plan

BuildPlan builds a plan for a query based on the specified schema.

func (*Plan) IsMulti

func (pln *Plan) IsMulti() bool

IsMulti returns true if the SELECT query can potentially be sent to more than one shard.

func (*Plan) MarshalJSON

func (pln *Plan) MarshalJSON() ([]byte, error)

MarshalJSON serializes the Plan into a JSON representation.

func (*Plan) Size

func (pln *Plan) Size() int

Size is defined so that Plan can be given to an LRUCache.

type PlanID

type PlanID int

PlanID is number representing the plan id.

func PlanByName

func PlanByName(s string) (id PlanID, ok bool)

PlanByName returns the PlanID from the plan name. If it cannot be found, then it returns NumPlans.

func (PlanID) MarshalJSON

func (id PlanID) MarshalJSON() ([]byte, error)

MarshalJSON serializes the plan id as a JSON string.

func (PlanID) String

func (id PlanID) String() string

type Reversible

type Reversible interface {
	ReverseMap(cursor VCursor, ks []byte) (interface{}, error)
}

A Reversible vindex is one that can perform a reverse lookup from a keyspace id to an id. This is optional. If present, VTGate can use it to fill column values based on the target keyspace id.

type Schema

type Schema struct {
	Tables map[string]*Table
}

Schema represents the denormalized version of SchemaFormal, used for building routing plans.

func BuildSchema

func BuildSchema(source *SchemaFormal) (schema *Schema, err error)

BuildSchema builds a Schema from a SchemaFormal.

func LoadFile

func LoadFile(filename string) (schema *Schema, err error)

LoadFile creates a new Schema from a JSON file.

func NewSchema

func NewSchema(data []byte) (schema *Schema, err error)

NewSchema creates a new Schema from a JSON byte array.

func (*Schema) FindTable

func (schema *Schema) FindTable(tablename string) (table *Table, reason string)

FindTable returns a pointer to the Table if found. Otherwise, it returns a reason, which is equivalent to an error.

type SchemaFormal

type SchemaFormal struct {
	Keyspaces map[string]KeyspaceFormal
}

SchemaFormal is the formal representation of the schema as loaded from the source.

type Table

type Table struct {
	Name        string
	Keyspace    *Keyspace
	ColVindexes []*ColVindex
	Ordered     []*ColVindex
	Owned       []*ColVindex
}

Table represnts a table in Schema.

type Unique

type Unique interface {
	Map(cursor VCursor, ids []interface{}) ([][]byte, error)
}

Unique defines the interface for a unique vindex. For a vindex to be unique, an id has to map to at most one keyspace id.

type VCursor

type VCursor interface {
	Execute(query *tproto.BoundQuery) (*mproto.QueryResult, error)
}

A VCursor is an interface that allows you to execute queries in the current context and session of a VTGate request. Vindexes can use this interface to execute lookup queries.

type Vindex

type Vindex interface {
	// Cost is used by planbuilder to prioritize vindexes.
	// The cost can be 0 if the id is basically a keyspace id.
	// The cost can be 1 if the id can be hashed to a keyspace id.
	// The cost can be 2 or above if the id needs to be looked up
	// from an external data source. These guidelines are subject
	// to change in the future.
	Cost() int

	// Verify must be implented by all vindexes. It should return
	// true if the id can be mapped to the keyspace id.
	Verify(cursor VCursor, id interface{}, ks []byte) (bool, error)
}

Vindex defines the interface required to register a vindex. Additional to these functions, a vindex also needs to satisfy the Unique or NonUnique interface.

func CreateVindex

func CreateVindex(vindexType string, params map[string]interface{}) (Vindex, error)

CreateVindex creates a vindex of the specified type using the supplied params. The type must have been previously registered.

type VindexFormal

type VindexFormal struct {
	Type   string
	Params map[string]interface{}
	Owner  string
}

VindexFormal is the info for each index as loaded from the source.