Show / Hide Table of Contents

Class ScanProperties

This class holds the information to perform a Scan

It allows to configure a range scan over the primary table or an index. If no range is specified a full scan is performed. The scan can also perform filtering, aggregation, grouping and sorting.

If the scan is performed over the primary table, it is provided as the "table" parameter of the constructor. If the scan is performed over a secondary table, it is provided as the "index" parameter of the constructor.

Once an instance is created of the scan is created for either the primary table or and index, it is possible to configure the scan and extra functionality such as filtering, grouping, ... as follows:

  • Add a filter to a primary table scanaddPredicate(Expression), fieldRange(Int32, Double[], Int32) , fieldRange(Int32, Int64[], Int32) and , fieldRange(Int32, String[], Int32)
  • Add a filter to an index scan. addIndexPredicate(Expression)
  • Add a search range of primary keys for a primary table scan. pkRange(Tuple, Tuple, Int32)
  • Add a search range of secondary keys for an index scan. skRange(Tuple, Tuple, Int32)
  • The number of rows to be returned can be limited:maxrows(Int64)
  • The resultset can be projected (select a subset of the columns to be returned)project(UInt16[])
  • In order to perform grouping (like the group by of SQL), the fields expressions and aggregations should be configuredgroupBy(Expression[])
  • To sort the resultet, a sortBy clause can be addedsortBy(UInt16[])

A scan can be reused as many times as needed within the same session

Inheritance
System.Object
ScanProperties
Implements
System.IDisposable
Inherited Members
System.Object.Equals(System.Object)
System.Object.Equals(System.Object, System.Object)
System.Object.GetHashCode()
System.Object.GetType()
System.Object.MemberwiseClone()
System.Object.ReferenceEquals(System.Object, System.Object)
System.Object.ToString()
Namespace: lxapi
Assembly: lxapi.dll
Syntax
public class ScanProperties : IDisposable

Constructors

ScanProperties(Index)

Create scan properties for an index scan

Declaration
public ScanProperties(Index index_)
Parameters
Type Name Description
Index index_

Index

ScanProperties(Table)

Create scan properties for a table scan

Declaration
public ScanProperties(Table table_)
Parameters
Type Name Description
Table table_

Table

ScanProperties(Table, String)

Create scan properties for a table. The propertied are created according to the expression string passed as parameter.

The string can be a single expression of an integral type, in which case it represents a predicate over the tuples. The predicate filter the tuples for which the value is zero. It only returns the tuples for which the value is non zero.

The string can also be a tuple spec with the syntax

 [ <fld1>, .... <fldn> ] where expr 

to represent a group-by request.

In this case, the expressions for different fields are separated by commas, within square brackets, to define the resulting tuple(s). The value of each resulting field is the value yielded by the corresponding expression. Optionally an expression can be provided as a predicate over the tuples visited.

For conditional upserts, the string can be like just described, but with no where predicate. In this case, it is possible to describe only the first fields, and all missing trailing fields will simply keep the new value being added.

An expression can use numbers written very much like in C source code, and names, corresponding to field names. A field may be selected using the syntax $n, where n is the field number (in user order) counting from zero.

Known operators are, from high to low precedence:

 old ! ~ + - (unary)
 * / %  & | << >> 
 + - (binary)
 > < >= <= == !=
  && 
 ||

with the usual meaning as in unix awk or in the C programming language. The precedence differs from that of C in that bitwise and shift operations share the precedence level with multiply operators. Use parenthesis when in doubt regarding precedence.

Operations shown above for expressions that do not have an operator can be used as functions in function calls, and their names correspond to the ones shown. Simply remove the initial KV prefix and use lowercase.

Use the reserved word null for null values.

The reserved word aggr can be used when defining a group-by result set to refer to the previous value of an aggregate (field) being computed. This can be used only as the first operand of the aggregation operator. For example:

[$1, aggr+1]

defines a result set using the second tuple field (field no. 1) as the key for the aggregation and counting such fields by aggregating a +1 in the second field.

If all fields are aggregations, a single result for the total is expected. If some fields are aggregations, they must be the last fields and the previous ones are the keys for the aggregation.

When defining conditional upserts, aggr is not permitted. Instead, the operator old may be used to indicate that the following field refers to the one in the previous version of the tuple. For example:

[$0, old $1, max($2, old $0)]

defines a conditional upsert where the first field is kept as in the new value, the second field is kept from the previous version, and the 3rd field is set as the maximum of the new value for it and the value for the first field in the previous version.

In this case, it is possible to use a field spec like $N or a field name, followed by a :, to specify the field being defined. The next specified field will be the following one, unless it also has a label showing its number or name. For example:

