NDB_DESC(1)

NAME
ndb_desc - describe NDB tables

SYNOPSIS

ndb_desc options

DESCRIPTION

ndb_desc provides a detailed description of one or more NDB tables. Usage

    ndb_desc -c connection_string tbl_name -d db_name [options]
    ndb_desc -c connection_string index_name -d db_name -t tbl_name

Additional options that can be used with ndb_desc are listed later in this section. Sample Output.PP MySQL table creation and population statements:

    USE test;
    CREATE TABLE fish (
        id INT(11) NOT NULL AUTO_INCREMENT,
        name VARCHAR(20) NOT NULL,
        length_mm INT(11) NOT NULL,
        weight_gm INT(11) NOT NULL,
        PRIMARY KEY pk (id),
        UNIQUE KEY uk (name)
    ) ENGINE=NDB;
    INSERT INTO fish VALUES
        (NULL, 'guppy', 35, 2), (NULL, 'tuna', 2500, 150000),
        (NULL, 'shark', 3000, 110000), (NULL, 'manta ray', 1500, 50000),
        (NULL, 'grouper', 900, 125000), (NULL ,'puffer', 250, 2500);

Output from ndb_desc:

    shell> ./ndb_desc -c localhost fish -d test -p
    -- fish --
    Version: 2
    Fragment type: HashMapPartition
    K Value: 6
    Min load factor: 78
    Max load factor: 80
    Temporary table: no
    Number of attributes: 4
    Number of primary keys: 1
    Length of frm data: 337
    Max Rows: 0
    Row Checksum: 1
    Row GCI: 1
    SingleUserMode: 0
    ForceVarPart: 1
    PartitionCount: 2
    FragmentCount: 2
    PartitionBalance: FOR_RP_BY_LDM
    ExtraRowGciBits: 0
    ExtraRowAuthorBits: 0
    TableStatus: Retrieved
    Table options:
    HashMap: DEFAULT-HASHMAP-3840-2
    -- Attributes --
    id Int PRIMARY KEY DISTRIBUTION KEY AT=FIXED ST=MEMORY AUTO_INCR
    name Varchar(20;latin1_swedish_ci) NOT NULL AT=SHORT_VAR ST=MEMORY DYNAMIC
    length_mm Int NOT NULL AT=FIXED ST=MEMORY DYNAMIC
    weight_gm Int NOT NULL AT=FIXED ST=MEMORY DYNAMIC
    -- Indexes --
    PRIMARY KEY(id) - UniqueHashIndex
    PRIMARY(id) - OrderedIndex
    uk(name) - OrderedIndex
    uk$unique(name) - UniqueHashIndex
    -- Per partition info --
    Partition       Row count       Commit count    Frag fixed memory       Frag varsized memory    Extent_space    Free extent_space
    0               2               2               32768                   32768                   0               0
    1               4               4               32768                   32768                   0               0
    NDBT_ProgramExit: 0 - OK

Information about multiple tables can be obtained in a single invocation of ndb_desc by using their names, separated by spaces. All of the tables must be in the same database.

You can obtain additional information about a specific index using the --table (short form: -t) option and supplying the name of the index as the first argument to ndb_desc, as shown here:

    shell> ./ndb_desc uk -d test -t fish
    -- uk --
    Version: 2
    Base table: fish
    Number of attributes: 1
    Logging: 0
    Index type: OrderedIndex
    Index status: Retrieved
    -- Attributes --
    name Varchar(20;latin1_swedish_ci) NOT NULL AT=SHORT_VAR ST=MEMORY
    -- IndexTable 10/uk --
    Version: 2
    Fragment type: FragUndefined
    K Value: 6
    Min load factor: 78
    Max load factor: 80
    Temporary table: yes
    Number of attributes: 2
    Number of primary keys: 1
    Length of frm data: 0
    Max Rows: 0
    Row Checksum: 1
    Row GCI: 1
    SingleUserMode: 2
    ForceVarPart: 0
    PartitionCount: 2
    FragmentCount: 2
    FragmentCountType: ONE_PER_LDM_PER_NODE
    ExtraRowGciBits: 0
    ExtraRowAuthorBits: 0
    TableStatus: Retrieved
    Table options:
    -- Attributes --
    name Varchar(20;latin1_swedish_ci) NOT NULL AT=SHORT_VAR ST=MEMORY
    NDB$TNODE Unsigned [64] PRIMARY KEY DISTRIBUTION KEY AT=FIXED ST=MEMORY
    -- Indexes --
    PRIMARY KEY(NDB$TNODE) - UniqueHashIndex
    NDBT_ProgramExit: 0 - OK

When an index is specified in this way, the --extra-partition-info and --extra-node-info options have no effect.

The Version column in the output contains the table's schema object version. For information about interpreting this value, see NDB Schema Object Versions[1].

