MySQL NDB Cluster API Developer Guide
This section provides information about the
NdbIndexScanOperation
class.
None
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”.
The following table lists the public methods of this class and the purpose or use of each method:
Table 2.44 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 |
The NdbIndexScanOperation
class defines
one public type
BoundType
.
This class also defines an
IndexBound
data structure, for use with operations employing
NdbRecord
.
This section provides information abut the
BoundType
data type.
This type is used to describe an ordered key bound.
Possible values are shown, along with descriptions, in the following table:
Table 2.45 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.
This method is used to mark the end of a bound; it is used when batching index reads (that is, when employing multiple ranges).
int end_of_bound
(
Uint32 range_no
)
The number of the range on which the bound occurs.
0
indicates success;
-1
indicates failure.
This method is used to check whether the scan is descending.
bool getDescending ( void ) const
None.
This method returns true
if the scan is
sorted in descending order; otherwise, it returns
false
.
This method returns the range number for the current row.
int get_range_no ( void )
None.
The range number (an integer).
This method is used to check whether the scan is sorted.
bool getSorted ( void ) const
None.
true
if the scan is sorted, otherwise
false
.
This section provides information about the
IndexBound
data structure.
IndexBound
is a structure used to
describe index scan bounds for
NdbRecord
scans.
Member names, types, and descriptions are shown in the following table:
Table 2.46 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”.
This method is used to read tuples, using an ordered index.
virtual int readTuples ( LockModemode
= LM_Read, Uint32flags
= 0, Uint32parallel
= 0, Uint32batch
= 0 )
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.
This parameter was ignored prior to MySQL 5.1.12, and the maximum was used.(Bug #20252)
An integer: 0
indicates success;
-1
indicates failure.
Resets the bounds, and puts the operation into the list sent
on the next call to
NdbTransaction::execute()
.
int reset_bounds
(
bool forceSend
= false
)
Set forceSend
to
true
in order to force the operation to
be sent immediately.
Returns 0
on success,
-1
on failure.
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.
int setBound ( const NdbRecord*keyRecord
, const IndexBound&bound
)
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).
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.
int setBound ( const NdbRecord*keyRecord
, const IndexBound&bound
, const Ndb::PartitionSpec*partInfo
, Uint32sizeOfPartInfo
= 0 )
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.
Returns 0
on success,
-1
on failure.
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.
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
, inttype
, 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 ( Uint32id
, inttype
, const void*value
)
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
).
Returns 0
on success,
-1
on failure.