Skip to content

HD SDK — Architecture

The SDK is one C++ core, fermihdi_client, with bindings for eight other languages built on top of it. See the SDK overview for the part that matters most — the control plane / data plane split — and the API reference for every method. This page is the shape underneath both.

Why one core, not eight implementations

A query's data plane is latency-sensitive: Storage Nodes stream records straight into the client's own listener, out of band from the request that asked for them. Reimplementing that wire protocol and the HD engine's memory handling separately in Go, Python and JavaScript would mean three copies to keep correct, and three places for the wire format to drift. Instead, every language wraps the same compiled core:

FHDWP transport + the HD engine (C++)
        │
        ▼
fermihdi_client — the public C++ API (FermiHDISDK.hpp)
        │
        ▼
per-language bindings — pybind11, cgo, N-API, cxx, JNA, Rcpp, ccall, or the C ABI directly

Both client classes (FermiHDIQueryClient, FermiHDIIngestClient) use the pimpl idiom and are non-copyable — construct one and keep it; see What construction actually does.

The C ABI

include/fermihdi_c_api.h exports a flat, nothrow C surface from the shared library, so any language with FFI can reach the SDK without a C++ toolchain. It is narrower than the full C++ API today: it carries a target-setting call (fhd_query_client_set_scc_target) but no register_with_dms and no ingest client, which is why six of the eight bindings (Go, Rust, Scala, Julia, R, Mojo) can be handed SCC targets but cannot register as an HD_CLIENT node or ingest. C++, Python, and — for querying only — JavaScript go through the fuller C++ surface instead. The wrapper maturity table has the exact support matrix per language.

What runs where

Construction does real work: it probes for a GPU runtime (falling back to CPU when none is found), starts the HD engine on its own thread, reserves one core and 1 GB of memory, and blocks until the engine reports ready — see What construction actually does.

Two embedded engines process query results locally, inside the client process, after the records arrive:

  • DuckDB — execute_to_sql() decodes the fixed-width record table into typed Arrow columns and runs the given SQL over it locally.
  • USearch — execute_vector_search() builds a dense vector index over the result with cosine distance and returns the nearest rows.

execute_graph() and set_local_aggregations() are declared in the public API but not implemented — see Not implemented for the full list and what each one actually does today. Nothing in the SDK currently offloads work to a GPU beyond the CPU/GPU runtime probe at construction.

Where to go next