MySQL NDB Cluster API Developer Guide

2.3.23 The NdbScanFilter Class

This section provides information about the NdbScanFilter class.

NdbScanFilter Class Overview

Parent class

None

Child classes

None

Description

NdbScanFilter provides an alternative means of specifying filters for scan operations.

Because development of this interface is ongoing, the characteristics of the NdbScanFilter class are subject to change in future releases.

Methods

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

Table 2.58 NdbScanFilter class methods and descriptions

Name Description
NdbScanFilter() Constructor method
~NdbScanFilter() Destructor method
begin() Begins a compound (set of conditions)
cmp() Compares a column value with an arbitrary value
cmp_param() Compares a column value with the value of a supplied parameter
end() Ends a compound
eq() Tests for equality
ge() Tests for a greater-than-or-equal condition
getNdbError() Provides access to error information
getNdbOperation() Gets the associated NdbOperation
gt() Tests for a greater-than condition
isfalse() Defines a term in a compound as FALSE
isnotnull() Tests whether a column value is not NULL
isnull() Tests whether a column value is NULL
istrue() Defines a term in a compound as TRUE
le() Tests for a less-than-or-equal condition
lt() Tests for a less-than condition
ne() Tests for inequality
reset() Resets this NdbScanFilter object
setSqlCmpSemantics() Forces use of SQL-compliant NULL comparison handling

Types

The NdbScanFilter class defines two public types:

  • BinaryCondition: The type of condition, such as lower bound or upper bound.

  • Group: A logical grouping operator, such as AND or OR.

NdbScanFilter Integer Comparison Methods.  NdbScanFilter provides several convenience methods which can be used in lieu of the cmp() method when the arbitrary value to be compared is an integer: eq(), ge(), gt(), le(), lt(), and ne().

Each of these methods is essentially a wrapper for cmp() that includes an appropriate value of BinaryCondition for that method's condition parameter; for example, NdbScanFilter::eq() is defined like this:

int eq(int columnId, Uint32 value)
{
  return cmp(BinaryCondition::COND_EQ, columnId, &value, 4);
}

NdbScanFilter::begin()

Description

This method is used to start a compound, and specifies the logical operator used to group the conditions making up the compound. The default is AND.

Signature
int begin
    (
      Group group = AND
    )
Parameters

A Group value: one of AND, OR, NAND, or NOR. See NdbScanFilter::Group, for additional information.

Return value

0 on success, -1 on failure.

NdbScanFilter::BinaryCondition

This section provides information about the BinaryCondition data type.

Description

This type represents a condition based on the comparison of a column value with some arbitrary value—that is, a bound condition. A value of this type is used as the first argument to the cmp() method.

When used in comparisons with COND_EQ, COND_NE, COND_LT, COND_LE, COND_GT, or COND_GE, fixed-length character and binary column values must be prefixed with the column size, and must be padded to length. This is not necessary for such values when used in COND_LIKE, COND_NOTLIKE, COL_AND_MASK_EQ_MASK, COL_AND_MASK_NE_MASK, COL_AND_MASK_EQ_ZERO, or COL_AND_MASK_NE_ZERO comparisons.

Strings compared using COND_LIKE and COND_NOTLIKE can use the pattern metacharacters % and _. See NdbScanFilter::cmp(), for more information.

The BIT comparison operators are COL_AND_MASK_EQ_MASK, COL_AND_MASK_NE_MASK, COL_AND_MASK_EQ_ZERO, and COL_AND_MASK_NE_ZERO. Corresponding methods are available for NdbInterpretedCode and NdbOperation; for more information about these methods, see NdbInterpretedCode Bitwise Comparison Operations.

Enumeration values

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

Table 2.59 NdbScanFilter data type values and descriptions

