MySQL :: MySQL NDB Cluster API Developer Guide

Column Class Overview

Parent class

NdbDictionary

Child classes

None

Description

Each instance of Column is characterized by its type, which is determined by a number of type specifiers:

Built-in type
Array length or maximum length
Precision and scale (currently not in use)
Character set (applicable only to columns using string data types)
Inline and part sizes (applicable only to blob columns)

These types in general correspond to MySQL data types and their variants. The data formats are same as in MySQL. The NDB API provides no support for constructing such formats; however, they are checked by the NDB kernel.

Methods

The following table lists the public methods of this class and the purpose or use of each method:

Table 2.5 Column class methods and descriptions

Method	Description
`Column()`	Class constructor; there is also a copy constructor
`~Column()`	Class destructor
`equal()`	Compares `Column` objects
`getArrayType()`	Gets the column's array type
`getAutoIncrement()`	Shows whether the column is auto-incrementing
`getCharset()`	Get the character set used by a string (text) column (not applicable to columns not storing character data)
`getColumnNo()`	Gets the column number
`getDefaultValue()`	Returns the column's default value
`getInlineSize()`	Gets the inline size of a blob column (not applicable to other column types)
`getLength()`	Gets the column's length
`getName()`	Gets the name of the column
`getNullable()`	Checks whether the column can be set to `NULL`
`getPartitionKey()`	Checks whether the column is part of the table's partitioning key
`getPartSize()`	Gets the part size of a blob column (not applicable to other column types)
`getPrecision()`	Gets the column's precision (used for decimal types only)
`getPrimaryKey()`	Check whether the column is part of the table's primary key
`getScale()`	Gets the column's scale (used for decimal types only)
`getSize()`	Gets the size of an element
`getSizeInBytesForRecord()`	Gets the space required for a column by `NdbRecord`, according to the column's type (added in NDB 7.4.7)
`getStripeSize()`	Gets a BLOB column's stripe size (not applicable to other column types)
`getStorageType()`	Gets the storage type used by this column
`getType()`	Gets the column's type (`Type` value)
`setArrayType()`	Sets the column's `ArrayType`
`setAutoIncrement()`	Sets the column's auto-increment flag
`setAutoIncrementInitialValue()`	Sets an auto-incrementing column's starting value
`setCharset()`	Sets the character set used by a column containing character data (not applicable to nontextual columns)
`setDefaultValue()`	Sets the column's default value
`setInlineSize()`	Sets the inline size for a blob column (not applicable to columns not of blob types)
`setLength()`	Sets the column's length
`setName()`	Sets the column's name
`setNullable()`	Toggles the column's nullability
`setPartitionKey()`	Determines whether the column is part of the table's partitioning key
`setPartSize()`	Sets the part size for a blob column (not applicable to columns not of blob types)
`setPrecision()`	Sets the column's precision (used for decimal types only)
`setPrimaryKey()`	Determines whether the column is part of the primary key
`setScale()`	Sets the column's scale (used for decimal types only)
`setStorageType()`	Sets the storage type to be used by this column
`setStripeSize()`	Sets the stripe size for a blob column (not applicable to columns not of blob types)
`setType()`	Sets the column's `Type`

Types

These are the public types of the Column class:

Table 2.6 Column class types and descriptionse.

Type	Description
`ArrayType`	Specifies the column's internal storage format
`StorageType`	Determines whether the column is stored in memory or on disk
`Type`	The column's data type. `NDB` columns have the same data types as found in MySQL

The assignment (=) operator is overloaded for this class, so that it always performs a deep copy.

Important

Columns created using this class cannot be seen by the MySQL Server. This means that they cannot be accessed by MySQL clients, and that they cannot be replicated. For these reasons, it is often preferable to avoid working with them.

In the NDB API, column names are handled in case-sensitive fashion. (This differs from the MySQL C API.) To reduce the possibility for error, it is recommended that you name all columns consistently using uppercase or lowercase.

As with other database objects, Column object creation and attribute changes to existing columns done using the NDB API are not visible from MySQL. For example, if you change a column's data type using Column::setType(), MySQL will regard the type of column as being unchanged. The only exception to this rule with regard to columns is that you can change the name of an existing column using Column::setName().

