MySQL 8.3.0
Source Code Documentation
item_json_func.h File Reference
#include <assert.h>
#include <sys/types.h>
#include <cstdint>
#include <memory>
#include <utility>
#include "field_types.h"
#include "my_alloc.h"
#include "my_inttypes.h"
#include "my_table_map.h"
#include "my_time.h"
#include "mysql/strings/m_ctype.h"
#include "mysql/udf_registration_types.h"
#include "mysql_com.h"
#include "mysql_time.h"
#include "prealloced_array.h"
#include "sql-common/json_error_handler.h"
#include "sql-common/json_path.h"
#include "sql/enum_query_type.h"
#include "sql/field.h"
#include "sql/item.h"
#include "sql/item_cmpfunc.h"
#include "sql/item_func.h"
#include "sql/item_strfunc.h"
#include "sql/mem_root_array.h"
#include "sql/parse_location.h"
#include "sql/psi_memory_key.h"
#include "sql_string.h"

Go to the source code of this file.

Classes

class  Json_path_cache
 Path cache for JSON functions. More...
 
struct  Json_path_cache::Path_cell
 Struct that points to a cell in m_paths and tells its status. More...
 
class  Item_json_func
 Base class for all item functions that a return JSON value. More...
 
class  Item_func_json_valid
 Represents the JSON function JSON_VALID( <value> ) More...
 
class  Item_func_json_schema_valid
 Represents the JSON function JSON_SCHEMA_VALID( <json schema>, <json doc> ) More...
 
class  Item_func_json_schema_validation_report
 Represents the JSON function JSON_SCHEMA_VALIDATION_REPORT( <json schema>, <json doc> ) More...
 
class  Item_func_json_contains
 Represents the JSON function JSON_CONTAINS() More...
 
class  Item_func_json_contains_path
 Represents the JSON function JSON_CONTAINS_PATH() More...
 
class  Item_func_json_type
 Represents the JSON function JSON_TYPE. More...
 
class  Item_typecast_json
 Represents a "CAST( <value> AS JSON )" coercion. More...
 
class  Item_func_json_length
 Represents the JSON function JSON_LENGTH() More...
 
class  Item_func_json_depth
 Represents the JSON function JSON_DEPTH() More...
 
class  Item_func_json_keys
 Represents the JSON function JSON_KEYS() More...
 
class  Item_func_json_extract
 Represents the JSON function JSON_EXTRACT() More...
 
class  Item_func_modify_json_in_path
 Base class for all the functions that take a JSON document as the first argument and one of more pairs of a JSON path and a value to insert into the JSON document, and returns the modified JSON document. More...
 
class  Item_func_json_array_append
 Represents the JSON function JSON_ARRAY_APPEND() More...
 
class  Item_func_json_insert
 Represents the JSON function JSON_INSERT() More...
 
class  Item_func_json_array_insert
 Represents the JSON function JSON_ARRAY_INSERT() More...
 
class  Item_func_json_set_replace
 Common base class for JSON_SET() and JSON_REPLACE(). More...
 
class  Item_func_json_set
 Represents the JSON function JSON_SET() More...
 
class  Item_func_json_replace
 Represents the JSON function JSON_REPLACE() More...
 
class  Item_func_json_array
 Represents the JSON function JSON_ARRAY() More...
 
class  Item_func_json_row_object
 Represents the JSON function JSON_OBJECT() More...
 
class  Item_func_json_search
 Represents the JSON function JSON_SEARCH() More...
 
class  Item_func_json_remove
 Represents the JSON function JSON_REMOVE() More...
 
class  Item_func_json_merge_preserve
 Represents the JSON function JSON_MERGE_PRESERVE. More...
 
class  Item_func_json_merge
 Represents the JSON function JSON_MERGE. More...
 
class  Item_func_json_merge_patch
 Represents the JSON function JSON_MERGE_PATCH. More...
 
class  Item_func_json_quote
 Represents the JSON function JSON_QUOTE() More...
 
class  Item_func_json_unquote
 Represents the JSON function JSON_UNQUOTE() More...
 
class  Item_func_json_pretty
 Represents the JSON_PRETTY function. More...
 
class  Item_func_json_storage_size
 Class that represents the function JSON_STORAGE_SIZE. More...
 
