无

无

任何重要的 NDB API 程序都至少使用一个 Ndb 实例。通过使用多个 Ndb 对象，可以实现多线程应用程序。您应该记住，一个 Ndb 对象不能在多个线程之间共享；但是，单个线程可以使用多个 Ndb 对象。单个应用程序进程最多支持 4711 个 Ndb 对象。

下表列出了此类的公共方法，以及每个方法的目的或用途

Ndb 类不定义任何公共类型，但定义了三个数据结构，列出如下

这将创建一个 Ndb 实例，它代表与 NDB 集群的连接。所有 NDB API 应用程序都应从创建至少一个 Ndb 对象开始。这需要创建至少一个 Ndb_cluster_connection 实例，它充当集群连接字符串的容器。

Ndb
    (
      Ndb_cluster_connection* ndb_cluster_connection,
      const char*                    catalogName = "",
      const char*                    schemaName = "def"
    )

Ndb 类构造函数最多可以接受 3 个参数，其中只有第一个是必需的

一个 Ndb 对象。

应调用 Ndb 类的析构函数以终止 Ndb 实例。它不需要任何参数，也不需要任何特殊处理。

这是 NDB API 提供的用于关闭事务的两种方法之一（另一种是 NdbTransaction::close()）。您必须在事务完成后调用这两个方法中的一个以关闭事务，无论事务是否成功。

如果事务尚未提交，则在调用此方法时会中止事务。见 Ndb::startTransaction()。

void closeTransaction
    (
      NdbTransaction *transaction
    )

此方法接受一个参数，一个指向要关闭的 NdbTransaction 的指针。

无 (void)。

此方法可用于计算分布哈希值，给定一个表及其键。

computeHash() 只能用于使用原生 NDB 分区的表。

static int computeHash
    (
      Uint32*                     hashvalueptr,
      const NdbDictionary::Table* table,
      const struct Key_part_ptr*  keyData,
      void*                       xfrmbuf = 0,
      Uint32                      xfrmbuflen = 0
    )

此方法采用以下参数

成功时为 0，失败时为错误代码。如果方法调用成功，则可以通过 hashvalueptr 获得计算出的哈希值。

此方法创建一个对数据库事件的订阅。

NDB API 事件订阅在使用 ndb_restore 恢复 NDB 集群后不会持久存在；在这种情况下，必须显式重新创建所有订阅。

NdbEventOperation* createEventOperation
    (
      const char *eventName
    )

此方法接受一个参数，即标识您要订阅的事件的唯一 eventName。

指向一个 NdbEventOperation 对象的指针（或 NULL，如果失败）。见 第 2.3.16 节，“NdbEventOperation 类”。

此方法删除由 NdbEventOperation 对象表示的对数据库事件的订阅。

已删除的事件操作使用的内存不会在事件缓冲区完全读取之前释放。这意味着您必须继续调用 pollEvents() 和 nextEvent()，直到这些方法分别返回 0 和 NULL，以便释放此内存。

int dropEventOperation
    (
      NdbEventOperation *eventOp
    )

此方法需要一个输入参数，一个指向 NdbEventOperation 实例的指针。

0 表示成功；任何其他结果都表示失败。

Ndb

此结构是在 NDB 7.4 中添加的，用于处理事件缓冲区内存使用统计信息。它用作 Ndb::get_event_buffer_memory_usage() 的参数。

EventBufferMemoryUsage 具有下表所示的属性

此方法用于获取一个对象，用于检索或操作数据库模式信息。这个 Dictionary 对象包含有关集群中所有表的元信息。

此方法返回的字典独立于任何事务运行。见 第 2.3.3 节，“Dictionary 类”，以获取更多信息。

NdbDictionary::Dictionary* getDictionary
    (
      void
    ) const

无.

一个 Dictionary 类实例。

此方法可用于获取当前数据库的名称。

const char* getDatabaseName
    (
      void
    )

无。

当前数据库的名称。

此方法可用于获取当前数据库模式的名称。

const char* getDatabaseSchemaName
    (
      void
    )

无.

当前数据库模式的名称。

迭代当前 GCI 中包含的各个事件操作，在调用 nextEvent() 后变得有效。您可以使用此方法在处理事件数据之前获取纪元摘要信息（例如，所有表的列表）。

此方法已弃用，并且可能会在未来的版本中删除。在可能的情况下，请使用 getNextEventOpInEpoch2() 代替。

const NdbEventOperation* getGCIEventOperations
    (
      Uint32* iter,
      Uint32* event_types
    )

一个迭代器和一个事件类型掩码。将 *iter=0 设置为开始。

