2.3.18 The NdbIndexScanOperation Class

This section provides information about the NdbIndexScanOperation class.

• NdbIndexScanOperation Class Overview

• NdbIndexScanOperation::BoundType

• NdbIndexScanOperation::end_of_bound()

• NdbIndexScanOperation::getDescending()

• NdbIndexScanOperation::get_range_no()

• NdbIndexScanOperation::getSorted()

• NdbIndexScanOperation::IndexBound

• NdbIndexScanOperation::readTuples()

• NdbIndexScanOperation::reset_bounds()

• NdbIndexScanOperation::setBound()

NdbIndexScanOperation Class Overview

Parent class

NdbScanOperation

Child classes

None

Description

The NdbIndexScanOperation class represents a scan operation using an ordered index. This class inherits from NdbScanOperation and NdbOperation.

NdbIndexScanOperation is for use with ordered indexes only; to work with unique hash indexes, use NdbIndexOperation.

For more information about the use of NdbIndexScanOperation, see Section 1.4.2.3.3, “Scan Operations”, and Section 1.4.2.3.4, “Using Scans to Update or Delete Rows”.

Methods

The following table lists the public methods of this class and the purpose or use of each method:

Table 2.45 NdbIndexScanOperation class methods and descriptions

Name	Description
end_of_bound()	Marks the end of a bound
get_range_no()	Gets the range number for the current row
getDescending()	Checks whether the current scan is sorted
getSorted()	Checks whether the current scan is sorted
readTuples()	Reads tuples using an ordered index
reset_bounds()	Resets bounds, puts the operation in the send queue
setBound()	Defines a bound on the index key for a range scan

Types

The NdbIndexScanOperation class defines one public type BoundType.

This class also defines an IndexBound data structure, for use with operations employing NdbRecord.

NdbIndexScanOperation::BoundType

This section provides information abut the BoundType data type.

Description

This type is used to describe an ordered key bound.

Enumeration values

Possible values are shown, along with descriptions, in the following table:

Table 2.46 NdbIndexScanOperation::BoundType values, numeric equivalents, and descriptions

Value	Numeric Value	Description
BoundLE	0	Lower bound
BoundLT	1	Strict lower bound
BoundGE	2	Upper bound
BoundGT	3	Strict upper bound
BoundEQ	4	Equality

The numeric values just shown are “safe”;that is, they are fixed in the API, and so can be calculated and used explicitly.

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.

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.

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).

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.

NdbIndexScanOperation::IndexBound

This section provides information about the IndexBound data structure.

Parent class

NdbIndexScanOperation

Description

IndexBound is a structure used to describe index scan bounds for NdbRecord scans.

Members

Member names, types, and descriptions are shown in the following table:

Table 2.47 IndexBound structure member names, types, and descriptions

Name	Type	Description
low_key	const char*	Row containing lower bound for scan (or NULL for scan from the start).
low_key_count	Uint32	Number of columns in lower bound (for bounding by partial prefix).
low_inclusive	bool	True for <= relation, false for <.
high_key	const char*	Row containing upper bound for scan (or NULL for scan to the end).
high_key_count	Uint32	Number of columns in upper bound (for bounding by partial prefix).
high_inclusive	bool	True for >= relation, false for >.
range_no	Uint32	Value to identify this bound; may be read using the get_range_no() method (see NdbIndexScanOperation::get_range_no()). This value must be less than 8192 (set to zero if it is not being used). For ordered scans, range_no must be strictly increasing for each range, or else the result set will not be sorted correctly.

For more information, see Section 2.3.22, “The NdbRecord Interface”.

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:

• The lock mode used for the scan. This is a LockMode value; see NdbOperation::LockMode for more information, including permitted values.

• One or more scan flags; multiple flags are OR'ed together as they are when used with NdbScanOperation::readTuples(). See NdbScanOperation::ScanFlag for possible values.

• The number of fragments to scan in parallel; use 0 to specify the maximum automatically.

• The batch parameter specifies how many records will be returned to the client from the server by the next NdbScanOperation::nextResult(true) method call. Use 0 to specify the maximum automatically.

  Note

  This parameter was ignored prior to MySQL 5.1.12, and the maximum was used.(Bug #20252)

Return value

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

NdbIndexScanOperation::reset_bounds()

Description

Resets the bounds, and puts the operation into the list sent on the next call to NdbTransaction::execute().

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.

NdbIndexScanOperation::setBound()

Description

This method defines a bound on an index key used in a range scan, and sets bounds for index scans defined using NdbRecord.

As used with NdbRecord, 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 NdbScanOperation::ScanFlag.)

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

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

Parameters

As used with NdbRecord, this method takes 2 parameters, listed here:

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

• The bound to add (see NdbIndexScanOperation::IndexBound).

Return value

Returns 0 on success, -1 on failure.

An additional version of this method 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)

This method can also 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 NdbIndexScanOperation::IndexBound).

• 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.

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.

“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:

• Either the name or the id of the attribute on which the bound is to be set.

• The bound type—see NdbIndexScanOperation::BoundType.

• A pointer to the bound value (use 0 for NULL).

Return value

Returns 0 on success, -1 on failure.