Column::ArrayType

Abstract

This section provides information about the ArrayType data type, which represents a column's internal attribute format.

Description

The attribute storage format can be either fixed or variable.

Enumeration values

Possible values are shown, along with descriptions, in the following table:

Table 2.7 Column object ArrayType data type values and descriptions

Name	Description
`ArrayTypeFixed`	stored as a fixed number of bytes
`ArrayTypeShortVar`	stored as a variable number of bytes; uses 1 byte overhead
`ArrayTypeMediumVar`	stored as a variable number of bytes; uses 2 bytes overhead

The fixed storage format is faster but also generally requires more space than the variable format. The default is ArrayTypeShortVar for Var* types and ArrayTypeFixed for others. The default is usually sufficient.

Column Constructor

Description

You can create a new Column or copy an existing one using the class constructor.

A Column created using the NDB API is not visible to a MySQL server.

The NDB API handles column names in case-sensitive fashion. For example, if you create a column named “myColumn”, you will not be able to access it later using “Mycolumn” for the name. You can reduce the possibility for error, by naming all columns consistently using only uppercase or only lowercase.

Signature

You can create either a new instance of the Column class, or by copying an existing Column object. Both of these are shown here:

Constructor for a new Column:

Column
    (
      const char* name = ""
    )

Copy constructor:

Column
    (
      const Column& column
    )

Parameters

When creating a new instance of Column, the constructor takes a single argument, which is the name of the new column to be created. The copy constructor also takes one parameter—in this case, a reference to the Column instance to be copied.

Return value

A Column object.

Destructor

The Column class destructor takes no arguments and returns nothing (void).

Column::equal()

Description

This method is used to compare one Column with another to determine whether the two Column objects are the same.

Signature

bool equal
    (
      const Column& column
    ) const

Parameters

equal() takes a single parameter, a reference to an instance of Column.

Return value

true if the columns being compared are equal, otherwise false.

Column::getArrayType()

Description

This method gets the column's array type.

Signature

ArrayType getArrayType
    (
      void
    ) const

Parameters

None.

Return value

An ArrayType; see Column::ArrayType for possible values.

Column::getAutoIncrement()

Description

This method shows whether the column is an auto-increment column.

Signature

bool getAutoIncrement
    (
      void
    ) const

Parameters

None.

Return value

TRUE if the column is an auto-increment column, FALSE if it is not.

Column::getCharset()

Description

This gets the character set used by a text column.

This method is applicable only to columns whose Type value is Char, Varchar, or Text.

The NDB API handles column names in case-sensitive fashion; “myColumn” and “Mycolumn” are not considered to refer to the same column. It is recommended that you minimize the possibility of errors from using the wrong lettercase for column names by naming all columns consistently using only uppercase or only lowercase.

Signature

CHARSET_INFO* getCharset
    (
      void
    ) const

Parameters

None.

Return value

A pointer to a CHARSET_INFO structure specifying both character set and collation. This is the same as a MySQL MY_CHARSET_INFO data structure; for more information, see mysql_get_character_set_info(),in the MySQL Manual.

Column::getColumnNo()

Description

This method gets the sequence number of a column within its containing table or index. If the column is part of an index (such as when returned by getColumn()), it is mapped to its position within that index, and not within the table containing the index.

Signature

int getColumnNo
    (
      void
    ) const

Parameters

None.

Return value

The column number as an integer.

Column::getDefaultValue()

Description

Gets a column's default value data.

To determine whether a table has any columns with default values, use Table::hasDefaultValues().

Signature

const void* getDefaultValue
    (
      unsigned int* len = 0
    ) const

Parameters

len holds either the length of the default value data, or 0 in the event that the column is nullable or has no default value.

Return value

The default value data.

Column::getInlineSize()

Description

This method retrieves the inline size of a blob column—that is, the number of initial bytes to store in the table's blob attribute. This part is normally in main memory and can be indexed.

This method is applicable only to blob columns.