class  Item_func_json_storage_free
 Class that represents the function JSON_STORAGE_FREE. More...
 
class  Item_func_array_cast
 Class that represents CAST(<expr> AS <type> ARRAY) More...
 
class  Item_func_json_overlaps
 
class  Item_func_member_of
 
class  Item_func_json_value
 Class implementing the JSON_VALUE function. More...
 

Typedefs

using Json_dom_ptr = std::unique_ptr< Json_dom >
 
typedef Prealloced_array< size_t, 16 > Sorted_index_array
 

Enumerations

enum  enum_one_or_all_type {
  ooa_one , ooa_all , ooa_null , ooa_error ,
  ooa_uninitialized
}
 For use by JSON_CONTAINS_PATH() and JSON_SEARCH() More...
 

Functions

bool sql_scalar_to_json (Item *arg, const char *calling_function, String *value, String *tmp, Json_wrapper *wr, Json_scalar_holder *scalar, bool scalar_string)
 Get a JSON value from an SQL scalar value. More...
 
bool json_value (Item *arg, Json_wrapper *result, bool *has_value)
 Return the JSON value of the argument in a wrapper. More...
 
bool get_json_wrapper (Item **args, uint arg_idx, String *str, const char *func_name, Json_wrapper *wrapper)
 Return the JSON value of the argument in a wrapper. More...
 
bool get_json_atom_wrapper (Item **args, uint arg_idx, const char *calling_function, String *value, String *tmp, Json_wrapper *wr, Json_scalar_holder *scalar, bool accept_string)
 Convert Json values or MySQL values to JSON. More...
 
bool ensure_utf8mb4 (const String &val, String *buf, const char **resptr, size_t *reslength, bool require_string)
 Check a non-empty val for character set. More...
 
bool geometry_to_json (Json_wrapper *wr, String *swkb, const char *calling_function, int max_decimal_digits, bool add_bounding_box, bool add_short_crs_urn, bool add_long_crs_urn, uint32 *geometry_srid)
 Turn a GEOMETRY value into a JSON value per the GeoJSON specification revision 1.0. More...
 
bool convert_value_to_json (Item *item, const char *func_name, Json_wrapper *wr)
 Convert a value represented with an Item to a JSON value. More...
 
bool get_atom_null_as_null (Item **args, uint arg_idx, const char *calling_function, String *value, String *tmp, Json_wrapper *wr)
 Convert JSON values or MySQL values to JSON. More...
 
bool get_json_object_member_name (const THD *thd, Item *arg_item, String *value, String *utf8_res, const char **safep, size_t *safe_length)
 Gets a JSON object member name from an Item. More...
 
bool parse_json (const String &res, Json_dom_ptr *dom, bool require_str_or_json, const JsonParseErrorHandler &error_handler, const JsonErrorHandler &depth_handler)
 Parse a JSON dom out of an argument to a JSON function. More...
 
enum_json_diff_status apply_json_diffs (Field_json *field, const Json_diff_vector *diffs)
 Apply a sequence of JSON diffs to the value stored in a JSON column. More...
 
bool sort_and_remove_dups (const Json_wrapper &orig, Sorted_index_array *v)
 Sort the elements of a JSON array and remove duplicates. More...
 
bool save_json_to_field (THD *thd, Field *field, const Json_wrapper *w, bool no_error)
 Save JSON to a given field. More...
 

Typedef Documentation

◆ Json_dom_ptr

using Json_dom_ptr = std::unique_ptr<Json_dom>

◆ Sorted_index_array

typedef Prealloced_array<size_t, 16> Sorted_index_array

Enumeration Type Documentation

◆ enum_one_or_all_type

For use by JSON_CONTAINS_PATH() and JSON_SEARCH()

Enumerator
ooa_one 
ooa_all 
ooa_null 
ooa_error 
ooa_uninitialized 

Function Documentation

◆ apply_json_diffs()

enum_json_diff_status apply_json_diffs ( Field_json field,
const Json_diff_vector diffs 
)

Apply a sequence of JSON diffs to the value stored in a JSON column.

Parameters
fieldthe column to update
diffsthe diffs to apply
Returns
an enum_json_diff_status value that tells if the diffs were applied successfully

