無

無

任何非微不足道的 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_restore 還原 NDB 叢集後，NDB API 事件訂閱不會持續存在；在這種情況下，必須明確重新建立所有訂閱。

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() 後才會生效。您可以使用此方法取得 epoch 的摘要資訊（例如所有資料表的清單），然後再處理事件資料。

此方法已過時，並可能在未來版本中移除。在可能的情況下，請改用 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 Cluster 版本中移除。

在 NDB 7.4.7 之前，此方法會傳回事件佇列中的最高 epoch 數。在 NDB 7.4.7 及更新版本中，它會在呼叫 pollEvents2() 後傳回找到的最高 epoch 數 (Bug #20700220)。

Uint64 getHighestQueuedEpoch
    (
      void
    )

無.

最近的 epoch 數，為整數。

取得最近的全域檢查點的索引。

此方法已在 NDB 7.4 中過時，並可能在未來版本中移除。在 NDB 7.4 及更新版本中，您應該改用 getHighestQueuedEpoch()。

Uint64 getLatestGCI
    (
      void
    )

無.

最近的 GCI，為整數。

此方法提供兩種不同的方式來取得代表錯誤狀況的 NdbError 物件。如需 NDB API 中錯誤處理的詳細資訊，請參閱 NDB Cluster 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() 取得 epoch 的摘要資訊，例如所有資料表的清單。

例外 epoch 沒有與它們相關聯的任何事件操作。

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

一開始將 iter 設定為 0；當此 epoch 中沒有更多事件時，它會是 NULL。如果 event_types 不是 NULL，則它會保留已接收事件類型的位元遮罩。

如果有的話，指向下一個 NdbEventOperation 的指標。

迭代構成目前全域檢查點的個別事件操作。在處理事件資料之前，使用下面的 nextEvent2() 取得 epoch 的摘要資訊，例如所有資料表的清單。與 getNextEventOpInEpoch3() 相同，但新增了第三個引數，該引數會保留所有接收到的 AnyValue 的合併，顯示給定資料表上所有操作設定的位元。

例外 epoch 沒有與它們相關聯的任何事件操作。

此方法已在 NDB 7.4.18 和 7.5.9 中新增 (Bug #26333981)。

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

一開始將 iter 設定為 0；當此 epoch 中沒有更多事件時，它會是 NULL。如果 event_types 不是 NULL，則它會保留已接收事件類型的位元遮罩。如果 cumulative_any_value 不是 NULL，則它會保留所有接收到的 AnyValue 的合併。

如果有的話，指向下一個 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() 是否已看到更高的佇列 epoch，或者是否找到 TE_CLUSTER_FAILURE 事件。

在偵測到叢集故障後，pollEvents2() 傳回的最高佇列 epoch 可能不再增加。在這種情況下，您應該使用 nextEvent() 來處理事件，直到偵測到 TE_CLUSTER_FAILURE，然後在叢集再次可用時重新連線到叢集，而不是輪詢更多事件。

bool isExpectingHigherQueuedEpochs
      (
        void
      )

無.

如果上次呼叫 pollEvents2() 時看到佇列 epoch，或在發生叢集故障時，則為 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() 來判斷 epoch，然後使用 NdbEventOperation::getEventType2() 來檢查傳回事件資料的類型。必須為所有異常的 TableEvent 類型（包括 TE_EMPTY、TE_INCONSISTENT 和 TE_OUT_OF_MEMORY（也在 NDB 7.4 中引入））提供處理。除了此處命名的兩種方法之外，不應為異常的 epoch 呼叫任何其他 NdbEventOperation 方法。當資料節點閒置時，傳回空的 epoch (TE_EMPTY) 可能會淹沒應用程式。如果這不是理想的情況，應用程式應該篩選掉任何空的 epoch。

NdbEventOperation* nextEvent2
    (
      void
    )

無。

此方法會傳回 NdbEventOperation 物件，表示事件佇列中的下一個事件（如果有的話）。如果佇列中沒有事件，則會改為傳回 NULL。

Ndb

使用以下任何一個條件來描述資料表分割區時，會使用 PartitionSpec：

PartitionSpec 有兩個屬性：SpecType 和 Spec，後者是與該 SpecType 對應的資料結構，如下表所示：

此方法會等待 GCP 完成。它用於判斷訂閱佇列中是否有任何事件可用。

此方法會等待下一個epoch，而不是下一個 GCP。有關更多資訊，請參閱 第 2.3.16 節「NdbEventOperation 類別」。

此方法已過時，並會在未來 NDB 叢集版本中移除；請改用 pollEvents2()。

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

此方法會採用此處列出的兩個參數：

pollEvents() 會回傳一個 int 型態的值，其意義如下：

當 pollEvents() 在事件佇列的頭部找到例外事件時，該方法會回傳 1，否則行為如下：

等待事件發生。一旦有任何事件資料可用，就會立即回傳。此方法也會將一個 epoch 的完整事件資料移到事件佇列中。

此方法取代了 pollEvents()，後者現在已棄用，並可能在未來的 NDB Cluster 版本中移除。

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

此方法會採用此處列出的兩個參數：

pollEvents2() 會回傳一個整數，其值可以解釋如下：

此方法用於設定目前資料庫的名稱。

void setDatabaseName
    (
      const char *databaseName
    )

setDatabaseName() 接受一個單一的必要參數，即要設定為目前資料庫的新資料庫名稱。

無.

此方法設定目前資料庫結構描述的名稱。

void setDatabaseSchemaName
    (
      const char *databaseSchemaName
    )

資料庫結構描述的名稱。

無.

預設情況下，會停用空 epoch 的佇列。此方法可用於啟用此佇列，在這種情況下，在方法呼叫後進入事件緩衝區的任何新的空 epoch 都會被排入佇列。

當啟用空 epoch 的佇列時，nextEvent() 會將一個空 epoch 與連接到訂閱 Ndb 物件的一個且僅一個訂閱（事件操作）建立關聯。這表示每個訂閱最多只能有一個空 epoch，即使使用者可能有多個與同一個 Ndb 物件相關聯的訂閱。

setEventBufferQueueEmptyEpoch() 沒有相關的 getter 方法。這是故意的，原因是因為此 setter 適用於佇列新的 epoch，而佇列本身可能仍然反映調用 setter 之前存在的狀態。因此，在過渡期間，即使停用佇列，也可能在佇列中找到空的 epoch。

setEventBufferQueueEmptyEpoch() 在 NDB 7.4.11 中新增。

void setEventBufferQueueEmptyEpoch
  (
    bool queue_empty_epoch
  )

此方法接受一個單一的輸入參數，即布林值。使用 true 呼叫方法會啟用空事件的佇列；傳遞 false 給方法會停用此佇列。

無.

設定事件緩衝區可以使用的最大記憶體量（以位元組為單位）。這與在 MySQL Server 中設定 ndb_eventbuffer_max_alloc 系統變數的值具有相同的效果。

void set_eventbuf_max_alloc
    (
      unsigned 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
    )

一個名稱，旨在讓人們可以讀懂。

成功時為 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。

假設資料表的分割區鍵是單一的 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() 的呼叫是否成功。