Beginning with NDB 8.0.29, you can also obtain this information in the mysql client, by querying the ndbinfo.blobs table.

Signature

int getInlineSize
    (
      void
    ) const

Parameters

None.

Return value

The blob column's inline size, as an integer.

Column::getLength()

Description

This method gets the length of a column. This is either the array length for the column or—for a variable length array—the maximum length.

Signature

int getLength
    (
      void
    ) const

Parameters

None.

Return value

The (maximum) array length of the column, as an integer.

Column::getName()

Description

This method returns the name of the column for which it is called.

The NDB API handles column names in case-sensitive fashion. For example, if you retrieve the name “myColumn” for a given column, attempting to access this column using “Mycolumn” for the name fails with an error such as Column is NULL or Table definition has undefined column. You can reduce the possibility for error, by naming all columns consistently using only uppercase or only lowercase.

Signature

const char* getName
    (
      void
    ) const

Parameters

None.

Return value

The name of the column.

Column::getNullable()

Description

This method is used to determine whether the column can be set to NULL.

Signature

bool getNullable
    (
      void
    ) const

Parameters

None.

Return value

A Boolean value: true if the column can be set to NULL, otherwise false.

Column::getPartitionKey()

Description

This method is used to check whether the column is part of the table's partitioning key.

A partitioning key is a set of attributes used to distribute the tuples onto the data nodes. This key a hashing function specific to the NDB storage engine.

An example where this would be useful is an inventory tracking application involving multiple warehouses and regions, where it might be good to use the warehouse ID and district id as the partition key. This would place all data for a specific district and warehouse in the same storage node. Locally to each fragment the full primary key will still be used with the hashing algorithm in such a case.

For more information about partitioning, partitioning schemes, and partitioning keys in MySQL, see Partitioning, in the MySQL Manual.

The only type of user-defined partitioning that is supported for use with the NDB storage engine is key partitioning, including linear key partitioning.

Signature

bool getPartitionKey
    (
      void
    ) const

Parameters

None.

Return value

true if the column is part of the partitioning key for the table, otherwise false.

Column::getPartSize()

Description

This method is used to get the blob part size of a BLOB column—that is, the number of bytes that are stored in each tuple of the blob table.

This method is applicable to BLOB columns only.

In NDB 8.0.29 and later, you can also obtain this information in the mysql client or other MySQL client, by querying the ndbinfo.blobs table.

Signature

int getPartSize
    (
      void
    ) const

Parameters

None.

Return value

The column's part size, as an integer. In the case of a Tinyblob column, this value is 0 (that is, only inline bytes are stored).

Column::getPrecision()

Description

This method gets the precision of a column.

This method is applicable to decimal columns only.

Signature

int getPrecision
    (
      void
    ) const

Parameters

None.

Return value

The column's precision, as an integer. The precision is defined as the number of significant digits; for more information, see the discussion of the DECIMAL data type in Numeric Data Types, in the MySQL Manual.

Column::getPrimaryKey()

Description

This method is used to determine whether the column is part of the table's primary key.

Signature

bool getPrimaryKey
    (
      void
    ) const

Parameters

None.

Return value

A Boolean value: true if the column is part of the primary key of the table to which this column belongs, otherwise false.

Column::getScale()

Description

This method gets the scale used for a decimal column value.

This method is applicable to decimal columns only.

Signature

int getScale
    (
      void
    ) const

Parameters

None.

Return value

The decimal column's scale, as an integer. The scale of a decimal column represents the number of digits that can be stored following the decimal point. It is possible for this value to be 0. For more information, see the discussion of the DECIMAL data type in Numeric Data Types, in the MySQL Manual.

Column::getSize()

Description

This function is used to obtain the size of a column.

Signature

int getSize
    (
      void
    ) const

Parameters

None.

Return value

The column's size in bytes (an integer value).

Column::getSizeInBytesForRecord()

Description

Gets the space required for a given column by an NdbRecord, depending on the column's type, as follows:

For a BLOB column, this value is the same as sizeof(NdbRecord*), which is 4 or 8 bytes (the size of a pointer; platform-dependent).
For columns of all other types, it is the same as the value returned by getSize().

