sqlgraph

package
v0.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 9, 2024 License: Apache-2.0 Imports: 12 Imported by: 148

Documentation

Overview

Package sqlgraph provides graph abstraction capabilities on top of sql-based databases for ent codegen.

Index

Constants

View Source
const FuncSelector fluent_ql.Func = "func_selector"

FuncSelector represents a selector function to be used as an fluent_ql foreign-function.

Variables

This section is empty.

Functions

func BatchCreate

func BatchCreate(ctx context.Context, drv dialect.Driver, spec *BatchCreateSpec) error

BatchCreate applies the BatchCreateSpec on the graph.

func CountNodes

func CountNodes(ctx context.Context, drv dialect.Driver, spec *QuerySpec) (int, error)

CountNodes counts the nodes in the given graph query.

func CreateNode

func CreateNode(ctx context.Context, drv dialect.Driver, spec *CreateSpec) error

CreateNode applies the CreateSpec on the graph. The operation creates a new record in the database, and connects it to other nodes specified in spec.Edges.

func DeleteNodes

func DeleteNodes(ctx context.Context, drv dialect.Driver, spec *DeleteSpec) (int, error)

DeleteNodes applies the DeleteSpec on the graph.

func HasNeighbors

func HasNeighbors(q *sql.Selector, s *Step)

HasNeighbors applies on the given Selector a neighbors check.

func HasNeighborsWith

func HasNeighborsWith(q *sql.Selector, s *Step, pred func(*sql.Selector))

HasNeighborsWith applies on the given Selector a neighbors check. The given predicate applies its filtering on the selector.

func IsConstraintError

func IsConstraintError(err error) bool

IsConstraintError returns true if the error resulted from a database constraint violation.

func IsForeignKeyConstraintError

func IsForeignKeyConstraintError(err error) bool

IsForeignKeyConstraintError reports if the error resulted from a database foreign-key constraint violation. e.g. parent row does not exist.

func IsUniqueConstraintError

func IsUniqueConstraintError(err error) bool

IsUniqueConstraintError reports if the error resulted from a DB uniqueness constraint violation. e.g. duplicate value in unique index.

func LimitNeighbors

func LimitNeighbors(partitionBy string, limit int, orderBy ...sql.Querier) func(*sql.Selector)

LimitNeighbors returns a modifier that limits the number of neighbors (rows) loaded per parent row (node). The "partitionBy" is the foreign-key column (edge) to partition the window function by, the "limit" is the maximum number of rows per parent, and the "orderBy" defines the order of how neighbors (connected by the edge) are returned.

This function is useful for non-unique edges, such as O2M and M2M, where the same parent can have multiple children.

func Neighbors

func Neighbors(dialect string, s *Step) (q *sql.Selector)

Neighbors returns a Selector for evaluating the path-step and getting the neighbors of one vertex.

func OrderByNeighborTerms

func OrderByNeighborTerms(q *sql.Selector, s *Step, opts ...sql.OrderTerm)

OrderByNeighborTerms appends ordering based on the number of neighbors. For example, order users by their number of posts.

func OrderByNeighborsCount

func OrderByNeighborsCount(q *sql.Selector, s *Step, opts ...sql.OrderTermOption)

OrderByNeighborsCount appends ordering based on the number of neighbors. For example, order users by their number of posts.

func QueryEdges

func QueryEdges(ctx context.Context, drv dialect.Driver, spec *EdgeQuerySpec) error

QueryEdges queries the edges in the graph and scans the result with the given dest function.

func QueryNodes

func QueryNodes(ctx context.Context, drv dialect.Driver, spec *QuerySpec) error

QueryNodes queries the nodes in the graph query and scans them to the given values.

func SetNeighbors

func SetNeighbors(dialect string, s *Step) (q *sql.Selector)

SetNeighbors returns a Selector for evaluating the path-step and getting the neighbors of set of vertices.

func UpdateNode

func UpdateNode(ctx context.Context, drv dialect.Driver, spec *UpdateSpec) error

UpdateNode applies the UpdateSpec on one node in the graph.

func UpdateNodes

