Querying Data with Ickle and the JavaScript Client

What You Will Learn

How to register a Protobuf schema, store Protostream-encoded data, and run Ickle queries including WHERE clauses and projections.

Prerequisites

Node.js 22+
An Infinispan Server running on localhost:11222
The protobufjs npm package (installed via npm install)

Start an Infinispan Server with Docker or Podman:

docker run -it --rm -p 11222:11222 -e USER=admin -e PASS=password quay.io/infinispan/server:latest

Tip	You can replace `docker` with `podman` in the command above if you use Podman.

Note	The `protoStreamCache` is created automatically by the setup script using the admin API.

Step 1: Define a Protobuf Schema

Define a Person schema with a @TypeId annotation for Protostream registration:

syntax = "proto3";
package tutorial;
/**
 * @TypeId(1000042)
 */
message Person {
    string firstName = 1;
    string lastName = 2;
    int32 bornYear = 3;
    string bornIn = 4;
}

const metaClient = await ispn.client(addr, {
    cacheName: '___protobuf_metadata',
    dataFormat: {keyType: 'text/plain', valueType: 'text/plain'},
    authentication: { ... }
});
await metaClient.put('tutorial/Person.proto', personProto);

Step 2: Connect with Protostream Encoding

Connect to the cache with Protostream value format, text/plain keys, and register the type:

const client = await ispn.client(addr, {
    cacheName: 'protoStreamCache',
    topologyUpdates: false,
    dataFormat: {
        keyType: 'text/plain',
        valueType: 'application/x-protostream'
    },
    authentication: { ... }
});

client.registerProtostreamRoot(root);
client.registerProtostreamType('.tutorial.Person', 1000042);

Step 3: Add Data

Create Protobuf messages with protobufjs and put them in the cache:

const Person = root.lookupType('.tutorial.Person');
const message = Person.create({firstName: 'Hermione', lastName: 'Granger', bornYear: 1979, bornIn: 'London'});
await client.put('0', message);

Step 4: Run Ickle Queries

Query all entries:

const all = await client.query({queryString: 'from tutorial.Person'});

Filter with a WHERE clause:

const grangers = await client.query({
    queryString: "from tutorial.Person p where p.lastName = 'Granger'"
});

Use projections to select specific fields:

const names = await client.query({
    queryString: "select p.firstName, p.lastName from tutorial.Person p where p.bornIn = 'London'"
});

Projection results are returned as arrays of field values.

Step 5: Run the Tutorial

npm run query

You should see output like:

Registered person.proto schema.
Added 4 people.

=== Query all ===
Total results: 4
  Draco Malfoy
  Harry Potter
  Hermione Granger
  Ron Wesley

=== Query: people with lastName = 'Granger' ===
  Hermione Granger

=== Query: projection of people born in London ===
  Draco Malfoy
  Hermione Granger
  Ron Wesley

Cache cleared.

What’s Next

Schema management for registering and retrieving schemas
Basic cache operations for standard cache usage