jmespath

Documentation

Overview

Package jmespath queries JSON-shaped values and typed Lambda events.

Search evaluates a query once; Compile prepares an immutable Expression for reuse across invocations. Typed inputs are normalized using JSON field tags, and JSON numbers are represented as float64.

Functions and failures

Standard JMESPath functions are enabled by default. Opt in to JSON, Base64 and gzip decoding with WithPowertoolsFunctions. Custom functions must be safe for concurrent calls and must not mutate or retain input values.

Error identifies syntax, function and value failures without requiring callers to parse engine messages. PurgeCache removes cached syntax trees without invalidating expressions that have already been compiled.

For usage and compatibility details, see the user guide.

Index

• Constants
• func ExtractDataFromEnvelope(data any, envelope string, options ...Option) (any, error)
• func PurgeCache()
• func Search(source string, data any, options ...Option) (any, error)
• type Argument
• type Error
  • func (e *Error) Error() string
  • func (e *Error) Unwrap() error
• type ErrorKind
• type Expression
  • func Compile(source string, options ...Option) (*Expression, error)
  • func MustCompile(source string, options ...Option) *Expression
  • func (e *Expression) Search(data any) (any, error)
• type ExpressionReference
• type Function
• type Option
  • func WithFunctions(functions ...Function) Option
  • func WithPowertoolsFunctions() Option
• type Type

Examples

• Compile

Constants

const (
	APIGatewayREST            = "powertools_json(body)"
	APIGatewayHTTP            = "powertools_json(body)"
	SQS                       = "Records[*].powertools_json(body)"
	SNS                       = "Records[0].Sns.Message | powertools_json(@)"
	EventBridge               = "detail"
	CloudWatchEventsScheduled = "detail"
	KinesisDataStream         = "Records[*].kinesis.powertools_json(powertools_base64(data))"
	CloudWatchLogs            = "awslogs.powertools_base64_gzip(data) | powertools_json(@).logEvents[*]"
	S3SNSSQS                  = "Records[*].powertools_json(body).powertools_json(Message).Records[0]"
	S3SQS                     = "Records[*].powertools_json(body).Records[0]"
	S3SNSKinesisFirehose      = "records[*].powertools_json(powertools_base64(data)).powertools_json(Message).Records[0]"
	S3KinesisFirehose         = "records[*].powertools_json(powertools_base64(data)).Records[0]"
	S3EventBridgeSQS          = "Records[*].powertools_json(body).detail"
)

Built-in envelopes match all thirteen constants in TypeScript v2.35.0.

Functions

func ExtractDataFromEnvelope

func ExtractDataFromEnvelope(data any, envelope string, options ...Option) (any, error)

ExtractDataFromEnvelope enables Powertools functions when options are omitted. Explicit options replace that default, following the reference helper.

func PurgeCache

func PurgeCache()

PurgeCache removes cached syntax trees; already compiled expressions remain valid.

func Search

func Search(source string, data any, options ...Option) (any, error)

Types

type Argument

type Argument struct {
	Types    []Type
	Variadic bool
}

Argument accepts any listed type. Only the final argument may be variadic.

type Error

type Error struct {
	Kind       ErrorKind
	Expression string
	Function   string
	Err        error
}

Error preserves expression context and the original failure through Unwrap.

func (*Error) Error

func (e *Error) Error() string

func (*Error) Unwrap

func (e *Error) Unwrap() error

type ErrorKind

type ErrorKind string

ErrorKind classifies failures without relying on engine error text.

const (
	EmptyExpression ErrorKind = "empty-expression"
	SyntaxError     ErrorKind = "syntax"
	UnknownFunction ErrorKind = "unknown-function"
	InvalidArity    ErrorKind = "invalid-arity"
	InvalidType     ErrorKind = "invalid-type"
	InvalidValue    ErrorKind = "invalid-value"
)

type Expression

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

Expression is immutable and reusable across goroutines. Custom functions must be concurrency-safe and must not mutate or retain their input values.

func Compile

func Compile(source string, options ...Option) (*Expression, error)

Compile prepares an expression. Standard functions are enabled by default; use WithPowertoolsFunctions for JSON, Base64 and gzip decoding.

Example

package main

import (
	"fmt"

	"github.com/rambow-cloud/powertools-lambda-go/jmespath"
)

func main() {
	expression, err := jmespath.Compile("detail.orderId")
	if err != nil {
		panic(err)
	}
	value, err := expression.Search(map[string]any{
		"detail": map[string]any{"orderId": "order-123"},
	})
	fmt.Println(value, err)
}

Output:
order-123 <nil>

func MustCompile

func MustCompile(source string, options ...Option) *Expression

func (*Expression) Search

func (e *Expression) Search(data any) (any, error)

Search accepts JSON-shaped values and typed Go events with JSON field tags. Data is normalized to a private JSON snapshot; numbers use float64 as in JS.

type ExpressionReference

type ExpressionReference = engine.ExpRef

type Function

type Function struct {
	Name      string
	Arguments []Argument
	Handler   func([]any) (any, error)
}

type Option

type Option func(functionTable) error

func WithFunctions

func WithFunctions(functions ...Function) Option

WithFunctions snapshots definitions and allows overriding built-in functions.

func WithPowertoolsFunctions

func WithPowertoolsFunctions() Option

WithPowertoolsFunctions enables the reference JSON, Base64 and gzip functions. Gzip inputs are fully buffered, matching the reference; bound untrusted inputs at the application boundary. Base64 uses Commons validation before decoding.

type Type

type Type = engine.JpType

const (
	Number      Type = engine.JpNumber
	String      Type = engine.JpString
	Array       Type = engine.JpArray
	Object      Type = engine.JpObject
	ArrayNumber Type = engine.JpArrayNumber
	ArrayString Type = engine.JpArrayString
	Expref      Type = engine.JpExpref
	Any         Type = engine.JpAny
	Boolean     Type = "boolean"
	Null        Type = "null"
)