zvec 0.5.2

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 Flutter and Dart via dart:ffi — no servers, no IPC, just a single dynamic library running in your app's process. Build on-device and desktop 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 + desktop — Ships prebuilt binaries for Android, iOS, macOS, Linux, and Windows.
• ☁️ 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)
macOS	arm64	CocoaPods prepare_command (curl + unzip)
Linux	x64	Flutter desktop CMake download + bundle
Windows	x64	Flutter desktop CMake download + bundle

⚡ 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
macOS	prepare_command in macos/zvec.podspec (curl + unzip)	pod install
Linux	linux/CMakeLists.txt downloads and bundles libzvec.so	flutter build linux / flutter run -d linux
Windows	windows/CMakeLists.txt downloads and bundles zvec.dll	flutter build windows / flutter run -d windows

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.