changed documented method from get/setDistributionKey to get/setPartitionKey (aae10cd1) · Commits · Software / OSDI20 Artifacts / mariadb

ndb/include/ndbapi/Ndb.hpp

+49 −40

Original line number	Diff line number	Diff line
		@@ -328,12 +328,13 @@
		- Scan subset of table using @ref NdbIndexScanOperation::setBound()
		- Ordering result set ascending or descending,
		@ref NdbIndexScanOperation::readTuples()
		- When using NdbIndexScanOperation::BoundEQ on distribution key
		only fragment containing rows will be scanned.
		- When using NdbIndexScanOperation::BoundEQ on partition key
		only fragments containing rows will be scanned.

		Rows are returned unordered unless sorted is set to true.

		@note When performing sorted scan, parameter parallelism to readTuples will
		@note When performing sorted scan, parameter parallelism to
		NdbIndexScanOperation::readTuples() will
		be ignored and max parallelism will be used instead.

		@subsection secScanLocks Lock handling with scans
		@@ -343,10 +344,10 @@

		But Ndb will only lock a batch of rows per fragment at a time.
		How many rows will be locked per fragment is controlled by the
		batch parameter to @ref NdbScanOperation::readTuples.
		batch parameter to NdbScanOperation::readTuples().

		To let the application handle how locks are released
		@ref NdbScanOperation::nextResult() have a parameter fetch_allow.
		NdbScanOperation::nextResult() have a parameter fetch_allow.
		If NdbScanOperation::nextResult() is called with fetch_allow = false, no
		locks may be released as result of the function call. Otherwise the locks
		for the current batch may be released.
		@@ -380,11 +381,12 @@

		One recommended way to handle a transaction failure
		(i.e. an error is reported) is to:
		-# Rollback transaction (NdbTransaction::execute with a special parameter)
		-# Rollback transaction (NdbTransaction::execute() with a special parameter)
		-# Close transaction
		-# Restart transaction (if the error was temporary)

		@note Transaction are not automatically closed when an error occur.
		@note Transactions are not automatically closed when an error occur. Call
		Ndb::closeTransaction() to close.

		Several errors can occur when a transaction holds multiple
		operations which are simultaneously executed.
		@@ -392,9 +394,9 @@
		objects and query for their NdbError objects to find out what really
		happened.

		NdbTransaction::getNdbErrorOperation returns a reference to the
		NdbTransaction::getNdbErrorOperation() returns a reference to the
		operation causing the latest error.
		NdbTransaction::getNdbErrorLine delivers the method number of the
		NdbTransaction::getNdbErrorLine() delivers the method number of the
		erroneous method in the operation.

		@code
		@@ -417,14 +419,14 @@
		Getting errorLine == 0 means that the error occurred when executing the
		operations.
		Here errorOperation will be a pointer to the theOperation object.
		NdbTransaction::getNdbError will return the NdbError object
		NdbTransaction::getNdbError() will return the NdbError object
		including holding information about the error.

		Since errors could have occurred even when a commit was reported,
		there is also a special method, NdbTransaction::commitStatus,
		there is also a special method, NdbTransaction::commitStatus(),
		to check the commit status of the transaction.

		*******************************************************************************/
		******************************************************************************/

		/**
		* @page ndbapi_simple.cpp ndbapi_simple.cpp
		@@ -458,32 +460,14 @@
		@page secAdapt Adaptive Send Algorithm

		At the time of "sending" the transaction
		(using NdbTransaction::execute), the transactions
		(using NdbTransaction::execute()), the transactions
		are in reality <em>not</em> immediately transfered to the NDB Kernel.
		Instead, the "sent" transactions are only kept in a
		special send list (buffer) in the Ndb object to which they belong.
		The adaptive send algorithm decides when transactions should
		be transfered to the NDB kernel.

		For each of these "sent" transactions, there are three
		possible states:
		-# Waiting to be transferred to NDB Kernel.
		-# Has been transferred to the NDB Kernel and is currently
		being processed.
		-# Has been transferred to the NDB Kernel and has
		finished processing.
		Now it is waiting for a call to a poll method.
		(When the poll method is invoked,
		then the transaction callback method will be executed.)

		The poll method invoked (either Ndb::pollNdb or Ndb::sendPollNdb)
		will return when:
		-# at least 'minNoOfEventsToWakeup' of the transactions
		in the send list have transitioned to state 3 as described above, and
		-# all of these transactions have executed their callback methods.


		Since the NDB API is designed as a multi-threaded interface,
		The NDB API is designed as a multi-threaded interface and
		it is desirable to transfer database operations from more than
		one thread at a time.
		The NDB API keeps track of which Ndb objects are active in transfering
		@@ -514,14 +498,36 @@
		later releases of NDB Cluster.
		However, to support faster than 10 ms checks,
		there has to be support from the operating system.
		-# When calling NdbTransaction::execute synchronously or calling any
		of the poll-methods, there is a force parameter that overrides the
		adaptive algorithm and forces the send to all nodes.
		-# When methods that are affected by the adaptive send alorithm,
		e.g. NdbTransaction::execute(), there is a force parameter
		that overrides it forces the send to all nodes.

		@note The times mentioned above are examples. These might
		@note The reasons mentioned above are examples. These might
		change in later releases of NDB Cluster.
		*/

		#ifndef DOXYGEN_SHOULD_SKIP_INTERNAL
		/**

		For each of these "sent" transactions, there are three
		possible states:
		-# Waiting to be transferred to NDB Kernel.
		-# Has been transferred to the NDB Kernel and is currently
		being processed.
		-# Has been transferred to the NDB Kernel and has
		finished processing.
		Now it is waiting for a call to a poll method.
		(When the poll method is invoked,
		then the transaction callback method will be executed.)

		The poll method invoked (either Ndb::pollNdb() or Ndb::sendPollNdb())
		will return when:
		-# at least 'minNoOfEventsToWakeup' of the transactions
		in the send list have transitioned to state 3 as described above, and
		-# all of these transactions have executed their callback methods.
		*/
		#endif

		/**
		@page secConcepts NDB Cluster Concepts

		@@ -563,14 +569,17 @@

		The application programmer can however hint the NDB API which
		transaction coordinator to use
		by providing a <em>distribution key</em> (usually the primary key).
		By using the primary key as distribution key,
		by providing a <em>partition key</em> (usually the primary key).
		By using the primary key as partition key,
		the transaction will be placed on the node where the primary replica
		of that record resides.
		Note that this is only a hint, the system can be
		reconfigured and then the NDB API will choose a transaction
		coordinator without using the hint.
		For more information, see NdbDictionary::Column::setDistributionKey.
		For more information, see NdbDictionary::Column::getPartitionKey(),
		Ndb::startTransaction(). The application programmer can specify
		the partition key from SQL by using the construct,
		"CREATE TABLE ... ENGINE=NDB PARTITION BY KEY (<attribute list>)".


		@section secRecordStruct Record Structure
		@@ -639,7 +648,7 @@
		A simple example is an application that uses many simple updates where
		a transaction needs to update one record.
		This record has a 32 bit primary key,
		which is also the distribution key.
		which is also the partition key.
		Then the keyData will be the address of the integer
		of the primary key and keyLen will be 4.
		*/

