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, SQL, and SAM.

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.

SAM

SAM is separate from vector search. It performs term and intent-style lookup, not vector similarity search.

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

Response status = client.samStatus("music");
Response history = client.samHistory("music", 5);
Response results = client.samSearch("music", "queen of pop");

System.out.println(status.getRawBody());
System.out.println(history.getRawBody());
System.out.println(results.getRawBody());

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 issues or create new ones
• Contribute to client libraries (Node.js, Go, Java, Python, PHP, Ruby, Rust, Perl, C++)
• Test and report bugs
• Improve documentation

Community

• 📖 Documentation
• 🐦 X (Twitter)
• 📦 GitHub