A modern async Rust client library for hlquery, designed with a familiar and intuitive API structure.

What is the hlquery Rust API?

The hlquery Rust API is the official Rust client for hlquery. It wraps the server's HTTP interface in an async client with helpers for collections, documents, search, and SQL.

It is intended for async services, tools, and applications that want strong typing and a small high-level integration layer over hlquery.

Why use it?

• Async-first design built for Tokio.
• Strong typing and structured error handling.
• Modular API objects for collections, search, and SQL.
• Raw request helper for custom routes.

Why choose it over raw HTTP?

Choose the Rust client over raw HTTP when you want less repetitive request building and JSON parsing, cleaner auth and timeout handling, and application-level search code that stays compact.

Install

Add to Cargo.toml:

[dependencies]
hlquery-rust-client = { path = "../etc/api/rust" }
tokio = { version = "1", features = ["full"] }

If published:

[dependencies]
hlquery-rust-client = "1.0"
tokio = { version = "1", features = ["full"] }

Quick Start

use hlquery_rust_client::Client;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let base_url = std::env::var("HLQ_BASE_URL")
        .or_else(|_| std::env::var("HLQUERY_BASE_URL"))
        .unwrap_or_else(|_| "http://localhost:9200".to_string());

    let client = Client::new(&base_url, None)?;

    let health = client.health().await?;
    println!("Status: {}", health.get_status_code());

    let collections = client.list_collections(0, 10).await?;
    println!("{}", collections.get_body());

    Ok(())
}

Auth

use hlquery_rust_client::Client;
use std::collections::HashMap;

let mut options = HashMap::new();
options.insert("token".to_string(), "your_token_here".to_string());
options.insert("auth_method".to_string(), "bearer".to_string());

let client = Client::new("http://localhost:9200", Some(options))?;
client.set_auth_token("your_api_key_here".to_string(), "api-key".to_string());

SQL

let client = Client::new("http://localhost:9200", None)?;

let rows = client.sql("SHOW COLLECTIONS;", None).await?;
let exec_result = client
    .exec_sql("INSERT INTO logs_archive (id, title) VALUES ('row-1', 'warm cache');")
    .await?;
let products = client
    .sql_search(
        "products",
        "SELECT id, title, price FROM products WHERE price > 100 ORDER BY price DESC LIMIT 3;",
        None,
    )
    .await?;

let sql_api = client.sql_api();
let same_rows = sql_api.query("SHOW COLLECTIONS;", None).await?;

Contributing

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

How to Contribute

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

Search all collections

let result = client.search_api().search_all("GET", None, Some(params)).await?;

Use POST with a JSON body to pass a collection array. global_search remains available as an equivalent name. Results are globally merged and each hit includes document._collection.

Community

• 📖 Documentation
• 🐦 X (Twitter)
• 🛡️ Rust API GitHub
• 📦 hlquery GitHub

License

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