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
Implements
Inherited Members
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_ |
ScanProperties(Table)
Create scan properties for a table scan
Declaration
public ScanProperties(Table table_)
Parameters
Type | Name | Description |
---|---|---|
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 |
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 |
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);