◆ convert_value_to_json()

bool convert_value_to_json ( Item item,
const char *  func_name,
Json_wrapper wr 
)

Convert a value represented with an Item to a JSON value.

Parameters
[in]itemthe input value, may be any data type
[in]func_namefor error reporting
[in,out]wrthe result wrapper for the JSON value
Returns
false if success, true if error

◆ ensure_utf8mb4()

bool ensure_utf8mb4 ( const String val,
String buf,
const char **  resptr,
size_t *  reslength,
bool  require_string 
)

Check a non-empty val for character set.

If it has character set my_charset_binary, signal error and return false. Else, try to convert to my_charset_utf8mb4_bin. If this fails, signal error and return true, else return false.

Parameters
[in]valthe string to be checked
[in,out]bufbuffer to hold the converted string
[out]resptrthe resulting, possibly converted string, only set if no error
[out]reslengththe length of resptr
[in]require_stringIf true, give error messages if binary string. If we see a conversion error (space), we give error notwithstanding this parameter value
Returns
True if the string could not be converted. False on success.

Check a non-empty val for character set.

◆ geometry_to_json()

bool geometry_to_json ( Json_wrapper wr,
String swkb,
const char *  calling_function,
int  max_decimal_digits,
bool  add_bounding_box,
bool  add_short_crs_urn,
bool  add_long_crs_urn,
uint32 geometry_srid 
)

Turn a GEOMETRY value into a JSON value per the GeoJSON specification revision 1.0.

This method is implemented in item_geofunc.cc.

Parameters
[in,out]wrThe wrapper to be stuffed with the JSON value.
[in]swkbThe source GEOMETRY value.
[in]calling_functionName of user-invoked function (for errors)
[in]max_decimal_digitsSee the user documentation for ST_AsGeoJSON.
[in]add_bounding_boxSee the user documentation for ST_AsGeoJSON.
[in]add_short_crs_urnSee the user documentation for ST_AsGeoJSON.
[in]add_long_crs_urnSee the user documentation for ST_AsGeoJSON.
[in,out]geometry_sridSpatial Reference System Identifier to be filled in.
Returns
false if the conversion succeeds, true otherwise

Turn a GEOMETRY value into a JSON value per the GeoJSON specification revision 1.0.

◆ get_atom_null_as_null()

bool get_atom_null_as_null ( Item **  args,
uint  arg_idx,
const char *  calling_function,
String value,
String tmp,
Json_wrapper wr 
)

Convert JSON values or MySQL values to JSON.

Converts SQL NULL to the JSON null literal.

Parameters
[in]argsarguments to function
[in]arg_idxthe index of the argument to process
[in]calling_functionname of the calling function
[in,out]valueworking area (if the returned Json_wrapper points to a binary value rather than a DOM, this string will end up holding the binary representation, and it must stay alive until the wrapper is destroyed or converted from binary to DOM)
[in,out]tmptemporary scratch space for converting strings to the correct charset; only used if accept_string is true and conversion is needed
[in,out]wrthe result wrapper
Returns
false if we found a value or NULL, true otherwise

◆ get_json_atom_wrapper()

bool get_json_atom_wrapper ( Item **  args,
uint  arg_idx,
const char *  calling_function,
String value,
String tmp,
Json_wrapper wr,
Json_scalar_holder scalar,
bool  accept_string 
)

Convert Json values or MySQL values to JSON.

Parameters
[in]argsarguments to function
[in]arg_idxthe index of the argument to process
[in]calling_functionname of the calling function
[in,out]valueworking area (if the returned Json_wrapper points to a binary value rather than a DOM, this string will end up holding the binary representation, and it must stay alive until the wrapper is destroyed or converted from binary to DOM)
[in,out]tmptemporary scratch space for converting strings to the correct charset; only used if accept_string is true and conversion is needed
[in,out]wrthe result wrapper
[in,out]scalarpointer to pre-allocated memory that can be borrowed by the result wrapper if the result is a scalar. If the pointer is NULL, memory for a scalar result will be allocated on the heap.
[in]accept_stringif true, accept MySQL strings as JSON strings by converting them to UTF8, else emit an error
Returns
false if we found a value or NULL, true otherwise