下一个事件操作；当没有更多事件操作时返回 NULL。如果 event_types 不为 NULL，则在调用该方法后，它将包含收到的事件类型的位掩码。。

获取可用于事件缓冲区的最大内存（以字节为单位）。这与在 MySQL Server 中读取 ndb_eventbuffer_max_alloc 系统变量的值相同。

unsigned get_eventbuf_max_alloc
    (
      void
    )

无.

事件缓冲区可用的最大内存，以字节为单位。

获取 ndb_eventbuffer_free_percent，即在 ndb_eventbuffer_max_alloc 已达上限后，在恢复缓冲之前，应保留的事件缓冲区内存的百分比。此值计算为 used * 100 / ndb_eventbuffer_max_alloc，其中 used 是实际使用的事件缓冲区内存量，以字节为单位。

此方法是在 NDB 7.4 中添加的。

unsigned get_eventbuffer_free_percent
    (
      void
    )

必须存在的事件缓冲区内存的百分比 (pct)。有效范围为 1 到 99（含）。

无.

获取事件缓冲区使用率，以 ndb_eventbuffer_max_alloc 的百分比表示。与 get_eventbuffer_free_percent() 不同，此方法以 EventBufferMemoryUsage 数据结构的形式提供完整的使用信息。

此方法是在 NDB 7.4 中添加的。

void get_event_buffer_memory_usage
    (
      EventBufferMemoryUsage&
    )

指向一个 EventBufferMemoryUsage 结构的引用，该结构接收使用数据。

无.

在 NDB 7.4 中添加，此方法取代了 getLatestGCI()，该方法现在已弃用，并且可能会在未来的 NDB 集群版本中删除。

在 NDB 7.4.7 之前，此方法返回事件队列中最大的纪元编号。在 NDB 7.4.7 及更高版本中，它返回在调用 pollEvents2() 后找到的最大的纪元编号。（错误 #20700220）

Uint64 getHighestQueuedEpoch
    (
      void
    )

无.

最近的纪元编号，一个整数。

获取最新的全局检查点的索引。

此方法在 NDB 7.4 中已弃用，并且可能会在未来的版本中删除。在 NDB 7.4 及更高版本中，您应使用 getHighestQueuedEpoch() 代替。

Uint64 getLatestGCI
    (
      void
    )

无.

最新的 GCI，一个整数。

此方法提供两种不同的方法来获取一个 NdbError 对象，该对象表示错误条件。有关 NDB API 中错误处理的更详细的信息，请参见 NDB 集群 API 错误。

getNdbError() 方法实际上有两个变体。

第一个变体只获取最近发生的错误

const NdbError& getNdbError
    (
      void
    )

第二个变体返回与给定错误代码对应的错误

const NdbError& getNdbError
    (
      int errorCode
    )

无论使用哪种版本的该方法，返回的 NdbError 对象一直持续到下一个 NDB API 方法被调用。

要获取最近发生的错误，只需调用不带任何参数的 getNdbError() 即可。要获取与特定 errorCode 匹配的错误，请调用该方法并将其传递给它作为参数 (一个 int)。有关 NDB API 错误代码和相应错误消息的列表，请参见 第 2.4 节，“NDB API 错误和错误处理”。

一个 NdbError 对象，其中包含有关错误的信息，包括其类型以及在适用的情况下，有关错误如何发生的上下文信息。有关详细信息，请参见 第 2.3.15 节，“NdbError 结构”。

