Documentation
¶
Overview ¶
Package ast provides builder helpers for ergonomic AST construction.
Package ast defines the Abstract Syntax Tree (AST) for TypeQL queries.
Package ast defines the Abstract Syntax Tree (AST) for TypeQL queries.
It decouples query construction from string formatting, providing a structured way to build TypeQL queries programmatically.
Index ¶
- func EscapeString(s string) string
- func FormatGoValue(value any) string
- func FormatLiteral(val any, valueType string) string
- type AggregateExpr
- type ArithmeticValue
- type AttributePattern
- type Clause
- type Compiler
- type Constraint
- type DeleteClause
- type DeleteHasStatement
- type DeleteThingStatement
- type EntityPattern
- type FetchAttribute
- type FetchAttributeList
- type FetchClause
- type FetchFunction
- type FetchItem
- type FetchNestedWildcard
- type FetchVariable
- type FetchWildcard
- type FunctionCallValue
- type HasConstraint
- type HasPattern
- type HasStatement
- type IidConstraint
- type IidPattern
- type InsertClause
- type IsaConstraint
- type IsaStatement
- type LetAssignment
- type LimitClause
- type LiteralValue
- type MatchClause
- type MatchLetClause
- type NotPattern
- type OffsetClause
- type OrPattern
- type Pattern
- type PutClause
- type QueryNode
- type RawPattern
- type RawStatement
- type ReduceAssignment
- type ReduceClause
- type RelationPattern
- type RelationStatement
- type RolePlayer
- type SelectClause
- type SortClause
- type Statement
- type SubTypePattern
- type UpdateClause
- type Value
- type ValueComparisonPattern
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func EscapeString ¶
EscapeString escapes special characters in a string for use in TypeQL string literals. It handles backslashes, quotes, newlines, carriage returns, and tabs.
func FormatGoValue ¶
FormatGoValue converts a Go value into its TypeQL literal string representation. It uses reflection to determine the type and handles basic types, pointers, and time.Time. This is the canonical formatting function for Go values; other packages should use this instead of implementing their own formatting logic.
func FormatLiteral ¶
FormatLiteral formats a Go value as a TypeQL literal string.
Types ¶
type AggregateExpr ¶
type AggregateExpr struct {
// FuncName is the name of the aggregate function (count, sum, min, max, mean, std, median).
FuncName string
// Var is the variable being aggregated.
Var string
// AttrName is the optional attribute name to aggregate on if the variable is a thing.
AttrName string
}
AggregateExpr represents an aggregate expression like count($var) or sum($attr).
type ArithmeticValue ¶
type ArithmeticValue struct {
// Left is the left operand (Value or variable string).
Left any
// Operator is the infix operator (+, -, *, /, %, ^).
Operator string
// Right is the right operand (Value or variable string).
Right any
}
ArithmeticValue represents a binary arithmetic operation between two values. It supports TypeQL infix operators like +, -, *, /, %, and ^.
type AttributePattern ¶
type AttributePattern struct {
// Variable is the variable name for the attribute.
Variable string
// TypeName is the name of the attribute type.
TypeName string
// Value is the optional value of the attribute.
Value Value
}
AttributePattern matches an attribute of a specific type and optionally its value.
type Clause ¶
type Clause interface {
QueryNode
// contains filtered or unexported methods
}
Clause is the marker interface for top-level TypeQL clauses.
type Compiler ¶
type Compiler struct{}
Compiler compiles AST nodes into TypeQL query strings. It traverses the AST and generates the corresponding TypeQL syntax.
type Constraint ¶
type Constraint interface {
QueryNode
// contains filtered or unexported methods
}
Constraint is the marker interface for constraints applied to variables in a pattern.
type DeleteClause ¶
type DeleteClause struct {
// Statements are the statements defining what to delete.
Statements []Statement
}
DeleteClause represents a 'delete' clause containing one or more statements.
func Delete ¶
func Delete(statements ...Statement) DeleteClause
Delete creates a DeleteClause with the given statements.
type DeleteHasStatement ¶
type DeleteHasStatement struct {
// AttrVar is the variable representing the attribute to delete (e.g., "$old").
AttrVar string
// OwnerVar is the variable representing the owner entity/relation (e.g., "$e").
OwnerVar string
}
DeleteHasStatement represents a statement to delete an attribute from its owner. Compiles to: $attrVar of $ownerVar
func DeleteHas ¶
func DeleteHas(attrVar, ownerVar string) DeleteHasStatement
DeleteHas creates a DeleteHasStatement for deleting an attribute from its owner. Compiles to: $attrVar of $ownerVar
type DeleteThingStatement ¶
type DeleteThingStatement struct {
// Variable is the variable representing the thing to delete.
Variable string
}
DeleteThingStatement represents a statement to delete a thing instance identified by a variable.
type EntityPattern ¶
type EntityPattern struct {
// Variable is the variable name for the matched entity.
Variable string
// TypeName is the name of the entity type.
TypeName string
// Constraints are additional constraints applied to the entity.
Constraints []Constraint
// IsStrict indicates whether to use strict type checking (isa!).
IsStrict bool
}
EntityPattern matches an entity with an optional type and constraints.
func Entity ¶
func Entity(varName, typeName string, constraints ...Constraint) EntityPattern
Entity creates an EntityPattern with the given variable, type, and constraints.
type FetchAttribute ¶
type FetchAttribute struct {
// Key is the output key in the result JSON.
Key string
// Var is the variable whose attribute is being fetched.
Var string
// AttrName is the name of the attribute type to fetch.
AttrName string
}
FetchAttribute fetches a single attribute value of a variable.
func FetchAttr ¶
func FetchAttr(key, varName, attrName string) FetchAttribute
FetchAttr creates a FetchAttribute for fetching an attribute value. The attrPath should be like "$var.attrname".
func FetchAttrPath ¶
func FetchAttrPath(key, attrPath string) FetchAttribute
FetchAttrPath is a convenience for creating FetchAttribute from a dotted path like "$p.name".
func (FetchAttribute) FetchKey ¶
func (f FetchAttribute) FetchKey() string
FetchKey returns the output key for the attribute.
type FetchAttributeList ¶
type FetchAttributeList struct {
// Key is the output key in the result JSON.
Key string
// Var is the variable whose attributes are being fetched.
Var string
// AttrName is the name of the attribute type.
AttrName string
}
FetchAttributeList fetches all values of a multi-value attribute as a list.
func (FetchAttributeList) FetchKey ¶
func (f FetchAttributeList) FetchKey() string
FetchKey returns the output key for the attribute list.
type FetchClause ¶
type FetchClause struct {
// Items are the items to fetch, which can be FetchItem nodes or raw strings.
Items []any
}
FetchClause defines the output structure of a query.
func Fetch ¶
func Fetch(items ...FetchItem) FetchClause
Fetch creates a FetchClause with the given items.
type FetchFunction ¶
type FetchFunction struct {
// Key is the output key in the result JSON.
Key string
// FuncName is the name of the function (e.g., "iid").
FuncName string
// Var is the variable the function is applied to.
Var string
}
FetchFunction fetches the result of a function applied to a variable.
func FetchFunc ¶
func FetchFunc(key, funcName, varName string) FetchFunction
FetchFunc creates a FetchFunction for fetching the result of a function.
func (FetchFunction) FetchKey ¶
func (f FetchFunction) FetchKey() string
FetchKey returns the output key for the function result.
type FetchItem ¶
type FetchItem interface {
QueryNode
// FetchKey returns the key under which the item will be returned in the result JSON.
FetchKey() string
// contains filtered or unexported methods
}
FetchItem is the marker interface for items in a 'fetch' clause.
type FetchNestedWildcard ¶
type FetchNestedWildcard struct {
// Key is the output key in the result JSON.
Key string
// Var is the variable being fetched.
Var string
}
FetchNestedWildcard retrieves all attributes and their values recursively in a nested structure.
func (FetchNestedWildcard) FetchKey ¶
func (f FetchNestedWildcard) FetchKey() string
FetchKey returns the output key for the nested wildcard.
type FetchVariable ¶
type FetchVariable struct {
// Key is the output key in the result JSON.
Key string
// Var is the variable being fetched.
Var string
}
FetchVariable fetches a variable directly.
func FetchVar ¶
func FetchVar(key, varName string) FetchVariable
FetchVar creates a FetchVariable for fetching a variable directly.
func (FetchVariable) FetchKey ¶
func (f FetchVariable) FetchKey() string
FetchKey returns the output key for the variable.
type FetchWildcard ¶
type FetchWildcard struct {
// Key is the output key in the result JSON.
Key string
// Var is the variable whose attributes are all fetched.
Var string
}
FetchWildcard fetches all attributes of a variable.
func (FetchWildcard) FetchKey ¶
func (f FetchWildcard) FetchKey() string
FetchKey returns the output key for the wildcard.
type FunctionCallValue ¶
type FunctionCallValue struct {
// Function is the name of the function to call.
Function string
// Args contains the arguments for the function, which can be Value nodes or variable strings.
Args []any
}
FunctionCallValue represents a function call in TypeQL, such as iid($x).
func FuncCall ¶
func FuncCall(funcName string, args ...any) FunctionCallValue
FuncCall creates a FunctionCallValue with the given function name and arguments.
type HasConstraint ¶
type HasConstraint struct {
// AttrName is the name of the attribute type.
AttrName string
// Value is the value of the attribute (Value or variable string).
Value any
}
HasConstraint checks if a thing has a specific attribute with a given value.
func Has ¶
func Has(attrName string, value any) HasConstraint
Has creates a HasConstraint for the given attribute name and value. The value can be any Go value that will be formatted via FormatGoValue.
type HasPattern ¶
type HasPattern struct {
// ThingVar is the variable representing the thing (entity or relation).
ThingVar string
// AttrType is the type of the attribute.
AttrType string
// AttrVar is the variable representing the attribute instance.
AttrVar string
}
HasPattern represents a pattern where a thing has an attribute assignment ($x has Type $v).
type HasStatement ¶
type HasStatement struct {
// SubjectVar is the variable representing the thing being assigned an attribute.
SubjectVar string
// AttrName is the name of the attribute type.
AttrName string
// Value is the value being assigned.
Value Value
}
HasStatement assigns an attribute value to a subject variable.
func HasStmt ¶
func HasStmt(subjectVar, attrName string, value Value) HasStatement
HasStmt creates a HasStatement for the given subject variable, attribute name, and value. The value must be a Value type (use Str(), Long(), etc. to create literal values).
type IidConstraint ¶
type IidConstraint struct {
// IID is the unique instance identifier.
IID string
}
IidConstraint matches a thing by its internal instance ID (IID).
type IidPattern ¶
type IidPattern struct {
// Variable is the variable representing the thing.
Variable string
// IID is the instance ID string.
IID string
}
IidPattern represents a pattern matching a thing by its IID ($x iid 0x...).
type InsertClause ¶
type InsertClause struct {
// Statements are the statements to insert.
Statements []Statement
}
InsertClause represents an 'insert' clause containing one or more statements.
func Insert ¶
func Insert(statements ...Statement) InsertClause
Insert creates an InsertClause with the given statements.
type IsaConstraint ¶
type IsaConstraint struct {
// TypeName is the name of the type.
TypeName string
// Strict indicates whether to use strict type checking (isa!).
Strict bool
}
IsaConstraint checks if a thing is an instance of a specific type.
func Isa ¶
func Isa(typeName string) IsaConstraint
Isa creates an IsaConstraint for the given type name.
func IsaExact ¶
func IsaExact(typeName string) IsaConstraint
IsaExact creates a strict IsaConstraint (isa!) for the given type name.
type IsaStatement ¶
type IsaStatement struct {
// Variable is the variable name.
Variable string
// TypeName is the name of the type.
TypeName string
}
IsaStatement defines the type of a variable in an insert statement.
func IsaStmt ¶
func IsaStmt(variable, typeName string) IsaStatement
IsaStmt creates an IsaStatement for the given variable and type name.
type LetAssignment ¶
type LetAssignment struct {
// Variables are the variables being assigned values.
Variables []string
// Expression is the value or expression being assigned (Value or variable string).
Expression any
// IsStream indicates whether to use stream assignment ('in') or scalar assignment ('=').
IsStream bool
}
LetAssignment represents an assignment in a 'match let' clause.
type LimitClause ¶
type LimitClause struct {
// Count is the maximum number of results to return.
Count int
}
LimitClause represents a 'limit' clause for restricting result count.
type LiteralValue ¶
type LiteralValue struct {
// Val is the actual value.
Val any
// ValueType specifies the TypeQL type of the value (e.g., "string", "long", "boolean").
ValueType string
}
LiteralValue represents a literal value such as a string, number, or boolean.
func Lit ¶
func Lit(value any, valueType string) LiteralValue
Lit creates a LiteralValue with the given value and type.
type MatchClause ¶
type MatchClause struct {
// Patterns are the patterns to match.
Patterns []Pattern
}
MatchClause represents a 'match' clause containing one or more patterns.
func Match ¶
func Match(patterns ...Pattern) MatchClause
Match creates a MatchClause with the given patterns.
type MatchLetClause ¶
type MatchLetClause struct {
// Assignments are the let assignments in the clause.
Assignments []LetAssignment
}
MatchLetClause represents a 'match' clause using 'let' assignments.
type NotPattern ¶
type NotPattern struct {
// Patterns are the patterns to negate.
Patterns []Pattern
}
NotPattern represents a negation of one or more patterns (not { ... }).
type OffsetClause ¶
type OffsetClause struct {
// Count is the number of results to skip.
Count int
}
OffsetClause represents an 'offset' clause for skipping results.
func Offset ¶
func Offset(count int) OffsetClause
Offset creates an OffsetClause with the given count.
type OrPattern ¶
type OrPattern struct {
// Alternatives defines the multiple sets of patterns that satisfy the disjunction.
Alternatives [][]Pattern
}
OrPattern represents a disjunction of multiple pattern alternatives ({ ... } or { ... }).
type Pattern ¶
type Pattern interface {
QueryNode
// contains filtered or unexported methods
}
Pattern is the marker interface for patterns used in a match clause.
type PutClause ¶
type PutClause struct {
// Statements are the statements defining what to put.
Statements []Statement
}
PutClause represents a 'put' clause (upsert) containing one or more statements. Put inserts if not exists, or skips if already exists (based on key attributes).
type QueryNode ¶
type QueryNode interface {
// contains filtered or unexported methods
}
QueryNode is the marker interface for all AST nodes.
type RawPattern ¶
type RawPattern struct {
// Content is the raw TypeQL string.
Content string
}
RawPattern represents a raw TypeQL string pattern, typically for legacy support.
type RawStatement ¶
type RawStatement struct {
// Content is the raw TypeQL string.
Content string
}
RawStatement represents a raw TypeQL string statement.
type ReduceAssignment ¶
type ReduceAssignment struct {
// Variable is the variable receiving the aggregated value.
Variable string
// Expression is the aggregation expression (AggregateExpr or variable string).
Expression any
}
ReduceAssignment represents an assignment in a 'reduce' clause.
type ReduceClause ¶
type ReduceClause struct {
// Assignments are the aggregate assignments.
Assignments []ReduceAssignment
// GroupBy is the optional variable to group the results by.
GroupBy string
}
ReduceClause represents a 'reduce' clause for performing aggregations in TypeQL.
type RelationPattern ¶
type RelationPattern struct {
// Variable is the variable name for the matched relation.
Variable string
// TypeName is the name of the relation type.
TypeName string
// RolePlayers defines the participants in the relation.
RolePlayers []RolePlayer
// Constraints are additional constraints applied to the relation.
Constraints []Constraint
}
RelationPattern matches a relation with its role players and optional constraints.
func Relation ¶
func Relation(varName, typeName string, rolePlayers []RolePlayer, constraints ...Constraint) RelationPattern
Relation creates a RelationPattern with the given variable, type, role players, and constraints.
type RelationStatement ¶
type RelationStatement struct {
// Variable is the optional variable name for the relation.
Variable string
// TypeName is the name of the relation type.
TypeName string
// RolePlayers defines the participants in the relation.
RolePlayers []RolePlayer
// IncludeVariable indicates whether to include the variable prefix in the compiled query.
IncludeVariable bool
// Attributes are inline attribute assignments for the relation.
Attributes []HasStatement
}
RelationStatement defines a relation and its participants for an insert statement. In TypeDB 3.x, relations in insert statements often don't use a variable prefix.
func RelationStmt ¶
func RelationStmt(typeName string, rolePlayers ...RolePlayer) RelationStatement
RelationStmt creates a RelationStatement with the given relation type and role players.
type RolePlayer ¶
type RolePlayer struct {
// Role is the name of the role being played.
Role string
// PlayerVar is the variable name of the entity or relation playing the role (e.g., "$p").
PlayerVar string
}
RolePlayer represents a role player in a relation, mapping a role name to a player variable.
func Role ¶
func Role(roleName, playerVar string) RolePlayer
Role creates a RolePlayer with the given role name and player variable.
type SelectClause ¶
type SelectClause struct {
// Variables are the variable names to project (e.g., ["$did", "$name"]).
Variables []string
}
SelectClause represents a 'select' clause for variable projection. Compiles to: select $var1, $var2, ...;
func Select ¶
func Select(variables ...string) SelectClause
Select creates a SelectClause for variable projection.
type SortClause ¶
type SortClause struct {
// Variable is the variable name to sort by (e.g., "$name").
Variable string
// Direction is "asc" or "desc".
Direction string
}
SortClause represents a 'sort' clause for ordering query results.
func Sort ¶
func Sort(variable, direction string) SortClause
Sort creates a SortClause for the given variable and direction.
type Statement ¶
type Statement interface {
QueryNode
// contains filtered or unexported methods
}
Statement is the marker interface for statements used in insert, delete, or update clauses.
type SubTypePattern ¶
type SubTypePattern struct {
// Variable is the variable representing the subtype.
Variable string
// ParentType is the name of the parent type.
ParentType string
}
SubTypePattern matches types that are subtypes of a parent type ($t sub type).
type UpdateClause ¶
type UpdateClause struct {
// Statements are the statements defining what to update.
Statements []Statement
}
UpdateClause represents an 'update' clause containing one or more statements.
func Update ¶
func Update(statements ...Statement) UpdateClause
Update creates an UpdateClause with the given statements.
type Value ¶
type Value interface {
QueryNode
// contains filtered or unexported methods
}
Value is the marker interface for value nodes that can be used in expressions.
func ValueFromGo ¶
ValueFromGo converts a Go value to an AST Value node. Handles common types: string, int, int64, float64, bool, time.Time. Falls back to string representation for unknown types.
type ValueComparisonPattern ¶
type ValueComparisonPattern struct {
// Var is the variable being compared.
Var string
// Operator is the comparison operator (e.g., >, <, ==).
Operator string
// Value is the value to compare against (Value or variable string).
Value any
}
ValueComparisonPattern represents a comparison between a variable and a value ($v > 10).
func Cmp ¶
func Cmp(variable, operator string, value any) ValueComparisonPattern
Cmp creates a ValueComparisonPattern for comparing a variable to a value.