MySQL NDB Cluster API Developer Guide
This section provides information about the
Column
class, which models a column in an
NDBCLUSTER
table.
None
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.
The following table lists the public methods of this class and the purpose or use of each method:
Table 2.6 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 |
These are the public types of the Column
class:
Table 2.7 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.
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()
.
This section provides information about the
ArrayType
data type, which represents a
column's internal attribute format.
The attribute storage format can be either fixed or variable.
Possible values are shown, along with descriptions, in the following table:
Table 2.8 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.
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.
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
)
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.
A Column
object.
The Column
class destructor
takes no arguments and returns nothing
(void
).
This method is used to compare one
Column
with another to
determine whether the two
Column
objects are the
same.
bool equal
(
const Column& column
) const
equal()
takes a single parameter, a
reference to an instance of
Column
.
true
if the columns being compared are
equal, otherwise false
.
This method gets the column's array type.
ArrayType getArrayType ( void ) const
None.
An ArrayType
; see
Column::ArrayType for possible values.
This method shows whether the column is an auto-increment column.
bool getAutoIncrement ( void ) const
None.
TRUE
if the column is an auto-increment
column, FALSE
if it is not.
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.
CHARSET_INFO* getCharset ( void ) const
None.
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.
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.
int getColumnNo ( void ) const
None.
The column number as an integer.
Gets a column's default value data.
To determine whether a table has any columns with default
values, use
Table::hasDefaultValues()
.
const void* getDefaultValue
(
unsigned int* len
= 0
) const
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.
The default value data.
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.
int getInlineSize ( void ) const
None.
The blob column's inline size, as an integer.
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.
int getLength ( void ) const
None.
The (maximum) array length of the column, as an integer.
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.
const char* getName ( void ) const
None.
The name of the column.
This method is used to determine whether the column can be
set to NULL
.
bool getNullable ( void ) const
None.
A Boolean value: true
if the column can
be set to NULL
, otherwise
false
.
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.
bool getPartitionKey ( void ) const
None.
true
if the column is part of the
partitioning key for the table, otherwise
false
.
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.
int getPartSize ( void ) const
None.
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).
This method gets the precision of a column.
This method is applicable to decimal columns only.
int getPrecision ( void ) const
None.
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.
This method is used to determine whether the column is part of the table's primary key.
bool getPrimaryKey ( void ) const
None.
A Boolean value: true
if the column is
part of the primary key of the table to which this column
belongs, otherwise false
.
This method gets the scale used for a decimal column value.
This method is applicable to decimal columns only.
int getScale ( void ) const
None.
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.
This function is used to obtain the size of a column.
int getSize ( void ) const
None.
The column's size in bytes (an integer value).
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.
int getSizeInBytesForRecord ( void ) const
None.
An integer (see Description).
This method obtains a column's storage type.
StorageType getStorageType ( void ) const
None.
A StorageType
value; for more information
about this type, see
Column::StorageType.
This method gets the stripe size of a blob column—that is, the number of consecutive parts to store in each node group.
int getStripeSize ( void ) const
None.
The column's stripe size, as an integer.
This method gets the column's data type.
Type getType ( void ) const
None.
The Type
(data type) of the column. For a
list of possible values, see
Column::Type.
Sets the array type for the column.
void setArrayType
(
ArrayType type
)
A Column::ArrayType
value.
See Column::ArrayType, for more
information.
None.
Make the column auto-incrementing (or not).
void setAutoIncrement
(
bool flag
)
A boolean value: TRUE
to make the
column auto-incrementing; FALSE
to remove this property of the column.
None.
Set the initial value for an auto-incrementing column.
void setAutoIncrementInitialValue
(
Uint64 value
)
The initial value for the column (a 64-bit integer).
None.
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.
void setCharset
(
CHARSET_INFO* cs
)
This method takes one parameter.
cs
is a pointer to a
CHARSET_INFO
structure. For additional
information, see Column::getCharset().
None.
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()
.
int setDefaultValue ( const void*buf
, unsigned intlen
)
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.
0 on success, 1 on failure..
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.
void setInlineSize
(
int size
)
The integer size
is the new
inline size for the blob column.
None.
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.
void setLength
(
int length
)
This method takes a single argument—the integer value
length
is the new length for the
column.
None.
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.
void setName
(
const char* name
)
This method takes a single argument—the new name for the column.
This method None.
This method toggles the nullability of a column.
Changes made to columns using this method are not visible to MySQL.
void setNullable
(
bool nullable
)
A Boolean value. Using true
makes it
possible to insert NULL
s into the column;
if nullable
is
false
, then this method performs the
equivalent of changing the column to NOT
NULL
in MySQL.
None.
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().
void setPartitionKey
(
bool enable
)
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.
None.
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.
void setPartSize
(
int size
)
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
.
None.
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.
void setPrecision
(
int precision
)
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().
None.
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.
void setPrimaryKey
(
bool primary
)
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.
None.
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.
void setScale
(
int scale
)
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().
None.
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.
void setStripeSize
(
int size
)
This method takes a single argument. The integer
size
is the new stripe size for
the column.
None.
Sets the storage type for the column.
void setStorageType
(
StorageType type
)
A Column::StorageType
value. See Column::StorageType, for
more information.
None.
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.
void setType
(
Type type
)
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.
None.
This section provides information about the
StorageType
data type, which describes the
storage type used by a Column
object.
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
.
Possible values are shown, along with descriptions, in the following table:
Table 2.9 Column object StorageType data type values and descriptions
Name | Description |
---|---|
StorageTypeMemory |
Store the column in memory |
StorageTypeDisk |
Store the column on disk |
This section provides information about the
Type
data type, which is used to describe a
column's data type.
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
.
Possible values are shown, along with descriptions, in the following table:
Table 2.10 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.