Skip to content

Commit cf6dcfd

Browse files
cferryscferrys
committed
Refine documentation content in README.md.
1 parent 651bff7 commit cf6dcfd

1 file changed

Lines changed: 64 additions & 254 deletions

File tree

‎README.md‎

Lines changed: 64 additions & 254 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@
44

55
<div align="center">
66

7-
**A C++ API for a high-performance search engine built for modern applications.**
7+
**A modular C++ client library for hlquery, designed with a familiar and intuitive API structure.**
88

99
[![Follow hlquery](https://img.shields.io/badge/Follow-%40hlquery-blue?logo=x&logoColor=white)](https://x.com/hlquery)
1010
[![Linux Build](https://github.com/hlquery/cpp-api/workflows/Linux%20build/badge.svg)](https://github.com/hlquery/cpp-api/actions)
@@ -15,76 +15,48 @@
1515

1616
</div>
1717

18+
### What is the hlquery C++ API?
1819

19-
### hlquery C++ API Client
20+
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 SAM support.
2021

21-
A C++ client library for hlquery with modular APIs, authentication support, HTTPS support, type-safe responses, and basic SAM search helpers.
22+
It is intended for native services, command-line tools, and applications that want direct hlquery access without hand-rolling HTTP calls.
2223

23-
### Installation
24+
### Why use it?
2425

25-
Build the client and examples locally:
26+
- Less request and parsing boilerplate than raw HTTP.
27+
- One client entry point for collections, documents, search, SQL, and SAM.
28+
- Optional HTTPS/OpenSSL support.
29+
- Works well for native applications that want a small static client library.
2630

27-
```bash
28-
$ cd cpp-api
29-
$ make
30-
```
31-
32-
On FreeBSD, use GNU make:
33-
34-
```bash
35-
$ cd cpp-api
36-
$ gmake
37-
```
38-
39-
Build modes:
40-
41-
```bash
42-
# Auto-detect OpenSSL with pkg-config (default)
43-
$ make
31+
### Why choose it over raw HTTP?
4432

45-
# Force HTTP-only build with no OpenSSL dependency
46-
$ make OPENSSL=0
33+
- Consistent request setup and auth handling.
34+
- Convenience wrappers for common hlquery endpoints.
35+
- Type-safe response objects with predictable access patterns.
36+
- Raw request escape hatch still exists for custom routes.
4737

48-
# Require OpenSSL and fail fast if it is not available
49-
$ make OPENSSL=1
50-
```
51-
52-
### Using Make
53-
54-
```bash
55-
$ cd cpp-api
56-
$ make
57-
```
38+
### Install
5839

59-
FreeBSD:
40+
Build locally:
6041

6142
```bash
62-
$ cd cpp-api
63-
$ gmake
43+
make
6444
```
6545

66-
This will build:
67-
- `build/libhlqueryclient.a` - Static library
68-
- `build/basic_usage` - Example executable
46+
On FreeBSD, use:
6947

70-
All build artifacts are placed in the `build/` directory.
71-
72-
To clean build artifacts:
7348
```bash
74-
$ make clean
49+
gmake
7550
```
7651

77-
On FreeBSD:
52+
Build modes:
7853

7954
```bash
80-
$ gmake clean
55+
make OPENSSL=0
56+
make OPENSSL=1
8157
```
8258

83-
This removes the entire `build/` directory.
84-
85-
On systems where OpenSSL is installed outside the default compiler include path
86-
(for example Homebrew on macOS), the Makefile now pulls both compiler and linker
87-
flags from `pkg-config`.
59+
Artifacts are written to `build/`.
8860

8961
### Quick Start
9062

@@ -94,250 +66,88 @@ flags from `pkg-config`.
9466

9567
int main() {
9668
try {
97-
// Initialize client
9869
hlquery::Client client("http://localhost:9200");
9970

100-
auto collections = client.collections();
101-
auto documents = client.documents();
102-
103-
// Health check
10471
auto health = client.health();
10572
std::cout << "Status: " << health.getStatusCode() << std::endl;
106-
107-
// List collections
73+
74+
auto collections = client.collections();
10875
auto list = collections->list(0, 10);
76+
10977
if (list.isSuccess()) {
110-
auto body = list.getBody();
111-
// Process collections...
78+
std::cout << list.getBody().dump(2) << std::endl;
11279
}
113-
114-
auto results = collections->search("products", {
115-
{"like", "laptop"},
116-
{"query_by", "title,content"},
117-
{"limit", "10"}
118-
});
119-
12080
} catch (const std::exception& e) {
12181
std::cerr << "Error: " << e.what() << std::endl;
12282
return 1;
12383
}
124-
84+
12585
return 0;
12686
}
12787
```
12888

129-
### Authentication
89+
### Auth
13090

13191
```cpp
132-
// Set token
133-
client.setAuthToken("your_token_here", "bearer");
134-
135-
// Or use API key
136-
client.setAuthToken("your_api_key", "api-key");
92+
hlquery::Client client("http://localhost:9200");
13793

138-
// Clear authentication
94+
client.setAuthToken("your_token_here", "bearer");
95+
client.setAuthToken("your_api_key_here", "api-key");
13996
client.clearAuth();
14097
```
14198
142-
### Search API
99+
### SAM
143100
144-
```cpp
145-
auto collections = client.collections();
146-
147-
// Simple search. "like" is accepted as an alias for "q".
148-
std::map<std::string, std::string> params;
149-
params["like"] = "test";
150-
params["query_by"] = "title,content";
151-
params["limit"] = "10";
152-
auto results = collections->search("collection", params);
153-
154-
// Supported query semantics
155-
// Field-specific search
156-
params["like"] = "title:laptop";
157-
auto field_results = collections->search("collection", params);
158-
159-
// Boolean OR query
160-
params["like"] = "title:laptop OR title:notebook";
161-
auto or_results = collections->search("collection", params);
162-
163-
// Wildcard search
164-
params["like"] = "laptop*";
165-
auto wildcard_results = collections->search("collection", params);
166-
167-
// NOT query
168-
params["like"] = "title:laptop NOT title:refurbished";
169-
auto not_results = collections->search("collection", params);
170-
171-
// Phrase query
172-
params["like"] = "\"wireless keyboard\"";
173-
params["query_by"] = "title";
174-
auto phrase_results = collections->search("collection", params);
175-
176-
// Filter operators belong in filter_by
177-
params["like"] = "*";
178-
params["query_by"] = "title,content";
179-
params["filter_by"] = "price:>100&&category:electronics";
180-
auto filtered_results = collections->search("collection", params);
181-
182-
// SQL search
183-
auto sql_results = client.sql(
184-
"collection",
185-
"SELECT id, title, price FROM collection ORDER BY price DESC LIMIT 5;"
186-
);
187-
std::cout << sql_results.getBody().dump(2) << std::endl;
101+
Use the SAM helpers to inspect indexing status and run SAM search:
188102
189-
// Top-level SQL
190-
auto rows = client.sql("SHOW COLLECTIONS;");
191-
auto insert = client.execSql(
192-
"INSERT INTO collection (id, title, price) VALUES ('sku-9', 'Camp Stove', 89);"
193-
);
194-
195-
// Multi-search stays at the client level because it spans multiple collections/queries.
196-
nlohmann::json multi_a = {
197-
{"collection", "products"},
198-
{"q", "laptop"},
199-
{"query_by", "title,content"}
200-
};
201-
nlohmann::json multi_b = {
202-
{"collection", "products"},
203-
{"q", "keyboard"},
204-
{"query_by", "title,content"}
205-
};
206-
auto multi = client.multiSearch({multi_a, multi_b});
207-
208-
// Vector search
209-
std::map<std::string, std::string> vector_params;
210-
vector_params["vector_query"] = "[0.1,0.2,0.3]";
211-
vector_params["limit"] = "5";
212-
auto vector_results = collections->vectorSearch("collection", vector_params);
213-
214-
// Advanced vector search (POST JSON body)
215-
nlohmann::json vector_body = {
216-
{"vector", {0.1, 0.2, 0.3}},
217-
{"field_name", "embedding"},
218-
{"topk", 5},
219-
{"include_distance", true},
220-
{"query_params", {{"ef", 64}, {"nprobe", 4}, {"is_linear", true}}},
221-
{"radius", 1.0}
222-
};
223-
auto advanced = client.executeRequest("POST", "/collections/collection/vector_search", vector_body);
224-
225-
// SAM search
226-
auto sam = client.samSearch("collection", "wireless keyboard");
227-
auto sam_all = client.samSearchAll("guide", {{"limit", "5"}});
228-
```
229-
230-
Preferred structure:
103+
SAM is separate from vector search. It performs term and intent-style lookup, not vector similarity search.
231104
232105
```cpp
233-
auto collections = client.collections();
234-
auto result = collections->search("products", {{"like", "laptop"}});
235-
```
236-
237-
Compatibility note:
238-
239-
- `client.searchApi()`
240-
- `client.search(...)`
241-
- `client.sqlSearch(...)`
242-
- `client.vectorSearch(...)`
243-
244-
still exist for now, but they are compatibility shims. New code should prefer `client.collections()->search(...)`, `client.sql(...)`, and `client.collections()->vectorSearch(...)`.
245-
246-
### SAM Search
247-
248-
SAM search calls `/sam/search` directly and is useful for broader intent-style lookup.
249-
250-
```cpp
251-
auto sam = client.samSearch("products", "nineteen");
252-
auto sam_all = client.samSearchAll("benchmark", {{"distributed", "on"}, {"limit", "10"}});
253-
```
254-
255-
### Collections And Documents
256-
257-
```cpp
258-
auto collections = client.collections();
259-
auto documents = client.documents();
260-
261-
nlohmann::json schema = {
262-
{"fields", nlohmann::json::array({
263-
{{"name", "title"}, {"type", "string"}},
264-
{{"name", "content"}, {"type", "string"}},
265-
{{"name", "price"}, {"type", "float"}}
266-
})}
267-
};
268-
269-
auto created = collections->create("products", schema);
270-
auto updated = collections->update("products", {
271-
{"add_fields", nlohmann::json::array({
272-
{{"name", "brand"}, {"type", "string"}}
273-
})}
274-
});
275-
276-
auto added = documents->add("products", {
277-
{"id", "sku-1"},
278-
{"title", "Laptop Computer"},
279-
{"content", "High-performance laptop with 16GB RAM"},
280-
{"price", 1299.0}
281-
});
106+
hlquery::Client client("http://localhost:9200");
282107
283-
auto changed = documents->update("products", "sku-1", {
284-
{"price", 1199.0},
285-
{"brand", "hlquery"}
108+
auto sam = client.sam();
109+
auto status = sam->status("music");
110+
auto history = sam->history("music", 5);
111+
auto results = sam->search("music", "queen of pop", {
112+
{"limit", "10"}
286113
});
287114
288-
auto removed = documents->remove("products", "sku-1");
115+
std::cout << status.getBody().dump(2) << std::endl;
116+
std::cout << history.getBody().dump(2) << std::endl;
117+
std::cout << results.getBody().dump(2) << std::endl;
289118
```
290119

291120
### SQL
292121

293-
Quick SQL example:
294-
295-
```cpp
296-
#include "hlquery/client.h"
297-
#include <iostream>
298-
299-
int main()
300-
{
301-
hlquery::Client client("http://localhost:9200");
302-
303-
auto response = client.sql(
304-
"products",
305-
"SELECT id, title, price FROM products ORDER BY price DESC LIMIT 5;"
306-
);
307-
308-
if (!response.isSuccess())
309-
{
310-
std::cerr << response.getError() << std::endl;
311-
return 1;
312-
}
313-
314-
std::cout << response.getBody().dump(2) << std::endl;
315-
return 0;
316-
}
317-
```
318-
319-
Basic SQL example:
320-
321122
```cpp
322123
hlquery::Client client("http://localhost:9200");
323124

324-
auto response = client.sql(
125+
auto rows = client.sql("SHOW COLLECTIONS;");
126+
auto products = client.sql(
325127
"products",
326-
"SELECT id, title, price FROM products ORDER BY price DESC LIMIT 5;"
128+
"SELECT id, title, price FROM products ORDER BY price DESC LIMIT 3;"
327129
);
328-
329-
if (response.isSuccess())
330-
{
331-
std::cout << response.getBody().dump(2) << std::endl;
332-
}
333130
```
334131

335-
Top-level SQL execution:
132+
### Reduce Text Example
133+
134+
Use the raw request helper for custom module routes:
336135

337136
```cpp
338-
auto rows = client.sql("SHOW COLLECTIONS;");
137+
hlquery::Client client("http://localhost:9200");
339138

340-
auto insert = client.execSql(
341-
"INSERT INTO products (id, title, price) VALUES ('sku-9', 'Camp Stove', 89);"
139+
auto response = client.executeRequest(
140+
"GET",
141+
"/modules/<name>/<route>",
142+
"",
143+
{
144+
{"q", "example query"}
145+
}
342146
);
343147
```
148+
149+
### Notes
150+
151+
- `make clean` removes build artifacts.
152+
- When OpenSSL lives outside default include paths, the build uses `pkg-config` to resolve flags.
153+
- See `etc/api/cpp/include/hlquery/` and `etc/api/cpp/src/` for the full client surface.

0 commit comments

Comments
 (0)