ndb/include/ndbapi/NdbDictionary.hpp

+17 −10

Original line number	Diff line number	Diff line
		@@ -286,14 +286,14 @@ public:
		int getSize() const;

		/**
		* Check if column is part of distribution key
		* Check if column is part of partition key
		*
		* A <em>distribution key</em> is a set of attributes which are used
		* A <em>partition key</em> is a set of attributes which are used
		* to distribute the tuples onto the NDB nodes.
		* The distribution key uses the NDB Cluster hashing function.
		* The partition key uses the NDB Cluster hashing function.
		*
		* An example where this is useful is TPC-C where it might be
		* good to use the warehouse id and district id as the distribution key.
		* 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 database node.
		*
		@@ -301,9 +301,12 @@ public:
		* will still be used with the hashing algorithm.
		*
		* @return true then the column is part of
		* the distribution key.
		* the partition key.
		*/
		bool getDistributionKey() const;
		bool getPartitionKey() const;
		#ifndef DOXYGEN_SHOULD_SKIP_DEPRECATED
		inline bool getDistributionKey() const { return getPartitionKey(); };
		#endif

		/ @} *****************************************************************/

		@@ -401,13 +404,17 @@ public:
		void setStripeSize(int size);

		/**
		* Set distribution key
		* @see getDistributionKey
		* Set partition key
		* @see getPartitionKey
		*
		* @param enable If set to true, then the column will be part of
		* the distribution key.
		* the partition key.
		*/
		void setDistributionKey(bool enable);
		void setPartitionKey(bool enable);
		#ifndef DOXYGEN_SHOULD_SKIP_DEPRECATED
		inline void setDistributionKey(bool enable)
		{ setPartitionKey(enable); };
		#endif

		/ @} *****************************************************************/

