GridGain Developers Hub

Table API

To execute table operations on a specific table, you need to get a specific view of the table and use one of its methods. You can only create new tables by using SQL API.

GridGain supports mapping user objects to table tuples. This ensures that objects created in any programming language can be used for key-value operations directly.

Table Views in GridGain 9

Binary and Non-Binary Views

When working with tables, GridGain offers two approaches: directly handling the data or mapping the data to classes. The direct data handling approach is is referred to as the binary view. Alternatively, when mapping data to classes, the data is converted to and from these classes as needed for database interactions.

Record and Key-Value Views

When creating views, you can create a RecordView or KeyValueView. The primary difference between these view types is the API used.

In a RecordView, you create a single “record” that includes all the information about a row to be updated or retrieved from the table, and send this record to the server. This record should contain all the fields, including the primary key.

In a KeyValueView, you work with key-value mappings. Think of it as a dictionary where the key object contains the primary key field or fields, and the value object contains the data fields. This approach is useful when primary key is not directly related to the domain object thus you prefer not to add the primary key to it.

Getting a Table Instance

First, get an instance of the table. To obtain an instance of table, use the IgniteTables.table(String) method. You can also use IgniteTables.tables() method to list all existing tables.

IgniteTables tableApi = client.tables();
List<Table> existingTables = tableApi.tables();
Table firstTable = existingTables.get(0);

Table myTable = tableApi.table("MY_TABLE");
var existingTables = await Client.Tables.GetTablesAsync();
var firstTable = existingTables[0];

var myTable = await Client.Tables.GetTableAsync("MY_TABLE");
using namespace ignite;

auto table_api = client.get_tables();
std::vector<table> existing_tables = table_api.get_tables();
table first_table = existing_tables.front();