func UpdateNodes(ctx context.Context, drv dialect.Driver, spec *UpdateSpec) (int, error)

UpdateNodes applies the UpdateSpec on a set of nodes in the graph.

func WrapFunc

func WrapFunc(s func(*sql.Selector)) *fluent_ql.CallExpr

WrapFunc wraps a selector-func with an fluent_ql call expression.

Types

type BatchCreateSpec

type BatchCreateSpec struct {
	Nodes []*CreateSpec

	// The OnConflict option allows providing on-conflict
	// options to the INSERT statement.
	//
	//	sqlgraph.CreateSpec{
	//		OnConflict: []sql.ConflictOption{
	//			sql.ResolveWithNewValues(),
	//		},
	//	}
	//
	OnConflict []sql.ConflictOption
}

BatchCreateSpec holds the information for creating multiple nodes in the graph.

type ConstraintError

type ConstraintError struct {
	// contains filtered or unexported fields
}

A ConstraintError represents an error from mutation that violates a specific constraint.

func (ConstraintError) Error

func (e ConstraintError) Error() string

type CreateSpec

type CreateSpec struct {
	Table  string
	Schema string
	ID     *FieldSpec
	Fields []*FieldSpec
	Edges  []*EdgeSpec

	// The OnConflict option allows providing on-conflict
	// options to the INSERT statement.
	//
	//	sqlgraph.CreateSpec{
	//		OnConflict: []sql.ConflictOption{
	//			sql.ResolveWithNewValues(),
	//		},
	//	}
	//
	OnConflict []sql.ConflictOption
}

CreateSpec holds the information for creating a node in the graph.

func NewCreateSpec

func NewCreateSpec(table string, id *FieldSpec) *CreateSpec

NewCreateSpec creates a new node creation spec.

func (*CreateSpec) SetField

func (u *CreateSpec) SetField(column string, t field.Type, value driver.Value)

SetField appends a new field setter to the creation spec.

type DeleteSpec

type DeleteSpec struct {
	Node      *NodeSpec
	Predicate func(*sql.Selector)
}

DeleteSpec holds the information for delete one or more nodes in the graph.

func NewDeleteSpec

func NewDeleteSpec(table string, id *FieldSpec) *DeleteSpec

NewDeleteSpec creates a new node deletion spec.

type EdgeMut

type EdgeMut struct {
	Add   []*EdgeSpec
	Clear []*EdgeSpec
}

EdgeMut defines edge mutations.

type EdgeQuerySpec

type EdgeQuerySpec struct {
	Edge       *EdgeSpec
	Predicate  func(*sql.Selector)
	ScanValues func() [2]any
	Assign     func(out, in any) error
}

EdgeQuerySpec holds the information for querying edges in the graph.

type EdgeSpec

type EdgeSpec struct {
	Rel     Rel
	Inverse bool
	Table   string
	Schema  string
	Columns []string
	Bidi    bool        // bidirectional edge.
	Target  *EdgeTarget // target nodes.
}

EdgeSpec holds the information for updating a field column in the database.

type EdgeSpecs

type EdgeSpecs []*EdgeSpec

EdgeSpecs used for perform common operations on list of edges.

func (EdgeSpecs) FilterRel

func (es EdgeSpecs) FilterRel(r Rel) EdgeSpecs

FilterRel returns edges for the given relation type.

func (EdgeSpecs) GroupRel

func (es EdgeSpecs) GroupRel() map[Rel][]*EdgeSpec

GroupRel groups edges by their relation type.

func (EdgeSpecs) GroupTable

func (es EdgeSpecs) GroupTable() map[string][]*EdgeSpec

GroupTable groups edges by their table name.

type EdgeTarget

type EdgeTarget struct {
	Nodes  []driver.Value
	IDSpec *FieldSpec
	// Additional fields can be set on the
	// edge join table. Valid for M2M edges.
	Fields []*FieldSpec
}

EdgeTarget holds the information for the target nodes of an edge.

func (*EdgeTarget) FieldValues

func (e *EdgeTarget) FieldValues() []any

FieldValues returns the values of additional fields that were set on the join-table.

