zvec 0.5.1

Dart SDK for Zvec — a lightweight, lightning-fast, in-process vector database by Alibaba.

English | 中文

Lightning-fast, in-process vector database for Dart & Flutter — powered by Zvec.

---

Zvec Dart SDK brings Alibaba's open-source Zvec vector engine to mobile via dart:ffi — no servers, no IPC, just a single dynamic library running in your app's process. Build on-device semantic search, RAG, recommendation, and similarity workloads with milliseconds-level latency.

💫 Features

• 🚀 Native speed — Direct FFI calls into a battle-tested C++ engine; no method-channel hops, no isolate marshalling.
• 📱 Mobile-first — Ships prebuilt binaries for Android (arm64-v8a) and iOS (arm64).
• ☁️ Zero-friction install — Native libs are auto-fetched from GitHub Releases at build time. Your pub.dev package stays slim.
• 🧠 Rich vector ops — HNSW / IVF / Flat / Inverted indexes, hybrid filters, top-k & group-by queries.
• 🔒 Durable storage — Write-ahead log, atomic flush, persistent across app restarts.
• 🎯 Idiomatic Dart — Strongly-typed schema, exception-based error handling, synchronous API.

📦 Installation

flutter pub add zvec

Or in pubspec.yaml:

dependencies:
  zvec: ^0.5.1

Platform support

Platform	Architectures	Distribution
Android	arm64-v8a	Gradle task downloadZvecNativeLibs
iOS	arm64 (device)	CocoaPods prepare_command (curl + unzip)

⚡ Quick Start

import 'dart:typed_data';
import 'package:zvec/zvec.dart';

void main() {
  // 1. Boot the engine
  Zvec.initialize();
  print('Zvec ${Zvec.version}');

  // 2. Define a schema: 4-dim FP32 vector + a string field
  final schema = CollectionSchema(name: 'demo', fields: [
    VectorSchema('embedding', 4, indexParams: HnswIndexParams()),
    FieldSchema(name: 'title', dataType: DataType.string),
  ]);

  // 3. Create & open the collection
  final collection = Collection.createAndOpen('/tmp/zvec_demo', schema);

  // 4. Insert documents
  final docs = [
    Doc(id: 'doc_1')
      ..setField('title', 'hello')
      ..setVector('embedding', Float32List.fromList([0.1, 0.2, 0.3, 0.4])),
    Doc(id: 'doc_2')
      ..setField('title', 'world')
      ..setVector('embedding', Float32List.fromList([0.2, 0.3, 0.4, 0.1])),
  ];
  collection.insert(docs);
  for (final d in docs) d.destroy();

  // 5. Build the index
  collection.optimize();

  // 6. Vector search — top-k by cosine similarity
  final query = VectorQuery(
    fieldName: 'embedding',
    vector: Float32List.fromList([0.4, 0.3, 0.3, 0.1]),
    topk: 5,
    outputFields: ['title'],
  );
  for (final r in collection.query(query)) {
    print('${r.pk}  score=${r.score}  title=${r.getString('title')}');
  }
  query.destroy();

  // 7. Clean up
  collection.close();
  Zvec.shutdown();
}

A full Flutter demo lives in example/lib/main.dart.

🧬 How Native Libraries Are Distributed

Native libraries are NOT bundled in the pub.dev tarball — they're fetched on first build:

Platform	Mechanism	Trigger
Android	Gradle task downloadZvecNativeLibs (android/build.gradle)	flutter build apk / flutter run
iOS	prepare_command in ios/zvec.podspec (curl + unzip)	pod install

This keeps the Dart package small and lets us version native binaries independently.

🤝 Contributing

Issues and pull requests are welcome! Want to hack on the plugin or rebuild the native libraries? See BUILDING.md for the developer setup. For changes that touch the underlying engine, please file them in the upstream zvec repo instead.

📄 License

Released under the Apache License 2.0 — same as upstream Zvec.