std::optional<table> my_table = table_api.get_table("MY_TABLE);

Basic Table Operations

Once you’ve got a table you need to get a specific view to choose how you want to operate table records.

Binary Record View

A binary record view. It can be used to operate table tuples directly.

RecordView<Tuple> view = myTable.recordView();

//create a new person record
Tuple fullRecord = Tuple.create()
        .set("id", 42)
        .set("name", "John Doe");

view.upsert(null, fullRecord);

//create a key to find record with id = 42
Tuple keyRecord = Tuple.create().set("id", 42);

Tuple resultRecord = view.get(null, keyRecord);

System.out.println("id: " + resultRecord.intValue("id"));
System.out.println("name: " + resultRecord.stringValue("name"));
IRecordView<IIgniteTuple> view = table.RecordBinaryView;

IIgniteTuple fullRecord = new IgniteTuple
{
  ["id"] = 42,
  ["name"] = "John Doe"
};

await view.UpsertAsync(transaction: null, fullRecord);

IIgniteTuple keyRecord = new IgniteTuple { ["id"] = 42 };
(IIgniteTuple value, bool hasValue) = await view.GetAsync(transaction: null, keyRecord);

Debug.Assert(hasValue);
Debug.Assert(value.FieldCount == 2);
Debug.Assert(value["id"] as int? == 42);
Debug.Assert(value["name"] as string == "John Doe");
record_view<ignite_tuple> view = table.get_record_binary_view();

ignite_tuple record{
  {"id", 42},
  {"name", "John Doe"}
};

view.upsert(nullptr, record);
std::optional<ignite_tuple> res_record = view.get(nullptr, {"id", 42});

assert(res_record.has_value());
assert(res_record->column_count() == 2);
assert(res_record->get<std::int64_t>("id") == 42);
assert(res_record->get<std::string>("name") == "John Doe");

Record View

A record view mapped to a user type. It can be used to operate table using user objects which are mapped to table tuples.

RecordView<Person> personView = myTable.recordView(Mapper.of(Person.class));

//insert a new Person object
personView.upsert(null, new Person(42, "John Doe", 30));

//retrieve the Person object with id = 42
Person resultRecord = personView.get(null, new Person(42, "Jane Doe", 32));

System.out.println("id: " + resultRecord.id);
System.out.println("name:" + resultRecord.name);
var pocoView = table.GetRecordView<Poco>();

await pocoView.UpsertAsync(transaction: null, new Poco(42, "John Doe"));
var (value, hasValue) = await pocoView.GetAsync(transaction: null, new Poco(42));

Debug.Assert(hasValue);
Debug.Assert(value.Name == "John Doe");

public record Poco(long Id, string? Name = null);
record_view<person> view = table.get_record_view<person>();

person record(42, "John Doe");

view.upsert(nullptr, record);
std::optional<person> res_record = view.get(nullptr, person{42});

assert(res.has_value());
assert(res->id == 42);
assert(res->name == "John Doe");

Key-Value Binary View

A binary key-value view. It can be used to operate table using key and value tuples separately.

KeyValueView<Tuple, Tuple> kvView = myTable.keyValueView();

Tuple key = Tuple.create().set("id", 42);
Tuple val = Tuple.create().set("name", "John Doe").set("age", 30);

kvView.put(null, key, val);

Tuple resultRecord = kvView.get(null, key);
System.out.println("age: " + resultRecord.intValue("age"));
System.out.println("name: " + resultRecord.stringValue("name"));
IKeyValueView<IIgniteTuple, IIgniteTuple> kvView = table.KeyValueBinaryView;

IIgniteTuple key = new IgniteTuple { ["id"] = 42 };
IIgniteTuple val = new IgniteTuple { ["name"] = "John Doe" };

await kvView.PutAsync(transaction: null, key, val);
(IIgniteTuple? value, bool hasValue) = await kvView.GetAsync(transaction: null, key);

Debug.Assert(hasValue);
Debug.Assert(value.FieldCount == 1);
Debug.Assert(value["name"] as string == "John Doe");
key_value_view<ignite_tuple, ignite_tuple> kv_view = table.get_key_value_binary_view();

ignite_tuple key_tuple{{"id", 42}};
ignite_tuple val_tuple{{"name", "John Doe"}};

kv_view.put(nullptr, key_tuple, val_tuple);
std::optional<ignite_tuple> res_tuple = kv_view.get(nullptr, key_tuple);

assert(res_tuple.has_value());
assert(res_tuple->column_count() == 2);
assert(res_tuple->get<std::int64_t>("id") == 42);
assert(res_tuple->get<std::string>("name") == "John Doe");

Key-Value View

A key-value view with user objects. It can be used to operate table using key and value user objects mapped to table tuples.

KeyValueView<Integer, PersonKV> personView =
        myTable.keyValueView(Mapper.of(Integer.class), Mapper.of(PersonKV.class));

personView.put(null, 42, new PersonKV("John Doe", 30));
PersonKV val = personView.get(null, 42);

System.out.println("name: " + val.name);
IKeyValueView<long, Poco> kvView = table.GetKeyValueView<long, Poco>();

await kvView.PutAsync(transaction: null, 42, new Poco(Id: 0, Name: "John Doe"));
(Poco? value, bool hasValue) = await kvView.GetAsync(transaction: null, 42);

Debug.Assert(hasValue);
Debug.Assert(value.Name == "John Doe");

public record Poco(long Id, string? Name = null);
key_value_view<person, person> kv_view = table.get_key_value_view<person, person>();

kv_view.put(nullptr, {42}, {"John Doe"});
std::optional<person> res = kv_view.get(nullptr, {42});

assert(res.has_value());
assert(res->id == 42);
assert(res->name == "John Doe");

Criterion Queries

GridGain 9 provides the criterion queries that can be used to retrieve data from tables. Criterion queries work with any type of view, returning the appropriate data to the query specified.

The example below shows how you can execute a query within an implicit transaction:

try (Cursor<Map.Entry<Tuple, Tuple>> cursor = kvView.query(
        null,
        and(columnValue("name", equalTo("John Doe")), columnValue("age", greaterThan(20)))
)) {
    // ...
}

The comparison query are specified by using the query() method, and providing the comparison criteria in the columnValue method.

You can also specify the specific transaction to execute the query in to perform the query in that specific transaction.

Ignite client = node.api();
Transaction tx = client.transactions().begin();

try (Cursor<Map.Entry<Tuple, Tuple>> cursor = kvView.query(
        tx,
        and(columnValue("name", equalTo("John Doe")), columnValue("age", greaterThan(20)))
)) {
    // ...
}

tx.commit();

Asynchronous Queries

You can also perform the query asynchronously by using the queryAsync method. This way the query is executed without blocking the thread. For example, you can execute the above query asynchronously:

kvView.queryAsync(null, and(columnValue("name", equalTo("John Doe")), columnValue("age", greaterThan(20))))
        .thenCompose(this::fetchAllRowsInto)
        .join();

This operation uses the thenCompose() method to handle the query results asynchronously in the user-defined fetchAllRowsInto() method. Here is how this method may look like:

public CompletionStage<Void> fetchAllRowsInto(AsyncCursor<Map.Entry<Tuple, Tuple>> cursor) {
    // Process the current page.
    for (var row : cursor.currentPage()) {
        // ...
    }
    // Finish processing if no more data is currently available.
    if (!cursor.hasMorePages()) {
        return CompletableFuture.completedFuture(null);
    }
    // Request for the next page, then subscribe to the response.
    return cursor.fetchNextPage().thenCompose(this::fetchAllRowsInto);
}

Comparison Expressions

The following expressions are supported in criterion queries:

Expression Description Example

equalTo

Checks if the object is equal to the value.

columnValue("City", equalTo("New York"))

notEqualTo

Checks if the object is not equal to the value.

columnValue("City", notEqualTo("New York"))

greaterThan

Checks if the object is greater than the value.

columnValue("Salary", greaterThan(10000))

greaterThanOrEqualTo

Checks if the object is greater than or equal to the value.

columnValue("Salary", greaterThanOrEqualTo(10000))

lessThan

Checks if the object is less than the value.

columnValue("Salary", lessThan(10000))

lessThanOrEqualTo

Checks if the object is less than or equal to the value.

columnValue("Salary", lessThanOrEqualTo(10000))

nullValue

Checks if the object is null.

columnValue("City", nullValue()

notNullValue

Checks if the object is not null.

columnValue("City", notNullValue())

in

Checks if the object is in the collection.

columnValue("City", in("New York", "Washington"))

notIn

Checks if the object is not in the collection.

columnValue("City", notIn("New York", "Washington"))

Comparison Operators

The following operators are supported in criterion queries:

Operator Description Example

not

Negates the condition.

not(columnValue("City", equalTo("New York")))

and

Used to evaluate multiple conditions at the same time.

and(columnValue("City", equalTo("New York")), columnValue("Salary", greaterThan(10000)))

or

Used to evaluate for at least one matching condition.

or(columnValue("City", equalTo("New York")), columnValue("Salary", greaterThan(10000)))

© 2024 GridGain Systems, Inc. All Rights Reserved. Privacy Policy | Legal Notices. GridGain® is a registered trademark of GridGain Systems, Inc.
Apache, Apache Ignite, the Apache feather and the Apache Ignite logo are either registered trademarks or trademarks of The Apache Software Foundation.

Last updated on Nov 21, 2024