Skip to content

Commit 542b395

Browse files
genezhangCopilot
andcommitted
docs: add Language Bindings wiki page and update Embedded Mode for Go
- Create docs/wiki/Language-Bindings.md: comprehensive hub page covering Rust, Python, and Go APIs with comparison table, code examples, architecture diagram, and binding selection guide - Update docs/wiki/Embedded-Mode.md: add Go as Option D with full examples (query, S3 credentials, SQL debugging, export, build steps), update 'Three Ways' → 'Four Ways', add Go to comparison table - Update docs/wiki/Home.md: add Language Bindings link to Getting Started Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
1 parent f82382b commit 542b395

3 files changed

Lines changed: 431 additions & 1 deletion

File tree

docs/wiki/Embedded-Mode.md

Lines changed: 79 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -15,12 +15,13 @@ This is similar to how [DuckDB](https://duckdb.org/) and [Kuzu](https://kuzudb.c
1515
| Query S3 / Iceberg / Delta Lake without a server | **Embedded mode** |
1616
| Embed graph queries in a Rust application | **Embedded mode (Rust library)** |
1717
| Embed graph queries in a Python application | **Embedded mode (Python library)** |
18+
| Embed graph queries in a Go application | **Embedded mode (Go library)** |
1819
| Edge / serverless deployment | **Embedded mode** |
1920
| Development & prototyping without a database | **Embedded mode** |
2021

2122
---
2223

23-
## Three Ways to Use Embedded Mode
24+
## Four Ways to Use Embedded Mode
2425

2526
### Option A — Standalone Server (HTTP + Bolt)
2627

@@ -151,6 +152,80 @@ for row in result:
151152
print(row["u.name"]) # dict access, same as Neo4j Record
152153
```
153154

155+
### Option D — Go Library
156+
157+
Embed ClickGraph in a Go application. Bindings are auto-generated via [Mozilla UniFFI](https://github.com/mozilla/uniffi-rs):
158+
159+
```go
160+
package main
161+
162+
import (
163+
"fmt"
164+
"log"
165+
166+
clickgraph "github.com/genezhang/clickgraph-go"
167+
)
168+
169+
func main() {
170+
db, err := clickgraph.Open("schema.yaml")
171+
if err != nil { log.Fatal(err) }
172+
defer db.Close()
173+
174+
conn, err := db.Connect()
175+
if err != nil { log.Fatal(err) }
176+
defer conn.Close()
177+
178+
result, err := conn.Query("MATCH (u:User)-[:FOLLOWS]->(f:User) RETURN u.name, f.name LIMIT 10")
179+
if err != nil { log.Fatal(err) }
180+
defer result.Close()
181+
182+
for result.HasNext() {
183+
row := result.Next()
184+
fmt.Printf("%v%v\n", row.Get("u.name"), row.Get("f.name"))
185+
}
186+
}
187+
```
188+
189+
**With S3 credentials:**
190+
191+
```go
192+
db, _ := clickgraph.OpenWithConfig("schema.yaml", clickgraph.Config{
193+
S3AccessKeyID: "AKIA...",
194+
S3SecretAccessKey: "...",
195+
S3Region: "us-east-1",
196+
})
197+
```
198+
199+
**SQL debugging:**
200+
201+
```go
202+
sql, _ := conn.QueryToSQL("MATCH (u:User) RETURN u.name")
203+
fmt.Println(sql)
204+
// → SELECT <table>.<column> AS `u.name` FROM <database>.<table>
205+
```
206+
207+
**Export results to files:**
208+
209+
```go
210+
conn.Export("MATCH (u:User) RETURN u.name, u.email", "users.parquet", nil)
211+
conn.Export("MATCH (u:User) RETURN u.name", "users.csv", nil)
212+
conn.Export("MATCH (u:User) RETURN u.name", "data.parquet", &clickgraph.ExportOptions{
213+
Compression: "zstd",
214+
})
215+
```
216+
217+
**Building** requires the `clickgraph-ffi` Rust shared library:
218+
219+
```bash
220+
cargo build -p clickgraph-ffi --release
221+
export CGO_LDFLAGS="-L/path/to/clickgraph/target/release -lclickgraph_ffi"
222+
export LD_LIBRARY_PATH="/path/to/clickgraph/target/release"
223+
cd clickgraph-go && go build ./...
224+
```
225+
226+
👉 **Full Go API documentation**[`clickgraph-go/README.md`](../../clickgraph-go/README.md)
227+
👉 **All language bindings**[Language Bindings](Language-Bindings.md)
228+
154229
**Export results to files:**
155230

156231
Write query results directly to Parquet, CSV, TSV, JSON, or NDJSON files. The format is auto-detected from the file extension:
@@ -537,6 +612,8 @@ let db = Database::new("schema.yaml", SystemConfig {
537612
| **Export to file** | ❌ | ✅ Parquet, CSV, TSV, JSON, NDJSON |
538613
| HTTP + Bolt endpoints | ✅ | ✅ (`--embedded` flag) |
539614
| Rust library API | ❌ | ✅ (`clickgraph-embedded`) |
615+
| Python library API | ❌ | ✅ (`clickgraph-py`) |
616+
| Go library API | ❌ | ✅ (`clickgraph-go`) |
540617
| Performance at scale | ✅ Full ClickHouse cluster | ✅ Single-node chdb |
541618
| Schema admin endpoints | ✅ | ⚠️ Unavailable (no ClickHouse) |
542619
| Cargo feature flag | (default) | `--features embedded` |
@@ -554,6 +631,7 @@ let db = Database::new("schema.yaml", SystemConfig {
554631

555632
## Related Pages
556633

634+
- **[Language Bindings](Language-Bindings.md)** — Comparison of Rust, Python, and Go APIs
557635
- **[Schema Basics](Schema-Basics.md)** — YAML schema configuration
558636
- **[API Reference HTTP](API-Reference-HTTP.md)** — HTTP endpoint documentation
559637
- **[Quick Start Guide](Quick-Start-Guide.md)** — Standard ClickHouse setup

docs/wiki/Home.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -70,6 +70,7 @@ curl -X POST http://localhost:8080/query \
7070
### Getting Started
7171
- **[Quick Start Guide](Quick-Start-Guide.md)** - 5-minute Docker setup
7272
- **[Embedded Mode](Embedded-Mode.md)** - 🆕 In-process graph queries over Parquet/Iceberg/Delta (no ClickHouse needed)
73+
- **[Language Bindings](Language-Bindings.md)** - 🆕 Rust, Python, and Go library APIs
7374
- **[Installation Guide](Installation-Guide.md)** - Detailed installation options
7475
- **[Your First Graph](Your-First-Graph.md)** - Build a simple social network graph
7576

0 commit comments

Comments
 (0)