type FieldMut

type FieldMut struct {
	Set   []*FieldSpec // field = ?
	Add   []*FieldSpec // field = field + ?
	Clear []*FieldSpec // field = NULL
}

FieldMut defines field mutations.

type FieldSpec

type FieldSpec struct {
	Column string
	Type   field.Type
	Value  driver.Value // value to be stored.
}

FieldSpec holds the information for updating a field column in the database.

func NewFieldSpec

func NewFieldSpec(column string, typ field.Type) *FieldSpec

NewFieldSpec creates a new FieldSpec with its required fields.

type NeighborsLimit

type NeighborsLimit struct {
	// SrcCTE, LimitCTE and RowNumber hold the identifier names
	// to src query, new limited one (using window function) and
	// the column for counting rows.
	SrcCTE, LimitCTE, RowNumber string
	// DefaultOrderField sets the default ordering for
	// sub-queries in case no order terms were provided.
	DefaultOrderField string
}

NeighborsLimit provides a modifier function that limits the number of neighbors (rows) loaded per parent row (node).

func (*NeighborsLimit) Modifier

func (l *NeighborsLimit) Modifier(partitionBy string, limit int, orderBy ...sql.Querier) func(s *sql.Selector)

Modifier returns a modifier function that limits the number of rows of the eager load query.

type Node

type Node struct {
	NodeSpec

	// Type holds the node type (schema name).
	Type string

	// Fields maps from field names to their spec.
	Fields map[string]*FieldSpec

	// Edges maps from edge names to their spec.
	Edges map[string]struct {
		To   *Node
		Spec *EdgeSpec
	}
}

A Node in the graph holds the SQL information for an ent/schema.

type NodeSpec

type NodeSpec struct {
	Table       string
	Schema      string
	Columns     []string
	ID          *FieldSpec   // primary key.
	CompositeID []*FieldSpec // composite id (edge schema).
}

NodeSpec defines the information for querying and decoding nodes in the graph.

func (*NodeSpec) AddColumnOnce

func (n *NodeSpec) AddColumnOnce(column string) *NodeSpec

AddColumnOnce adds the given column to the spec if it is not already present.

type NotFoundError

type NotFoundError struct {
	// contains filtered or unexported fields
}

NotFoundError returns when trying to update an entity, and it was not found in the database.

func (*NotFoundError) Error

func (e *NotFoundError) Error() string

type QuerySpec

type QuerySpec struct {
	Node *NodeSpec     // Nodes info.
	From *sql.Selector // Optional query source (from path).

	Limit     int
	Offset    int
	Unique    bool
	Order     func(*sql.Selector)
	Predicate func(*sql.Selector)
	Modifiers []func(*sql.Selector)

	ScanValues func(columns []string) ([]any, error)
	Assign     func(columns []string, values []any) error
}

QuerySpec holds the information for querying nodes in the graph.

func NewQuerySpec

func NewQuerySpec(table string, columns []string, id *FieldSpec) *QuerySpec

NewQuerySpec creates a new node query spec.

type Rel

type Rel int

Rel is an edge relation type.

const (
	O2O Rel // One to one / has one.
	O2M     // One to many / has many.
	M2O     // Many to one (inverse perspective for O2M).
	M2M     // Many to many.
)

Relation types.

func (Rel) String

func (r Rel) String() (s string)

String returns the relation name.

type Schema

type Schema struct {
	Nodes []*Node
}

A Schema holds a representation of ent/schema at runtime. Each Node represents a single schema-type and its relations in the graph (storage).

It is used for translating common graph traversal operations to the underlying SQL storage. For example, an operation like `has_edge(E)`, will be translated to an SQL lookup based on the relation type and the FK configuration.

func (*Schema) AddE

func (g *Schema) AddE(name string, spec *EdgeSpec, from, to string) error

AddE adds an edge to the graph. It fails, if one of the node types is missing.

g.AddE("pets", spec, "user", "pet")
g.AddE("friends", spec, "user", "user")

func (*Schema) EvalP

func (g *Schema) EvalP(nodeType string, p fluent_ql.P, selector *sql.Selector) error

