{"id":49273503,"url":"https://github.com/zvec-ai/zvec-rust","last_synced_at":"2026-04-25T15:01:30.609Z","repository":{"id":353623953,"uuid":"1209048745","full_name":"zvec-ai/zvec-rust","owner":"zvec-ai","description":"zvec rust binding","archived":false,"fork":false,"pushed_at":"2026-04-24T17:23:48.000Z","size":126,"stargazers_count":0,"open_issues_count":0,"forks_count":2,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-24T19:24:40.901Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/zvec-ai.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-13T03:32:19.000Z","updated_at":"2026-04-24T17:23:59.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/zvec-ai/zvec-rust","commit_stats":null,"previous_names":["zvec-ai/zvec-rust"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/zvec-ai/zvec-rust","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zvec-ai%2Fzvec-rust","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zvec-ai%2Fzvec-rust/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zvec-ai%2Fzvec-rust/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zvec-ai%2Fzvec-rust/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zvec-ai","download_url":"https://codeload.github.com/zvec-ai/zvec-rust/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zvec-ai%2Fzvec-rust/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32265977,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-25T09:15:33.318Z","status":"ssl_error","status_checked_at":"2026-04-25T09:15:31.997Z","response_time":59,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-04-25T15:01:29.448Z","updated_at":"2026-04-25T15:01:30.602Z","avatar_url":"https://github.com/zvec-ai.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# zvec-rust\n\n[![CI](https://github.com/zvec-ai/zvec-rust/actions/workflows/ci.yml/badge.svg)](https://github.com/zvec-ai/zvec-rust/actions/workflows/ci.yml)\n[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)\n\nEnglish | [中文](README_CN.md)\n\nSafe, idiomatic Rust bindings for the [zvec](https://github.com/alibaba/zvec) vector database.\n\n## Features\n\n- **RAII Resource Management** — All C resources are automatically freed via `Drop`\n- **Builder Pattern** — Fluent APIs for schema, query, and configuration\n- **Type Safety** — Rust enums for all C constants with compile-time checks\n- **Comprehensive Error Handling** — All FFI calls return `Result\u003cT\u003e` with detailed error codes\n- **Zero-Copy Where Possible** — Minimizes data copying across the FFI boundary\n- **Prebuilt Libraries** — Automatically downloads prebuilt `libzvec_c_api` from GitHub Releases; advanced users can override with `ZVEC_LIB_DIR`\n\n## Supported Platforms\n\n| Platform | Architecture | CI Status | Notes |\n|----------|-------------|-----------|-------|\n| **macOS** | ARM64 (Apple Silicon) | ✅ Clippy + Test | Primary development platform |\n| **macOS** | x86_64 (Intel) | ✅ Clippy + Test | |\n| **Linux** | x86_64 | ✅ Clippy + Test + Fuzz + Coverage + Benchmark | Full CI coverage |\n| **Linux** | ARM64 (AArch64) | ✅ Clippy + Test + Fuzz + Coverage | |\n| **Windows** | x86_64 (MSVC) | ✅ Clippy + Test | CMake + MSVC toolchain |\n\n\u003e The dynamic library name varies by platform: `libzvec_c_api.dylib` (macOS), `libzvec_c_api.so` (Linux), `zvec_c_api.dll` (Windows).\n\n## Architecture\n\n```\nzvec-rust/\n├── zvec-sys/    # Low-level FFI bindings to libzvec_c_api\n├── zvec/        # Safe, high-level Rust wrapper\n└── fuzz/        # Fuzz testing targets\n```\n\n- **`zvec-sys`** — Raw `extern \"C\"` declarations, opaque pointer types, and constants\n- **`zvec`** — Safe wrappers with RAII, builders, iterators, and idiomatic Rust APIs\n\n## Prerequisites\n\nThe Rust SDK depends on the zvec C library (`libzvec_c_api`). **For most users, no manual setup is needed** — the build script automatically downloads a prebuilt library from GitHub Releases.\n\n### For Regular Users (Zero Setup)\n\nJust add the dependency — the build script handles everything:\n\n```toml\n[dependencies]\nzvec = { git = \"https://github.com/zvec-ai/zvec-rust.git\", tag = \"v0.3.1\" }\n```\n\nOn first build, `build.rs` will automatically download the prebuilt `libzvec_c_api` for your platform from [GitHub Releases](https://github.com/zvec-ai/zvec-rust/releases) and set up the library path via `rpath`.\n\n### For Advanced Users (Custom Build)\n\nIf you want to build the zvec C library yourself (e.g., for a custom configuration or unsupported platform), set the `ZVEC_LIB_DIR` environment variable to override the automatic download:\n\n```bash\n# Build zvec from source\ngit clone https://github.com/alibaba/zvec.git \u0026\u0026 cd zvec\nmkdir -p build \u0026\u0026 cd build\ncmake .. -DCMAKE_BUILD_TYPE=Release -DBUILD_C_BINDINGS=ON\nmake -j$(nproc)\n\n# Point zvec-rust to your custom build\nexport ZVEC_LIB_DIR=/path/to/zvec/build/lib\n```\n\nOr use the built-in Makefile for local development:\n\n```bash\nmake setup        # Install dev tools + init git submodule\nmake zvec-build   # Build the zvec C library from submodule\nmake test-all     # Run all tests\n```\n\n### Library Resolution Order\n\nThe build script resolves the C library in this order:\n\n1. **`ZVEC_LIB_DIR`** environment variable (highest priority)\n2. **Sibling checkout**: `../zvec/build/lib`\n3. **Git submodule**: `vendor/zvec/build/lib`\n4. **Vendor directory**: `vendor/lib/`\n5. **Prebuilt download**: from GitHub Releases (automatic)\n6. **Auto-build**: clone and build from source (requires `git`, `cmake`, C++17 compiler)\n\nSet `ZVEC_AUTO_BUILD=0` to disable steps 5 and 6.\n\n## Quick Start\n\n```rust\nuse zvec::*;\n\nfn main() -\u003e zvec::Result\u003c()\u003e {\n    initialize(None)?;\n\n    // Define schema\n    let schema = CollectionSchema::builder(\"my_collection\")\n        .add_field(FieldSchema::new(\"id\", DataType::String, false, 0))\n        .add_vector_field(\"embedding\", DataType::VectorFp32, 128,\n            IndexParams::hnsw(MetricType::Cosine, 16, 200))\n        .build()?;\n\n    // Create collection and insert data\n    let collection = Collection::create_and_open(\"./data\", \u0026schema, None)?;\n\n    let mut doc = Doc::new()?;\n    doc.set_pk(\"doc1\");\n    doc.add_string(\"id\", \"doc1\")?;\n    doc.add_vector_f32(\"embedding\", \u0026vec![0.1; 128])?;\n    collection.insert(\u0026[\u0026doc])?;\n\n    // Vector similarity search\n    let query = VectorQuery::new(\"embedding\", \u0026vec![0.2; 128], 10)?;\n    let results = collection.query(\u0026query)?;\n    for result in \u0026results {\n        println!(\"pk={}, score={:.4}\", result.get_pk().unwrap_or(\"\"), result.get_score());\n    }\n\n    shutdown()?;\n    Ok(())\n}\n```\n\n## Examples\n\nRun any example with `cargo run --example \u003cname\u003e`:\n\n| Example | Description |\n|---|---|\n| `basic` | End-to-end workflow: schema → insert → query → fetch → delete |\n| `schema_builder` | Various schema configurations: field types, index types, quantization |\n| `vector_search` | Vector query patterns: simple, builder, filter, output fields, HNSW params |\n| `crud_operations` | Full CRUD: insert, fetch, update, upsert, delete, stats, flush |\n| `config_logging` | Library configuration: memory limits, thread counts, logging |\n\n```bash\ncargo run --example basic\ncargo run --example vector_search\n```\n\n## API Overview\n\n### Initialization\n\n| Function | Description |\n|---|---|\n| `initialize(config)` | Initialize the library (call once) |\n| `shutdown()` | Release all resources |\n| `version()` | Get version string |\n| `is_initialized()` | Check initialization status |\n\n### Schema Definition\n\n```rust\nlet schema = CollectionSchema::builder(\"name\")\n    .add_field(FieldSchema::new(\"field\", DataType::String, false, 0))\n    .add_vector_field(\"vec\", DataType::VectorFp32, 128,\n        IndexParams::hnsw(MetricType::Cosine, 16, 200))\n    .build()?;\n```\n\n### Collection Operations\n\n| Method | Description |\n|---|---|\n| `Collection::create_and_open()` | Create a new collection |\n| `Collection::open()` | Open an existing collection |\n| `collection.insert(\u0026docs)` | Insert documents |\n| `collection.update(\u0026docs)` | Update documents |\n| `collection.upsert(\u0026docs)` | Insert or update |\n| `collection.delete(\u0026pks)` | Delete by primary keys |\n| `collection.query(\u0026query)` | Vector similarity search |\n| `collection.fetch(\u0026pks)` | Fetch by primary keys |\n| `collection.stats()` | Get collection statistics |\n| `collection.flush()` | Flush to disk |\n\n### Document Operations\n\n```rust\nlet mut doc = Doc::new()?;\ndoc.set_pk(\"my_pk\");\ndoc.add_string(\"name\", \"value\")?;\ndoc.add_i64(\"count\", 42)?;\ndoc.add_vector_f32(\"embedding\", \u0026[0.1, 0.2, 0.3])?;\n\nlet name = doc.get_string(\"name\")?;\nlet count = doc.get_i64(\"count\")?;\n```\n\n### Vector Query\n\n```rust\n// Simple query\nlet query = VectorQuery::new(\"embedding\", \u0026query_vec, 10)?;\n\n// Builder pattern with filters\nlet query = VectorQuery::builder()\n    .field_name(\"embedding\")\n    .vector(\u0026query_vec)\n    .topk(10)\n    .filter(\"category = 'tech'\")\n    .output_fields(\u0026[\"id\", \"name\"])\n    .build()?;\n```\n\n## Supported Types\n\n| Category | Types |\n|---|---|\n| **Scalar** | `Bool`, `Int32`, `Int64`, `Uint32`, `Uint64`, `Float`, `Double`, `String`, `Binary` |\n| **Vector** | `VectorFp16`, `VectorFp32`, `VectorFp64`, `VectorInt4`, `VectorInt8`, `VectorInt16`, `VectorBinary32`, `VectorBinary64` |\n| **Sparse** | `SparseVectorFp16`, `SparseVectorFp32` |\n| **Array** | `ArrayBool`, `ArrayInt32`, `ArrayInt64`, `ArrayFloat`, `ArrayDouble`, `ArrayString` |\n\n## Index Types\n\n| Type | Constructor | Description |\n|---|---|---|\n| HNSW | `IndexParams::hnsw(metric, m, ef)` | Graph index (recommended) |\n| HNSW+Q | `IndexParams::hnsw_with_quantize(...)` | HNSW with quantization |\n| IVF | `IndexParams::ivf(metric, nlist, niters, soar)` | Inverted file index |\n| Flat | `IndexParams::flat(metric)` | Brute-force index |\n| Invert | `IndexParams::invert(range, wildcard)` | Scalar field index |\n\n## Testing\n\n```bash\n# Using Makefile (recommended — auto-detects library paths)\nmake test-unit         # Unit tests (no C library required)\nmake test-integration  # Integration tests (requires C library)\nmake test-all          # All tests (unit + integration + doc)\n\n# Using cargo directly (requires ZVEC_LIB_DIR / DYLD_LIBRARY_PATH)\ncargo test --lib\ncargo test --test integration_test\n\n# Fuzz tests (requires nightly)\ncargo install cargo-fuzz\ncargo +nightly fuzz run fuzz_types -- -max_total_time=60\n\n# Benchmarks\nmake bench\n\n# Code coverage\ncargo install cargo-llvm-cov\n./scripts/coverage.sh --html\n```\n\n## Keeping in Sync with zvec Core\n\nThis SDK tracks the [zvec](https://github.com/alibaba/zvec) C-API. When the upstream C-API changes:\n\n1. Update `zvec-sys/src/lib.rs` with new FFI declarations\n2. Add safe wrappers in the `zvec` crate\n3. Update integration tests to cover new functionality\n4. Run the full test suite to verify compatibility\n\nThe CI pipeline automatically clones the latest zvec and builds the C library, ensuring FFI compatibility on every PR.\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Ensure all tests pass (`cargo test`)\n4. Ensure code is formatted (`cargo fmt --all -- --check`)\n5. Ensure clippy is clean (`cargo clippy --workspace --all-targets -- -D warnings`)\n6. Submit a pull request\n\n## License\n\nApache-2.0 — see [LICENSE](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzvec-ai%2Fzvec-rust","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzvec-ai%2Fzvec-rust","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzvec-ai%2Fzvec-rust/lists"}