This method was added in NDB NDB 7.4.7.

Signature

int getSizeInBytesForRecord
    (
      void
    ) const

Parameters

None.

Return value

An integer (see Description).

Column::getStorageType()

Description

This method obtains a column's storage type.

Signature

StorageType getStorageType
    (
      void
    ) const

Parameters

None.

Return value

A StorageType value; for more information about this type, see Column::StorageType.

Column::getStripeSize()

Description

This method gets the stripe size of a blob column—that is, the number of consecutive parts to store in each node group.

Signature

int getStripeSize
    (
      void
    ) const

Parameters

None.

Return value

The column's stripe size, as an integer.

Column::getType()

Description

This method gets the column's data type.

Signature

Type getType
    (
      void
    ) const

Parameters

None.

Return value

The Type (data type) of the column. For a list of possible values, see Column::Type.

Column::setArrayType()

Description

Sets the array type for the column.

Signature

void setArrayType
    (
      ArrayType type
    )

Parameters

A Column::ArrayType value. See Column::ArrayType, for more information.

Return value

None.

Column::setAutoIncrement()

Description

Make the column auto-incrementing (or not).

Signature

void setAutoIncrement
    (
      bool flag
    )

Parameters

A boolean value: TRUE to make the column auto-incrementing; FALSE to remove this property of the column.

Return value

None.

Column::setAutoIncrementInitialValue()

Description

Set the initial value for an auto-incrementing column.

Signature

void setAutoIncrementInitialValue
    (
      Uint64 value
    )

Parameters

The initial value for the column (a 64-bit integer).

Return value

None.

Column::setCharset()

Description

This method can be used to set the character set and collation of a Char, Varchar, or Text column.

This method is applicable to Char, Varchar, and Text columns only.

Changes made to columns using this method are not visible to MySQL.

Signature

void setCharset
    (
      CHARSET_INFO* cs
    )

Parameters

This method takes one parameter. cs is a pointer to a CHARSET_INFO structure. For additional information, see Column::getCharset().

Return value

None.

Column::setDefaultValue()

Description

This method sets a column value to its default, if it has one; otherwise it sets the column to NULL.

To determine whether a table has any columns with default values, use Table::hasDefaultValues().

Signature

int setDefaultValue
    (
      const void* buf,
      unsigned int len
    )

Parameters

This method takes 2 arguments: a value pointer buf; and the length len of the data, as the number of significant bytes. For fixed size types, this is the type size. For variable length types, the leading 1 or 2 bytes pointed to by buffer also contain size information as normal for the type.

Return value

0 on success, 1 on failure..

Column::setInlineSize

Description

This method gets the inline size of a blob column—that is, the number of initial bytes to store in the table's blob attribute. This part is normally kept in main memory, and can be indexed and interpreted.

This method is applicable to blob columns only.

Changes made to columns using this method are not visible to MySQL. Beginning with NDB 8.0.30, you can change the inline size of a blob column in the mysql client by setting BLOB_INLINE_SIZE in a column comment as part of CREATE TABLE or ALTER TABLE. See NDB_COLUMN Options, for more information.

Signature

void setInlineSize
    (
      int size
    )

Parameters

The integer size is the new inline size for the blob column.

Return value

None.

Column::setLength()

Description

This method sets the length of a column. For a variable-length array, this is the maximum length; otherwise it is the array length.

Changes made to columns using this method are not visible to MySQL.

Signature

void setLength
    (
      int length
    )

Parameters

This method takes a single argument—the integer value length is the new length for the column.

Return value

None.

Column::setName()

Description

This method is used to set the name of a column.

setName() is the only Column method whose result is visible from a MySQL Server. MySQL cannot see any other changes made to existing columns using the NDB API.

Signature

void setName
    (
      const char* name
    )

Parameters

This method takes a single argument—the new name for the column.

Return value

This method None.

Column::setNullable()

Description

This method toggles the nullability of a column.

Changes made to columns using this method are not visible to MySQL.

Signature

void setNullable
    (
      bool nullable
    )

Parameters

