Skip to main content

C++ Client

The hlquery C++ client provides a modern C++17 API for interacting with hlquery servers from C++ applications. The preferred call style uses service objects, for example client.system()->health() and client.collections()->list(0, 10).

Features​

  • C++17: Modern C++ features
  • Minimal Dependencies: Uses nlohmann/json (included) and standard C++ libraries
  • HTTPS Support: Optional OpenSSL support for secure connections
  • Type-safe Responses: Response objects with helper methods
  • Consistent API Design: Familiar structure for developers
  • Authentication Support: Bearer token and X-API-Key authentication
  • Comprehensive Validation: Input validation for all operations

Requirements​

  • C++17 or later
  • nlohmann/json (included in vendor/json/json.hpp)
  • OpenSSL (optional, for HTTPS support)

Building​

Using Make​

cd api/cpp
make

This will build:

  • build/libhlqueryclient.a - Static library
  • build/basic_usage - Example executable

All build artifacts are placed in the build/ directory.

To clean build artifacts:

make clean

This removes the entire build/ directory.

Quick Start​

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

int main() {
    try {
        // Initialize client
        hlquery::Client client("http://localhost:9200");
        
        // Health check
        auto health = client.system()->health();
        std::cout << "Status: " << health.getStatusCode() << std::endl;
        
        // List collections
        auto collections = client.collections();
        auto list = collections->list(0, 10);
        if (list.isSuccess()) {
            auto body = list.getBody();
            // Process collections...
        }
        
    } catch (const std::exception& e) {
        std::cerr << "Error: " << e.what() << std::endl;
        return 1;
    }
    
    return 0;
}

API Reference​

Client Initialization​

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

// With options
std::map<std::string, std::string> options;
options["timeout"] = "60";
options["token"] = "your_token";
options["auth_method"] = "bearer";
hlquery::Client client("http://localhost:9200", options);

Authentication​

// Set token
client.setAuthToken("your_token_here", "bearer");

// Or use API key
client.setAuthToken("your_api_key", "api-key");

// Clear authentication
client.clearAuth();

Health & Status​

health()​

Check server health status.

auto health = client.system()->health();
if (health.isSuccess()) {
    auto body = health.getBody();
    std::cout << "Status: " << body["status"] << std::endl;
}

stats()​

Get server statistics.

auto stats = client.system()->stats();
auto body = stats.getBody();
std::cout << "Collections: " << body["collections"]["total"] << std::endl;

info()​

Get server information.

auto info = client.system()->info();

Collections API​

Using Collections API Object​

auto collections = client.collections();

// List collections
auto result = collections->list(0, 10);

// Get collection
auto result = collections->get("my_collection");

// Create collection
nlohmann::json schema = {
    {"fields", {
        {{"name", "title"}, {"type", "string"}},
        {{"name", "price"}, {"type", "float"}}
    }}
};
auto result = collections->create("new_collection", schema);

// Delete collection
auto result = collections->remove("collection_name");

// Update collection
auto result = collections->update("collection_name", {
    {"fields", {{{"name", "new_field"}, {"type", "string"}}}}
});

Direct Client compatibility shortcuts exist for some collection operations, but new code should use client.collections()->....

Documents API​

Using Documents API Object​

auto documents = client.documents();

// List documents
auto result = documents->list("collection_name", {{"offset", "0"}, {"limit", "10"}});

// Get document
auto result = documents->get("collection_name", "document_id");

// Add document
nlohmann::json doc = {
    {"id", "doc1"},
    {"title", "Example"},
    {"price", 99.99}
};
auto result = documents->add("collection_name", doc);

// Update document
auto result = documents->update("collection_name", "doc_id", doc);

// Delete document
auto result = documents->remove("collection_name", "doc_id");

// Import documents (bulk)
std::vector<nlohmann::json> docs = {doc1, doc2, doc3};
auto result = documents->importDocuments("collection_name", docs);

Direct Client compatibility shortcuts exist for some document operations, but new code should use client.documents()->....

Search API​

Using Collection Search Methods​

// Perform search
std::map<std::string, std::string> params = {
    {"q", "laptop"},
    {"query_by", "title,description"},
    {"filter_by", "price:>1000"},
    {"sort_by", "price:asc"},
    {"limit", "10"}
};
auto result = client.collections()->search("collection_name", params);

// Multi-search
std::vector<nlohmann::json> searches = {
    {{"collection", "products"}, {"q", "laptop"}},
    {{"collection", "articles"}, {"q", "laptop"}}
};
auto multi = client.multiSearch(searches);

// Vector search
std::map<std::string, std::string> vectorParams = {
    {"vector", "0.1,0.2,0.3"},
    {"limit", "10"}
};
auto vector = client.collections()->vectorSearch("collection_name", vectorParams);

Direct Client compatibility shortcuts exist for some search operations, but collection-scoped search should use client.collections()->search(...).

Response Objects​

All API methods return a Response object with helper methods:

auto response = client.system()->health();

// Get HTTP status code
int status_code = response.getStatusCode();

// Get response body
auto body = response.getBody();

// Check if successful
if (response.isSuccess()) {
    // Handle success
}

// Check if error
if (response.isError()) {
    std::string error = response.getError();
    std::cerr << "Error: " << error << std::endl;
}

Error Handling​

The client throws custom exceptions:

#include "hlquery/exceptions.h"

try {
    auto result = client.collections()->create("collection", schema);
} catch (const hlquery::AuthenticationException& e) {
    std::cerr << "Authentication failed: " << e.what() << std::endl;
} catch (const hlquery::RequestException& e) {
    std::cerr << "Request failed: " << e.what() << std::endl;
} catch (const hlquery::HlqueryException& e) {
    std::cerr << "Error: " << e.what() << std::endl;
}

Linking the Library​

To use the client library in your project:

// Include the headers
#include "hlquery/client.h"

// Link against the static library
// g++ -std=c++17 your_code.cpp -L/path/to/build -lhlqueryclient -lcurl -lssl -lcrypto

Examples​

See the examples/ directory for complete examples:

  • basic_usage.cpp - Basic usage examples

Next Steps​