Name Description Column type compared
COND_EQ Equality (=) any
COND_NE Inequality (<> or !=) any
COND_LE Lower bound (<=) any
COND_LT Strict lower bound (<) any
COND_GE Upper bound (>=) any
COND_GT Strict upper bound (>) any
COND_LIKE LIKE condition string or binary
COND_NOTLIKE NOT LIKE condition string or binary
COL_AND_MASK_EQ_MASK Column value ANDed with bitmask is equal to bitmask BIT
COL_AND_MASK_NE_MASK Column value ANDed with bitmask is not equal to bitmask BIT
COL_AND_MASK_EQ_ZERO Column value ANDed with bitmask is equal to zero BIT
COL_AND_MASK_NE_ZERO Column value ANDed with bitmask is not equal to zero BIT

NdbScanFilter::cmp()

Description

This method is used to define a comparison between a given value and the value of a column. In NDB 8.0, it can also be used to compare two columns. (This method does not actually execute the comparison, which is done later when performing the scan for which this NdbScanFilter is defined.)

In many cases, where the value to be compared is an integer, you can instead use one of several convenience methods provided by NdbScanFilter for this purpose. See NdbScanFilter Integer Comparison Methods.

Signature
int cmp
    (
      BinaryCondition condition,
      int columnId,
      const void* value,
      Uint32 length = 0
    )

Addtionally, in NDB 8.0:

int cmp
    (
      BinaryCondition condition,
      int ColumnId1,
      int ColumnId2
    )
Parameters

When used to compare a value with a column, this method takes the following parameters:

  • condition: This represents the condition to be tested which compares the value of the column having the column ID columnID with some arbitrary value. The condition is a BinaryCondition value; for permitted values and the relations that they represent, see NdbScanFilter::BinaryCondition.

    The condition values COND_LIKE or COND_NOTLIKE are used to compare a column value with a string pattern.

  • columnId: This is the column's identifier, which can be obtained using the Column::getColumnNo() method.

  • value: The value to be compared, represented as a pointer to void.

    When using a COND_LIKE or COND_NOTLIKE comparison condition, the value is treated as a string pattern. This string must not be padded or use a prefix. The string value can include the pattern metacharacters or wildcard characters % and _, which have the meanings shown here:

    Table 2.60 Pattern metacharacters used with COND_LIKE and COND_NOTLIKE comparisons

    Metacharacter Description
    % Matches zero or more characters
    _ Matches exactly one character

    To match against a literal % or _ character, use the backslash (\) as an escape character. To match a literal \ character, use \\.

    These are the same wildcard characters that are supported by the SQL LIKE and NOT LIKE operators, and are interpreted in the same way. See String Comparison Functions and Operators, for more information.

  • length: The length of the value to be compared. The default value is 0. Using 0 for the length has the same effect as comparing to NULL, that is using the isnull() method.

When used to compare two columns, cmp() takes the following parameters:

  • condition: The condition to be tested when comparing the columns. The condition may be any one of the BinaryCondition values EQ, NE, LT, LE, GT, or GE. Other values are not accepted.

  • columnID1: ID of the first of the two columns to be compared.

  • columnID1: ID of the second column.

Columns being compared using this method must be of exactly the same type. This includes length, precision, scale, and all other particulars.

Return value

This method returns an integer: 0 on success, and -1 on failure.

NdbScanFilter::cmp_param()

Description

This method is used to define a comparison between the value of a column and that of a parameter having the specified ID. The comparison is actually performed later when executing the scan for which this NdbScanFilter is defined.

This method was added in NDB 8.0.27.

Signature
int cmp_param()
    (
      BinaryCondition condition,
      int colId,
      int paramId
    )
Parameters

When used to compare a value with a column, this method takes the following parameters:

  • condition: This represents the condition to be tested which compares the value of the column having the column ID columnID with some arbitrary value. The condition is a BinaryCondition value; for permitted values and the relations that they represent, see NdbScanFilter::BinaryCondition.

    The condition values COND_LIKE or COND_NOTLIKE are used to compare a column value with a string pattern.

  • colId: This is the column's identifier, which can be obtained using the Column::getColumnNo() method.

  • paramId: The ID of the parameter whose value is to be compared.

