Dynamic Columns API

#include <mysql/ma_dyncol.h>

The functions are present in both libmysql and libmysqld.

Result codes of functions

General rule is that if result code less then 0 it is an error.

Following codes are defined in enum enum_dyncol_func_result:

Type of dynamic column encoded string

We add special type for dynamic column encoded string: DYNAMIC_COLUMN but in fact it is DYNAMIC_STRING.

Types of data used by dynamic string routines

The types defined as a DYNAMIC_COLUMN_TYPE (enum enum_dynamic_column_type).

Storing unpacked values

Unpacked (not encoded to the string) values of dynamic columns stored in the following structure

struct st_dynamic_column_value
{
  DYNAMIC_COLUMN_TYPE type;
  union
  {
    long long long_value;
    unsigned long long ulong_value;
    double double_value;
    struct {
      MYSQL_LEX_STRING value;
      CHARSET_INFO *charset;
    } string;
    struct {
      decimal_digit_t buffer[DECIMAL_BUFF_LENGTH];
      decimal_t value;
    } decimal;
    MYSQL_TIME time_value;
  } x;
};
typedef struct st_dynamic_column_value DYNAMIC_COLUMN_VALUE;

Values should be requested from different underlying unuon fieds depending on type (value.type)

Before putting value into value.x.decimal.value mariadb_dyncol_prepare_decimal should be called for correct initialization of the value and buffer where decimal will be stored.

Functions

Mostly there is 2 pairs of function, one works only with old (numeric) format other one can read old (numeric) and new (with names) format but produce string in the new format.

To check packed dynamic string format use mariadb_dyncol_has_names function

Creating string from unpacked value array

enum enum_dyncol_func_result
mariadb_dyncol_create_many(DYNAMIC_COLUMN *str,
                           uint column_count,
                           uint *column_numbers,
                           DYNAMIC_COLUMN_VALUE *values,
                           my_bool new_string);
enum enum_dyncol_func_result
mariadb_dyncol_create_many_named(DYNAMIC_COLUMN *str,
                                 uint column_count,
                                 MYSQL_LEX_STRING *column_keys,
                                 DYNAMIC_COLUMN_VALUE *values,
                                 my_bool new_string);

where

Changing dynamic column packed string content

Following function add columns if they are not present in the string, update a column values if they was already in the string. To delete column you should update its value to NULL.

enum enum_dyncol_func_result
mariadb_dyncol_update_many(DYNAMIC_COLUMN *str,
                           uint column_count,
                           uint *column_numbers,
                           DYNAMIC_COLUMN_VALUE *values);
enum enum_dyncol_func_result
mariadb_dyncol_update_many_named(DYNAMIC_COLUMN *str,
                                 uint column_count,
                                 MYSQL_LEX_STRING *column_keys,
                                 DYNAMIC_COLUMN_VALUE *values);

Checking column existance

enum enum_dyncol_func_result
mariadb_dyncol_exists(DYNAMIC_COLUMN *str, uint column_number);
enum enum_dyncol_func_result
mariadb_dyncol_exists_named(DYNAMIC_COLUMN *str, MYSQL_LEX_STRING *column_key);

The function returns YES/NO or Error code

Get number of non-NULL columns

enum enum_dyncol_func_result
mariadb_dyncol_column_count(DYNAMIC_COLUMN *str, uint *column_count);

List of non-NULL columns

enum enum_dyncol_func_result
mariadb_dyncol_list(DYNAMIC_COLUMN *str, uint *column_count, uint **column_numbers);
enum enum_dyncol_func_result
mariadb_dyncol_list_named(DYNAMIC_COLUMN *str, uint *column_count,
                          MYSQL_LEX_STRING **column_keys);

Get one column value

enum enum_dyncol_func_result
mariadb_dyncol_get(DYNAMIC_COLUMN *org, uint column_number,
                   DYNAMIC_COLUMN_VALUE *value);
enum enum_dyncol_func_result
mariadb_dyncol_get_named(DYNAMIC_COLUMN *str, MYSQL_LEX_STRING *column_key,
                         DYNAMIC_COLUMN_VALUE *value);

If the column is not found NULL returned as a value of the column.

Get all non-NULL columns values

enum enum_dyncol_func_result
mariadb_dyncol_unpack(DYNAMIC_COLUMN *str,
                      uint *column_count,
                      MYSQL_LEX_STRING **column_keys,
                      DYNAMIC_COLUMN_VALUE **values);

Check packed dynamic column string format

my_bool mariadb_dyncol_has_names(DYNAMIC_COLUMN *str);

The function check only one byte of the string so it is quite efficient, but also wrong data tolerant.

Check packed dynamic column integrity

enum enum_dyncol_func_result
mariadb_dyncol_check(DYNAMIC_COLUMN *str);

Get dynamic columns as JSON object

enum enum_dyncol_func_result
mariadb_dyncol_json(DYNAMIC_COLUMN *str, DYNAMIC_STRING *json);

Get dynamic column value as one of base 3 types

enum enum_dyncol_func_result
mariadb_dyncol_val_str(DYNAMIC_STRING *str, DYNAMIC_COLUMN_VALUE *val,
                       CHARSET_INFO *cs, my_bool quote);
enum enum_dyncol_func_result
mariadb_dyncol_val_long(longlong *ll, DYNAMIC_COLUMN_VALUE *val);
enum enum_dyncol_func_result
mariadb_dyncol_val_double(double *dbl, DYNAMIC_COLUMN_VALUE *val);

Initialization of dynamic string value before assigning decimal value

void mariadb_dyncol_prepare_decimal(DYNAMIC_COLUMN_VALUE *value);

This function correctly lick decimal buffer to the decimal value.

Initialization of dynamic string value

#define mariadb_dyncol_value_init(V) (V)->type= DYN_COL_NULL

Above is a correct way to initialize "empty" dynamic column value.

Comparator of two column names

int mariadb_dyncol_column_cmp_named(const MYSQL_LEX_STRING *s1,
                                    const MYSQL_LEX_STRING *s2);

Columns stored sorted inside the packed dynamic column string, it is how routines compare the names.