RESTful queries coming to Infinispan 9.2
RESTful queries coming to Infinispan 9.2
One of the interesting features in the upcoming Infinispan 9.2 release is the possibility to execute queries over the REST endpoint, enabling users to take advantage of the easy-to-use and expressiveness of the Ickle query language, that combines a subset of JP-QL with full-text features. You can learn more info about Ickle in a previous post.
Besides exposing query over REST, Infinispan 9.2 also adds support for mapping between JSON and Protobuf formats, allowing an efficient storage in binary format while exposing queries, reading and writing content as JSON documents.
To illustrate those new capabilities, this post will walk you through a sample app from scratch!
Sample app
Running the server
We start by running the Infinispan Server 9.2.0.CR2 (the latest release candidate):
This will get you a fresh instance of Infinispan running, with login and password 'user' and the REST port 8080 mapped to localhost. TIP: if you run more than one container, they’ll form a cluster automatically.
Creating an indexed cache
Next step is to create an indexed cache called 'pokemon'. We make use of the CLI (Command Line Interface) to create this cache. In the future, with ISPN-8529, we’ll also be able to create cache with arbitrary configuration using REST, but for now we execute a CLI recipe:
Creating the schema
In order to be able to query, we need to define a protobuf schema for our data. The schema follows the Protobuf 2 format (Protobuf 3 support is coming) and allows for extensions to define indexing properties (analyzers, storage, etc).
Here’s how it looks like:
The protobuf schema can contain some comments on top of fields and messages with "annotations" to control indexing. Hibernate Search users will recognize some of those pseudo annotations we are using here: they resemble closely their counterpart.
Registering the schema
Once we have our schema, we can easily register it via REST:
Populating the cache
We’re now ready to put some data in the cache. As mentioned earlier, ingesting can be done by sending JSON documents directly. Once Infinispan receives those documents, it will convert them to protobuf, index and store them.
In order to match a particular inbound document to an entity in the schema, Infinispan uses a special meta field called _type that must be provided in the document. Here’s an example of a JSON document that conforms to our schema:
Writing the document is easy:
we can retrieve content by key as JSON:
Querying
The new query endpoint can be called with an "action" parameter named "search", after the cache name. The simplest query, which returns all data can be done with:
If you do not want to return all the fields, use a Select clause:
Pagination can be controlled with the offset, max_results URL parameters:
Grouping is also possible:
Example of a query result:
Results:
Conclusion
Infinispan 9.2 makes it easier to quickly ingest and query datasets using the ubiquitous JSON format, without sacrificing type safety and storage size.
By storing Protobuf, this will also enable other clients like the Hot Rod C#/C++ clients to query, read and write data simultaneously with REST clients.
The full source code for the demo, along with instructions on how to populate the whole dataset can be found at Github.
Finally, please try out this new feature in your own dataset and let us know how it goes!
Get it, Use it, Ask us!
We’re hard at work on new features, improvements and fixes, so watch this space for more announcements!Please, download and test the latest release.
The source code is hosted on GitHub. If you need to report a bug or request a new feature, look for a similar one on our JIRA issues tracker. If you don’t find any, create a new issue.
If you have questions, are experiencing a bug or want advice on using Infinispan, you can use GitHub discussions. We will do our best to answer you as soon as we can.
The Infinispan community uses Zulip for real-time communications. Join us using either a web-browser or a dedicated application on the Infinispan chat.
