tmp

This page describes client-side API for reading and writing Dynamic Columns blobs.

Normally, you should use Dynamic column functions which are run inside the MariaDB server and allow one to access Dynamic Columns content without any client-side libraries.

If you need to read/write dynamic column blobs on the client for some reason, this API enables that.

Where to get it

The API is a part of libmysql C client library. In order to use it, one needs to include this header file

#include <mysql/ma_dyncol.h>

and link against libmysql.

Data structures

DYNAMIC_COLUMN

DYNAMIC_COLUMN represents a packed dynamic column blob. It is essentially a string-with-length and is defined as follows:

/* A generic-purpose arbitrary-length string defined in MySQL Client API */
typedef struct st_dynamic_string
{
  char *str;
  size_t length,max_length,alloc_increment;
} DYNAMIC_STRING;

...

typedef DYNAMIC_STRING DYNAMIC_COLUMN;

DYNAMIC_COLUMN_VALUE

Dynamic columns blob stores {name, value} pairs. DYNAMIC_COLUMN_VALUE structure is used to represent the value in accessible form.

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;

Every value has a type, which is determined by the type member.

Notes

• Values with type DYN_COL_NULL do not ever occur in dynamic columns blobs.
• Type DYN_COL_DYNCOL means that the value is a packed dynamic blob. This is how nested dynamic columns are done.
• Before storing a value to value.x.decimal.value, one must call mariadb_dyncol_prepare_decimal() to initialize the space for storage.

enum_dyncol_func_result

enum enum_dyncol_func_result is used as return value.

Result codes that are less than zero represent error conditions.

Function reference

Functions come in pairs:

• xxx() operates on the old (pre-MariaDB-10.0.1) data format where columns were identified by numbers.
• xxx_named() will operate on either old or new data format. If it modifies the blob, it will convert it to the new data format.

You should use xxx_named() functions, unless you need to keep the data compatible with MariaDB versions before 10.0.1.

mariadb_dyncol_create_many

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

mariadb_dyncol_update_many

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);

mariadb_dyncol_exists

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

mariadb_dyncol_column_count

Get number of non-NULL columns

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

mariadb_dyncol_list

List 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);

mariadb_dyncol_get

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.

mariadb_dyncol_unpack

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);

mariadb_dyncol_has_names

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.

mariadb_dyncol_check

Check packed dynamic column integrity

enum enum_dyncol_func_result
mariadb_dyncol_check(DYNAMIC_COLUMN *str);

mariadb_dyncol_json

Get dynamic columns as JSON object

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

mariadb_dyncol_val_(TYPE)

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);

mariadb_dyncol_prepare_decimal

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.

mariadb_dyncol_column_cmp_named

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.