Documentation Home
MySQL NDB Cluster API Developer Guide
Download this Manual

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

"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.  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.29.9, “NdbScanOperation::ScanFlag”.)

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. 

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

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

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 Section 2.3.12, “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.