jsonpath.h

Go to the documentation of this file.

/*-------------------------------------------------------------------------
 *
 * jsonpath.h
 *  Definitions for jsonpath datatype
 *
 * Copyright (c) 2019-2025, PostgreSQL Global Development Group
 *
 * IDENTIFICATION
 *  src/include/utils/jsonpath.h
 *
 *-------------------------------------------------------------------------
 */
 
#ifndef JSONPATH_H
#define JSONPATH_H
 
#include "executor/tablefunc.h"
#include "fmgr.h"
#include "nodes/pg_list.h"
#include "nodes/primnodes.h"
#include "utils/jsonb.h"
 
typedef struct
{
    int32       vl_len_;        /* varlena header (do not touch directly!) */
    uint32      header;         /* version and flags (see below) */
    char        data[FLEXIBLE_ARRAY_MEMBER];
} JsonPath;
 
#define JSONPATH_VERSION    (0x01)
#define JSONPATH_LAX        (0x80000000)
#define JSONPATH_HDRSZ      (offsetof(JsonPath, data))
 
static inline JsonPath *
DatumGetJsonPathP(Datum d)
{
    return (JsonPath *) PG_DETOAST_DATUM(d);
}
 
static inline JsonPath *
DatumGetJsonPathPCopy(Datum d)
{
    return (JsonPath *) PG_DETOAST_DATUM_COPY(d);
}
 
#define PG_GETARG_JSONPATH_P(x)         DatumGetJsonPathP(PG_GETARG_DATUM(x))
#define PG_GETARG_JSONPATH_P_COPY(x)    DatumGetJsonPathPCopy(PG_GETARG_DATUM(x))
#define PG_RETURN_JSONPATH_P(p)         PG_RETURN_POINTER(p)
 
#define jspIsScalar(type) ((type) >= jpiNull && (type) <= jpiBool)
 
/*
 * All node's type of jsonpath expression
 *
 * These become part of the on-disk representation of the jsonpath type.
 * Therefore, to preserve pg_upgradability, the order must not be changed, and
 * new values must be added at the end.
 *
 * It is recommended that switch cases etc. in other parts of the code also
 * use this order, to maintain some consistency.
 */
typedef enum JsonPathItemType
{
    jpiNull = jbvNull,          /* NULL literal */
    jpiString = jbvString,      /* string literal */
    jpiNumeric = jbvNumeric,    /* numeric literal */
    jpiBool = jbvBool,          /* boolean literal: TRUE or FALSE */
    jpiAnd,                     /* predicate && predicate */
    jpiOr,                      /* predicate || predicate */
    jpiNot,                     /* ! predicate */
    jpiIsUnknown,               /* (predicate) IS UNKNOWN */
    jpiEqual,                   /* expr == expr */
    jpiNotEqual,                /* expr != expr */
    jpiLess,                    /* expr < expr */
    jpiGreater,                 /* expr > expr */
    jpiLessOrEqual,             /* expr <= expr */
    jpiGreaterOrEqual,          /* expr >= expr */
    jpiAdd,                     /* expr + expr */
    jpiSub,                     /* expr - expr */
    jpiMul,                     /* expr * expr */
    jpiDiv,                     /* expr / expr */
    jpiMod,                     /* expr % expr */
    jpiPlus,                    /* + expr */
    jpiMinus,                   /* - expr */
    jpiAnyArray,                /* [*] */
    jpiAnyKey,                  /* .* */
    jpiIndexArray,              /* [subscript, ...] */
    jpiAny,                     /* .** */
    jpiKey,                     /* .key */
    jpiCurrent,                 /* @ */
    jpiRoot,                    /* $ */
    jpiVariable,                /* $variable */
    jpiFilter,                  /* ? (predicate) */
    jpiExists,                  /* EXISTS (expr) predicate */
    jpiType,                    /* .type() item method */
    jpiSize,                    /* .size() item method */
    jpiAbs,                     /* .abs() item method */
    jpiFloor,                   /* .floor() item method */
    jpiCeiling,                 /* .ceiling() item method */
    jpiDouble,                  /* .double() item method */
    jpiDatetime,                /* .datetime() item method */
    jpiKeyValue,                /* .keyvalue() item method */
    jpiSubscript,               /* array subscript: 'expr' or 'expr TO expr' */
    jpiLast,                    /* LAST array subscript */
    jpiStartsWith,              /* STARTS WITH predicate */
    jpiLikeRegex,               /* LIKE_REGEX predicate */
    jpiBigint,                  /* .bigint() item method */
    jpiBoolean,                 /* .boolean() item method */
    jpiDate,                    /* .date() item method */
    jpiDecimal,                 /* .decimal() item method */
    jpiInteger,                 /* .integer() item method */
    jpiNumber,                  /* .number() item method */
    jpiStringFunc,              /* .string() item method */
    jpiTime,                    /* .time() item method */
    jpiTimeTz,                  /* .time_tz() item method */
    jpiTimestamp,               /* .timestamp() item method */
    jpiTimestampTz,             /* .timestamp_tz() item method */
} JsonPathItemType;
 
