Documentation
¶
Overview ¶
Package funcs implements the built-in Cypher function registry.
Registry ¶
DefaultRegistry is the pre-populated registry containing all essential built-ins. It implements expr.FunctionRegistry and is safe for concurrent use after construction.
Implementing built-ins ¶
Each function follows the expr.BuiltinFn signature:
func(args []expr.Value) (expr.Value, error)
Type errors are returned as typed TypeError values rather than propagated as Go errors, unless the error is truly fatal (impossible with well-formed arguments). NULL arguments propagate according to each function's documented NULL-handling behaviour.
Concurrency ¶
The registry is immutable after NewRegistry returns; all exported symbols are safe for concurrent use.
Index ¶
- Variables
- func ClearStatementNow()
- func SetStatementNow(t time.Time)
- func StatementNow() time.Time
- type Aggregator
- type AggregatorFactory
- func NewAvgAgg() AggregatorFactory
- func NewCollectAgg() AggregatorFactory
- func NewCountAgg() AggregatorFactory
- func NewCountStarAgg() AggregatorFactory
- func NewMaxAgg() AggregatorFactory
- func NewMinAgg() AggregatorFactory
- func NewPercentileContAgg(p float64) AggregatorFactory
- func NewPercentileDiscAgg(p float64) AggregatorFactory
- func NewStdDevAgg() AggregatorFactory
- func NewStdDevPAgg() AggregatorFactory
- func NewSumAgg() AggregatorFactory
- type ArityError
- type AvgAgg
- type CollectAgg
- type CountAgg
- type CountStarAgg
- type MaxAgg
- type MinAgg
- type PercentileContAgg
- type PercentileDiscAgg
- type Registry
- type StdDevAgg
- type StdDevPAgg
- type SumAgg
- type TypeError
Examples ¶
Constants ¶
This section is empty.
Variables ¶
var DefaultRegistry = buildDefaultRegistry()
DefaultRegistry is the pre-populated registry containing all essential built-ins. It is safe for concurrent use.
Functions ¶
func ClearStatementNow ¶
func ClearStatementNow()
ClearStatementNow removes the frozen "now" so subsequent calls to StatementNow fall back to time.Now().
func SetStatementNow ¶
SetStatementNow installs t as the statement-frozen "now" for every subsequent temporal "now" constructor in this process until ClearStatementNow is called.
func StatementNow ¶
StatementNow returns the statement-frozen instant when one has been installed via SetStatementNow, otherwise time.Now().UTC(). The temporal "now" constructors call this in place of time.Now() so repeated calls within the same statement observe the same instant.
Types ¶
type Aggregator ¶
type Aggregator interface {
// Init resets the aggregator to its initial (empty) state. Called once per
// group before any Step calls for that group.
Init()
// Step incorporates a single input value into the running accumulation.
// NULL handling is defined per aggregator (most skip NULLs).
Step(v expr.Value)
// Result returns the final aggregated value for the group. It must be called
// exactly once after all Step calls for the group, and before any reuse.
Result() expr.Value
}
Aggregator accumulates values from a single aggregate column across multiple input rows within one group.
Lifecycle: Init → Step (once per row) → Result (once per group).
Aggregator is NOT safe for concurrent use.
type AggregatorFactory ¶
type AggregatorFactory func() Aggregator
AggregatorFactory is a zero-argument constructor that returns a new, initialised Aggregator. EagerAggregation holds one factory per aggregate expression and calls it once per group.
func NewAvgAgg ¶
func NewAvgAgg() AggregatorFactory
NewAvgAgg returns an AggregatorFactory for AvgAgg.
func NewCollectAgg ¶
func NewCollectAgg() AggregatorFactory
NewCollectAgg returns an AggregatorFactory for CollectAgg.
func NewCountAgg ¶
func NewCountAgg() AggregatorFactory
NewCountAgg returns an AggregatorFactory for CountAgg.
func NewCountStarAgg ¶
func NewCountStarAgg() AggregatorFactory
NewCountStarAgg returns an AggregatorFactory for CountStarAgg.
func NewMaxAgg ¶
func NewMaxAgg() AggregatorFactory
NewMaxAgg returns an AggregatorFactory for MaxAgg.
func NewMinAgg ¶
func NewMinAgg() AggregatorFactory
NewMinAgg returns an AggregatorFactory for MinAgg.
func NewPercentileContAgg ¶
func NewPercentileContAgg(p float64) AggregatorFactory
NewPercentileContAgg returns an AggregatorFactory for PercentileContAgg with the given percentile p (in [0.0, 1.0]).
func NewPercentileDiscAgg ¶
func NewPercentileDiscAgg(p float64) AggregatorFactory
NewPercentileDiscAgg returns an AggregatorFactory for PercentileDiscAgg with the given percentile p (in [0.0, 1.0]).
func NewStdDevAgg ¶
func NewStdDevAgg() AggregatorFactory
NewStdDevAgg returns an AggregatorFactory for StdDevAgg.
func NewStdDevPAgg ¶
func NewStdDevPAgg() AggregatorFactory
NewStdDevPAgg returns an AggregatorFactory for StdDevPAgg.
func NewSumAgg ¶
func NewSumAgg() AggregatorFactory
NewSumAgg returns an AggregatorFactory for SumAgg.
type ArityError ¶
type ArityError struct {
// Function is the name of the function.
Function string
// Got is the number of arguments received.
Got int
// Want is a human-readable description of the expected argument count.
Want string
}
ArityError is returned when a built-in receives an unexpected number of arguments.
func (*ArityError) Error ¶
func (e *ArityError) Error() string
Error implements the error interface.
type AvgAgg ¶
type AvgAgg struct {
// contains filtered or unexported fields
}
AvgAgg computes the arithmetic mean of numeric inputs, skipping NULLs.
AvgAgg is NOT safe for concurrent use.
type CollectAgg ¶
type CollectAgg struct {
// contains filtered or unexported fields
}
CollectAgg collects non-NULL values into an ordered expr.ListValue.
CollectAgg is NOT safe for concurrent use.
func (*CollectAgg) Result ¶
func (a *CollectAgg) Result() expr.Value
Result returns a expr.ListValue containing all accumulated non-NULL values, or an empty list if none were collected.
func (*CollectAgg) Step ¶
func (a *CollectAgg) Step(v expr.Value)
Step appends v to the collection if it is non-NULL.
type CountAgg ¶
type CountAgg struct {
// contains filtered or unexported fields
}
CountAgg counts non-NULL input values. Corresponds to count(expr).
CountAgg is NOT safe for concurrent use.
type CountStarAgg ¶
type CountStarAgg struct {
// contains filtered or unexported fields
}
CountStarAgg counts every input row regardless of NULLs. Corresponds to count(*).
CountStarAgg is NOT safe for concurrent use.
func (*CountStarAgg) Result ¶
func (a *CountStarAgg) Result() expr.Value
Result returns the count as an IntegerValue.
func (*CountStarAgg) Step ¶
func (a *CountStarAgg) Step(_ expr.Value)
Step increments the counter unconditionally.
type MaxAgg ¶
type MaxAgg struct {
// contains filtered or unexported fields
}
MaxAgg accumulates the maximum value across all non-NULL inputs using the openCypher total ordering defined by expr.Compare.
MaxAgg is NOT safe for concurrent use.
type MinAgg ¶
type MinAgg struct {
// contains filtered or unexported fields
}
MinAgg accumulates the minimum value across all non-NULL inputs using the openCypher total ordering defined by expr.Compare.
MinAgg is NOT safe for concurrent use.
type PercentileContAgg ¶
type PercentileContAgg struct {
// contains filtered or unexported fields
}
PercentileContAgg computes a percentile by linear interpolation (ANSI SQL PERCENTILE_CONT semantics). p must be in [0.0, 1.0]; it is clamped to that range. NULLs and non-numeric values are skipped.
Returns NULL if no non-NULL values were accumulated.
PercentileContAgg is NOT safe for concurrent use.
func (*PercentileContAgg) Init ¶
func (a *PercentileContAgg) Init()
Init resets the accumulated values.
func (*PercentileContAgg) Result ¶
func (a *PercentileContAgg) Result() expr.Value
Result sorts the values and applies linear interpolation. Returns NULL if the list is empty.
func (*PercentileContAgg) Step ¶
func (a *PercentileContAgg) Step(v expr.Value)
Step appends v to the list, skipping NULLs and non-numerics.
type PercentileDiscAgg ¶
type PercentileDiscAgg struct {
// contains filtered or unexported fields
}
PercentileDiscAgg computes a percentile by choosing the nearest discrete value in the sorted set (ANSI SQL PERCENTILE_DISC semantics). p must be in [0.0, 1.0]; it is clamped to that range. NULLs and non-numeric values are skipped.
Returns NULL if no non-NULL values were accumulated.
PercentileDiscAgg is NOT safe for concurrent use.
func (*PercentileDiscAgg) Init ¶
func (a *PercentileDiscAgg) Init()
Init resets the accumulated values.
func (*PercentileDiscAgg) Result ¶
func (a *PercentileDiscAgg) Result() expr.Value
Result sorts the values and picks the element at the floor of p*(n-1). Returns NULL if the list is empty. When every input was IntegerValue, the result is also IntegerValue (PERCENTILE_DISC preserves the representation of the chosen element).
func (*PercentileDiscAgg) Step ¶
func (a *PercentileDiscAgg) Step(v expr.Value)
Step appends v to the list, skipping NULLs and non-numerics.
type Registry ¶
type Registry struct {
// contains filtered or unexported fields
}
Registry maps lower-cased function names to their implementations. It is immutable after NewRegistry returns; safe for concurrent reads.
func NewRegistry ¶
func NewRegistry() *Registry
NewRegistry creates an empty registry. Use DefaultRegistry to obtain the pre-populated built-in registry.
func (*Registry) Register ¶
Register adds fn under the given name (stored lower-cased). Panics on duplicate; this is a programming error, not a runtime condition.
func (*Registry) Resolve ¶
Resolve implements expr.FunctionRegistry.
Example ¶
ExampleRegistry_Resolve resolves the built-in toUpper from DefaultRegistry and invokes it. Lookup is case-insensitive: names are lower-cased before resolution, so "toUpper" and "toupper" reach the same implementation.
package main
import (
"fmt"
"github.com/FlavioCFOliveira/GoGraph/cypher/expr"
"github.com/FlavioCFOliveira/GoGraph/cypher/funcs"
)
func main() {
fn, ok := funcs.DefaultRegistry.Resolve("toupper")
if !ok {
fmt.Println("toupper not registered")
return
}
out, err := fn([]expr.Value{expr.StringValue("hello")})
if err != nil {
fmt.Println("error:", err)
return
}
// out is a StringValue; print its raw text rather than the quoted String().
fmt.Println(string(out.(expr.StringValue)))
}
Output: HELLO
Example (Unknown) ¶
ExampleRegistry_Resolve_unknown shows the not-found path: Resolve reports false for a name that is not registered.
package main
import (
"fmt"
"github.com/FlavioCFOliveira/GoGraph/cypher/funcs"
)
func main() {
_, ok := funcs.DefaultRegistry.Resolve("no_such_function")
fmt.Println("found:", ok)
}
Output: found: false
type StdDevAgg ¶
type StdDevAgg struct {
// contains filtered or unexported fields
}
StdDevAgg computes the sample standard deviation using Welford's numerically stable online algorithm. NULLs and non-numeric values are skipped.
Returns NULL if fewer than 2 non-NULL values were accumulated (sample std dev of a single value is undefined). Returns 0.0 for exactly 2 identical values.
StdDevAgg is NOT safe for concurrent use.
type StdDevPAgg ¶
type StdDevPAgg struct {
// contains filtered or unexported fields
}
StdDevPAgg computes the population standard deviation using Welford's numerically stable online algorithm. NULLs and non-numeric values are skipped. Returns NULL if no non-NULL values were accumulated.
StdDevPAgg is NOT safe for concurrent use.
func (*StdDevPAgg) Result ¶
func (a *StdDevPAgg) Result() expr.Value
Result returns NULL if n == 0, otherwise FloatValue(sqrt(M2/n)).
func (*StdDevPAgg) Step ¶
func (a *StdDevPAgg) Step(v expr.Value)
Step incorporates v via Welford's online update, skipping NULLs.
type SumAgg ¶
type SumAgg struct {
// contains filtered or unexported fields
}
SumAgg accumulates a numeric sum. Integer-only inputs produce an integer result; any float input causes the result to be a float.
SumAgg is NOT safe for concurrent use.
type TypeError ¶
type TypeError struct {
// Function is the name of the function that encountered the type error.
Function string
// ArgIndex is the 0-based index of the offending argument.
ArgIndex int
// Got is the kind of the offending argument.
Got expr.Kind
// Want is a human-readable description of the expected type.
Want string
}
TypeError is returned by built-in functions when an argument has the wrong type for the operation requested.
Source Files