Values being compared using this method must be of exactly the same type. This includes length, precision, scale, and all other particulars.

Return value

This method returns an integer: 0 on success, and -1 on failure.

NdbScanFilter Constructor

Description

This is the constructor method for NdbScanFilter, and creates a new instance of the class.

Signature
NdbScanFilter
    (
      class NdbOperation* op
    )
Parameters

This method takes a single parameter, a pointer to the NdbOperation to which the filter applies.

Return value

A new instance of NdbScanFilter.

Destructor

The destructor takes no arguments and does not return a value. It should be called to remove the NdbScanFilter object when it is no longer needed.

NdbScanFilter::end()

Description

This method completes a compound, signalling that there are no more conditions to be added to it.

Signature
int end
    (
      void
    )
Parameters

None.

Return value

Returns 0 on success, or -1 on failure.

NdbScanFilter::eq()

Description

This method is used to perform an equality test on a column value and an integer.

Signature
int eq
    (
      int    ColId,
      Uint32 value
    )

or

int eq
    (
      int    ColId,
      Uint64 value
    )
Parameters

This method takes two parameters, listed here:

  • The ID (ColId) of the column whose value is to be tested

  • An integer with which to compare the column value; this integer may be either 32-bit or 64-bit, and is unsigned in either case.

Return value

Returns 0 on success, or -1 on failure.

NdbScanFilter::isfalse()

Description

Defines a term of the current group as FALSE.

Signature
int isfalse
    (
      void
    )
Parameters

None.

Return value

0 on success, or -1 on failure.

NdbScanFilter::isnotnull()

Description

This method is used to check whether a column value is not NULL.

Signature
int isnotnull
    (
      int ColId
    )
Parameters

The ID of the column whose value is to be tested.

Return value

Returns 0, if the column value is not NULL.

NdbScanFilter::isnull()

Description

This method is used to check whether a column value is NULL.

Signature
int isnull
    (
      int ColId
    )
Parameters

The ID of the column whose value is to be tested.

Return value

Returns 0, if the column value is NULL.

NdbScanFilter::istrue()

Description

Defines a term of the current group as TRUE.

Signature
int istrue
    (
      void
    )
Parameters

None.

Return value

Returns 0 on success, -1 on failure.

NdbScanFilter::ge()

Description

This method is used to perform a greater-than-or-equal test on a column value and an integer.

Signature

This method accepts both 32-bit and 64-bit values, as shown here:

int ge
    (
      int    ColId,
      Uint32 value
    )


int ge
    (
      int    ColId,
      Uint64 value
    )
Parameters

Like eq(), lt(), le(), and the other NdbScanFilter methods of this type, this method takes two parameters:

  • The ID (ColId) of the column whose value is to be tested

  • An integer with which to compare the column value; this integer may be either 32-bit or 64-bit, and is unsigned in either case.

Return value

0 on success; -1 on failure.

NdbScanFilter::getNdbError()

Description

Because errors encountered when building an NdbScanFilter do not propagate to any involved NdbOperation object, it is necessary to use this method to access error information.

Signature
const NdbError& getNdbError
    (
      void
    )
Parameters

None.

Return value

A reference to an NdbError.

NdbScanFilter::getNdbOperation()

Description

If the NdbScanFilter was constructed with an NdbOperation, this method can be used to obtain a pointer to that NdbOperation object.

Signature
NdbOperation* getNdbOperation
    (
      void
    )
Parameters

None.

Return value

A pointer to the NdbOperation associated with this NdbScanFilter, if there is one. Otherwise, NULL.

NdbScanFilter::Group

This section provides information about the Group data type.

Description

This type is used to describe logical (grouping) operators, and is used with the begin() method. (See NdbScanFilter::begin().)

Enumeration values

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

Table 2.61 NdbScanFilter::Group data type values and descriptions

Value Description
AND Logical AND: A AND B AND C
OR Logical OR: A OR B OR C
NAND Logical NOT AND: NOT (A AND B AND C)
NOR Logical NOT OR: NOT (A OR B OR C)

