Documentation
¶
Overview ¶
Package ir defines the wire form clients send (JSON, docs/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
- func OpAllowed(c *runtimemodel.Field, op string) bool
- func ParamUses(m *runtimemodel.Model, r *Request) [][]ParamUse
- 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
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 OpAllowed ¶
func OpAllowed(c *runtimemodel.Field, op string) bool
OpAllowed는 op가 field의 type과 codec에 허용되는지 알린다.
func ParamUses ¶
func ParamUses(m *runtimemodel.Model, r *Request) [][]ParamUse
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/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는 driver code의 driver 오류이거나 ROLLBACK의 callback 오류와 rollback
// 오류다. JSON 형태에는 들어가지 않는다.
Cause error `json:"-"`
}
Error is a compile error with a stable code (docs/errors.yaml).
type Group ¶
type Group struct {
Conn string `json:"conn,omitempty"` // and | or
// Not은 nested group 전체를 부정한다(`NOT (…)`). top-level where와 on group은 부정하지 않는다.
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은 statement에 child table을 더한다. Rel은 join 이름이고, Left는 parent column, Right는 child column이다.
type KeyPair ¶
KeyPair는 relation key의 한 성분이다: 부모 column Left와 자식 column Right가 같다. composite key의 relation은 성분마다 한 쌍을 key 순서대로 담는다.
type ParamUse ¶
type ParamUse struct {
Type string
Column *runtimemodel.Field
}
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은 별도 statement로 행을 읽는다. Rel은 결과 이름이고 Left, Right, Kind가 key와 종류를 정한다.
type Request ¶
type Request struct {
IRVersion int `json:"ir_version"`
// ManifestHash는 request를 만든 generated code의 manifestHash다.
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은 insert가 행을 저장된 key 그대로 적재한다는 뜻이다: identity column의 값을
// 받고, identity가 있는 table이면 그 값을 요구한다. 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/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.