◆ get_json_object_member_name()

bool get_json_object_member_name ( const THD thd,
Item arg_item,
String value,
String utf8_res,
const char **  safep,
size_t *  safe_length 
)

Gets a JSON object member name from an Item.

An error is raised if the Item evaluates to NULL, or if it cannot be converted to a utf8mb4 string.

Parameters
[in]thdTHD handle
[in]arg_itemAn argument Item
[out]valueWhere to materialize the arg_item's string value
[out]utf8_resBuffer for use by ensure_utf8mb4.
[out]safepString pointer after any relevant conversion
[out]safe_lengthCorresponding string length
Returns
true if the Item is not a utf8mb4 string

◆ get_json_wrapper()

bool get_json_wrapper ( Item **  args,
uint  arg_idx,
String str,
const char *  func_name,
Json_wrapper wrapper 
)

Return the JSON value of the argument in a wrapper.

Abstracts whether the value comes from a field or a function or a valid JSON text.

Parameters
[in]argsthe arguments
[in]arg_idxthe argument index
[out]strthe string buffer
[in]func_namethe name of the function we are executing
[out]wrapperthe JSON value wrapper
Returns
false if we found a value or NULL, true if not.

◆ json_value()

bool json_value ( Item arg,
Json_wrapper result,
bool *  has_value 
)

Return the JSON value of the argument in a wrapper.

Handles arguments with type JSON, including array objects (which do not report type JSON but rather the type of individual elements).

Does not handle literals. See also get_json_wrapper.

Parameters
[in]argthe argument
[in,out]resultthe JSON value wrapper
[out]has_valuetrue if argument was handled, false otherwise undefined when error

◆ parse_json()

bool parse_json ( const String res,
Json_dom_ptr dom,
bool  require_str_or_json,
const JsonParseErrorHandler error_handler,
const JsonErrorHandler depth_handler 
)

Parse a JSON dom out of an argument to a JSON function.

Parameters
[in]resPointer to string value of arg.
[in,out]domIf non-null, we want any text parsed DOM returned at the location pointed to
[in]require_str_or_jsonIf true, generate an error if other types used as input
[in]error_handlerPointer to a function that should handle reporting of parsing error.
[in]depth_handlerPointer to a function that should handle error occurred when depth is exceeded.
Returns
false if the arg parsed as valid JSON, true otherwise

◆ save_json_to_field()

bool save_json_to_field ( THD thd,
Field field,
const Json_wrapper w,
bool  no_error 
)

Save JSON to a given field.

Value is saved in type-aware manner. Into a JSON-typed column any JSON data could be saved. Into an SQL scalar field only a scalar could be saved. If data being saved isn't scalar or can't be coerced to the target type, an error is returned.

Parameters
thdThread handler
fieldField to save data to
wJSON data to save
no_errorIf true, don't raise an error when the value cannot be converted to the target type
Returns
false ok true coercion error occur

◆ sort_and_remove_dups()

bool sort_and_remove_dups ( const Json_wrapper orig,
Sorted_index_array v 
)

Sort the elements of a JSON array and remove duplicates.

Parameters
[in]origthe original JSON array
[out]vvector that will be filled with the indexes of the array elements in increasing order
Returns
false on success, true on error

◆ sql_scalar_to_json()

bool sql_scalar_to_json ( Item arg,
const char *  calling_function,
String value,
String tmp,
Json_wrapper wr,
Json_scalar_holder scalar,
bool  scalar_string 
)

Get a JSON value from an SQL scalar value.

Parameters
[in]argthe function argument
[in]calling_functionthe name of the calling function
[in,out]valuea scratch area
[in,out]tmptemporary scratch space for converting strings to the correct charset; only used if accept_string is true and conversion is needed
[out]wrthe retrieved JSON value
[in,out]scalarpointer to pre-allocated memory that can be borrowed by the result wrapper to hold the scalar result. If the pointer is NULL, memory will be allocated on the heap.
[in]scalar_stringif true, interpret SQL strings as scalar JSON strings. if false, interpret SQL strings as JSON objects. If conversion fails, return the string as a scalar JSON string instead.
Returns
false if we could get a value or NULL, otherwise true

Scalar processing is irrelevant. Geometry types are converted to JSON objects.