ndb/include/ndbapi/NdbIndexScanOperation.hpp

+1 −1

Original line number	Diff line number	Diff line
		@@ -73,7 +73,7 @@ public:
		*
		* For equality, it is better to use BoundEQ instead of the equivalent
		* pair of BoundLE and BoundGE. This is especially true when table
		* distribution key is an initial part of the index key.
		* partition key is an initial part of the index key.
		*
		* The sets of lower and upper bounds must be on initial sequences of
		* index keys. All but possibly the last bound must be non-strict.

ndb/include/ndbapi/NdbOperation.hpp

+1 −1

Original line number	Diff line number	Diff line
		@@ -731,7 +731,7 @@ public:
		void setAbortOption(Int8 ao) { m_abortOption = ao; }

		/**
		* Set/get distribution/partition key
		* Set/get partition key
		*/
		void setPartitionId(Uint32 id);
		void setPartitionHash(Uint32 key);

ndb/include/ndbapi/NdbTransaction.hpp

+26 −20

Original line number	Diff line number	Diff line
		@@ -76,33 +76,35 @@ enum ExecType {
		* @brief Represents a transaction.
		*
		* A transaction (represented by an NdbTransaction object)
		* belongs to an Ndb object and is typically created using
		* Ndb::startTransaction.
		* belongs to an Ndb object and is created using
		* Ndb::startTransaction().
		* A transaction consists of a list of operations
		* (represented by NdbOperation objects).
		* (represented by NdbOperation, NdbScanOperation, NdbIndexOperation,
		* and NdbIndexScanOperation objects).
		* Each operation access exactly one table.
		*
		* After getting the NdbTransaction object,
		* the first step is to get (allocate) an operation given the table name.
		* the first step is to get (allocate) an operation given the table name using
		* one of the methods getNdbOperation(), getNdbScanOperation(),
		* getNdbIndexOperation(), or getNdbIndexScanOperation().
		* Then the operation is defined.
		* Several operations can be defined in parallel on the same
		* NdbTransaction object.
		* When all operations are defined, the NdbTransaction::execute
		* Several operations can be defined on the same
		* NdbTransaction object, they will in that case be executed in parallell.
		* When all operations are defined, the execute()
		* method sends them to the NDB kernel for execution.
		*
		* The NdbTransaction::execute method returns when the NDB kernel has
		* The execute() method returns when the NDB kernel has
		* completed execution of all operations defined before the call to
		* NdbTransaction::execute.
		* All allocated operations should be properly defined
		* before calling NdbTransaction::execute.
		* execute(). All allocated operations should be properly defined
		* before calling execute().
		*
		* A call to NdbTransaction::execute uses one out of three types of execution:
		* A call to execute() uses one out of three types of execution:
		* -# ExecType::NoCommit Executes operations without committing them.
		* -# ExecType::Commit Executes remaining operation and commits the
		* complete transaction
		* -# ExecType::Rollback Rollbacks the entire transaction.
		*
		* NdbTransaction::execute is equipped with an extra error handling parameter
		* execute() is equipped with an extra error handling parameter.
		* There are two alternatives:
		* -# AbortOption::AbortOnError (default).
		* The transaction is aborted if there are any error during the
		@@ -345,6 +347,8 @@ public:

		/**
		* Close transaction
		*
		* @note Equivalent to to calling Ndb::closeTransaction()
		*/
		#ifndef DOXYGEN_SHOULD_SKIP_INTERNAL
		/**
		@@ -415,10 +419,7 @@ public:
		Uint64 getTransactionId();

		/**
		* Returns the commit status of the transaction.
		*
		* @return The commit status of the transaction, i.e. one of
		* { NotStarted, Started, TimeOut, Committed, Aborted, NeedAbort }
		* The commit status of the transaction.
		*/
		enum CommitStatusType {
		NotStarted, ///< Transaction not yet started
		@@ -428,6 +429,11 @@ public:
		NeedAbort ///< <i>Missing explanation</i>
		};

		/**
		* Get the commit status of the transaction.
		*
		* @return The commit status of the transaction
		*/
		CommitStatusType commitStatus();

		/ @} *******************************************************************/
		@@ -449,7 +455,7 @@ public:
		* This method is used on the NdbTransaction object to find the
		* NdbOperation causing an error.
		* To find more information about the
		* actual error, use method NdbOperation::getNdbError
		* actual error, use method NdbOperation::getNdbError()
		* on the returned NdbOperation object.
		*
		* @return The NdbOperation causing the latest error.