MySQL :: MySQL NDB Cluster API Developer Guide :: 2.3.23 The NdbScanFilter Class

NdbScanFilter Class Overview

Parent class

None

Child classes

None

Description

NdbScanFilterprovides an alternative means of specifying filters for scan operations.

Because development of this interface is ongoing, the characteristics of theNdbScanFilterclass 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.57 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
`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

TheNdbScanFilterclass defines two public types:

BinaryCondition: The type of condition, such as lower bound or upper bound.
Group: A logical grouping operator, such asANDorOR.

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

Each of these methods is essentially a wrapper forcmp()that includes an appropriate value ofBinaryConditionfor that method'sconditionparameter; for example,NdbScanFilter::eq()is defined like this:

int eq(intcolumnId, Uint32value) { 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 isAND.

Signature

int begin ( Groupgroup= AND )

Parameters

AGroupvalue: one ofAND,OR,NAND, orNOR. SeeNdbScanFilter::Group, for additional information.

Return value

0on success,-1on failure.

NdbScanFilter::BinaryCondition

This section provides information about theBinaryConditiondata 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 thecmp()method.

When used in comparisons withCOND_EQ,COND_NE,COND_LT,COND_LE,COND_GT, orCOND_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 inCOND_LIKE,COND_NOTLIKE,COL_AND_MASK_EQ_MASK,COL_AND_MASK_NE_MASK,COL_AND_MASK_EQ_ZERO, orCOL_AND_MASK_NE_ZEROcomparisons.

Strings compared usingCOND_LIKEandCOND_NOTLIKEcan use the pattern metacharacters%and_. SeeNdbScanFilter::cmp(), for more information.

TheBITcomparison operators areCOL_AND_MASK_EQ_MASK,COL_AND_MASK_NE_MASK,COL_AND_MASK_EQ_ZERO, andCOL_AND_MASK_NE_ZERO. Corresponding methods are available forNdbInterpretedCodeandNdbOperation; for more information about these methods, seeNdbInterpretedCode Bitwise Comparison Operations.

Enumeration values

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

Table 2.58 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. Beginning with NDB 8.0.18, 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 thisNdbScanFilteris defined.)

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

Signature

int cmp ( BinaryConditioncondition, intcolumnId, const void*value, Uint32length= 0 )

Addtionally, in NDB 8.0.18 and later:

int cmp ( BinaryConditioncondition, intColumnId1, intColumnId2)

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 IDcolumnIDwith some arbitrary value. Theconditionis aBinaryConditionvalue; for permitted values and the relations that they represent, seeNdbScanFilter::BinaryCondition.
TheconditionvaluesCOND_LIKEorCOND_NOTLIKEare used to compare a column value with a string pattern.
columnId: This is the column's identifier, which can be obtained using theColumn::getColumnNo()method.

value: The value to be compared, repesented as a pointer tovoid.

When using aCOND_LIKEorCOND_NOTLIKEcomparison condition, thevalueis treated as a string pattern. This string must not be padded or use a prefix. The stringvaluecan include the pattern metacharacters or“wildcard”characters%and_, which have the meanings shown here:

Table 2.59 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 SQLLIKEandNOT LIKEoperators, and are interpreted in the same way. SeeString Comparison Functions and Operators, for more information.

length: The length of the value to be compared. The default value is0. Using0for thelengthhas the same effect as comparing toNULL, that is using theisnull()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 theBinaryConditionvaluesEQ,NE,LT,LE,GT, orGE. 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:0on success, and-1on failure.

NdbScanFilter Constructor

Description

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

Signature

NdbScanFilter ( class NdbOperation*op)

Parameters

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

Return value

A new instance ofNdbScanFilter.

Destructor

The destructor takes no arguments and does not return a value. It should be called to remove theNdbScanFilterobject 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

Returns0on success, or-1on failure.

NdbScanFilter::eq()

Description

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

Signature

int eq ( intColId, Uint32value)

or

int eq ( intColId, Uint64value)

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

Returns0on success, or-1on failure.

NdbScanFilter::isfalse()

Description

Defines a term of the current group asFALSE.

Signature

int isfalse ( void )

Parameters

None.

Return value

0on success, or-1on failure.

NdbScanFilter::isnotnull()

Description

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

Signature

int isnotnull ( intColId)

Parameters

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

Return value

Returns0,如果列值NULL.

NdbScanFilter::isnull()

Description

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

Signature

int isnull ( intColId)

Parameters

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

Return value

Returns0, if the column value isNULL.

NdbScanFilter::istrue()

Description

Defines a term of the current group asTRUE.

Signature

int istrue ( void )

Parameters

None.

Return value

Returns0on success,-1on 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 ( intColId, Uint32value) int ge ( intColId, Uint64value)

Parameters

Likeeq(),lt(),le(), and the otherNdbScanFiltermethods 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

0on success;-1on failure.

NdbScanFilter::getNdbError()

Description

Because errors encountered when building anNdbScanFilterdo not propagate to any involvedNdbOperationobject, it is necessary to use this method to access error information.

Signature

const NdbError& getNdbError ( void )

Parameters

None.

Return value

A reference to anNdbError.

NdbScanFilter::getNdbOperation()

Description

If theNdbScanFilterwas constructed with anNdbOperation, this method can be used to obtain a pointer to thatNdbOperationobject.

Signature

NdbOperation* getNdbOperation ( void )

Parameters

None.

Return value

A pointer to theNdbOperationassociated with thisNdbScanFilter, if there is one. Otherwise,NULL.

NdbScanFilter::Group

This section provides information about theGroupdata type.

Description

This type is used to describe logical (grouping) operators, and is used with thebegin()method. (SeeNdbScanFilter::begin().)

Enumeration values

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

Table 2.60 NdbScanFilter::Group data type values and descriptions

Value	Description
`AND`	Logical`AND`:`AANDBANDC`
`OR`	Logical`OR`:`AORBORC`
`NAND`	Logical`NOT AND`:`NOT (AANDBANDC)`
`NOR`	Logical`NOT OR`:`NOT (AORBORC)`

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 ( intColId, Uint32value) int gt ( intColId, Uint64value)

Parameters

Like the otherNdbScanFiltermethods 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

0on success;-1on failure.

NdbScanFilter::le()

Description: This method is used to perform a less-than-or-equal test on a column value and an integer.
Signature: 这个方法有两个版本,以适应32-bit and 64-bit values:

int le ( intColId, Uint32value) int le ( intColId, Uint64value)

Parameters

Like the otherNdbScanFiltermethods 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

Returns0on success, or-1on failure.

NdbScanFilter::lt()

Description

这个方法是用来执行的小于(严格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 ( intColId, Uint32value) int lt ( intColId, Uint64value)

Parameters

Likeeq(),ne(), and the otherNdbScanFiltermethods 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

Retrturns0on success, or-1on 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 ( intColId, Uint32value) int ne ( intColId, Uint64value)

Parameters

Likeeq()and the otherNdbScanFiltermethods 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

Returns0on success, or-1on failure.

NdbScanFilter::reset()

Description

This method resets theNdbScanFilterobject, discarding any previous filter definition and error state.

Signature

void reset ( void )

Parameters

None.

Return value

None.

reset()has no effect on the SQL-compliantNULLcomparison mode set bysetSqlCmpSemantics().

This method was added in NDB 8.0.15.

NdbScanFilter::setSqlCmpSemantics()

Description

Traditionally, when making comparisons involvingNULL,NdbScanFiltertreatsNULLas equal toNULL(and thus considersNULL == NULLto beTRUE). This is not the same as specified by the SQL Standard, which requires that any comparison withNULLreturnNULL, includingNULL == 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 nextNdbScanFilterobject to be created to employ SQL-compliantNULLcomparison for all operations for its entire lifetime. This cannot be unset oncesetSqlCmpSemantics()is called; invokingreset()has no effect in this regard. The effect of this method extends only to the next instance ofNdbScanFilterto be created; any subsequent instance uses the traditional comparison mode unlesssetSqlCmpSemantics()is invoked beforehand.

This method has no effect onNULLsorting;NdbScanFilteralways considersNULLto be less than any other value.

Signature

void setSqlCmpSemantics ( void )

Parameters

None

Return value

None

This method was added in NDB 8.0.26.