MySQL NDB Cluster API Developer Guide
This section provides information about the
NdbScanFilter
class.
None
None
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.
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 |
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(intcolumnId
, Uint32value
) { return cmp(BinaryCondition::COND_EQ,columnId
,&value
, 4); }
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
.
int begin
(
Group group
= AND
)
A Group
value: one of
AND
, OR
,
NAND
, or NOR
. See
NdbScanFilter::Group, for additional
information.
0
on success, -1
on
failure.
This section provides information about the
BinaryCondition
data type.
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.
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 |
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 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.
int cmp ( BinaryConditioncondition
, intcolumnId
, const void*value
, Uint32length
= 0 )
Addtionally, in NDB 8.0.18 and later:
int cmp ( BinaryConditioncondition
, intColumnId1
, intColumnId2
)
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, repesented 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.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 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.
This method returns an integer: 0
on
success, and -1
on failure.
This is the constructor method for
NdbScanFilter
, and creates
a new instance of the class.
NdbScanFilter
(
class NdbOperation* op
)
This method takes a single parameter, a pointer to the
NdbOperation
to which the
filter applies.
A new instance of
NdbScanFilter
.
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.
This method completes a compound, signalling that there are no more conditions to be added to it.
int end ( void )
None.
Returns 0
on success, or
-1
on failure.
This method is used to perform an equality test on a column value and an integer.
int eq ( intColId
, Uint32value
)
or
int eq ( intColId
, Uint64value
)
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.
Returns 0
on success, or
-1
on failure.
Defines a term of the current group as
FALSE
.
int isfalse ( void )
None.
0
on success, or -1
on
failure.
This method is used to check whether a column value is not
NULL
.
int isnotnull
(
int ColId
)
The ID of the column whose value is to be tested.
Returns 0
, if the column value is not
NULL
.
This method is used to check whether a column value is
NULL
.
int isnull
(
int ColId
)
The ID of the column whose value is to be tested.
Returns 0
, if the column value is
NULL
.
Defines a term of the current group as
TRUE
.
int istrue ( void )
None.
Returns 0
on success,
-1
on failure.
This method is used to perform a greater-than-or-equal test on a column value and an integer.
This method accepts both 32-bit and 64-bit values, as shown here:
int ge ( intColId
, Uint32value
) int ge ( intColId
, Uint64value
)
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.
0
on success; -1
on
failure.
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.
const NdbError& getNdbError ( void )
None.
A reference to an NdbError
.
If the NdbScanFilter
was
constructed with an
NdbOperation
, this method
can be used to obtain a pointer to that
NdbOperation
object.
NdbOperation* getNdbOperation ( void )
None.
A pointer to the
NdbOperation
associated
with this NdbScanFilter
, if
there is one. Otherwise, NULL
.
This section provides information about the
Group
data type.
This type is used to describe logical (grouping) operators,
and is used with the begin()
method. (See
NdbScanFilter::begin().)
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 :
|
OR |
Logical OR :
|
NAND |
Logical NOT AND : NOT
( |
NOR |
Logical NOT OR : NOT
( |
This method is used to perform a greater-than (strict upper bound) test on a column value and an integer.
This method accommodates both 32-bit and 64-bit values:
int gt ( intColId
, Uint32value
) int gt ( intColId
, Uint64value
)
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.
0
on success; -1
on
failure.
This method is used to perform a less-than-or-equal test on a column value and an integer.
This method has two variants, to accommodate 32-bit and 64-bit values:
int le ( intColId
, Uint32value
) int le ( intColId
, Uint64value
)
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.
Returns 0
on success, or
-1
on failure.
This method is used to perform a less-than (strict lower bound) test on a column value and an integer.
This method has 32-bit and 64-bit variants, as shown here:
int lt ( intColId
, Uint32value
) int lt ( intColId
, Uint64value
)
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.
Retrturns 0
on success, or
-1
on failure.
This method is used to perform an inequality test on a column value and an integer.
This method has 32-bit and 64-bit variants, as shown here:
int ne ( intColId
, Uint32value
) int ne ( intColId
, Uint64value
)
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.
Returns 0
on success, or
-1
on failure.