/* XQuery regex mode flags for LIKE_REGEX predicate */
#define JSP_REGEX_ICASE     0x01    /* i flag, case insensitive */
#define JSP_REGEX_DOTALL    0x02    /* s flag, dot matches newline */
#define JSP_REGEX_MLINE     0x04    /* m flag, ^/$ match at newlines */
#define JSP_REGEX_WSPACE    0x08    /* x flag, ignore whitespace in pattern */
#define JSP_REGEX_QUOTE     0x10    /* q flag, no special characters */
 
/*
 * Support functions to parse/construct binary value.
 * Unlike many other representation of expression the first/main
 * node is not an operation but left operand of expression. That
 * allows to implement cheap follow-path descending in jsonb
 * structure and then execute operator with right operand
 */
 
typedef struct JsonPathItem
{
    JsonPathItemType type;
 
    /* position form base to next node */
    int32       nextPos;
 
    /*
     * pointer into JsonPath value to current node, all positions of current
     * are relative to this base
     */
    char       *base;
 
    union
    {
        /* classic operator with two operands: and, or etc */
        struct
        {
            int32       left;
            int32       right;
        }           args;
 
        /* any unary operation */
        int32       arg;
 
        /* storage for jpiIndexArray: indexes of array */
        struct
        {
            int32       nelems;
            struct
            {
                int32       from;
                int32       to;
            }          *elems;
        }           array;
 
        /* jpiAny: levels */
        struct
        {
            uint32      first;
            uint32      last;
        }           anybounds;
 
        struct
        {
            char       *data;   /* for bool, numeric and string/key */
            int32       datalen;    /* filled only for string/key */
        }           value;
 
        struct
        {
            int32       expr;
            char       *pattern;
            int32       patternlen;
            uint32      flags;
        }           like_regex;
    }           content;
} JsonPathItem;
 
#define jspHasNext(jsp) ((jsp)->nextPos > 0)
 
extern void jspInit(JsonPathItem *v, JsonPath *js);
extern void jspInitByBuffer(JsonPathItem *v, char *base, int32 pos);
extern bool jspGetNext(JsonPathItem *v, JsonPathItem *a);
extern void jspGetArg(JsonPathItem *v, JsonPathItem *a);
extern void jspGetLeftArg(JsonPathItem *v, JsonPathItem *a);
extern void jspGetRightArg(JsonPathItem *v, JsonPathItem *a);
extern Numeric jspGetNumeric(JsonPathItem *v);
extern bool jspGetBool(JsonPathItem *v);
extern char *jspGetString(JsonPathItem *v, int32 *len);
extern bool jspGetArraySubscript(JsonPathItem *v, JsonPathItem *from,
                                 JsonPathItem *to, int i);
extern bool jspIsMutable(JsonPath *path, List *varnames, List *varexprs);
 
extern const char *jspOperationName(JsonPathItemType type);
 
/*
 * Parsing support data structures.
 */
 
typedef struct JsonPathParseItem JsonPathParseItem;
 
struct JsonPathParseItem
{
    JsonPathItemType type;
    JsonPathParseItem *next;    /* next in path */
 
    union
    {
 
        /* classic operator with two operands: and, or etc */
        struct
        {
            JsonPathParseItem *left;
            JsonPathParseItem *right;
        }           args;
 
        /* any unary operation */
        JsonPathParseItem *arg;
 
        /* storage for jpiIndexArray: indexes of array */
        struct
        {
            int         nelems;
            struct
            {
                JsonPathParseItem *from;
                JsonPathParseItem *to;
            }          *elems;
        }           array;
 
        /* jpiAny: levels */
        struct
        {
            uint32      first;
            uint32      last;
        }           anybounds;
 
        struct
        {
            JsonPathParseItem *expr;
            char       *pattern;    /* could not be not null-terminated */
            uint32      patternlen;
            uint32      flags;
        }           like_regex;
 
        /* scalars */
        Numeric numeric;
        bool        boolean;
        struct
        {
            uint32      len;
            char       *val;    /* could not be not null-terminated */
        }           string;
    }           value;
};
 
typedef struct JsonPathParseResult
{
    JsonPathParseItem *expr;
    bool        lax;
} JsonPathParseResult;
 
extern JsonPathParseResult *parsejsonpath(const char *str, int len,
                                          struct Node *escontext);
 
extern bool jspConvertRegexFlags(uint32 xflags, int *result,
                                 struct Node *escontext);
 
/*
 * Struct for details about external variables passed into jsonpath executor
 */
typedef struct JsonPathVariable
{
    char       *name;
    int         namelen;        /* strlen(name) as cache for GetJsonPathVar() */
    Oid         typid;
    int32       typmod;
    Datum       value;
    bool        isnull;
} JsonPathVariable;
 
 
/* SQL/JSON query functions */
extern bool JsonPathExists(Datum jb, JsonPath *jp, bool *error, List *vars);
extern Datum JsonPathQuery(Datum jb, JsonPath *jp, JsonWrapper wrapper,
                           bool *empty, bool *error, List *vars,
                           const char *column_name);
extern JsonbValue *JsonPathValue(Datum jb, JsonPath *jp, bool *empty,
                                 bool *error, List *vars,
                                 const char *column_name);
 
/* For JSON_TABLE() */
extern PGDLLIMPORT const TableFuncRoutine JsonbTableRoutine;
 
#endif