exec

Documentation

Overview

Package exec provides the routines for SQL/JSON path execution.

Index

• Variables
• func Exists(ctx context.Context, path *ast.AST, value any, opt ...Option) (bool, error)
• func First(ctx context.Context, path *ast.AST, value any, opt ...Option) (any, error)
• func Match(ctx context.Context, path *ast.AST, value any, opt ...Option) (bool, error)
• func Query(ctx context.Context, path *ast.AST, value any, opt ...Option) ([]any, error)
• type Executor
• type Option
  • func WithSilent() Option
  • func WithTZ() Option
  • func WithVars(vars Vars) Option
• type Vars

Variables

var (
	// ErrExecution errors denote runtime execution errors.
	ErrExecution = errors.New("exec")

	// ErrVerbose errors are execution errors that can be suppressed by
	// [WithSilent].
	ErrVerbose = fmt.Errorf("%w", ErrExecution)

	// ErrInvalid errors denote invalid or unexpected execution. Generally
	// internal-only.
	ErrInvalid = errors.New("exec invalid")
)

var (
	// NULL is returned when Postgres would return NULL from Match and Exists.
	NULL = errors.New("NULL")
)

Functions

func Exists

func Exists(ctx context.Context, path *ast.AST, value any, opt ...Option) (bool, error)

Exists checks whether the JSON path returns any item for the specified JSON value. (This is useful only with SQL-standard JSON path expressions, not predicate check expressions, since those always return a value.) If the WithVars Option is specified its fields provide named values to be substituted into the jsonpath expression. If the WithSilent Option is specified, the function suppresses some errors. If the WithTZ Option is specified, it allows comparisons of date/time values that require timezone-aware conversions. The example below requires interpretation of the date-only value 2015-08-02 as a timestamp with time zone, so the result depends on the current TimeZone setting:

Exists(
	[]any{"2015-08-01 12:00:00-05"},
	`$[*] ? (@.datetime() < "2015-08-02".datetime())`,
	WithTZ(),
) → true

func First

func First(ctx context.Context, path *ast.AST, value any, opt ...Option) (any, error)

First returns the first JSON item returned by the JSON path for the specified JSON value, or nil if there are no results. The parameters are the same as for Query.

func Match

func Match(ctx context.Context, path *ast.AST, value any, opt ...Option) (bool, error)

Match returns the result of a JSON path predicate check for the specified JSON value. (This is useful only with predicate check expressions, not SQL-standard JSON path expressions, since it will either fail or return NULL if the path result is not a single boolean value.) The optional WithVars and WithSilent Options act the same as for Exists.

func Query

func Query(ctx context.Context, path *ast.AST, value any, opt ...Option) ([]any, error)

Query returns all JSON items returned by the JSON path for the specified JSON value. For SQL-standard JSON path expressions it returns the JSON values selected from target. For predicate check expressions it returns the result of the predicate check: true, false, or null (false + ErrNull). The optional WithVars and WithSilent Options act the same as for Exists.

Types

type Executor

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

Executor represents the context for jsonpath execution.

type Option

type Option func(*Executor)

Option specifies an execution option.

func WithSilent

func WithSilent() Option

WithSilent suppresses the following errors: missing object field or array element, unexpected JSON item type, datetime and numeric errors. This behavior emulates the behavior of the PostgreSQL @? and @@ operators, and might be helpful when searching JSON document collections of varying structure.

func WithTZ

func WithTZ() Option

WithTZ allows casting between TZ and non-TZ time and timestamp types.

func WithVars

func WithVars(vars Vars) Option

WithVars specifies variables to use during execution.

type Vars

type Vars map[string]any

Vars represents JSON path variables and their values.