Description\n-----------\n\nThis page describes the client-side API for reading and writing Dynamic Columns blobs.\n\nNormally, 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.\n\nIf you need to read/write dynamic column blobs on the client for some reason, this API enables that.\n\nWhere to get it\n\nThe API is a part of libmysql C client library. In order to use it, you need to include this header file and link against libmysql:\n\n``c\n#include <mysql/ma_dyncol.h>\n`\n\nData structures\n\nDYNAMIC_COLUMN\n\nDYNAMIC_COLUMN represents a packed dynamic column blob. It is essentially a string-with-length and is defined as follows:\n\n`c\n/ A generic-purpose arbitrary-length string defined in MySQL Client API /\ntypedef struct st_dynamic_string\n{\n  char str;\n  size_t length,max_length,alloc_increment;\n} DYNAMIC_STRING;\n\n...\n\ntypedef DYNAMIC_STRING DYNAMIC_COLUMN;\n`\n\nDYNAMIC_COLUMN_VALUE\n\nDynamic columns blobs store {name, value} pairs. The DYNAMIC_COLUMN_VALUE structure is used to represent the value in accessible form.\n\n`c\nstruct st_dynamic_column_value\n{\n  DYNAMIC_COLUMN_TYPE type;\n  union\n  {\n    long long long_value;\n    unsigned long long ulong_value;\n    double double_value;\n    struct {\n      MYSQL_LEX_STRING value;\n      CHARSET_INFO charset;\n    } string;\n    struct {\n      decimal_digit_t buffer[DECIMAL_BUFF_LENGTH];\n      decimal_t value;\n    } decimal;\n    MYSQL_TIME time_value;\n  } x;\n};\ntypedef struct st_dynamic_column_value DYNAMIC_COLUMN_VALUE;\n`\n\nEvery value has a type, which is determined by the type member.\n\n| Type               | Structure field                              |\n| ------------------ | -------------------------------------------- |\n| DYN_COL_NULL     | -                                            |\n| DYN_COL_INT      | value.x.long_value                          |\n| DYN_COL_UINT     | value.x.ulong_value                         |\n| DYN_COL_DOUBLE   | value.x.double_value                        |\n| DYN_COL_STRING   | value.x.string.value, value.x.string.charset |\n| DYN_COL_DECIMAL  | value.x.decimal.value                        |\n| DYN_COL_DATETIME | value.x.time_value                          |\n| DYN_COL_DATE     | value.x.time_value                          |\n| DYN_COL_TIME     | value.x.time_value                          |\n| DYN_COL_DYNCOL   | value.x.string.value                         |\n\nNotes\n\n Values with type DYN_COL_NULL do not ever occur in dynamic columns blobs.\n Type DYN_COL_DYNCOL means that the value is a packed dynamic blob. This is how nested dynamic columns are done.\n Before storing a value to value.x.decimal.value, you must call mariadb_dyncol_prepare_decimal() to initialize the space for storage.\n\nenum_dyncol_func_result\n\nenum enum_dyncol_func_result is used as return value.\n\n| Value | Name                         | Comments                                                             |\n| ----- | ---------------------------- | -------------------------------------------------------------------- |\n| 0     | ER_DYNCOL_OK               | OK                                                                   |\n| 0     | ER_DYNCOL_NO               | (the same as ER_DYNCOL_OK but for functions which return a YES/NO) |\n| 1     | ER_DYNCOL_YES              | YES response or success                                            |\n| 2     | ER_DYNCOL_TRUNCATED        | Operation succeeded but the data was truncated                       |\n| -1    | ER_DYNCOL_FORMAT           | Wrong format of the encoded string                                   |\n| -2    | ER_DYNCOL_LIMIT            | A limit of implementation reached                                    |\n| -3    | ER_DYNCOL_RESOURCE         | Out of resources                                                     |\n| -4    | ER_DYNCOL_DATA             | Incorrect input data                                                 |\n| -5    | ER_DYNCOL_UNKNOWN_CHARSET | Unknown character set                                                |\n\nResult codes that are less than zero represent error conditions.\n\nFunction reference\n\nFunctions come in pairs:\n\n xxx_num() operates on the old (pre-MariaDB-10.0.1) dynamic column blob format, where columns were identified by numbers.\n xxx_named() can operate on both old or new data format. If it modifies the blob, it converts it to the new data format.\n\nYou should use xxx_named() functions, unless you need to keep the data compatible with MariaDB versions before 10.0.1.\n\nmariadb_dyncol_init <a href="#mariadb_dyncol_init" id="mariadb_dyncol_init"></a>\n\nFirst, define mariadb_dyncol_init(A) memset((A), 0, sizeof(\\(A))). It is the correct initialization for an empty packed dynamic blob.\n\nmariadb_dyncol_free <a href="#mariadb_dyncol_free" id="mariadb_dyncol_free"></a>\n\nCopy where str is IN. Packed dynamic blob which memory should be freed.\n\n`c\nvoid mariadb_dyncol_free(DYNAMIC_COLUMN str);\n`\n\nmariadb_dyncol_create_many\n\nCreate a packed dynamic blob from arrays of values and names.\n\n`c\nenum enum_dyncol_func_result\nmariadb_dyncol_create_many(DYNAMIC_COLUMN str,\n                           uint column_count,\n                           uint column_numbers,\n                           DYNAMIC_COLUMN_VALUE values,\n                           my_bool new_string);\nenum enum_dyncol_func_result\nmariadb_dyncol_create_many_named(DYNAMIC_COLUMN str,\n                                 uint column_count,\n                                 MYSQL_LEX_STRING column_keys,\n                                 DYNAMIC_COLUMN_VALUE values,\n                                 my_bool new_string);\n`\n\nHere are the names and values:\n\n| Name            | Value | Comments                                                            |\n| --------------- | ----- | ------------------------------------------------------------------- |\n| str             | OUT   | Packed dynamic blob will be put here                                |\n| column_count   | IN    | Number of columns                                                   |\n| column_numbers | IN    | Column numbers array (old format)                                   |\n| column_keys    | IN    | Column names array (new format)                                     |\n| values          | IN    | Column values array                                                 |\n| new_string     | IN    | If TRUE then the str will be reinitialized (not freed) before usage |\n\nmariadb_dyncol_update_many\n\nAdd or update columns in a dynamic columns blob. To delete a column, update its value to a "non-value" of type DYN_COL_NULL :\n\n`c\nenum enum_dyncol_func_result\nmariadb_dyncol_update_many(DYNAMIC_COLUMN str,\n                           uint column_count,\n                           uint column_numbers,\n                           DYNAMIC_COLUMN_VALUE values);\nenum enum_dyncol_func_result\nmariadb_dyncol_update_many_named(DYNAMIC_COLUMN str,\n                                 uint column_count,\n                                 MYSQL_LEX_STRING column_keys,\n                                 DYNAMIC_COLUMN_VALUE values);\n`\n\n| Name            | Value  | Comments                              |\n| --------------- | ------ | ------------------------------------- |\n| str             | IN/OUT | Dynamic columns blob to be modified   |\n| column_count   | IN     | Number of columns in following arrays |\n| column_numbers | IN     | Column numbers array (old format)     |\n| column_keys    | IN     | Column names array (new format)       |\n| values          | IN     | Column values array                   |\n\nmariadb_dyncol_exists\n\nCheck if column with given names exist in the blob:\n\n`c\nenum enum_dyncol_func_result\nmariadb_dyncol_exists(DYNAMIC_COLUMN str, uint column_number);\nenum enum_dyncol_func_result\nmariadb_dyncol_exists_named(DYNAMIC_COLUMN str, MYSQL_LEX_STRING column_key);\n`\n\n| Name           | Value | Comments                      |\n| -------------- | ----- | ----------------------------- |\n| str            | IN    | Packed dynamic columns string |\n| column_number | IN    | Column number (old format)    |\n| column_key    | IN    | Column name (new format)      |\n\nThe function returns YES, or NO or Error code.\n\nmariadb_dyncol_column_count\n\nGet the number of columns in a dynamic column blob:\n\n`c\nenum enum_dyncol_func_result\nmariadb_dyncol_column_count(DYNAMIC_COLUMN str, uint column_count);\n`\n\n| Name          | Value | Comments                                                 |\n| ------------- | ----- | -------------------------------------------------------- |\n| str           | IN    | Packed dynamic columns string                            |\n| column_count | OUT   | Number of not NULL columns in the dynamic columns string |\n\nmariadb_dyncol_list\n\nList columns in a dynamic column blob:\n\n`c\nenum enum_dyncol_func_result\nmariadb_dyncol_list(DYNAMIC_COLUMN str, uint column_count, uint *column_numbers);\nenum enum_dyncol_func_result\nmariadb_dyncol_list_named(DYNAMIC_COLUMN str, uint column_count,\n                          MYSQL_LEX_STRING column_keys);\n`\n\n|                 |     |                                                                  |\n| --------------- | --- | ---------------------------------------------------------------- |\n| str             | IN  | Packed dynamic columns string                                    |\n| column_count   | OUT | Number of columns in following arrays                            |\n| column_numbers | OUT | Column numbers array (old format). Caller should free this array |\n| column_keys    | OUT | Column names array (new format). Caller should free this array   |\n\nmariadb_dyncol_get\n\nGet a value of one column:\n\n`c\nenum enum_dyncol_func_result\nmariadb_dyncol_get(DYNAMIC_COLUMN org, uint column_number,\n                   DYNAMIC_COLUMN_VALUE value);\nenum enum_dyncol_func_result\nmariadb_dyncol_get_named(DYNAMIC_COLUMN str, MYSQL_LEX_STRING column_key,\n                         DYNAMIC_COLUMN_VALUE value);\n`\n\n| Name           | Value | Comments                          |\n| -------------- | ----- | --------------------------------- |\n| str            | IN    | Packed dynamic columns string     |\n| column_number | IN    | Column numbers array (old format) |\n| column_key    | IN    | Column names array (new format)   |\n| value          | OUT   | Value of the column               |\n\nIf the column is not found, NULL is returned as the value of the column.\n\nmariadb_dyncol_unpack\n\nGet the value of all columns:\n\n`c\nenum enum_dyncol_func_result\nmariadb_dyncol_unpack(DYNAMIC_COLUMN str,\n                      uint column_count,\n                      MYSQL_LEX_STRING column_keys,\n                      DYNAMIC_COLUMN_VALUE values);\n`\n\n| Name          | Value | Comments                                               |\n| ------------- | ----- | ------------------------------------------------------ |\n| str           | IN    | Packed dynamic columns string to unpack                |\n| column_count | OUT   | Number of columns in following arrays                  |\n| column_keys  | OUT   | Column names array (should be free by caller)          |\n| values        | OUT   | Values of the columns array (should be free by caller) |\n\nmariadb_dyncol_has_names\n\nCheck whether the dynamic columns blob uses the new data format (the one where columns are identified by names):\n\n`c\nmy_bool mariadb_dyncol_has_names(DYNAMIC_COLUMN str);\n`\n\n| Name | Value | Comments                      |\n| ---- | ----- | ----------------------------- |\n| str  | IN    | Packed dynamic columns string |\n\nmariadb_dyncol_check\n\nCheck whether the dynamic column blob has the correct data format:\n\n`c\nenum enum_dyncol_func_result\nmariadb_dyncol_check(DYNAMIC_COLUMN str);\n`\n\n| Name | Value | Comments                      |\n| ---- | ----- | ----------------------------- |\n| str  | IN    | Packed dynamic columns string |\n\nmariadb_dyncol_json\n\nGet contents of a dynamic columns blob in a JSON form:\n\n`c\nenum enum_dyncol_func_result\nmariadb_dyncol_json(DYNAMIC_COLUMN str, DYNAMIC_STRING json);\n`\n\n| Name | Value | Comments                      |\n| ---- | ----- | ----------------------------- |\n| str  | IN    | Packed dynamic columns string |\n| json | OUT   | JSON representation           |\n\nmariadb_dyncol_val_TYPE\n\nGet the dynamic column value as one of the base types:\n\n`c\nenum enum_dyncol_func_result\nmariadb_dyncol_val_str(DYNAMIC_STRING str, DYNAMIC_COLUMN_VALUE val,\n                       CHARSET_INFO cs, my_bool quote);\nenum enum_dyncol_func_result\nmariadb_dyncol_val_long(longlong ll, DYNAMIC_COLUMN_VALUE val);\nenum enum_dyncol_func_result\nmariadb_dyncol_val_double(double dbl, DYNAMIC_COLUMN_VALUE val);\n`\n\n| Name             | Value | Comments            |\n| ---------------- | ----- | ------------------- |\n| str or ll or dbl | OUT   | value of the column |\n| val              | IN    | Value               |\n\nmariadb_dyncol_prepare_decimal\n\nInitialize DYNAMIC_COLUMN_VALUE before setting the value of value.x.decimal.value:\n\n`c\nvoid mariadb_dyncol_prepare_decimal(DYNAMIC_COLUMN_VALUE value);\n`\n\n| Name  | Value | Comments            |\n| ----- | ----- | ------------------- |\n| value | OUT   | Value of the column |\n\nThis function links value.x.decimal.value to value.x.decimal.buffer.\n\nmariadb_dyncol_value_init\n\nInitialize a DYNAMIC_COLUMN_VALUE structure to a safe default:\n\n`c\n#define mariadb_dyncol_value_init(V) (V)->type= DYN_COL_NULL\n`\n\nmariadb_dyncol_column_cmp_named\n\nCompare two column names (column names are compared with memcmp()):\n\n`c\nint mariadb_dyncol_column_cmp_named(const MYSQL_LEX_STRING s1,\n                                    const MYSQL_LEX_STRING s2);\n``\n\nURL: https://mariadb.com/docs/server/reference/sql-structure/nosql/dynamic-column-api