2.3.28.1 The NdbScanOperation::ScanFlag Type

Description.  Values of this type are the scan flags used with the readTuples() method. More than one may be used, in which case, they are OR'ed together as the second argument to that method. See Section 2.3.28.2.7, “NdbScanOperation::readTuples()”, for more information.

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

ValueDescription
SF_TupScanScan in TUP order (that is, in the order of the rows in memory). Applies to table scans only.
SF_DiskScanScan in disk order (order of rows on disk). Applies to table scans only.
SF_OrderBy

Ordered index scan (ascending); rows returned from an index scan are sorted, and ordered on the index key. Scans in either ascending or descending order are affected by this flag, which causes the API to perform a merge-sort among the ordered scans of each fragment to obtain a single sorted result set.

Notes:

  • Ordered indexes are distributed, with one ordered index for each fragment of a table.

  • Range scans are often parallel across all index fragments. Occasionally, they can be pruned to one index fragment.

  • Each index fragment range scan can return results in either ascending or descending order. Ascending is the default; to choose descending order, set the SF_Descending flag.

  • When multiple index fragments are scanned in parallel, the results are sent back to NDB where they can optionally be merge-sorted before being returned to the user. This merge sorting is controlled using the SF_OrderBy and SF_OrderByFull flags.

  • If SF_OrderBy or SF_OrderByFull is not used, the results from each index fragment are in order (either ascending or descending), but results from different fragments may be interleaved.

  • When using SF_OrderBy or SF_OrderByFull, some extra constraints are imposed internally; these are listed here:

    1. If the range scan is not pruned to one index fragment then all index fragments must be scanned in parallel. (Unordered scans can be executed with less than full parallelism.)

    2. Results from every index fragment must be available before returning any rows, to ensure a correct merge sort. This serialises the scrolling of the scan, potentially resulting in lower row throughput.

    3. Unordered scans can return rows to the API client before all index fragments have returned any batches, and can overlap next-batch requests with row processing.

SF_OrderByFullThis is the same as SF_OrderBy, except that all key columns are added automatically to the read bitmask.
SF_DescendingCauses an ordered index scan to be performed in descending order.
SF_ReadRangeNoFor index scans, when this flag is set, NdbIndexScanOperation::get_range_no() can be called to read back the range_no defined in NdbIndexScanOperation::setBound(). In addition, when this flag is set, and SF_OrderBy or SF_OrderByFull is also set, results from ranges are returned in their entirety before any results are returned from subsequent ranges.
SF_MultiRangeIndicates that this scan is part of a multirange scan; each range is scanned separately.
SF_KeyInfoRequests KeyInfo to be sent back to the caller. This enables the option to take over the row lock taken by the scan, using lockCurrentTuple(), by making sure that the kernel sends back the information needed to identify the row and the lock. This flag is enabled by default for scans using LM_Exclusive, but must be explicitly specified to enable the taking over of LM_Read locks. (See the LockMode documentation for more information.)