MySQL :: MySQL NDB Cluster API Developer Guide :: 2.3.23 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 `AND`ed with bitmask is equal to bitmask	`BIT`
`COL_AND_MASK_NE_MASK`	Column value `AND`ed with bitmask is not equal to bitmask	`BIT`
`COL_AND_MASK_EQ_ZERO`	Column value `AND`ed with bitmask is equal to zero	`BIT`
`COL_AND_MASK_NE_ZERO`	Column value `AND`ed 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.