[$1: old $1, max($2, old $0)]
is another way of writing the previous example.
Declaration
public ScanProperties(Table lxtbl, string expr)
Parameters
Type Name Description
Table lxtbl

table object

System.String expr

expression

Fields

index

Index when building a secondary table scan

Declaration
public readonly Index index
Field Value
Type Description
Index

kvFilter

Scan Properties Handle

Declaration
public readonly IntPtr kvFilter
Field Value
Type Description
System.IntPtr

table

Table when building a primary table scan

Declaration
public readonly Table table
Field Value
Type Description
Table

Methods

addIndexPredicate(Expression)

Set a predicate for index keys, to be used for filtering (secondary) indexes before recovering the tuple value from the primary table.

Declaration
public ScanProperties addIndexPredicate(Expression expression)
Parameters
Type Name Description
Expression expression

Expression

Returns
Type Description
ScanProperties

scan properties with the added predicate

Examples

Filter those rows whose secondary key on field #2 is smaller than 70

        Expression expr = Expression.fieldInt(2).op(Expression.Op.KVLE, new Expression((70));
    ScanProperties properties = new ScanProperties(table).addIndexPredicate(expr);</code></pre>

addPredicate(Expression)

Filter the data according to a predicate expression.

Declaration
public ScanProperties addPredicate(Expression expression)
Parameters
Type Name Description
Expression expression

Expression

Returns
Type Description
ScanProperties

scan properties with the added filter

Examples

Filter those rows whose field #9 is smaller than 70

        Expression expr = Expression.fieldFloat(9).op(Expression.Op.KVLE, new Expression((double)70));
    ScanProperties properties = new ScanProperties(table).addPredicate(expr);</code></pre>

buildScan(Int32)

Build a scan from the current properties.

Declaration
public Scan buildScan(int flags = 0)
Parameters
Type Name Description
System.Int32 flags

bit mask to indicate how the server is going to iterate over the rows ScanPropFlags

Returns
Type Description
Scan
Examples
        Expression expr = Expression.fieldFloat(9).op(Expression.Op.KVLE, new Expression((double)70));

        Scan scan = new ScanProperties(table).addPredicate(expr).maxrows(10).buildScan();

Dispose()

Dispose

Declaration
public void Dispose()

Dispose(Boolean)

Release scan properties Handle

Declaration
protected virtual void Dispose(bool disposing)
Parameters
Type Name Description
System.Boolean disposing

fieldRange(Int32, Double[], Int32)

Set a range filter for a double/float column.

The arrays must have an even number of entries, and each pair is considered an interval of values (min. included, max. excluded). The filter succeeds when the field value is in any of the given intervals. Multiple filters may be installed, but not many.

The argument overlap must be non-zero if any of the intervals overlap, or if they are not sorted by their minimum value. When it is zero, matching is faster.

Following range will search in [0,40[ and [100, 1000[ intervals

double[] ranges = {0.0, 4.5, 10.0, 10,10};
ScanProperties properties = new ScanProperties(table).fieldRange(3, ranges, 0);
Declaration
public ScanProperties fieldRange(int fno, double[] vals, int overlap)
Parameters
Type Name Description
System.Int32 fno

column position

System.Double[] vals

array of consecutive intervals

System.Int32 overlap

overlap

Returns
Type Description
ScanProperties

scan properties with the added filter

fieldRange(Int32, Int64[], Int32)

Set a range filter over an integer/long column.

The arrays must have an even number of entries, and each pair is considered an interval of values (min. included, max. excluded). The filter succeeds when the field value is in any of the given intervals. Multiple filters may be set, but a high number results in a non-neglectable overhead.

The argument overlap must be non-zero if any of the intervals overlap, or if they are not sorted by their minimum value. When it is zero, matching is faster.

The following range will search in [0,40[ and [100, 1000[ intervals

long[] ranges = {0, 40, 100, 1000};
ScanProperties properties = new ScanProperties(table).fieldRange(3, ranges, 0);
Declaration
public ScanProperties fieldRange(int fno, long[] vals, int overlap)
Parameters
Type Name Description
System.Int32 fno

column position

System.Int64[] vals

array of consecutive intervals

System.Int32 overlap

overlap

Returns
Type Description
ScanProperties

modified scan properties

fieldRange(Int32, String[], Int32)

Set a range filter for a atring column.

The arrays must have an even number of entries, and each pair is considered an interval of values (min. included, max. excluded). The filter selects the rows for which the field value is in any of the given intervals. Multiple filters can be installed, but too many result in a non-neglectable overhead.

The argument overlap must be non-zero if any of the intervals overlap, or if they are not sorted by their minimum value. When it is zero, matching is faster.

Following range will search in [0,40[ and [100, 1000[ intervals

string[] ranges = {"0", "40", "100", "1000"};
ScanProperties properties = new ScanProperties(table).fieldRange(3, ranges, 0);
Declaration
public ScanProperties fieldRange(int fno, string[] vals, int overlap)
Parameters
Type Name Description
System.Int32 fno

column position

System.String[] vals

array of consecutive intervals

System.Int32 overlap

overlap

Returns
Type Description
ScanProperties

scan properties with the added filter

Finalize()

Destructor

Declaration
protected void Finalize()

groupBy(Expression[])

Add a group by expression.

The scan will return tuples where each field will be the result of its group by expression.

Declaration
public ScanProperties groupBy(Expression[] expressions)
Parameters
Type Name Description
Expression[] expressions

group by expressionExpression

Returns
Type Description
ScanProperties

scan properties with the added group by clause

Examples

Group by scan with having the first field as the field #3, second as the maximun value for field #9

        Expression[] groupbyexprs = new Expression[2];
        groupbyexprs[0] = Expression.fieldStr(3);
        groupbyexprs[1] = Expression.aggr(Expression.Op.KVMAX, Expression.fieldFloat(9));

        Scan scan = table.scan(new ScanProperties(table).groupBy(groupbyexprs), 0);

maxrows(Int64)

Limit the maximum number of tuples to retrieve from the database

Declaration
public ScanProperties maxrows(long nvals)
Parameters
Type Name Description
System.Int64 nvals

max number of tuples to retrieve

Returns
Type Description
ScanProperties

scan properties with the added tuple limit

Examples

Limit the result to the first 10 filtered visited rows:

        ScanProperties properties = new ScanProperties(table).maxrows(10);

pkRange(Tuple, Tuple, Int32)

Add a primary key search range to a primary table scan

Declaration
public ScanProperties pkRange(Tuple min, Tuple max, int flags)
Parameters
Type Name Description
Tuple min

Complete or partial key tuple

Tuple max

Complete or partial key tuple

System.Int32 flags

bitmask to exclude min or/and to include max KVInclMax and KVExclMin

Returns
Type Description
ScanProperties

scan properties with the added search range

Examples

Primary table scan over an string field starting at minimun value to "111111111Q", including "111111111Q"

        lxapi.Tuple max = index.tupleBuilder().add(0, 111111111Q).build(table);

        ScanProperties properties = new ScanProperties(index).pkRange(null, max, ScanPropFlags.KVInclMax);

        scan = new Scan(properties, 0);

project(UInt16[])

Add a projection to scan properties to select a subset of columns to be returned

Declaration
public ScanProperties project(ushort[] flds)
Parameters
Type Name Description
System.UInt16[] flds

positions of projected columns

Returns
Type Description
ScanProperties

the scan properties with the added projection

Examples

Project PKs, #1, #2 and #4 fields, the rest are not returned

        ushort[] projection = { 1, 2, 4 };
        ScanProperties properties = new ScanProperties(table).project(projection);

skRange(Tuple, Tuple, Int32)

Add a secondary key search range to an index scan

Declaration
public ScanProperties skRange(Tuple min, Tuple max, int flags)
Parameters
Type Name Description
Tuple min

Complete or partial key tuple

Tuple max

Complete or partial key tuple

System.Int32 flags

bitmask to include max or/and to exclude min KVInclMax and KVExclMin

Returns
Type Description
ScanProperties

scan properties with the added index search range

Examples

Index scan over an string field starting at "111111111Q" to "511111111A", excluding "111111111Q" and "511111111A"

        TupleBuilder builder = index.tupleBuilder();
        lxapi.Tuple min = builder.add(0, "111111111Q").build(index);
        lxapi.Tuple max = builder.add(0, "511111111A").build(index);
    ScanProperties properties = new ScanProperties(index).skRange(min, max, ScanPropFlags.KVExclMin);

    scan = new Scan(properties, 0);</code></pre>

sortBy(UInt16[])

Sort a group by expression

Declaration
public ScanProperties sortBy(ushort[] positions)
Parameters
Type Name Description
System.UInt16[] positions

field positions in the group by expressions

Returns
Type Description
ScanProperties

modified scan properties

Examples

Group by scan having the first field as the field #3, second as the maximun value for field #9 and sorted by the max value column.

        Expression[] groupbyexprs = new Expression[2];
        groupbyexprs[0] = Expression.fieldStr(3);
        groupbyexprs[1] = Expression.aggr(Expression.Op.KVMAX, Expression.fieldFloat(9));
        ushort[] sortpos = {1};
        Scan scan = table.scan(new ScanProperties(table).groupBy(groupbyexprs).sortBy(), 0);

Implements

System.IDisposable
Back to top Generated by DocFX