Documentation
¶
Overview ¶
Package query defines Ridu's transport-independent query language.
The same query model is shared by access filters, local operations, the HTTP API, generated clients, and storage adapters.
Index ¶
- Constants
- type Comparison
- type Direction
- type Expression
- func And(conditions ...Expression) Expression
- func Compare(path Path, operator Operator, value Value) (Expression, error)
- func Contains[P FieldPath](path P, value string) Expression
- func Equal[P FieldPath, V Operand](path P, value V) Expression
- func Exists[P FieldPath](path P, exists bool) Expression
- func GreaterThan[P FieldPath, V Ordered](path P, value V) Expression
- func GreaterThanEqual[P FieldPath, V Ordered](path P, value V) Expression
- func In[P FieldPath, V Operand](path P, values ...V) Expression
- func LessThan[P FieldPath, V Ordered](path P, value V) Expression
- func LessThanEqual[P FieldPath, V Ordered](path P, value V) Expression
- func Like[P FieldPath](path P, value string) Expression
- func Not(condition Expression) Expression
- func NotEqual[P FieldPath, V Operand](path P, value V) Expression
- func Or(conditions ...Expression) Expression
- type ExpressionKind
- type FieldPath
- type Node
- type Operand
- type Operator
- type Ordered
- type Path
- func (path Path) AppendSegments(segments []string) []string
- func (path Path) Len() int
- func (path Path) MarshalJSON() ([]byte, error)
- func (path Path) Segment(index int) string
- func (path Path) Segments() []string
- func (path Path) String() string
- func (path *Path) UnmarshalJSON(encoded []byte) error
- type Population
- type Sort
- type Value
- func (value Value) BooleanValue() (bool, bool)
- func (value Value) Kind() ValueKind
- func (value Value) MarshalJSON() ([]byte, error)
- func (value Value) NumberValue() (float64, bool)
- func (value Value) ReferenceValue() (relationTo, id string, ok bool)
- func (value Value) StringValue() (string, bool)
- func (value Value) Values() []Value
- type ValueKind
Constants ¶
const ( // MaxPathSegments bounds recursive query compilation and schema traversal. // Ridu's operation engine supports substantially shallower authored models, // leaving this ceiling as a fail-safe rather than a practical restriction. MaxPathSegments = 64 // MaxPathBytes bounds user-supplied filter/sort/population path allocation. MaxPathBytes = 4096 )
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Comparison ¶
Comparison is a read-only snapshot of a comparison expression.
type Expression ¶
type Expression interface {
Kind() ExpressionKind
Node() Node
// contains filtered or unexported methods
}
Expression is an immutable query expression. Implementations are sealed so every transport and store sees the same finite query language.
func And ¶
func And(conditions ...Expression) Expression
And matches documents that satisfy every condition. With one condition it returns that condition. Like Equal, it panics when given no conditions or a nil one; check the length of a list built from input before calling it.
func Compare ¶
func Compare(path Path, operator Operator, value Value) (Expression, error)
Compare constructs a validated field comparison from an operator chosen at run time, such as one read from a request. It returns an error where the helpers below panic.
func Contains ¶
func Contains[P FieldPath](path P, value string) Expression
Contains matches documents whose text field contains value, ignoring case.
func Equal ¶
func Equal[P FieldPath, V Operand](path P, value V) Expression
Equal matches documents whose field equals value, as in Equal("status", "published") or Equal("parent", query.Null()).
func Exists ¶ added in v0.6.0
func Exists[P FieldPath](path P, exists bool) Expression
Exists matches documents that have a value for the field when exists is true, and documents without one when it is false.
func GreaterThan ¶
func GreaterThan[P FieldPath, V Ordered](path P, value V) Expression
GreaterThan matches documents whose field is greater than value.
func GreaterThanEqual ¶
func GreaterThanEqual[P FieldPath, V Ordered](path P, value V) Expression
GreaterThanEqual matches documents whose field is at least value.
func In ¶
func In[P FieldPath, V Operand](path P, values ...V) Expression
In matches documents whose field equals one of values, as in In("status", "draft", "published"). With no values it matches nothing.
func LessThan ¶
func LessThan[P FieldPath, V Ordered](path P, value V) Expression
LessThan matches documents whose field is less than value.
func LessThanEqual ¶
func LessThanEqual[P FieldPath, V Ordered](path P, value V) Expression
LessThanEqual matches documents whose field is at most value.
func Like ¶
func Like[P FieldPath](path P, value string) Expression
Like matches documents whose text field contains every word of value, ignoring case and word order.
func Not ¶
func Not(condition Expression) Expression
Not matches documents that do not satisfy condition. It panics when condition is nil.
func NotEqual ¶
func NotEqual[P FieldPath, V Operand](path P, value V) Expression
NotEqual matches documents whose field differs from value.
func Or ¶
func Or(conditions ...Expression) Expression
Or matches documents that satisfy at least one condition. With one condition it returns that condition. It panics when given no conditions or a nil one.
type ExpressionKind ¶
type ExpressionKind string
ExpressionKind identifies the shape of an expression node.
const ( ExpressionComparison ExpressionKind = "comparison" ExpressionAnd ExpressionKind = "and" ExpressionOr ExpressionKind = "or" ExpressionNot ExpressionKind = "not" )
type FieldPath ¶ added in v0.6.0
FieldPath is a field in a filter or sort: a dot-separated name written in your code, such as "title" or "seo.title", or a Path. A malformed name panics, like regexp.MustCompile; use ParsePath for names from user input.
type Node ¶
type Node struct {
Kind ExpressionKind
Comparison *Comparison
Children []Node
}
Node is a detached recursive snapshot for adapters and protocol encoders. Mutating a Node never mutates the originating Expression.
type Operand ¶ added in v0.6.0
type Operand interface {
~string | ~bool | ~int | ~int8 | ~int16 | ~int32 | ~int64 | ~uint | ~uint8 | ~uint16 | ~uint32 | ~uint64 | ~float32 | ~float64 | Value
}
Operand is a value compared with a field: a string, boolean, integer, or float, including named types such as a string enum, or a Value built with String, Number, Boolean, Null, Reference, or List.
type Operator ¶
type Operator string
Operator identifies a field comparison.
const ( OperatorEqual Operator = "equal" OperatorNotEqual Operator = "not_equal" OperatorIn Operator = "in" OperatorExists Operator = "exists" OperatorGreaterThan Operator = "greater_than" OperatorGreaterThanEqual Operator = "greater_than_equal" OperatorLessThan Operator = "less_than" OperatorLessThanEqual Operator = "less_than_equal" OperatorContains Operator = "contains" OperatorLike Operator = "like" )
type Ordered ¶ added in v0.6.0
type Ordered interface {
~string | ~int | ~int8 | ~int16 | ~int32 | ~int64 | ~uint | ~uint8 | ~uint16 | ~uint32 | ~uint64 | ~float32 | ~float64 | Value
}
Ordered is an Operand that greater-than and less-than comparisons accept: strings and numbers, or a Value holding one.
type Path ¶
type Path struct {
// contains filtered or unexported fields
}
Path is an immutable, validated document field path. Its canonical string form joins segments with a dot, for example "seo.title". The exact single-segment paths "_status" and "_revision" address Ridu's finite version metadata; arbitrary underscore-prefixed or nested system paths remain invalid.
func Field ¶ added in v0.5.0
Field names a field by its segments, such as Field("seo", "title"). Like regexp.MustCompile, it panics when a name is malformed. Filter helpers also accept the dot-separated string "seo.title" directly; use Field when you need a Path value, such as for ListOptions.Select.
func NewPath ¶
NewPath validates and constructs a field path from segments computed at run time, such as names read from a schema. For a name written in your code, pass the string to a filter helper instead.
func ParsePath ¶
ParsePath validates and constructs a path from its dot-separated form. Use it for names that come from user input, where a malformed name is an error.
func (Path) AppendSegments ¶ added in v0.15.0
AppendSegments appends the path segments to segments.
func (Path) MarshalJSON ¶
MarshalJSON encodes a path in its canonical dot-separated form.
func (*Path) UnmarshalJSON ¶
UnmarshalJSON validates the canonical string before replacing the path.
type Population ¶
type Population struct {
Path Path
Depth int
// Select is nil for the complete populated target. A non-nil empty slice
// returns only document metadata.
Select []Path
}
Population asks a store to replace one relationship ID with its projected target document. Depth is bounded by the operation engine.
type Sort ¶
Sort is one validated ordered field term. Stores append ID as a stable tiebreaker when callers do not provide it explicitly.
type Value ¶
type Value struct {
// contains filtered or unexported fields
}
Value is an immutable query operand. Explicit constructors prevent arbitrary application values from leaking into the public query contract.
func DateTime ¶ added in v0.6.0
DateTime converts t to the text a date-and-time field stores, so it can be compared with that field or with createdAt and updatedAt, as in GreaterThan("publishedAt", DateTime(time.Now())). Date-only fields store "2006-01-02"; compare them with t.Format(time.DateOnly).
func Reference ¶ added in v0.15.0
Reference constructs a polymorphic relationship candidate: document id in collection relationTo. It equals a stored {relationTo, id} reference, as in In("subjects", Reference("posts", postID)).
func (Value) BooleanValue ¶
BooleanValue returns the boolean and true when this is a boolean operand.
func (Value) MarshalJSON ¶
func (Value) NumberValue ¶
NumberValue returns the number and true when this is a number operand.
func (Value) ReferenceValue ¶ added in v0.15.0
ReferenceValue returns the collection slug, document ID, and true when this is a reference operand.
func (Value) StringValue ¶
StringValue returns the string and true when this is a string operand.
type ValueKind ¶
type ValueKind string
ValueKind identifies the concrete scalar, reference, or list represented by a Value.
const ( ValueString ValueKind = "string" ValueNumber ValueKind = "number" ValueBoolean ValueKind = "boolean" ValueNull ValueKind = "null" ValueList ValueKind = "list" // ValueReference names one document among a polymorphic relationship's // target collections, in the relationship's {relationTo, id} value shape. ValueReference ValueKind = "reference" )
Source Files