2.3.22.2 NdbIndexScanOperation Methods

2.3.22.2.1 NdbIndexScanOperation::end_of_bound()
2.3.22.2.2 NdbIndexScanOperation::getDescending()
2.3.22.2.3 NdbIndexScanOperation::get_range_no()
2.3.22.2.4 NdbIndexScanOperation::getSorted()
2.3.22.2.5 NdbIndexScanOperation::readTuples()
2.3.22.2.6 NdbIndexScanOperation::reset_bounds()
2.3.22.2.7 NdbIndexScanOperation::setBound

Abstract

This section lists and describes the public methods of the NdbIndexScanOperation class.

2.3.22.2.1 NdbIndexScanOperation::end_of_bound()

Description.  This method is used to mark the end of a bound; it is used when batching index reads (that is, when employing multiple ranges).

Signature. 

int end_of_bound
    (
      Uint32 range_no
    )

Parameters.  The number of the range on which the bound occurs.

Return value.  0 indicates success; -1 indicates failure.

2.3.22.2.2 NdbIndexScanOperation::getDescending()

Description.  This method is used to check whether the scan is descending.

Signature. 

bool getDescending
    (
      void
    ) const

Parameters.  None.

Return value.  This method returns true if the scan is sorted in descending order; otherwise, it returns false.

2.3.22.2.3 NdbIndexScanOperation::get_range_no()

Description.  This method returns the range number for the current row.

Signature. 

int get_range_no
    (
      void
    )

Parameters.  None.

Return value.  The range number (an integer).

2.3.22.2.4 NdbIndexScanOperation::getSorted()

Description.  This method is used to check whether the scan is sorted.

Signature. 

bool getSorted
    (
      void
    ) const

Parameters.  None.

Return value.  true if the scan is sorted, otherwise false.

2.3.22.2.5 NdbIndexScanOperation::readTuples()

Description.  This method is used to read tuples, using an ordered index.

Signature. 

virtual int readTuples
    (
      LockMode mode = LM_Read,
      Uint32   flags = 0,
      Uint32   parallel = 0,
      Uint32   batch = 0

    )

Parameters.  The readTuples() method takes the three parameters listed here:

Return value.  An integer: 0 indicates success; -1 indicates failure.

2.3.22.2.6 NdbIndexScanOperation::reset_bounds()

Description.  Resets the bounds, and puts the operation into the list that will be sent on the next NdbTransaction::execute() call.

Signature. 

int reset_bounds
    (
      bool forceSend = false
    )

Parameters.  Set forceSend to true in order to force the operation to be sent immediately.

Return value.  Returns 0 on success, -1 on failure.

2.3.22.2.7 NdbIndexScanOperation::setBound

Description.  This method defines a bound on an index key used in a range scan. In MySQL Cluster NDB 6.2.3 and later, it is also sets bounds for index scans defined using NdbRecord.

Old API usage (prior to introduction of NdbRecord).  Each index key can have a lower bound, upper bound, or both. Setting the key equal to a value defines both upper and lower bounds. Bounds can be defined in any order. Conflicting definitions gives rise to an error.

Bounds must be set on initial sequences of index keys, and all but possibly the last bound must be nonstrict. This means, for example, that a >= 2 AND b > 3 is permissible, but a > 2 AND b >= 3 is not.

The scan may currently return tuples for which the bounds are not satisfied. For example, a <= 2 && b <= 3 not only scans the index up to (a=2, b=3), but also returns any (a=1, b=4) as well.

When setting bounds based on equality, it is better to use BoundEQ instead of the equivalent pair BoundLE and BoundGE. This is especially true when the table partition key is a prefix of the index key.

NULL is considered less than any non-NULL value and equal to another NULL value. To perform comparisons with NULL, use setBound() with a null pointer (0).

An index also stores all-NULL keys as well, and performing an index scan with an empty bound set returns all tuples from the table.

Signature (Old API).  Using the old API, this method could be called in either of two ways. Both of these use the bound type and value; the first also uses the name of the bound, as shown here:

int setBound
    (
      const char* name,
      int         type,
      const void* value
    )

The second way to invoke this method under the old API uses the bound's ID rather than the name, as shown here:

int setBound
    (
      Uint32      id,
      int         type,
      const void* value
    )

Parameters (Old API).  This method takes 3 parameters:

As used with NdbRecord (MySQL Cluster NDB 6.2.3 and later).  This method is called to add a range to an index scan operation which has been defined with a call to NdbTransaction::scanIndex(). To add more than one range, the index scan operation must have been defined with the SF_MultiRange flag set. (See Section 2.3.28.1, “The NdbScanOperation::ScanFlag Type”.)

Note

Where multiple numbered ranges are defined with multiple calls to setBound(), and the scan is ordered, the range number for each range must be larger than the range number for the previously defined range.

Signature (when used with NdbRecord).  MySQL Cluster NDB 6.2.3 and later:

int setBound
    (
      const NdbRecord* keyRecord,
      const IndexBound& bound
    )

Parameters.  As used with NdbRecord in MySQL Cluster NDB 6.2.3 and later, this method takes 2 parameters, listed here:

Starting with MySQL Cluster NDB 6.3.24 and NDB 7.0.4, an additional version of this method is available, which can be used when the application knows that rows in-range will be found only within a particular partition. This is the same as that shown previously, except for the addition of a PartitionSpec. Doing so limits the scan to a single partition, improving system efficiency.

Signature (when specifying a partition). 

int setBound
    (
      const NdbRecord* keyRecord,
      const IndexBound& bound,
      const Ndb::PartitionSpec* partInfo,
      Uint32 sizeOfPartInfo = 0
    )

Parameters (when specifying a partition).  Beginning with MySQL Cluster NDB 6.3.24 and MySQL Cluster NDB 7.0.4, this method can be invoked with the following four parameters:

  • keyRecord: This is an NdbRecord structure corresponding to the key on which the index is defined.

  • The bound to be added to the scan (see Section 2.3.11, “The IndexBound Structure”).

  • partInfo: This is a pointer to a PartitionSpec, which provides extra information making it possible to scan a reduced set of partitions.

  • sizeOfPartInfo: The length of the partition specification.

Note

keyRecord and bound are defined and used in the same way as with the 2-parameter version of this method.

Return value.  Returns 0 on success, -1 on failure.