A clean, idiomatic Java client library for hlquery, designed with a familiar and intuitive API structure.

What is the hlquery Java API?

The hlquery Java API is the official Java client for hlquery. It wraps hlquery's HTTP/JSON endpoints in a single client object with helpers for collections, documents, search, vector search, and SQL.

It is intended for JVM services, tools, and applications that want a straightforward hlquery integration layer instead of manual request construction.

Why use it?

The Java API gives Java applications a familiar client layout, response objects for status checks and raw body access, coverage for the main hlquery endpoint families, and a simple path for both high-level helpers and raw requests.

Install

Build with the included Makefile:

$ make

This downloads the required org.json dependency and compiles the client sources.

SQL

Client client = new Client(Config.getDefaultBaseUrl());

Response rows = client.sql("SHOW COLLECTIONS;");
Response products = client.sqlSearch(
    "products",
    "SELECT id, title, price FROM products ORDER BY price DESC LIMIT 3;"
);
Response insert = client.sqlWrite(
    "INSERT INTO products (id, title, price) VALUES ('sku-4', 'Desk Lamp', 49);"
);
Response delete = client.sqlExec("DELETE FROM products WHERE id = 'sku-4';");
Response drop = client.sqlPost("DROP COLLECTION old_products;");

System.out.println(rows.getRawBody());
System.out.println(products.getRawBody());

The SQL helpers cover top-level SQL (client.sql, client.sqlPost, client.sqlExec, client.sqlSelect, client.sqlWrite) and collection-bound SQL search (client.sqlSearch, client.sqlSearchPost). Use top-level SQL for SHOW COLLECTIONS, INSERT, DELETE, and DROP; use collection-bound SQL for SELECT queries tied to one collection.

Reduce Text Example

Use the raw request helper for custom module routes:

Map<String, String> query = new HashMap<>();
query.put("q", "example query");

Response moduleResponse = client.executeRequest(
    "GET",
    "/modules/<name>/<route>",
    null,
    query
);

System.out.println(moduleResponse.getRawBody());

TODO

• Add a small typed layer (request/response DTOs) for the most common endpoints.
• Publish as a proper Maven artifact (use Maven/Gradle dependency management, not curl).

Contributing

We welcome contributions from the community! All contributions must be released under the BSD 3-Clause license.

How to Contribute

• Check existing Java API issues or create new ones
• Contribute Java client changes to hlquery/java-api
• Contribute shared server/API changes to hlquery/hlquery
• Test and report bugs against the Java client
• Improve Java-specific documentation and examples

Search all collections

Response result = client.searchAll(Map.of("q", "research", "limit", 20));
Response selected = client.searchAll(Map.of("q", "research", "collections", "universities,science"));

globalSearch remains available as an equivalent name. Results are globally merged and each hit includes document._collection.

Community

• 📖 Documentation
• 🐦 X (Twitter)
• ☕ Java API GitHub
• 📦 hlquery GitHub

License

The hlquery Java API is licensed under the BSD 3-Clause License.