此方法提供了一种简单而安全的方法来访问有关错误的任何额外信息。与从 NdbError 对象的 details 属性 (现在已弃用，转而使用 getNdbErrorDetail()，参见 Bug #48851) 读取这些额外详细信息不同，此方法允许将这些详细信息存储在用户提供的缓冲区中，并返回指向该缓冲区开头的指针。如果包含详细信息的字符串超过缓冲区长度，则会将其截断以适应缓冲区。

getErrorDetail() 以字符串的形式提供错误的来源。在唯一约束违反的情况下 (错误 893)，此字符串提供问题起源的索引的完全限定名称，格式为 database-name/schema-name/table-name/index-name，(NdbError.details 另一方面，只提供索引 ID，而且通常不清楚该索引属于哪个表。) 无论错误的类型和有关此错误的详细信息如何，由 getErrorDetail() 检索的字符串始终以 null 结尾。

getNdbErrorDetail() 方法具有以下签名

const char* getNdbErrorDetail
            (
              const NdbError& error,
              char*           buffer,
              Uint32          bufferLength
            ) const

要获取有关错误的详细信息，请使用对相应 NdbError 对象、buffer 和该缓冲区的长度 (以无符号 32 位整数表示) 的引用调用 getNdbErrorDetail()。

当 error 的额外详细信息可用时，此方法将返回指向提供的 buffer 开头的指针。如前所述，如果包含详细信息的字符串长于 bufferLength，则字符串将被截断以适应缓冲区。如果没有任何额外详细信息可用，getNdbErrorDetail() 将返回 NULL。

如果在 Ndb 对象初始化之前为其设置了名称，则可以使用此方法检索该名称。用于调试。

const char* getNdbObjectName
    (
      void
    ) const

无.

Ndb 对象的名称 (如果已使用 setNdbObjectName() 设置)。否则，此方法将返回 0。

迭代构成当前全局检查点的单个事件操作。使用以下 nextEvent2() 获取时期的摘要信息，例如所有表的列表，然后再处理事件数据。

异常时期没有与之关联的任何事件操作。

const NdbEventOperation* getNextEventOpInEpoch2
    (
      Uint32* iter,
      Uint32* event_types
    )

最初将 iter 设置为 0；当此时期内没有更多事件时，此值将为 NULL。如果 event_types 不为 NULL，它将保存接收到的事件类型的位掩码。

指向下一个 NdbEventOperation 的指针 (如果有)。

迭代构成当前全局检查点的单个事件操作。使用以下 nextEvent2() 获取时期的摘要信息，例如所有表的列表，然后再处理事件数据。与 getNextEventOpInEpoch3() 相同，但新增了第三个参数，该参数保存接收到的所有 AnyValues 的合并结果，显示为给定表上的所有操作设置了哪些位。

异常时期没有与之关联的任何事件操作。

此方法是在 NDB 7.4.18 和 7.5.9 中添加的。(Bug #26333981)

const NdbEventOperation* getNextEventOpInEpoch2
    (
      Uint32* iter,
      Uint32* event_types
      Uint32* cumulative_any_value
    )

最初将 iter 设置为 0；当此时期内没有更多事件时，此值将为 NULL。如果 event_types 不为 NULL，它将保存接收到的事件类型的位掩码。如果 cumulative_any_value 不为 NULL，它将保存接收到的所有 AnyValues 的合并结果。

指向下一个 NdbEventOperation 的指针 (如果有)。

此方法可用于获取对给定 Ndb 对象的引用。此值与 DUMP 2350 输出中与该对象对应的给定操作返回的值相同。

Uint32 getReference
    (
      void
    )

无.

一个 32 位无符号整数。

此方法用于初始化 Ndb 对象。

int init
    (
      int maxNoOfTransactions = 4
    )

init() 方法接受一个类型为整数的单个参数 maxNoOfTransactions。此参数指定此 Ndb 实例可以处理的并行 NdbTransaction 对象的最大数量。maxNoOfTransactions 的最大允许值为 1024；如果未指定，则默认为 4。

每个扫描或索引操作都会使用额外的 NdbTransaction 对象。

此方法返回一个 int，它可以是以下两个值之一

检查所有事件是否一致。如果在资源耗尽时发生节点故障，事件可能会丢失，因此传递的事件数据可能不完整。此方法可以确定是否发生了这种情况。

此方法在 NDB 7.4 中已弃用，并且将在未来的版本中被删除。在 NDB 7.4 及更高版本中，您应该使用 NdbEventOperation::getEventType2() 来确定事件的类型，在本例中，确定事件是否为类型 TE_INCONSISTENT。请参见 Event::TableEvent。

bool isConsistent
    (
      Uint64& gci
    )

对全局检查点索引的引用。如果存在任何不一致，这是找到的第一个不一致 GCI。

如果所有事件都一致，则为 true。

如果在资源耗尽时发生节点故障，事件可能会丢失，因此传递的事件数据可能不完整。此方法可以通过检查给定 GCI 中的所有事件是否一致来确定是否发生了这种情况。

此方法在 NDB 7.4 中已弃用，并且将在未来的版本中被删除。在 NDB 7.4 及更高版本中，您应该使用 NdbEventOperation::getEventType2() 来确定事件的类型，在本例中，确定事件是否为类型 TE_INCONSISTENT。请参见 Event::TableEvent。

bool isConsistentGCI
    (
      Uint64 gci
    )

一个全局检查点索引。

如果此 GCI 一致，则为 true；false 表示 GCI 可能不一致。

检查最后一次调用 Ndb::pollEvents2() 时是否已看到更高的排队时期，或者是否找到了 TE_CLUSTER_FAILURE 事件。

在检测到集群故障后，有可能 pollEvents2() 返回的最高排队时期不再增加。在这种情况下，您应该使用 nextEvent() 使用事件，而不是轮询更多事件，直到检测到 TE_CLUSTER_FAILURE，然后在集群再次可用时重新连接到集群。

bool isExpectingHigherQueuedEpochs
      (
        void
      )

无.

如果最后一次调用 pollEvents2() 时已看到排队时期，或在集群发生故障时，则为 true。

Ndb

Key_part_ptr 提供了一种方便的方式来定义开始事务和计算哈希值时的键部分数据，方法是传入指向分布键值的指针。当分布键包含多个部分时，应将其作为数组传入，最后一个部分的指针应设置为 NULL。有关此结构如何使用的更多信息，请参见 Ndb::startTransaction() 和 Ndb::computeHash()。

Key_part_ptr 具有下表中显示的属性

返回订阅队列中包含数据的下一个事件操作。

此方法在处理事件时会从事件队列中清除不一致的数据事件。为了能够清除所有此类事件，即使在 pollEvents() 已返回 0 的情况下，应用程序也必须调用此方法。

此方法在 NDB 7.4 中已弃用，并且将在未来的版本中被删除。在 NDB 7.4 及更高版本中，您应该使用 nextEvent2() 代替。

NdbEventOperation* nextEvent
    (
      void
    )

无。

此方法返回一个 NdbEventOperation 对象，该对象表示订阅队列中的下一个事件 (如果有)。如果队列中没有事件，它将返回 NULL。

返回与从事件队列中出队的关联的事件操作。在 pollEvents2() 填充队列后，应重复调用此方法，直到事件队列为空。

此方法是在 NDB 7.4 中添加的，它取代了 nextEvent()，后者现在已弃用，并将被删除，以便在将来的 NDB 集群版本中使用。

调用此方法后，使用 NdbEventOperation::getEpoch() 确定纪元，然后使用 NdbEventOperation::getEventType2() 检查返回事件数据的类型。必须针对所有异常 TableEvent 类型提供处理，包括 TE_EMPTY、TE_INCONSISTENT 和 TE_OUT_OF_MEMORY（也引入 NDB 7.4）。对于异常纪元，不应调用此处命名的两个方法以外的任何其他 NdbEventOperation 方法。返回空纪元 (TE_EMPTY) 可能会在数据节点处于空闲状态时淹没应用程序。如果这是不可取的，应用程序应该过滤掉任何空纪元。

NdbEventOperation* nextEvent2
    (
      void
    )

无。

此方法返回一个 NdbEventOperation 对象，表示事件队列中的下一个事件（如果有这样的事件）。如果队列中没有事件，它将返回 NULL。

Ndb

使用 PartitionSpec 来描述表分区，使用以下任意一个标准

一个 PartitionSpec 具有两个属性，一个 SpecType 和一个 Spec，它是一个对应于该 SpecType 的数据结构，如以下表格所示

此方法等待 GCP 完成。它用于确定订阅队列中是否有任何事件可用。

此方法等待下一个 纪元，而不是下一个 GCP。有关更多信息，请参见 第 2.3.16 节，“NdbEventOperation 类”。

此方法已弃用，将在将来的 NDB Cluster 版本中删除；请改用 pollEvents2()。

int pollEvents
    (
      int     maxTimeToWait,
      Uint64* latestGCI = 0
    )

此方法接受此处列出的两个参数

pollEvents() 返回一个类型为 int 的值，可以将其解释如下

当 pollEvents() 在事件队列的开头找到异常事件时，该方法将返回 1，否则将按如下方式运行

等待事件发生。一旦有任何事件数据可用，就会返回。此方法还将纪元的完整事件数据移动到事件队列。

此方法取代了 pollEvents()，后者现已弃用，将在将来的 NDB Cluster 版本中删除。

int pollEvents2
    (
      int aMillisecondNumber,
      Uint64* highestQueuedEpoch = 0
    )

此方法接受此处列出的两个参数

pollEvents2() 返回一个整数，其值可以解释如下

此方法用于设置当前数据库的名称。

void setDatabaseName
    (
      const char *databaseName
    )

setDatabaseName() 接受一个必需的参数，即要设置为当前数据库的新数据库的名称。

无.

此方法设置当前数据库模式的名称。

void setDatabaseSchemaName
    (
      const char *databaseSchemaName
    )

数据库模式的名称。

无.

默认情况下，禁用空纪元的排队。可以使用此方法来启用这种排队，在这种情况下，在方法调用之后进入事件缓冲区的任何新的空纪元都将被排队。

当启用空纪元的排队时，nextEvent() 将空纪元关联到一个订阅（事件操作）到订阅 Ndb 对象的事件操作。这意味着每个订阅最多只能有一个空纪元，即使用户可能与同一个 Ndb 对象关联了多个订阅。

setEventBufferQueueEmptyEpoch() 没有关联的 getter 方法。这是故意的，这是因为此 setter 适用于排队 新的 纪元，而队列本身可能仍然反映在调用 setter 之前存在的现状。因此，在过渡期间，即使关闭了排队，也可能会在队列中找到空纪元。

setEventBufferQueueEmptyEpoch() 是在 NDB 7.4.11 中添加的。

void setEventBufferQueueEmptyEpoch
  (
    bool queue_empty_epoch
  )

此方法接受一个输入参数，即布尔值。用 true 调用该方法将启用空事件的排队；将 false 传递给该方法将禁用这种排队。

无.

设置可用于事件缓冲区的最大内存量（以字节为单位）。这与在 MySQL 服务器中设置 ndb_eventbuffer_max_alloc 系统变量的值的效果相同。

void set_eventbuf_max_alloc
    (
      unsigned size
    )

事件缓冲区的所需最大 size（以字节为单位）。

无.

设置 ndb_eventbuffer_free_percent，即一旦达到 ndb_eventbuffer_max_alloc，缓冲区恢复之前应可用的事件缓冲区内存的百分比。

此方法是在 NDB 7.4 中添加的。

int set_eventbuffer_free_percent
    (
      unsigned pct
    )

必须存在的事件缓冲区内存的百分比 (pct)。有效范围为 1 到 99（含）。

设置的值。

您还可以设置一个任意的、人类可读的名称来标识 Ndb 对象，以用于调试目的。然后可以使用 getNdbObjectName() 检索此名称。必须在调用 init() 来初始化此对象之前完成此操作；尝试在初始化后设置名称会导致错误。

对于给定的 Ndb 对象，您只能设置一次名称；在名称已设置后进行的后续尝试会导致错误。

int setNdbObjectName
    (
      const char* name
    )

一个旨在供人类阅读的 name。

成功时返回 0。

此方法用于启动新的事务。有三种变体，其中最简单的一种使用一个表和一个分区键或分区 ID 来指定事务协调器 (TC)。第三种变体允许您通过指向键数据的指针来指定 TC。

事务完成后，必须使用 NdbTransaction::close() 或 Ndb::closeTransaction() 关闭它。否则，事务将中止。无论事务的最终结果如何，都必须执行此操作，即使它因错误而失败也是如此。

有关更多信息，请参阅 Ndb::closeTransaction() 和 NdbTransaction::close()。

NdbTransaction* startTransaction
    (
      const NdbDictionary::Table* table = 0,
      const char* keyData = 0,
      Uint32* keyLen = 0
    )

此方法接受以下三个参数

NdbTransaction* startTransaction
    (
      const NdbDictionary::Table* table,
      const struct Key_part_ptr*  keyData,
      void*                       xfrmbuf = 0,
      Uint32                      xfrmbuflen = 0
    )

在指定事务协调器时，此方法接受此处列出的四个参数

成功时，返回一个 NdbTransaction 对象。如果失败，则返回 NULL。

假设表的 partition key 是一个单独的 BIGINT 列。然后，您将按如下所示声明分布键数组

Key_part_ptr distkey[2];

分布键的值将按如下所示定义

unsigned long long distkeyValue= 23;

指向分布键数组的指针将按如下所示设置

distkey[0].ptr= (const void*) &distkeyValue;

此指针的长度将相应地设置

distkey[0].len= sizeof(distkeyValue);

分布键数组必须以 NULL 元素结尾。这是为了避免使用额外的参数来提供分布键中的列数

distkey[1].ptr= NULL;
distkey[1].len= NULL;

将缓冲区设置为 NULL 允许 startTransaction() 自动分配和释放内存

xfrmbuf= NULL;
xfrmbuflen= 0;

现在，当您启动事务时，可以直接访问包含所需信息的节点。

此方法的另一个分布式感知版本允许您指定一个表和一个分区（使用分区 ID）作为选择事务协调器的提示，定义如下

NdbTransaction* startTransaction
    (
      const NdbDictionary::Table* table,
      Uint32 partitionId
    )

如果集群的数据节点数量与其碎片副本数量相同，则指定事务协调器不会提高性能，因为每个数据节点都包含整个数据库。但是，如果数据节点的数量大于碎片副本的数量（例如，如果 NoOfReplicas 在具有四个数据节点的集群中设置为 2），则使用此方法的分布式感知版本会显着提高性能。

仍然可以使用以前的方式使用此方法，而无需指定事务协调器。无论哪种情况，您都必须显式关闭事务，无论对 startTransaction() 的调用是否成功。