A Boolean value. Using true makes it possible to insert NULLs into the column; if nullable is false, then this method performs the equivalent of changing the column to NOT NULL in MySQL.

Return value

None.

Column::setPartitionKey()

Description

This method makes it possible to add a column to the partitioning key of the table to which it belongs, or to remove the column from the table's partitioning key.

Changes made to columns using this method are not visible to MySQL.

For additional information, see Column::getPartitionKey().

Signature

void setPartitionKey
    (
      bool enable
    )

Parameters

The single parameter enable is a Boolean value. Passing true to this method makes the column part of the table's partitioning key; if enable is false, then the column is removed from the partitioning key.

Return value

None.

Column::setPartSize()

Description

This method sets the blob part size of a blob column—that is, the number of bytes to store in each tuple of the blob table.

This method is applicable to blob columns only.

Changes made to columns using this method are not visible to MySQL. You can increase the blob part size of a blob column to the maximum supported by NDB (13948) in mysql or another MySQL client by setting the MAX_BLOB_PART_SIZE option in a column comment as part of a CREATE TABLE or ALTER TABLE statement. See NDB_COLUMN Options.

Signature

void setPartSize
    (
      int size
    )

Parameters

The integer size is the number of bytes to store in the blob table. Using zero for this value means only inline bytes can be stored, in effect making the column's type TINYBLOB.

Return value

None.

Column::setPrecision()

Description

This method can be used to set the precision of a decimal column.

This method is applicable to decimal columns only.

Changes made to columns using this method are not visible to MySQL.

Signature

void setPrecision
    (
      int precision
    )

Parameters

This method takes a single parameter—precision is an integer, the value of the column's new precision. For additional information about decimal precision and scale, see Column::getPrecision(), and Column::getScale().

Return value

None.

Column::setPrimaryKey()

Description

This method is used to make a column part of the table's primary key, or to remove it from the primary key.

Changes made to columns using this method are not visible to MySQL.

Signature

void setPrimaryKey
    (
      bool primary
    )

Parameters

This method takes a single Boolean value. If it is true, then the column becomes part of the table's primary key; if false, then the column is removed from the primary key.

Return value

None.

Column::setScale()

Description

This method can be used to set the scale of a decimal column.

This method is applicable to decimal columns only.

Changes made to columns using this method are not visible to MySQL.

Signature

void setScale
    (
      int scale
    )

Parameters

This method takes a single parameter—the integer scale is the new scale for the decimal column. For additional information about decimal precision and scale, see Column::getPrecision(), and Column::getScale().

Return value

None.

Column::setStripeSize()

Description

This method sets the stripe size of a blob column—that is, the number of consecutive parts to store in each node group.

This method is applicable to blob columns only.

Changes made to columns using this method are not visible to MySQL.

Signature

void setStripeSize
    (
      int size
    )

Parameters

This method takes a single argument. The integer size is the new stripe size for the column.

Return value

None.

Column::setStorageType()

Description

Sets the storage type for the column.

Signature

void setStorageType
    (
      StorageType type
    )

Parameters

A Column::StorageType value. See Column::StorageType, for more information.

Return value

None.

Column::setType()

Description

This method sets the Type (data type) of a column.

setType() resets all column attributes to their (type dependent) default values; it should be the first method that you call when changing the attributes of a given column.

Changes made to columns using this method are not visible to MySQL.

Signature

void setType
    (
      Type type
    )

Parameters

This method takes a single parameter—the new Column::Type for the column. The default is Unsigned. For a listing of all permitted values, see Column::Type.

Return value

None.

Column::StorageType

This section provides information about the StorageType data type, which describes the storage type used by a Column object.

Description

The storage type used for a given column can be either in memory or on disk. Columns stored on disk mean that less RAM is required overall but such columns cannot be indexed, and are potentially much slower to access. The default is StorageTypeMemory.

Enumeration values

Possible values are shown, along with descriptions, in the following table:

Table 2.8 Column object StorageType data type values and descriptions

Name	Description
`StorageTypeMemory`	Store the column in memory
`StorageTypeDisk`	Store the column on disk

Column::Type

This section provides information about the Type data type, which is used to describe a column's data type.

