Documentation
¶
Overview ¶
Package ir defines the wire form clients send (JSON, docs/spec/protocol.md) and validates it against the manifest. Validation is the only place the DSL's rules live; every client renders the same IR.
Index ¶
- Constants
- func ConflictKey(ent *runtimemodel.Entity, set []Assign) (runtimemodel.Key, error)
- func FunctionType(name string, f *runtimemodel.Field) (string, bool)
- func IntervalType(name string) string
- func ItemConn(item Item) string
- func OpAllowed(c *runtimemodel.Field, op string) bool
- func ParamUses(m *runtimemodel.Model, r *Request) ([][]ParamUse, error)
- func Validate(m *runtimemodel.Model, r *Request) error
- type Assign
- type ColFunc
- type ColRef
- type Columns
- type Error
- type Func
- type Group
- type IfParent
- type Item
- type Join
- type JoinedRef
- type KeyPair
- type Limit
- type Optimist
- type Order
- type ParamUse
- type Pred
- type Query
- type Relation
- type Request
- type RestoreParts
- type Sub
Constants ¶
const Version = 1
Variables ¶
This section is empty.
Functions ¶
func ConflictKey ¶
func ConflictKey(ent *runtimemodel.Entity, set []Assign) (runtimemodel.Key, error)
ConflictKey returns the one key an insert with on_duplicate conflicts on. MySQL updates the row met on any unique key, while PostgreSQL and SQLite name one target and a meeting on another key is a unique violation, so no order of keys reproduces both: an upsert has exactly one key that can meet the inserted row, and the insert assigns every column of it. The candidates are the primary key, unless the insert leaves it out (an identity, or a key an IR executor assigns), and each unique key; a blind index column counts as assigned with its AES source.
func FunctionType ¶
func FunctionType(name string, f *runtimemodel.Field) (string, bool)
FunctionType is the type of a column function's result on column f: the type of a parameter compared with it and of the output column it selects.
func IntervalType ¶ added in v0.0.19
IntervalType is the type of the interval of a relative time function: seconds take a fraction, the other units an integer.
func ItemConn ¶ added in v0.0.19
ItemConn is the connector that joins an item to the item before it.
func OpAllowed ¶
func OpAllowed(c *runtimemodel.Field, op string) bool
OpAllowed reports whether op is allowed for the field's type and codec.
func ParamUses ¶
func ParamUses(m *runtimemodel.Model, r *Request) ([][]ParamUse, error)
ParamUses lists the uses of each parameter of a validated request, by parameter index: the compared or assigned column; a column function's result; i32, or f64 for seconds, for the interval of a relative time function; text for contains and contains_binary; the parent column for if_parent; the column for optimistic. An IR executor message writes each parameter in the form of its slot's type (docs/spec/protocol.md §5), so the client reads the type here.
Types ¶
type Assign ¶
type Assign struct {
Column string `json:"column"`
P *int `json:"p,omitempty"`
Null bool `json:"null,omitempty"`
PlusP *int `json:"plus_p,omitempty"`
MinusP *int `json:"minus_p,omitempty"`
}
Assign sets one column: exactly one of P (value), PlusP, MinusP, Null.
type ColRef ¶
ColRef points at a column on another entity in the same statement: Path is the relation path from the root ("" = root, "campaign", "campaign/service").
type Columns ¶
type Columns struct {
Mode string `json:"mode,omitempty"` // "" (default) | all | none
Add []string `json:"add,omitempty"`
Remove []string `json:"remove,omitempty"`
Fn map[string]ColFunc `json:"fn,omitempty"` // out name -> column function
Sub map[string]*Sub `json:"sub,omitempty"` // out name -> scalar subquery
}
type Error ¶
type Error struct {
Code string `json:"code"`
Msg string `json:"msg"`
// Cause is a driver error from the driver code, or the callback error of ROLLBACK and a rollback
// error. It is not included in the JSON form.
Cause error `json:"-"`
}
Error is a compile error with a stable code (docs/spec/errors.yaml).
type Group ¶
type Group struct {
Conn string `json:"conn,omitempty"` // and | or
// Not negates the whole nested group (`NOT (…)`). The top-level where and on groups are not negated.
Not bool `json:"not,omitempty"`
Items []Item `json:"items"`
}
Group is a parenthesised list. Conn joins the group to its previous sibling; the first item of a group has no connector.
type Item ¶
type Item struct {
Pred *Pred `json:"pred,omitempty"`
Group *Group `json:"group,omitempty"`
Joined *JoinedRef `json:"joined,omitempty"`
}
Item is exactly one of Pred, Group, Joined.
type Join ¶
type Join struct {
Rel string `json:"rel"`
Kind string `json:"kind"` // inner | left
Query *Query `json:"query"`
Left string `json:"left,omitempty"`
Right string `json:"right,omitempty"`
}
Join adds a child table to the statement. Rel is the join name, and Left is the parent column, and Right is the child column.
type KeyPair ¶
KeyPair is one component of a relation key: the parent column Left and the child column Right are equal. A relation of a composite key holds one pair per component, in key order.
type ParamUse ¶
type ParamUse struct {
Type string
Column *runtimemodel.Field
// Assign marks the assignment of Column (set, rows, on_duplicate): a non-null column
// refuses NULL.
Assign bool
}
ParamUse is one slot that a request parameter fills: the slot's logical type, a dbspec type kind, and for a column slot the compared or assigned column with its precision, scale, length and nullability.
type Pred ¶
type Pred struct {
Conn string `json:"conn,omitempty"`
Column string `json:"column,omitempty"`
Op string `json:"op,omitempty"`
P *int `json:"p,omitempty"` // single value
Ps []int `json:"ps,omitempty"` // in, not_in, between, tuple rows
Ref *ColRef `json:"ref,omitempty"` // *_col operators
Fn *Func `json:"fn,omitempty"` // column function applied to Column
Value *Func `json:"value,omitempty"` // value function compared with Column
Cols []string `json:"cols,omitempty"` // tuple_in, tuple_not_in columns; Ps holds the rows in order
Sub *Sub `json:"sub,omitempty"` // in, not_in subquery
}
Values never travel inside the tree: a predicate references parameters by index (P, Ps) into the request's Params list. The plan is therefore value-independent and executors fill placeholders from their own Params.
type Query ¶
type Query struct {
Entity string `json:"entity"`
Columns *Columns `json:"columns,omitempty"`
On *Group `json:"on,omitempty"` // join children only
Where *Group `json:"where,omitempty"`
Joins []*Join `json:"joins,omitempty"`
Relations []*Relation `json:"relations,omitempty"`
Order []Order `json:"order,omitempty"`
GroupBy []string `json:"group_by,omitempty"`
Limit *Limit `json:"limit,omitempty"`
ForceIdx string `json:"force_index,omitempty"`
Lock string `json:"lock,omitempty"` // update, share, update_nowait or share_nowait; root row-select only
// Relation-child options.
KeyBy string `json:"key_by,omitempty"`
Flatten bool `json:"flatten,omitempty"`
LimitPerParent int `json:"limit_per_parent,omitempty"`
IfParent *IfParent `json:"if_parent,omitempty"`
NoCascadeDelete bool `json:"no_cascade_delete,omitempty"` // deleteCascade stops at this relation
}
Query is the shape shared by the root, join children and relation children.
func CloneQuery ¶
CloneQuery copies every mutable part of a query tree before it is attached to another request. Parameter values live outside this tree.
type Relation ¶
type Relation struct {
Rel string `json:"rel"`
Query *Query `json:"query"`
Kind string `json:"kind,omitempty"` // one | many
Keys []KeyPair `json:"keys,omitempty"`
}
Relation reads rows with a separate statement. Rel is the result name, and Left, Right, Kind decide the key and the kind.
type Request ¶
type Request struct {
IRVersion int `json:"ir_version"`
// ManifestHash is the manifestHash of the generated code that made the request.
ManifestHash string `json:"manifest_hash"`
Kind string `json:"kind"` // one all count group_count sum avg paginate insert update delete restore restart_identity
Query
// Load means insert loads a row under the stored key as it is: it takes the value of the identity column,
// and requires that value if the table has an identity. It is not used with on_duplicate.
Load bool `json:"load,omitempty"`
Set []Assign `json:"set,omitempty"`
OnDuplicate []Assign `json:"on_duplicate,omitempty"` // insert: assignments applied when the unique key already exists
// Rows holds the parameters of each additional inserted row, in the
// column order of Set. Every Set item is then a value assignment.
Rows [][]int `json:"rows,omitempty"`
Optimistic *Optimist `json:"optimistic,omitempty"`
Agg string `json:"agg,omitempty"` // column for sum/avg
// NParams is how many parameters the client holds. The engine only checks
// indices against it; values never reach the engine.
NParams int `json:"n_params"`
}
Request is one statement: a query (select/count/sum/avg), a write (insert/update/delete/restore), or a paginate (select + count).
type RestoreParts ¶
type RestoreParts struct {
// Key is the primary key, or the unique key, whose columns the request gives values.
Key []string
// Where is the where of the request with an eq condition for each set value of a key column.
Where Group
// Set holds the set values of the columns outside the key: the new values of the row.
Set []Assign
}
RestoreParts are the parts of the statement of a restore request: the key that names its row, the conditions and the new values.
func RestoreKey ¶
func RestoreKey(ent *runtimemodel.Entity, r *Request) (RestoreParts, error)
RestoreKey picks the key of a restore request (docs/spec/protocol.md 1.5) after the request hook. The set values with a parameter and the eq conditions with a parameter that the where joins with and give columns their values; the key is the primary key when they cover it, otherwise the first unique key in name order that they cover. A set value of a key column becomes a condition, every other set value is a new value, and the where keeps its other conditions, which narrow the restore further; the key still names at most one row.
type Sub ¶
type Sub struct {
Query *Query `json:"query"`
Column string `json:"column,omitempty"`
Agg string `json:"agg,omitempty"`
}
Sub is a subquery. Column selects one column (IN lists and scalar columns); Agg selects sum, avg, or count over Column for a scalar column. Refs with path "^" inside the subquery point at the enclosing query.