EvalP evaluates the fluent_ql predicate on the given selector (query builder).

func (*Schema) MustAddE

func (g *Schema) MustAddE(name string, spec *EdgeSpec, from, to string)

MustAddE is like AddE but panics if the edge can be added to the graph.

type Step

type Step struct {
	// From is the source of the step.
	From struct {
		// V can be either one vertex or set of vertices.
		// It can be a pre-processed step (sql.Query) or a simple Go type (integer or string).
		V any
		// Table holds the table name of V (from).
		Table string
		// Column to join with. Usually the "id" column.
		Column string
	}
	// Edge holds the edge information for getting the neighbors.
	Edge struct {
		// Rel of the edge.
		Rel Rel
		// Schema is an optional name of the database
		// where the table is defined.
		Schema string
		// Table name of where this edge columns reside.
		Table string
		// Columns of the edge.
		// In O2O and M2O, it holds the foreign-key column. Hence, len == 1.
		// In M2M, it holds the primary-key columns of the join table. Hence, len == 2.
		Columns []string
		// Inverse indicates if the edge is an inverse edge.
		Inverse bool
	}
	// To is the dest of the path (the neighbors).
	To struct {
		// Table holds the table name of the neighbors (to).
		Table string
		// Schema is an optional name of the database
		// where the table is defined.
		Schema string
		// Column to join with. Usually the "id" column.
		Column string
	}
}

A Step provides a path-step information to the traversal functions.

func NewStep

func NewStep(opts ...StepOption) *Step

NewStep gets list of options and returns a configured step.

NewStep(
	From("table", "pk", V),
	To("table", "pk"),
	Edge("name", O2M, "fk"),
)

func (*Step) FromEdgeOwner

func (s *Step) FromEdgeOwner() bool

FromEdgeOwner returns true if the step is from an edge owner. i.e., from the table that holds the foreign-key.

func (*Step) ThroughEdgeTable

func (s *Step) ThroughEdgeTable() bool

ThroughEdgeTable returns true if the step is through a join-table.

func (*Step) ToEdgeOwner

func (s *Step) ToEdgeOwner() bool

ToEdgeOwner returns true if the step is to an edge owner. i.e., to the table that holds the foreign-key.

type StepOption

type StepOption func(*Step)

StepOption allows configuring Steps using functional options.

func Edge

func Edge(rel Rel, inverse bool, table string, columns ...string) StepOption

Edge sets the edge info for getting the neighbors.

func From

func From(table, column string, v ...any) StepOption

From sets the source of the step.

func To

func To(table, column string) StepOption

To sets the destination of the step.

type UpdateSpec

type UpdateSpec struct {
	Node      *NodeSpec
	Edges     EdgeMut
	Fields    FieldMut
	Predicate func(*sql.Selector)
	Modifiers []func(*sql.UpdateBuilder)

	ScanValues func(columns []string) ([]any, error)
	Assign     func(columns []string, values []any) error
}

UpdateSpec holds the information for updating one or more nodes in the graph.

func NewUpdateSpec

func NewUpdateSpec(table string, columns []string, id ...*FieldSpec) *UpdateSpec

NewUpdateSpec creates a new node update spec.

func (*UpdateSpec) AddField

func (u *UpdateSpec) AddField(column string, t field.Type, value driver.Value)

AddField appends a new field adder to the update spec.

func (*UpdateSpec) AddModifier

func (u *UpdateSpec) AddModifier(m func(*sql.UpdateBuilder))

AddModifier adds a new statement modifier to the spec.

func (*UpdateSpec) AddModifiers

func (u *UpdateSpec) AddModifiers(m ...func(*sql.UpdateBuilder))

AddModifiers adds a list of statement modifiers to the spec.

func (*UpdateSpec) ClearField

func (u *UpdateSpec) ClearField(column string, t field.Type)

ClearField appends a new field cleaner (set to NULL) to the update spec.

func (*UpdateSpec) SetField

func (u *UpdateSpec) SetField(column string, t field.Type, value driver.Value)

SetField appends a new field setter to the update spec.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL