MySQL NDB Cluster API Developer Guide
This section provides information about the Table
class, which models a database table in the NDB API.
None
The Table
class represents a table in an
NDB Cluster database. This class extends the
Object
class, which in turn
is an inner class of the
NdbDictionary
class.
It is possible using the NDB API to create tables
independently of the MySQL server. However, it is usually
not advisable to do so, since tables created in this fashion
cannot be seen by the MySQL server. Similarly, it is
possible using Table
methods to modify
existing tables, but these changes (except for renaming
tables) are not visible to MySQL.
The following table lists the public methods of this class and the purpose or use of each method:
Table 2.78 Table class methods and descriptions
Name | Description |
---|---|
Table() |
Class constructor |
~Table() |
Destructor |
addColumn() |
Adds a column to the table |
aggregate() |
Computes aggregate data for the table |
equal() |
Compares the table with another table |
getColumn() |
Gets a column (by name) from the table |
getDefaultNoPartitionsFlag() |
Checks whether the default number of partitions is being used |
getFragmentCount() |
Gets the number of fragments for this table |
getExtraMetadata() |
Gets extra metadata for this table |
getFragmentData() |
Gets table fragment data (ID, state, and node group) |
getFragmentDataLen() |
Gets the length of the table fragment data |
getFragmentNodes() |
Gets IDs of data nodes on which fragments are located |
getFragmentType() |
Gets the table's FragmentType |
getFrmData() |
Gets the data from the table .FRM file |
getFrmLength() |
Gets the length of the table's .FRM file |
getHashMap() |
Gets the table's hash map. |
getKValue() |
Gets the table's KValue |
getLinearFlag() |
Gets the current setting for the table's linear hashing flag |
getLogging() |
Checks whether logging to disk is enabled for this table |
getMaxLoadFactor() |
Gets the table's maximum load factor |
getMaxRows() |
Gets the maximum number of rows that this table may contain |
getMinLoadFactor() |
Gets the table's minimum load factor |
getName() |
Gets the table's name |
getNoOfColumns() |
Gets the number of columns in the table |
getNoOfPrimaryKeys() |
Gets the number of columns in the table's primary key. |
getObjectId() |
Gets the table's object ID |
getObjectStatus() |
Gets the table's object status |
getObjectType() |
Removed in NDB 7.5.0 (Bug #47960, Bug #11756088) |
getObjectVersion() |
Gets the table's object version |
getPartitionBalance() |
Gets partition balance (fragment count type) used for this table (NDB 7.5.4 and later) |
getPartitionBalanceString() |
Gets partition balance used for this table, as a string (NDB 7.5.4 and later) |
getPartitionId() |
Gets a partition ID from a hash value |
getPrimaryKey() |
Gets the name of the table's primary key |
getRangeListData() |
Gets a RANGE or LIST array |
getRangeListDataLen() |
Gets the length of the table RANGE or
LIST array |
getRowChecksumIndicator() |
Checks whether the row checksum indicator has been set |
getRowGCIIndicator() |
Checks whether the row GCI indicator has been set |
getSingleUserMode() |
Gets the SingleUserMode for this
table |
getTableId() |
Gets the table's ID |
getTablespace() |
Gets the tablespace containing this table |
getTablespaceData() |
Gets the ID and version of the tablespace containing the table |
getTablespaceDataLen() |
Gets the length of the table's tablespace data |
getTablespaceNames() |
Gets the names of the tablespaces used in the table fragments |
hasDefaultValues() |
Determine whether table has any columns using default values |
setDefaultNoPartitionsFlag() |
Toggles whether the default number of partitions should be used for the table |
setExtraMetadata() |
Sets extra metadata for this table |
getFragmentCount() |
Gets the number of fragments for this table |
setFragmentData() |
Sets the fragment ID, node group ID, and fragment state |
setFragmentType() |
Sets the table's FragmentType |
setFrm() |
Sets the .FRM file to be used for this table |
setHashMap() |
Sets the table's hash map. |
setKValue() |
Set the KValue |
setLinearFlag() |
Sets the table's linear hashing flag |
setLogging() |
Toggle logging of the table to disk |
setMaxLoadFactor() |
Set the table's maximum load factor
(MaxLoadFactor ) |
setMaxRows() |
Sets the maximum number of rows in the table |
setMinLoadFactor() |
Set the table's minimum load factor
(MinLoadFactor ) |
setPartitionBalance() |
Sets the partition balance (fragment count type) for this table (NDB 7.5.4 and later) |
setName() |
Sets the table's name |
setObjectType() |
Removed in NDB 7.5.0 (Bug #47960, Bug #11756088) |
setRangeListData() |
Sets LIST and RANGE partition data |
setRowChecksumIndicator() |
Sets the row checksum indicator |
setRowGCIIndicator() |
Sets the row GCI indicator |
setSingleUserMode() |
Sets the SingleUserMode value for
this table |
setStatusInvalid() |
|
setTablespace() |
Set the tablespace to use for this table |
setTablespaceData() |
Sets the tablespace ID and version |
setTablespaceNames() |
Sets the tablespace names for fragments |
validate() |
Validates the definition for a new table prior to creating it |
The Table
class defines a single public
type SingleUserMode
.
The assignment (=
) operator is overloaded for
this class, so that it always performs a deep copy.
As with other database objects,
Table
object creation and
attribute changes to existing tables done using the NDB API are
not visible from MySQL. For example, if you add a new column to a
table using Table::addColumn()
,
MySQL cannot see the new column. The only exception to this rule
with regard to tables is that a change of name of an existing
NDB
table using
Table::setName()
is visible to
MySQL.
Calculating Table Sizes. When calculating the data storage one should add the size of all attributes (each attribute consuming a minimum of 4 bytes) and well as 12 bytes overhead. Variable size attributes have a size of 12 bytes plus the actual data storage parts, with an additional overhead based on the size of the variable part. For example, consider a table with 5 attributes: one 64-bit attribute, one 32-bit attribute, two 16-bit attributes, and one array of 64 8-bit attributes. The amount of memory consumed per record by this table is the sum of the following:
8 bytes for the 64-bit attribute
4 bytes for the 32-bit attribute
8 bytes for the two 16-bit attributes, each of these taking up 4 bytes due to right-alignment
64 bytes for the array (64 * 1 byte per array element)
12 bytes overhead
This totals 96 bytes per record. In addition, you should assume an overhead of about 2% for the allocation of page headers and wasted space. Thus, 1 million records should consume 96 MB, and the additional page header and other overhead comes to approximately 2 MB. Rounding up yields 100 MB.
Adds a column to a table.
void addColumn
(
const Column& column
)
A reference to the column which is to be added to the table.
This method's return type is void
,
but it does create a copy of the original
Column
object.
This method computes aggregate data for the table. It is
required in order for aggregate methods such as
getNoOfPrimaryKeys()
to work properly before the table has been created and
retrieved via
getTableId()
.
int aggregate
(
struct NdbError& error
)
A reference to an NdbError
object.
An integer, whose value is 0
on success,
and -1
if the table is in an inconsistent
state. In the latter case, the
error
is also set.
Creates a Table
instance.
There are two versions of the
Table
constructor, one for
creating a new instance, and a copy constructor.
Tables created in the NDB API using this method are not accessible from MySQL.
New instance:
Table
(
const char* name
= ""
)
Copy constructor:
Table
(
const Table& table
)
For a new instance, the name of the table to be created. For a copy, a reference to the table to be copied.
A Table
object.
virtual ~Table()
This method is used to obtain a column definition, given either the index or the name of the column.
This method can be invoked using either the column ID or column name, as shown here:
Column* getColumn ( const intAttributeId
) Column* getColumn ( const char*name
)
Either of: the column's index in the table (as it would
be returned by the column's
getColumnNo()
method), or the name of the
column.
A pointer to the column with the specified index or name. If
there is no such column, then this method returns
NULL
.
This method is used to find out whether the default number of partitions is used for the table.
Uint32 getDefaultNoPartitionsFlag ( void ) const
None.
A 32-bit unsigned integer.
Get and unpack extra metadata for this table.
This method was added in NDB 8.0.13.
int getExtraMetadata ( Uint32&version
, void**data
, Uint32*length
) const
This method takes the following three parameters:
version
: By convention, as
used in NDB Cluster code, 1
means
that the extra metadata contains a
.frm
file (BLOB
)
as in NDB 7.6 and earlier; 2
indicates that it is serialized dictionary information
as in NDB 8.0. The values are actually arbritrary, and
application-specific.
data
: The stored data
retrieved as metadata.
length
: The length of the
stored data (metadata).
Returns 0
on success, any other value on
failure. A nonzer4o value should be interpreted as an error
code for the type of error.
This method gets the number of fragments in the table.
Uint32 getFragmentCount ( void ) const
None.
The number of table fragments, as a 32-bit unsigned integer.
This method gets the table's fragment data (ID, state, and node group).
const void* getFragmentData ( void ) const
None.
A pointer to the data to be read.
Gets the length of the table fragment data to be read, in bytes.
Uint32 getFragmentDataLen ( void ) const
None.
The number of bytes to be read, as an unsigned 32-bit integer.
This method retrieves a list of nodes storing a given fragment.
Uint32 getFragmentNodes ( Uint32fragmentId
, Uint32*nodeIdArrayPtr
, Uint32arraySize
) const
This method takes the following three parameters:
fragmentId
: The ID of the
desired fragment.
nodeIdArrayPtr
: Pointer to an
array of node IDs of the nodes containing this fragment.
Normally, the primary fragment is entry 0 in this array.
arraySize
: The size of the
array containing the node IDs. If this is less than the
number of fragments, then only the first
arraySize
entries are written
to this array.
A return value of 0
indicates an error;
otherwise, this is the number of table fragments, as a
32-bit unsigned integer.
This method gets the table's fragmentation type.
FragmentType getFragmentType ( void ) const
None.
An Object::FragmentType
value.
The the data from the .FRM
file
associated with the table.
const void* getFrmData ( void ) const
None.
A pointer to the .FRM
data.
Gets the length of the table's
.FRM
file data, in bytes.
Uint32 getFrmLength ( void ) const
None.
The length of the .FRM
file data (an
unsigned 32-bit integer).
Get the hash map used for this table.
bool getHashMap ( Uint32*id
= 0, Uint32*version
= 0 ) const
The table ID and version.
True if the table has a hash map, otherwise false.
This method gets the KValue, a hashing parameter which is
currently restricted to the value 6
. In a
future release, it may become feasible to set this parameter
to other values.
int getKValue ( void ) const
None.
An integer (currently always 6
).
This method retrieves the value of the table's linear hashing flag.
bool getLinearFlag ( void ) const
None.
true
if the flag is set, and
false
if it is not.
This class is used to check whether a table is logged to disk—that is, whether it is permanent or temporary.
bool getLogging ( void ) const
None.
Returns a Boolean value. If this method returns
true
, then full checkpointing and logging
are done on the table. If false
, then the
table is a temporary table and is not logged to disk; in the
event of a system restart the table still exists and retains
its definition, but it will be empty. The default logging
value is true
.
This method returns the load factor (a hashing parameter) when splitting of the containers in the local hash tables begins.
int getMaxLoadFactor ( void ) const
None.
An integer whose maximum value is 100. When the maximum value is returned, this means that memory usage is optimised. Smaller values indicate that less data is stored in each container, which means that keys are found more quickly but more memory is consumed.
This method gets the maximum number of rows that the table can hold. This is used for calculating the number of partitions.
Uint64 getMaxRows ( void ) const
None.
The maximum number of table rows, as a 64-bit unsigned integer.
This method gets the value of the load factor when reduction
of the hash table begins. This should always be less than
the value returned by getMaxLoadFactor()
.
int getMinLoadFactor ( void ) const
None.
A percentage expressed as an integer; see Table::getMaxLoadFactor().
Gets the name of a table.
const char* getName ( void ) const
None.
The name of the table (a string).
This method is used to obtain the number of columns in a table.
int getNoOfColumns ( void ) const
None.
An integer representing the number of columns in the table.
This method finds the number of primary key columns in the table.
int getNoOfPrimaryKeys ( void ) const
None.
An integer representing the number of primary key columns in the table.
This method gets the table's object ID.
virtual int getObjectId ( void ) const
None.
The object ID is returned as an integer.
This method gets the table's status..
virtual Object::Status getObjectStatus ( void ) const
None.
An Object::Status
value.
This method did not work as intended, and was removed in NDB 7.5.0 (Bug #47960, Bug #11756088).
Object::Type getObjectType ( void ) const
None.
Returns an Object::Type
value.
This method gets the table's object version (see NDB Schema Object Versions).
virtual int getObjectVersion ( void ) const
None.
The table's object version, as an integer.
This method gets the table' partition balance scheme (fragment count type).
Prior to NDB 7.5.4, this method was known as
getFragmentCountType()
.
Object::PartitionBalance getPartitionBalance ( void ) const
None.
The partition balancing scheme, as a value of type
Object::PartitionBalance
.
This method gets the table' partition balance scheme (fragment count type), and returns it as a string.
Prior to NDB 7.5.4, this method was known as
getFragmentCountTypeString()
.
const char* getPartitionBalanceString ( void ) const
None.
The partition balancing scheme, as a string value.
Gets a table partition ID, given its hash value.
Uint32 getPartitionId
(
Uint32 hashvalue
) const
A hashvalue
. Note that if the
table has not actually been retrieved (using, for example,
getTableId()
), then
the result is likely not to be accurate or useful.
The identifier of the partition corresponding to the
hashvalue
.
This method is used to obtain the name of the table's primary key.
const char* getPrimaryKey
(
int no
) const
None.
The name of the primary key, a string (character pointer).
This method gets the range or list data associated with the table.
const void* getRangeListData ( void ) const
None.
A pointer to the data.
This method gets the size of the table's range or list array.
Uint32 getRangeListDataLen ( void ) const
None.
The length of the list or range array, as an integer.
Check whether the row checksum indicator has been set.
bool getRowChecksumIndicator ( void ) const
None.
A true
or false
value.
Checks whether the row GCI indicator has been set.
bool getRowGCIIndicator ( void ) const
None.
A true
or false
value.
Gets the single user mode of the table.
enum SingleUserMode getSingleUserMode ( void ) const
None.
A SingleUserMode
value.
This method gets a table's ID.
int getTableId ( void ) const
None.
The table ID, as an integer.
This method is used in two ways: to obtain the name of the tablespace to which this table is assigned; to verify that a given tablespace is the one being used by this table.
To obtain the name of the tablespace, invoke without any arguments:
const char* getTablespace ( void ) const
To determine whether the tablespace is the one indicated by the given ID and version, supply these as arguments, as shown here:
bool getTablespace ( Uint32*id
= 0, Uint32*version
= 0 ) const
The number and types of parameters depend on how this method is being used:
When used to obtain the name of the tablespace in use by the table, it is called without any arguments.
When used to determine whether the given tablespace is the one being used by this table, then getTablespace() takes two parameters:
The tablespace id
, given
as a pointer to a 32-bit unsigned integer
The tablespace version
,
also given as a pointer to a 32-bit unsigned integer
The default value for both id
and version
is
0
.
The return type depends on how the method is called:
When getTablespace()
is called
without any arguments, it returns a
Tablespace
object
instance.
When called with two arguments, it returns
true
if the tablespace is the same as
the one having the ID and version indicated; otherwise,
it returns false
.
This method gets the table's tablespace data (ID and version).
const void* getTablespaceData ( void ) const
None.
A pointer to the data.
This method is used to get the length of the table's tablespace data.
Uint32 getTablespaceDataLen ( void ) const
None.
The length of the data, as a 32-bit unsigned integer.
This method gets a pointer to the names of the tablespaces used in the table fragments.
const void* getTablespaceNames ( void )
None.
Returns a pointer to the tablespace name data.
This method gets the length of the tablespace name data
returned by getTablespaceNames()
. (See
Table::getTablespaceNames().)
Uint32 getTablespaceNamesLen ( void ) const
None.
Returns the length of the name data, in bytes, as a 32-but unsigned integer.
Used to determine whether the table has any columns that are
defined with default values other than
NULL
.
To read and write default column values, use
Column::getDefaultValue()
and
Column::setDefaultValue()
.
bool hasDefaultValues ( void ) const
None.
Returns true
if the table has any
non-NULL
columns with default values,
otherwise false
.
This method sets an indicator that determines whether the default number of partitions is used for the table.
void setDefaultNoPartitionsFlag
(
Uint32 indicator
) const
This method takes a single argument
indicator
, a 32-bit unsigned
integer.
None.
Store packed extra metadata for this table. The data is
packed without any modification into the buffer of the given
Table
object.
Added in NDB 8.0.13.
int setExtraMetadata ( Uint32version
, const void*data
, Uint32length
)
The three parameters used by this method are listed here:
version
: As used in NDB
Cluster code, 1
means that the extra
metadata contains a .frm
file
(BLOB
) as in NDB 7.6 and earlier;
2
indicates that it is serialized
dictionary information as in NDB 8.0. You should be
aware that this is merely a convention, and the values
can be application-specific, as desired.
data
: The actual data to be
stored as metadata.
length
: The length of the
data to be stored.
0
on success. Any other value indicates
failure; in this case, the value is an error code indicating
indicating the type of error.
Sets the number of table fragments.
void setFragmentCount
(
Uint32 count
)
count
is the number of fragments
to be used for the table.
None.
This method writes an array containing the following fragment information:
Fragment ID
Node group ID
Fragment State
void setFragmentData ( const void*data
, Uint32len
)
This method takes the following two parameters:
A pointer to the fragment data to be written
The length (len
) of this
data, in bytes, as a 32-bit unsigned integer
None.
This method sets the table's fragmentation type.
void setFragmentType
(
FragmentType fragmentType
)
This method takes one argument, an
Object::FragmentType
value.
None.
This method is used to write data to this table's
.FRM
file.
void setFrm ( const void*data
, Uint32len
)
This method takes the following two arguments:
A pointer to the data
to be
written.
The length (len
) of the data.
None.
Set a hash map for the table.
int setHashMap ( const class HashMap & )
A reference to the hash map.
Returns 0 on success; on failure, returns -1 and sets error.
This sets the KValue
, a hashing
parameter.
void setKValue
(
int kValue
)
kValue
is an integer. Currently
the only permitted value is 6
. In a
future version this may become a variable parameter.
None.
Set the table's linear hash flag. See Table::getLinearFlag().
void setLinearFlag
(
Uint32 flag
)
The flag
is a 32-bit unsigned
integer.
None.
Toggles the table's logging state. See Table::getLogging().
void setLogging
(
bool enable
)
If enable
is
true
, then logging for this table is
enabled; if it is false
, then logging is
disabled.
None.
This method sets the maximum load factor when splitting the containers in the local hash tables.
void setMaxLoadFactor
(
int max
)
This method takes a single parameter
max
, an integer representation of
a percentage (for example, 45
represents
45 percent). For more information, see
Table::getMaxLoadFactor().
This should never be greater than the minimum load factor.
None.
This method sets the maximum number of rows that can be held by the table.
void setMaxRows
(
Uint64 maxRows
)
maxRows
is a 64-bit unsigned
integer that represents the maximum number of rows to be
held in the table.
None.
This method sets the minimum load factor when reduction of the hash table begins.
void setMinLoadFactor
(
int min
)
This method takes a single parameter
min
, an integer representation of
a percentage (for example, 45
represents
45 percent). For more information, see
Table::getMinLoadFactor().
None.
This method sets the name of the table.
This is the only
set
method
of *
()Table
whose effects are
visible to MySQL.
void setName
(
const char* name
)
name
is the (new) name of the
table.
None.
This method did not work as intended, and was removed in NDB 7.5.0 (Bug #47960, Bug #11756088).
void setObjectType
(
Object::Type type
)
The desired object type
. This
must be one of the Type
values listed in
Object::Type.
None.
Sets the table's partition balancing scheme.
Prior to NDB 7.5.4, this method was known as
setFragmentCountType()
.
void setPartitionBalance
(
Object::PartitionBalance scheme
)
scheme
is the partition balancing
scheme to be used for the table. This is a value of type
PartitionBalance
.
None.
This method sets an array containing information that maps range values and list values to fragments. This is essentially a sorted map consisting of fragment-ID/value pairs. For range partitions there is one pair per fragment. For list partitions it could be any number of pairs, but at least as many pairs as there are fragments.
void setRangeListData ( const void*data
, Uint32len
)
This method requires the following two parameters:
A pointer to the range or list
data
containing the ID/value
pairs
The length (len
) of this
data, as a 32-bit unsigned integer.
None.
Set the row checksum indicator.
void setRowChecksumIndicator
(
bool value
) const
A true
or false
value
.
None.
Sets the row GCI indicator.
void setRowGCIIndicator
(
bool value
) const
A true
or false
value
.
None.
Sets a SingleUserMode
for the table.
void setSingleUserMode
(
enum SingleUserMode
)
A SingleUserMode
value.
None.
Forces the table's status to be invalidated.
void setStatusInvalid ( void ) const
None.
None.
This method sets the tablespace for the table.
Using the name of the tablespace:
void setTablespace
(
const char* name
)
Using a Tablespace
object:
void setTablespace
(
const class Tablespace& tablespace
)
This method can be called with a single argument, which can be of either one of these two types:
The name
of the tablespace (a
string).
A reference to an existing
Tablespace
instance.
None.
This method sets the tablespace information for each fragment, and includes a tablespace ID and a tablespace version.
void setTablespaceData ( const void*data
, Uint32len
)
This method requires the following two parameters:
A pointer to the data
containing the tablespace ID and version
The length (len
) of this
data, as a 32-bit unsigned integer.
None.
Sets the names of the tablespaces used by the table fragments.
void setTablespaceNames ( const void*data
Uint32len
)
This method takes the following two parameters:
A pointer to the tablespace names
data
The length (len
) of the names
data, as a 32-bit unsigned integer.
None.
This section provides information about the
SingleUserMode
data type.
Single user mode specifies access rights to the table when single user mode is in effect.
Possible values for SingleUserMode
are
shown, along with descriptions, in the following table:
Table 2.79 Table::SingleUserMode values and descriptions
Name | Description |
---|---|
SingleUserModeLocked |
The table is locked (unavailable). |
SingleUserModeReadOnly |
The table is available in read-only mode. |
SingleUserModeReadWrite |
The table is available in read-write mode. |
This method validates the definition for a new table prior
to creating it, executes the
Table::aggregate()
method,
and performs additional checks.
validate()
is called automatically when a
table is created or retrieved. For this reason, it is
usually not necessary to call aggregate()
or validate()
directly.
You should be aware that, even after the
validate()
method is called, there may
still exist errors which can be detected only by the
NDB
kernel when the table is actually
created.
int validate
(
struct NdbError& error
)
A reference to an NdbError
object.
An integer, whose value is 0
on success,
and -1
if the table is in an inconsistent
state. In the latter case, the
error
is also set.