Skip to content

JMESPath Functions

Built-in JMESPath Functions to easily deserialize common encoded JSON payloads in Lambda functions.

Usage Documentation

JMESPath Functions

FUNCTION DESCRIPTION
extract_data_from_envelope

Searches and extracts data using JMESPath
query

Searches and extracts data using JMESPath

extract_data_from_envelope 

extract_data_from_envelope(
    data: dict | str,
    envelope: str,
    jmespath_options: dict | None = None,
) -> Any

Searches and extracts data using JMESPath

Deprecated: Use query instead

Source code in aws_lambda_powertools/utilities/jmespath_utils/__init__.py 
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
@deprecated("`extract_data_from_envelope` is deprecated; use `query` instead.", category=None)
def extract_data_from_envelope(data: dict | str, envelope: str, jmespath_options: dict | None = None) -> Any:
    """Searches and extracts data using JMESPath

    *Deprecated*: Use query instead
    """
    warnings.warn(
        "The extract_data_from_envelope method is deprecated in V3 "
        "and will be removed in the next major version. Use query instead.",
        category=PowertoolsDeprecationWarning,
        stacklevel=2,
    )

    return query(data=data, envelope=envelope, jmespath_options=jmespath_options)

query 

query(
    data: dict | str,
    envelope: str,
    jmespath_options: dict | None = None,
) -> Any

Searches and extracts data using JMESPath

Envelope being the JMESPath expression to extract the data you're after

Built-in JMESPath functions include: powertools_json, powertools_base64, powertools_base64_gzip

Example

Deserialize JSON string and extracts data from body key

1
2
3
4
5
6
7
8
9
from aws_lambda_powertools.utilities.jmespath_utils import query
from aws_lambda_powertools.utilities.typing import LambdaContext


def handler(event: dict, context: LambdaContext):
    # event = {"body": "{"customerId":"dd4649e6-2484-4993-acb8-0f9123103394"}"}  # noqa: ERA001
    payload = query(data=event, envelope="powertools_json(body)")
    customer = payload.get("customerId")  # now deserialized
    ...
PARAMETER DESCRIPTION
data

Data set to be filtered

TYPE: dict | str

envelope

JMESPath expression to filter data against

TYPE: str

jmespath_options

Alternative JMESPath options to be included when filtering expr

TYPE: dict | None DEFAULT: None

RETURNS DESCRIPTION
Any

Data found using JMESPath expression given in envelope
Source code in aws_lambda_powertools/utilities/jmespath_utils/__init__.py 
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
def query(data: dict | str, envelope: str, jmespath_options: dict | None = None) -> Any:
    """Searches and extracts data using JMESPath

    Envelope being the JMESPath expression to extract the data you're after

    Built-in JMESPath functions include: powertools_json, powertools_base64, powertools_base64_gzip

    Example
    --------

    **Deserialize JSON string and extracts data from body key**

        from aws_lambda_powertools.utilities.jmespath_utils import query
        from aws_lambda_powertools.utilities.typing import LambdaContext


        def handler(event: dict, context: LambdaContext):
            # event = {"body": "{\"customerId\":\"dd4649e6-2484-4993-acb8-0f9123103394\"}"}  # noqa: ERA001
            payload = query(data=event, envelope="powertools_json(body)")
            customer = payload.get("customerId")  # now deserialized
            ...

    Parameters
    ----------
    data : dict | str
        Data set to be filtered
    envelope : str
        JMESPath expression to filter data against
    jmespath_options : dict | None
        Alternative JMESPath options to be included when filtering expr


    Returns
    -------
    Any
        Data found using JMESPath expression given in envelope
    """
    if not jmespath_options:
        jmespath_options = {"custom_functions": PowertoolsFunctions()}

    try:
        logger.debug(f"Envelope detected: {envelope}. JMESPath options: {jmespath_options}")
        return jmespath.search(envelope, data, options=jmespath.Options(**jmespath_options))
    except (LexerError, TypeError, UnicodeError) as e:
        message = f"Failed to unwrap event from envelope using expression. Error: {e} Exp: {envelope}, Data: {data}"  # noqa: B306, E501
        raise InvalidEnvelopeExpressionError(message)