Description

Data types for Column objects are analogous to the data types used by MySQL. The types Tinyint, Tinyintunsigned, Smallint, Smallunsigned, Mediumint, Mediumunsigned, Int, Unsigned, Bigint, Bigunsigned, Float, and Double (that is, types Tinyint through Double in the order listed in the Enumeration Values table) can be used in arrays.

Do not confuse Column::Type with Object::Type.

Enumeration values

Possible values are shown, along with descriptions, in the following table:

Table 2.9 Column object Type data type values and descriptions

Name	Description
`Undefined`	Undefined
`Tinyint`	1-byte signed integer
`Tinyunsigned`	1-byte unsigned integer
`Smallint`	2-byte signed integer
`Smallunsigned`	2-byte unsigned integer
`Mediumint`	3-byte signed integer
`Mediumunsigned`	3-byte unsigned integer
`Int`	4-byte signed integer
`Unsigned`	4-byte unsigned integer
`Bigint`	8-byte signed integer
`Bigunsigned`	8-byte signed integer
`Float`	4-byte float
`Double`	8-byte float
`Olddecimal`	Signed decimal as used prior to MySQL 5.0 (OBSOLETE)
`Olddecimalunsigned`	Unsigned decimal as used prior to MySQL 5.0 (OBSOLETE)
`Decimal`	Signed decimal as used by MySQL 5.0 and later
`Decimalunsigned`	Unsigned decimal as used by MySQL 5.0 and later
`Char`	A fixed-length array of 1-byte characters; maximum length is 255 characters
`Varchar`	A variable-length array of 1-byte characters; maximum length is 255 characters
`Binary`	A fixed-length array of 1-byte binary characters; maximum length is 255 characters
`Varbinary`	A variable-length array of 1-byte binary characters; maximum length is 255 characters
`Datetime`	An 8-byte date and time value, with a precision of 1 second (DEPRECATED)
`Datetime2`	An 8-byte date and time value, with fractional seconds.
`Date`	A 4-byte date value, with a precision of 1 day
`Blob`	A binary large object; see Section 2.3.13, “The NdbBlob Class”
`Text`	A text blob
`Bit`	A bit value; the length specifies the number of bits
`Longvarchar`	A 2-byte `Varchar`
`Longvarbinary`	A 2-byte `Varbinary`
`Time`	Time without date (DEPRECATED)
`Time2`	Time without date, with fractional seconds.
`Year`	1-byte year value in the range 1901-2155 (same as MySQL)
`Timestamp`	Unix time (DEPRECATED)
`Timestamp2`	Unix time, with fractional seconds.

The NDB API provides access to time types with microseconds (TIME, DATETIME, and TIMESTAMP) as Time2, Datetime2, and Timestamp2. (Time, Datetime, and Timestamp are deprecated as of the same version.) Use setPrecision() to set up to 6 fractional digits (default 0). Data formats are as in MySQL and must use the correct byte length.

Since NDB can compare any of these values as binary strings, it does not perform any checks on the actual data.

2.3.1 The Column Class

Column Class Overview

Column::ArrayType

Column Constructor

Column::equal()

Column::getArrayType()

Column::getAutoIncrement()

Column::getCharset()

Column::getColumnNo()

Column::getDefaultValue()

Column::getInlineSize()

Column::getLength()

Column::getName()

Column::getNullable()

Column::getPartitionKey()

Column::getPartSize()

Column::getPrecision()

Column::getPrimaryKey()

Column::getScale()

Column::getSize()

Column::getSizeInBytesForRecord()

Column::getStorageType()

Column::getStripeSize()

Column::getType()

Column::setArrayType()

Column::setAutoIncrement()

Column::setAutoIncrementInitialValue()

Column::setCharset()

Column::setDefaultValue()

Column::setInlineSize

Column::setLength()

Column::setName()

Column::setNullable()

Column::setPartitionKey()

Column::setPartSize()

Column::setPrecision()

Column::setPrimaryKey()

Column::setScale()

Column::setStripeSize()

Column::setStorageType()

Column::setType()

Column::StorageType

Column::Type