Java Client

The hlquery Java client provides a robust, object-oriented API for interacting with hlquery servers from Java applications. It is built using Java 11's native HttpClient and the org.json library.

Features

• Native Java 11+: Built on Java 11's modern HttpClient
• Minimal Dependencies: Only requires org.json
• Type-safe Responses: Response objects with helper methods for JSON parsing
• Consistent API Design: Matches the hlquery API structure across all modules
• Authentication Support: Bearer token and X-API-Key authentication
• Easy Build: Simple Makefile and Maven support

Installation

Using Maven

Add the following to your pom.xml:

<dependency>
    <groupId>hlquery</groupId>
    <artifactId>java-client</artifactId>
    <version>1.0-SNAPSHOT</version>
</dependency>

Manual Build

If you don't use Maven, you can use the provided Makefile to compile:

cd etc/api/java
make

Quick Start

Basic Usage

import hlquery.Client;
import hlquery.Response;
import org.json.JSONObject;

public class Main {
    public static void main(String[] args) {
        // Initialize client
        Client client = new Client("http://localhost:9200");

        // Health check
        Response health = client.health();
        System.out.println("Status: " + health.getStatusCode());

        // List collections
        Response collections = client.listCollections(0, 10);
        if (collections.isSuccess()) {
            JSONObject body = collections.getBodyAsObject();
            System.out.println("Found collections: " + body.getJSONArray("collections").length());
        }
    }
}

With Authentication

// Method 1: Set token in options
Map<String, Object> options = new HashMap<>();
options.put("token", "your_token_here");
options.put("auth_method", "bearer"); // or "api-key"
Client client = new Client("http://localhost:9200", options);

// Method 2: Set token dynamically
client.setAuthToken("your_token_here", "bearer");

// Method 3: Use X-API-Key
client.setAuthToken("your_token_here", "api-key");

API Reference

Client Initialization

Client client = new Client(String baseUrl);
Client client = new Client(String baseUrl, Map<String, Object> options);

Options:

• token (String): Authentication token
• auth_method (String): "bearer" (default) or "api-key"
• timeout (int): Request timeout in seconds (default: 30)

Health & Status

health()

Check server health status.

stats()

Get server statistics.

flush()

Flush all data to disk.

info()

Get server information.

Collections API

Access via client.collections():

Collections collections = client.collections();

// List collections
Response res = collections.list(0, 10);

// Get collection
Response res = collections.get("my_collection");

// Create collection
JSONObject schema = new JSONObject();
// ... define schema ...
Response res = collections.create("new_collection", schema);

// Delete collection
Response res = collections.delete("collection_name");

Documents API

Access via client.documents():

Documents documents = client.documents();

// List documents
Map<String, Object> params = new HashMap<>();
params.put("limit", 10);
Response res = documents.list("collection_name", params);

// Add document
JSONObject doc = new JSONObject();
doc.put("id", "doc1");
doc.put("title", "Java Example");
Response res = documents.add("collection_name", doc);

// Delete document
Response res = documents.delete("collection_name", "doc1");

Search API

Access via client.searchApi() or convenience methods:

Map<String, Object> searchParams = new HashMap<>();
searchParams.put("q", "search term");
searchParams.put("query_by", "title");

// Standard search
Response res = client.search("collection_name", searchParams);

// Vector search
Map<String, Object> vectorParams = new HashMap<>();
vectorParams.put("vector_query", new double[]{0.1, 0.2, 0.3});
Response res = client.vectorSearch("collection_name", vectorParams);

Response Objects

The Response object provides several helper methods:

Response res = client.health();

int status = res.getStatusCode();      // HTTP status code
boolean success = res.isSuccess();      // True if 2xx
String raw = res.getRawBody();          // Raw String response
JSONObject obj = res.getBodyAsObject(); // Parse as JSONObject
JSONArray arr = res.getBodyAsArray();   // Parse as JSONArray

Examples

See the Example.java in the Java client directory for a complete working example.