Skip to content

README.md

Latest commit

 

History

History
188 lines (130 loc) · 5.88 KB

README.md

File metadata and controls

188 lines (130 loc) · 5.88 KB
Raw
hlquery logo

A modular C++ client library for hlquery with a familiar service-based API.

Follow hlquery cpp-api GitHub License

What is the hlquery C++ API?

The hlquery C++ API is the official C++ client for hlquery. It wraps the server's HTTP/JSON interface in a small typed client with response helpers, auth support, SQL helpers, and service objects for system, collections, documents, search, and administration routes.

It is intended for native services, command-line tools, and applications that want direct hlquery access without manually assembling HTTP calls.

Why use it?

Use the C++ client when your application already lives close to hlquery and you want the search layer to feel native instead of like a pile of hand-built HTTP calls. The library keeps request setup, authentication, response parsing, and endpoint routing in one place, so application code can work with collections, documents, search, SQL, and system routes through one small client surface.

It is still close to the server API. The preferred style is to access endpoints through service objects, such as client.system()->health() and client.collections()->list(0, 10). Compatibility shortcuts on Client remain available, and the raw request helper can still be used for custom module routes or newer endpoints that have not yet grown a dedicated wrapper. That makes it useful for production services that want a stable integration point without losing access to hlquery's full HTTP surface.

Installation

Build locally:

$ make

On FreeBSD, use:

$ gmake

Build modes:

$ make OPENSSL=0
$ make OPENSSL=1

Artifacts are written to build/.

Quick start

#include "hlquery/client.h"
#include <iostream>

int main() {
    try {
        hlquery::Client client("http://localhost:9200");

        auto health = client.system()->health();
        std::cout << "Status: " << health.getStatusCode() << std::endl;

        auto collections = client.collections();
        auto list = collections->list(0, 10);

        if (list.isSuccess()) {
            std::cout << list.getBody().dump(2) << std::endl;
        }
    } catch (const std::exception& e) {
        std::cerr << "Error: " << e.what() << std::endl;
        return 1;
    }

    return 0;
}

Authentication

hlquery::Client client("http://localhost:9200");

client.setAuthToken("your_token_here", "bearer");
client.setAuthToken("your_api_key_here", "api-key");
client.clearAuth();

System

Use the system helper for operational routes:

hlquery::Client client("http://localhost:9200");

auto system = client.system();
auto status = system->status();
auto metrics = system->metricsJson();
auto storage = system->storageStatus();

std::cout << status.getBody().dump(2) << std::endl;
std::cout << metrics.getBody().dump(2) << std::endl;
std::cout << storage.getBody().dump(2) << std::endl;

Collections

hlquery::Client client("http://localhost:9200");

auto collections = client.collections();
auto list = collections->list(0, 10);
auto metadata = collections->get("products");

std::cout << list.getBody().dump(2) << std::endl;
std::cout << metadata.getBody().dump(2) << std::endl;

SQL

hlquery::Client client("http://localhost:9200");

auto rows = client.system()->sql("SHOW COLLECTIONS;");
auto products = client.sql(
    "products",
    "SELECT id, title, price FROM products ORDER BY price DESC LIMIT 3;"
);

Copy Collections

Copy a collection (schema + all documents) into a new collection name:

hlquery::Client client("http://localhost:9200");
auto result = client.collections()->copy("source_collection", "target_collection");
std::cout << result.getBody().dump(2) << std::endl;

Custom Module Routes

Use the raw request helper for custom module routes:

hlquery::Client client("http://localhost:9200");

auto response = client.executeRequest(
    "GET",
    "/modules/<name>/<route>",
    "",
    {
        {"q", "example query"}
    }
);

Contributing

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

How to Contribute

  • Check existing C++ API issues or open a new one
  • Contribute C++ client changes to hlquery/cpp-api
  • Contribute shared server/API changes to hlquery/hlquery
  • Test and report bugs against the C++ client
  • Improve C++-specific documentation and examples

Search all collections

auto result = client.searchAll({{"q", "research"}, {"limit", "20"}});
auto selected = client.searchAll({{"q", "research"}, {"collections", "universities,science"}});

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

Community

License

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