Three of the table properties that can be set using NDB_TABLE comments embedded in CREATE TABLE and ALTER TABLE statements are also visible in ndb_desc output. The table's FRAGMENT_COUNT_TYPE is always shown in the FragmentCountType column. READ_ONLY and FULLY_REPLICATED, if set to 1, are shown in the Table options column. You can see this after executing the following ALTER TABLE statement in the mysql client:

    mysql> ALTER TABLE fish COMMENT='NDB_TABLE=READ_ONLY=1,FULLY_REPLICATED=1';
    1 row in set, 1 warning (0.00 sec)
    mysql> SHOW WARNINGS\G
    +---------+------+---------------------------------------------------------------------------------------------------------+
    | Level   | Code | Message                                                                                                 |
    +---------+------+---------------------------------------------------------------------------------------------------------+
    | Warning | 1296 | Got error 4503 'Table property is FRAGMENT_COUNT_TYPE=ONE_PER_LDM_PER_NODE but not in comment' from NDB |
    +---------+------+---------------------------------------------------------------------------------------------------------+
    1 row in set (0.00 sec)

The warning is issued because READ_ONLY=1 requires that the table's fragment count type is (or be set to) ONE_PER_LDM_PER_NODE_GROUP; NDB sets this automatically in such cases. You can check that the ALTER TABLE statement has the desired effect using SHOW CREATE TABLE:

    mysql> SHOW CREATE TABLE fish\G
    *************************** 1. row ***************************
           Table: fish
    Create Table: CREATE TABLE `fish` (
      `id` int(11) NOT NULL AUTO_INCREMENT,
      `name` varchar(20) NOT NULL,
      `length_mm` int(11) NOT NULL,
      `weight_gm` int(11) NOT NULL,
      PRIMARY KEY (`id`),
      UNIQUE KEY `uk` (`name`)
    ) ENGINE=ndbcluster DEFAULT CHARSET=latin1
    COMMENT='NDB_TABLE=READ_BACKUP=1,FULLY_REPLICATED=1'
    1 row in set (0.01 sec)

Because FRAGMENT_COUNT_TYPE was not set explicitly, its value is not shown in the comment text printed by SHOW CREATE TABLE. ndb_desc, however, displays the updated value for this attribute. The Table options column shows the binary properties just enabled. You can see this in the output shown here (emphasized text):

    shell> ./ndb_desc -c localhost fish -d test -p
    -- fish --
    Version: 4
    Fragment type: HashMapPartition
    K Value: 6
    Min load factor: 78
    Max load factor: 80
    Temporary table: no
    Number of attributes: 4
    Number of primary keys: 1
    Length of frm data: 380
    Max Rows: 0
    Row Checksum: 1
    Row GCI: 1
    SingleUserMode: 0
    ForceVarPart: 1
    PartitionCount: 1
    FragmentCount: 1
    FragmentCountType: ONE_PER_LDM_PER_NODE_GROUP
    ExtraRowGciBits: 0
    ExtraRowAuthorBits: 0
    TableStatus: Retrieved
    Table options: readbackup, fullyreplicated
    HashMap: DEFAULT-HASHMAP-3840-1
    -- Attributes --
    id Int PRIMARY KEY DISTRIBUTION KEY AT=FIXED ST=MEMORY AUTO_INCR
    name Varchar(20;latin1_swedish_ci) NOT NULL AT=SHORT_VAR ST=MEMORY DYNAMIC
    length_mm Int NOT NULL AT=FIXED ST=MEMORY DYNAMIC
    weight_gm Int NOT NULL AT=FIXED ST=MEMORY DYNAMIC
    -- Indexes --
    PRIMARY KEY(id) - UniqueHashIndex
    PRIMARY(id) - OrderedIndex
    uk(name) - OrderedIndex
    uk$unique(name) - UniqueHashIndex
    -- Per partition info --
    Partition       Row count       Commit count    Frag fixed memory       Frag varsized memory    Extent_space    Free extent_space
    NDBT_ProgramExit: 0 - OK

For more information about these table properties, see Section 13.1.18.10, “Setting NDB_TABLE Options”.

The Extent_space and Free extent_space columns are applicable only to NDB tables having columns on disk; for tables having only in-memory columns, these columns always contain the value 0.

To illustrate their use, we modify the previous example. First, we must create the necessary Disk Data objects, as shown here:

    CREATE LOGFILE GROUP lg_1
        ADD UNDOFILE 'undo_1.log'
        INITIAL_SIZE 16M
        UNDO_BUFFER_SIZE 2M
        ENGINE NDB;
    ALTER LOGFILE GROUP lg_1
        ADD UNDOFILE 'undo_2.log'
        INITIAL_SIZE 12M
        ENGINE NDB;
    CREATE TABLESPACE ts_1
        ADD DATAFILE 'data_1.dat'
        USE LOGFILE GROUP lg_1
        INITIAL_SIZE 32M
        ENGINE NDB;
    ALTER TABLESPACE ts_1
        ADD DATAFILE 'data_2.dat'
        INITIAL_SIZE 48M
        ENGINE NDB;

(For more information on the statements just shown and the objects created by them, see Section 21.5.13.1, “NDB Cluster Disk Data Objects”, as well as Section 13.1.15, “CREATE LOGFILE GROUP Syntax”, and Section 13.1.19, “CREATE TABLESPACE Syntax”.)