NdbScanFilter::gt()

Description

This method is used to perform a greater-than (strict upper bound) test on a column value and an integer.

Signature

This method accommodates both 32-bit and 64-bit values:

int gt
    (
      int    ColId,
      Uint32 value
    )


int gt
    (
      int    ColId,
      Uint64 value
    )
Parameters

Like the other NdbScanFilter methods of this type, this method takes two parameters:

  • The ID (ColId) of the column whose value is to be tested

  • An integer with which to compare the column value; this integer may be either 32-bit or 64-bit, and is unsigned in either case.

Return value

0 on success; -1 on failure.

NdbScanFilter::le()

Description

This method is used to perform a less-than-or-equal test on a column value and an integer.

Signature

This method has two variants, to accommodate 32-bit and 64-bit values:

int le
    (
      int    ColId,
      Uint32 value
    )


int le
    (
      int    ColId,
      Uint64 value
    )
Parameters

Like the other NdbScanFilter methods of this type, this method takes two parameters:

  • The ID (ColId) of the column whose value is to be tested

  • An integer with which to compare the column value; this integer may be either 32-bit or 64-bit, and is unsigned in either case.

Return value

Returns 0 on success, or -1 on failure.

NdbScanFilter::lt()

Description

This method is used to perform a less-than (strict lower bound) test on a column value and an integer.

Signature

This method has 32-bit and 64-bit variants, as shown here:

int lt
    (
      int    ColId,
      Uint32 value
    )

int lt
    (
      int    ColId,
      Uint64 value
    )
Parameters

Like eq(), ne(), and the other NdbScanFilter methods of this type, this method takes two parameters, listed here:

  • The ID (ColId) of the column whose value is to be tested

  • An integer with which to compare the column value; this integer may be either 32-bit or 64-bit, and is unsigned in either case.

Return value

Retrturns 0 on success, or -1 on failure.

NdbScanFilter::ne()

Description

This method is used to perform an inequality test on a column value and an integer.

Signature

This method has 32-bit and 64-bit variants, as shown here:

int ne
    (
      int    ColId,
      Uint32 value
    )

int ne
    (
      int    ColId,
      Uint64 value
    )
Parameters

Like eq() and the other NdbScanFilter methods of this type, this method takes two parameters:

  • The ID (ColId) of the column whose value is to be tested

  • An integer with which to compare the column value; this integer may be either 32-bit or 64-bit, and is unsigned in either case.

Return value

Returns 0 on success, or -1 on failure.

NdbScanFilter::reset()

Description

This method resets the NdbScanFilter object, discarding any previous filter definition and error state.

Signature
void reset
    (
      void
    )
Parameters

None.

Return value

None.

reset() has no effect on the SQL-compliant NULL comparison mode set by setSqlCmpSemantics().

This method was added in NDB 8.0.

NdbScanFilter::setSqlCmpSemantics()

Description

Traditionally, when making comparisons involving NULL, NdbScanFilter treats NULL as equal to NULL (and thus considers NULL == NULL to be TRUE). This is not the same as specified by the SQL Standard, which requires that any comparison with NULL return NULL, including NULL == NULL.

Beginning with NDB 8.0.26, it is possible to override this behavior by calling this method, which takes no arguments. Doing so causes the next NdbScanFilter object to be created to employ SQL-compliant NULL comparison for all operations for its entire lifetime. This cannot be unset once setSqlCmpSemantics() is called; invoking reset() has no effect in this regard. The effect of this method extends only to the next instance of NdbScanFilter to be created; any subsequent instance uses the traditional comparison mode unless setSqlCmpSemantics() is invoked beforehand.

This method has no effect on NULL sorting; NdbScanFilter always considers NULL to be less than any other value.

Signature
void setSqlCmpSemantics
    (
      void
    )
Parameters

None

Return value

None

This method was added in NDB 8.0.26.