Namespace lxapi
Classes
Connection
Class that stablish a connection with Kivi-direct to use the KiVi API.
The library support only one physical connection, although multiple virtual connections can be active at the same time but only if all of them are connected to the same server and with the same kivi-user, session provider and same environment. Therefore, it is needed to reset the connection to the server before connecting to another Leanxcale instance or with a different kivi-user. reset()
To create a Connection instance use connect(String). The connection string has the following format:
lx://<ip>:<port>/<database>[@<schema>][;user=<user>][;schema=<schema>]
[;kvnat=<auto or nat address>][;kvproxy=<no or ip!port>][;cert=<path to certificates>]
[;kvmsaddr=<ip!port when lxis and not the default>]
Where:
- kiviConnect through Kivi direct
- kvmsUse basic session provider
- lxisUse external session provider
- ip:portKivi metadata address when using basic session provider, or external session provider address when lxis. In this latter case, the default Kivi metaddata address is the same host on port 14400. This can be overriden by KVMSADDR property.
- databaseThe database name to connect to.
- user propertyUser id to connect with
- schema property [Opt]Optional schema to connect to. It is the user id by default
- kvmsaddr property [Opt]kvms address to override default kvms address when connecting to an external session provider
- kvnat property [Opt]Nat address used to connect to Kivi
- kvproxy property [Opt]Proxy address with format 'ip!port' to connect to Kivi
- kvuser property [Opt]Path to kivi certificates to secure the connectiong
In order to interact with Leanxcale, it is needed a session provider that will age every session along all the datastore nodes. This API supports two connections modes: a basic one that is based on the session timestamp, and an external provider, that will provide the age for every new session. To use the external one, use the 'lxis' mode on connection string when calling connect(String).
This class allows also to list all the tables in the Connection. tables()
It also provides a couple of method for debugging as debug(String) and lastError().
Decimal
Decimal Value Handle
Expression
This class manage the creation of Expressions. These can be Predicate, Artithmetich and String expressions. Also aggregations can be built using an instance of the Expression class
There are differnet kind of expression as constant values, field values, old field values (used in upsert definitios addUpsertDefition(Expression[])) and aggregations aggr(Expression.Op, Expression)
Every expression can be combined to create other Expresssions by using unary, binary and ternary operatos Expression.Op.
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);</code></pre>
Index
Wrap an Index Handle.
An index object is mainly used to perform scans Scan over a secondary table. It also holds the Index Info in order to retrieve some valuable information from it IndexInfo
To create an Index instance, it is neccesary to provide the table it belongs to, at the paremeter "table", and its name at the parameter "iname"
Once having an Index Instance, it is possible to create a Scan object by calling fullScan(Int32) in order to perform an scan. It is also possible to create a Scan by creating first a ScanPorperties object ScanProperties and then an Scan from it
IndexInfo
Index Info Handle wrapper to access index information.
An instance of this class allows to get the index name, the number of columns in the secondary index and their actual pposition in the primary table.
It is possible to create an instance of the object either from an Index Index object or with a Table Info TableInfo and its index name.
LxException
Exceptions generated by Leanxcale's API
Scan
To perform a scan it is neccesary to create an instance of this class with the required parameters to execute it.
The scan can be executed over the primary table or an index and it allows to read a range of rows of a table between two keys (primary key for the primary table or secondary key for an index). Also, it can perform filtering, aggregation, grouping and sorting.
The range of keys to read in the scan, the filter conditions, aggregation expressions and grouping definition are configured through an instance of ScanProperties. This is provided at the parameter "properties" of the constructor
Furthermore, you can pass a bit mask to either index and table scans to tell the server how to perform an scan. This is provided at the parameter "flags" of the constructor. Find below the possible flags to use. Note that these flags provide sorting, reverse sorting and other features:
.- KVHist Perform a histogram scan
- KVReverse Travel the table data in primary key descendant order. Otherwise, it is ascendant
- KVSort The server returns the data sorted.
- KVGetBlobs Include the blob pointer in the returned rows.
Once a scan is created, it can be executed by calling begin() and then iterate over the rows using next(). Close the scan when done with end(). To perform another scan it is neccesary to create a new instance of this class.
Find below some examples:
session = new Session();
table = new Table(session, "person");
Scan scan = table.scan();
scan.begin();
lxapi.Tuple tuple = scan.next();
int count = 0;
while (tuple != null)
{
count++;
tuple = scan.next();
}
scan.end();
session = new Session();
table = new Table(session, "person");
Scan scan = table.scan(null, (int)ScanPropFlags.KVSort|(int)ScanPropFlags.KVReverse);
lxapi.Index index = new lxapi.Index(table, idcardidx);
lxapi.Tuple min = index.tupleBuilder().add(0, 111111111Q).build(index);
ScanProperties properties = new ScanProperties(index).skRange(min, null, 0);
scan = new Scan(properties, 0);</code></pre>
Project #1, #2 and #4 fields and filter those rows whose field #9 is smaller than 70 and limit the result to the first 10 filtered rows visited:
Expression expr = Expression.fieldFloat(9).op(Expression.Op.KVLE, new Expression((double)70));
ScanProperties properties = new ScanProperties(table).addPredicate(expr).maxrows(10);
ushort[] projection = { 1, 2, 4 };
properties.project(projection)
Scan scan = new Scan(properties, 0);</code></pre>
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);</code></pre>
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
Session
Class that manages a session.
Every session is provided by an External provider, otherwise it will use a basic one provided by the server lxapi.Connection.#ctor(System.String)
Once a session is ended, every object related to it as Tables, Indexes, Scans, Table tuples, etc. become invalid and shouldn't be used anymore
Use flush() to flush the data to the server or abort abort() to clean the data from client
This class provides also tables, indexex and sequences creation but this is mainly for testing purposes. Use SQL inteface or the Console to take advantage of Leanxcale's full capabilities. Check "www.leanxcale.com/> for more information
session = new Session();
Table table = new Table(session, tablename);
int jimbirthday = (int)(new DateTimeOffset(new DateTime(2010, 12, 12)).ToUnixTimeSeconds() / 86400);
object[] jimrow = { 0, null, "Jim", "Doe", "No comments",
"Mulholland Drive", null, null, jimbirthday, 50, 3.26, null };
table.insert(jimrow);
// With Builder
TupleBuilder builder = table.tupleBuilder();
int johnbirthday = (int)(new DateTimeOffset(new DateTime(1975, 1, 1)).ToUnixTimeSeconds() / 86400);
object[] johnrow = { 1, "123456789A", "John", "Doe", "No comments",
"Mulholland Drive", "555333695", "johndoe@nowhere.no", johnbirthday, 70, 1.79, null };
builder.add(johnrow);
table.insert(builder.build(table));
// end::insert[]
// tag::insertWSeq[]
session.createSequence("seq", 100, 2, 10);// start at 2, increment by 10
ulong next_value = session.seqNextValue("seq");
Console.WriteLine("Next value: {0}", next_value);
// reuse builder
builder.add(0, next_value).add(1, "912345678B").add(2, "Jane");
int janebirthday = (int)(new DateTimeOffset(new DateTime(1972, 10, 7)).ToUnixTimeSeconds() / 86400);
builder.add(6, "0034698765432").add(7, "janedoe@lx.com").add(8, janebirthday)
.add(9, 75).add(10, 1.79);
table.upsert(builder.build(table));
session.end();</code></pre>
Table
Wrap a Table Handle.
A table object is mainly used to modify database's data massively. This class supports inserts, upserts, delta upserts, conditional upserts, updates and deletes.
A table object can be also used to retrieve data from the database directly from a row's key
Further, it allows perform a scan Scan over a primary table.
It also holds the Table Info in order to retrieve some valuable information from it TableInfo
To create an Table instance, it is neccesary to provide the session in which it will be used, at the paremeter "session", and its name at the parameter "tname". Note that the Table's Handle and other objects using it will belong to the specified session
Once having a Table Instance, it is possible to modify database's data by calling insert(Tuple), upsert(Tuple), update(Tuple) and delete(Tuple). Note that for deleting a tuple, a key Tuple is needed.
As mentioned before, delta and conditional upserts can be performed with a Table object. To upsert a delta, it is necessary to build a delta tuple first buildDelta(Table). Use addUpsertDefition(Expression[]) for conditionals upsert before invoking the upsert method.
A table instance allows also to create a Scan object by calling fullScan(Int32) in order to perform an scan. It is also possible to create a Scan by creating first an ScanPorperties object ScanProperties and then an Scan from it
In addition, it is possible to retrieve a row directly from its key by invoking get(Tuple), get(Tuple, ScanProperties), gets(Tuple[]) and gets(Tuple[], ScanProperties). Note that it is also possible to filter the Tuple on the before the server returns it
TableInfo
Table Info Handle wrapper to access table information.
An instance of this class allows to get table's name, the number of fields in the primary table, the number of keys, a table's key field actual position, the field name for a field postion, the position of a fields name, a field's type, a field's type name, the enum's field value from the enum's ordinal, the enum's ordinal from the enum's value, and a list of tits indexes
It is possible to create an instance of the object either from a Table Table object or by its name.
Tuple
Wrap a Leanxcale's Tuple Handle providing access to the row fields
This class represent the data stored in Kivi
Besides cloning, there are two ways to obtain a Tuple: One is building it with TupleBuilder. The other is by retrieving it from the database by a scan or a get. Hence, it is not possible to modify it once it has been obtained.
The Tuple class provide the functions to obtain its field values
There are three kind of tuples:
- Table tuplesThey are the kind of tuple that represent a regular table row in Leanxcale. They are created by build(Table). They are aldo the ones retrived from scans and gets
- Key tuplesThey are tuples where all tuple's fields belongs to the primary or secondary key. Note that the fields should be arranged following the same order as the table's primary key and there is no need to include all the key fields. They are created by buildKey(Table).
- Index tuplesThey are the kind of tuple that represent a regular index row in Leanxcale. They are created by build(Index).
- Delta tuplesUsed to upsert a row of a Table with delta fields. They are created by buildDelta(Table).
Scan scan = table.scan();
scan.begin();
lxapi.Tuple tableTuple = scan.next();
while (tableTuple != null)
{
tableTuple = scan.next();
for (int inx = 0; inx < table.info.numOfFields(); inx++)
{
if (!tableTuple.isNull(inx) && !tableTuple.isIgnore(inx))
{
Console.WriteLine("Field #{0} -> {1}", inx, tableTuple.getString(inx));
}
}
}
scan.end();
TupleBuilder
This class manages the creation of a Tuple Tuple
An instance of this class does not belong to a session so it is advise to reuse it for massive data management to gain a better perfomance. It keeps the values and its types in internal arrays. Hence, it can be reused for other tables, keys ar indexes as long as they have the same array of types.
To create an instance of this class, either a Table, an Index or a list of types must be provided.
This class allows the creation of all kinds of Tuples. These are Table tuplesbuild(Table), Index tuplesbuild(Index), key tuples buildKey(Table) and delta tuples buildDelta(Table).
This class provides the neccesary methods to set the columns values
Enums
Expression.Op
Expression's operators
IndexCreationFlags
Flags for Index creation.
Leanxcale supports two types of secondary tables: non-unique index and unique index. Also, it allows to define an index as global. Global indexes are like a regular table, horizontally partitioned, without any collocation to the primary index. Local indexes are local to each region.
These values might be used to build a bitmask to pass it as the parameter "flags" for createIndex(String, String, Int32, UInt16[], Int32) that is the function to create an index in the database.
LxTypes
Datastore format types
ScanPropFlags
Scan type flags. These are used to configure how the server will travel along the data.
KVExclMin and KVInclMax flags may be used for primary and secondary range search. The other ones may be used when creating an Scan instance.