Now we can create and populate a version of the fish table that stores 2 of its columns on disk (deleting the previous version of the table first, if it already exists):

    CREATE TABLE fish (
        id INT(11) NOT NULL AUTO_INCREMENT,
        name VARCHAR(20) NOT NULL,
        length_mm INT(11) NOT NULL,
        weight_gm INT(11) NOT NULL,
        PRIMARY KEY pk (id),
        UNIQUE KEY uk (name)
    ) TABLESPACE ts_1 STORAGE DISK
    ENGINE=NDB;
    INSERT INTO fish VALUES
        (NULL, 'guppy', 35, 2), (NULL, 'tuna', 2500, 150000),
        (NULL, 'shark', 3000, 110000), (NULL, 'manta ray', 1500, 50000),
        (NULL, 'grouper', 900, 125000), (NULL ,'puffer', 250, 2500);

When run against this version of the table, ndb_desc displays the following output:

    shell> ./ndb_desc -c localhost fish -d test -p
    -- fish --
    Version: 1
    Fragment type: HashMapPartition
    K Value: 6
    Min load factor: 78
    Max load factor: 80
    Temporary table: no
    Number of attributes: 4
    Number of primary keys: 1
    Length of frm data: 346
    Max Rows: 0
    Row Checksum: 1
    Row GCI: 1
    SingleUserMode: 0
    ForceVarPart: 1
    PartitionCount: 2
    FragmentCount: 2
    FragmentCountType: ONE_PER_LDM_PER_NODE
    ExtraRowGciBits: 0
    ExtraRowAuthorBits: 0
    TableStatus: Retrieved
    Table options:
    HashMap: DEFAULT-HASHMAP-3840-2
    -- Attributes --
    id Int PRIMARY KEY DISTRIBUTION KEY AT=FIXED ST=MEMORY AUTO_INCR
    name Varchar(20;latin1_swedish_ci) NOT NULL AT=SHORT_VAR ST=MEMORY
    length_mm Int NOT NULL AT=FIXED ST=DISK
    weight_gm Int NOT NULL AT=FIXED ST=DISK
    -- Indexes --
    PRIMARY KEY(id) - UniqueHashIndex
    PRIMARY(id) - OrderedIndex
    uk(name) - OrderedIndex
    uk$unique(name) - UniqueHashIndex
    -- Per partition info --
    Partition       Row count       Commit count    Frag fixed memory       Frag varsized memory    Extent_space    Free extent_space
    0               2               2               32768                   32768                   1048576         1044440
    1               4               4               32768                   32768                   1048576         1044400
    NDBT_ProgramExit: 0 - OK

This means that 1048576 bytes are allocated from the tablespace for this table on each partition, of which 1044440 bytes remain free for additional storage. In other words, 1048576 - 1044440 = 4136 bytes per partition is currently being used to store the data from this table's disk-based columns. The number of bytes shown as Free extent_space is available for storing on-disk column data from the fish table only; for this reason, it is not visible when selecting from the INFORMATION_SCHEMA.FILES table.

For fully replicated tables, ndb_desc shows only the nodes holding primary partition fragment replicas; nodes with copy fragment replicas (only) are ignored. Beginning with NDB 7.5.4, you can obtain such information, using the mysql client, from the table_distribution_status, table_fragments, table_info, and table_replicas tables in the ndbinfo database.

The following table includes options that are specific to ndb_desc. Additional descriptions follow the table. For options common to most NDB Cluster programs (including ndb_desc), see Options Common to NDB Cluster Programs(1).

Table 21.93. This table describes command-line options for the ndb_desc program

    • --blob-info, -b

    Include information about subordinate BLOB and TEXT columns.

    Use of this option also requires the use of the --extra-partition-info (-p) option.

    • --database=db_name, -d

    Specify the database in which the table should be found.

    • --extra-node-info, -n

    Include information about the mappings between table partitions and the data nodes upon which they reside. This information can be useful for verifying distribution awareness mechanisms and supporting more efficient application access to the data stored in NDB Cluster.

    Use of this option also requires the use of the --extra-partition-info (-p) option.

    • --extra-partition-info, -p

    Print additional information about the table's partitions.

    • --retries=#, -r

    Try to connect this many times before giving up. One connect attempt is made per second.

    • --table=tbl_name, -t

    Specify the table in which to look for an index.

    • --unqualified, -u

    Use unqualified table names.

In NDB 7.5.3 and later, table indexes listed in the output are ordered by ID. Previously, this was not deterministic and could vary between platforms. (Bug #81763, Bug #23547742)

COPYRIGHT

Copyright © 1997, 2017, Oracle and/or its affiliates. All rights reserved.

This documentation is free software; you can redistribute it and/or modify it only under the terms of the GNU General Public License as published by the Free Software Foundation; version 2 of the License.

This documentation is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with the program; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA or see http://www.gnu.org/licenses/.

NOTES

1.  NDB Schema Object Versions
    http://dev.mysql.com/doc/ndb-internals/en/ndb-internals-schema-object-versions.html

SEE ALSO
For more information, please refer to the MySQL Reference Manual, which may already be installed locally and which is also available online at http://dev.mysql.com/doc/.

AUTHOR
Oracle Corporation (http://dev.mysql.com/).