Package Exports

react-native-qdrant-edge
react-native-qdrant-edge/lib/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (react-native-qdrant-edge) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

react-native-qdrant-edge

Embedded vector search for React Native. Runs the Qdrant search engine in-process on the device -- no server, no network, fully offline.

Built on qdrant-edge (Rust) with Nitro Modules for near-zero JS-native overhead.

Features

HNSW-indexed vector search (dense, sparse, multi-vector)
Structured payload filtering (must / should / must_not)
Persistent storage -- survives app restarts
Snapshot interop with server Qdrant
Multiple independent shards
React hooks API
iOS and Android (Expo + bare RN)

Install

npm install react-native-qdrant-edge react-native-nitro-modules

Prebuilt native binaries for iOS (arm64 + simulator) and Android (arm64 + x86_64) are included in the npm package -- no Rust toolchain required.

Expo

Add the plugin to app.json:

{
  "plugins": ["react-native-qdrant-edge"]
}

Then run:

npx expo run:ios
npx expo run:android

Bare React Native

cd ios && pod install

Quick start

import { createShard, loadShard } from 'react-native-qdrant-edge'

// Create a new shard
const shard = createShard('/path/to/shard', {
  vectors: { '': { size: 384, distance: 'Cosine' } },
})

// Insert points
shard.upsert([
  { id: 1, vector: [0.1, 0.2, ...], payload: { title: 'Hello' } },
  { id: 2, vector: [0.3, 0.4, ...], payload: { title: 'World' } },
])

// Search
const results = shard.search({
  vector: [0.1, 0.2, ...],
  limit: 10,
  with_payload: true,
})
// [{ id: '1', score: 0.98, payload: { title: 'Hello' } }, ...]

// Persist to disk
shard.flush()
shard.close()

// Reload from disk on next app launch
const loaded = loadShard('/path/to/shard')
const count = loaded.count()  // 2
const info = loaded.info()    // { points_count: 2, segments_count: 1, ... }

API

`createShard(path, config)`

Create a new shard at the given filesystem path.

const shard = createShard(path, {
  vectors: {
    '': { size: 384, distance: 'Cosine' },        // default vector
    'title': { size: 128, distance: 'Dot' },       // named vector
  },
  sparse_vectors: {
    'keywords': { modifier: 'Idf' },               // sparse vector
  },
})

Distance metrics: Cosine | Euclid | Dot | Manhattan

`loadShard(path, config?)`

Load an existing shard from disk. Config is optional -- if omitted, uses the stored config.

Shard methods

Data

shard.upsert([{ id: 1, vector: [...], payload: { ... } }])
shard.deletePoints([1, 2, 3])
shard.setPayload(1, { key: 'value' })
shard.deletePayload(1, ['key'])
shard.createFieldIndex('category', 'keyword')
shard.deleteFieldIndex('category')

Search

const results = shard.search({
  vector: [0.1, 0.2, ...],
  limit: 10,
  offset: 0,
  with_payload: true,
  with_vector: false,
  score_threshold: 0.5,
  filter: {
    must: [{ key: 'category', match: { value: 'electronics' } }],
  },
})

Query (advanced)

const results = shard.query({
  vector: [0.1, 0.2, ...],
  limit: 10,
  filter: { ... },
  fusion: 'rrf',  // reciprocal rank fusion
})

Retrieval

const points = shard.retrieve([1, 2, 3], {
  withPayload: true,
  withVector: false,
})

const { points, next_offset } = shard.scroll({
  limit: 100,
  with_payload: true,
})

const count = shard.count({
  must: [{ key: 'active', match: { value: true } }],
})

Lifecycle

shard.flush()       // persist to disk
shard.optimize()    // merge segments, build HNSW index
shard.info()        // { points_count, segments_count, indexed_vectors_count }
shard.close()       // flush and release resources

Filtering

Filters follow the Qdrant filter syntax:

{
  must: [
    { key: 'price', range: { gte: 10, lte: 100 } },
    { key: 'category', match: { value: 'shoes' } },
  ],
  must_not: [
    { key: 'brand', match: { any: ['Nike', 'Adidas'] } },
  ],
}

Create an index before filtering on a field for best performance:

shard.createFieldIndex('price', 'float')
shard.createFieldIndex('category', 'keyword')

React hooks

`useShard`

import { useShard } from 'react-native-qdrant-edge'

function NotesScreen() {
  const { shard, isOpen, error, open, close } = useShard({
    path: `${documentDir}/notes`,
    config: { vectors: { '': { size: 384, distance: 'Cosine' } } },
    create: true,  // create new shard, or use false / omit to load existing
  })

  useEffect(() => { open() }, [])
  // Automatically closes the shard on unmount

  if (!isOpen) return <Text>Loading...</Text>

  return <NotesList shard={shard} />
}

`useUpsert`

import { useUpsert } from 'react-native-qdrant-edge'

function AddNote({ shard }) {
  const { upsert, error } = useUpsert(shard)

  const handleSave = (embedding: number[], text: string) => {
    upsert([{ id: Date.now(), vector: embedding, payload: { text } }])
  }

  return <Button onPress={() => handleSave(embedding, 'My note')} title="Save" />
}

`useDelete`

import { useDelete } from 'react-native-qdrant-edge'

function NoteItem({ shard, noteId }) {
  const { deletePoints, error } = useDelete(shard)

  return <Button onPress={() => deletePoints([noteId])} title="Delete" />
}

`useSearch`

import { useSearch } from 'react-native-qdrant-edge'

function SearchView({ shard, queryEmbedding }) {
  const { results, error, search } = useSearch({
    shard,
    request: { vector: queryEmbedding, limit: 10, with_payload: true },
    enabled: true,  // auto-search when request changes
  })

  // Or trigger manually:
  const handleRefresh = () => search({ vector: newEmbedding, limit: 5 })

  return results.map(r => <ResultCard key={r.id} point={r} />)
}

`useQuery`

Same as useSearch but uses the advanced query API with fusion support.

import { useQuery } from 'react-native-qdrant-edge'

const { results, query } = useQuery({
  shard,
  request: { vector: embedding, limit: 10, fusion: 'rrf' },
})

`useRetrieve`

import { useRetrieve } from 'react-native-qdrant-edge'

function NoteDetail({ shard, noteIds }) {
  const { points, retrieve } = useRetrieve(shard)

  useEffect(() => {
    retrieve(noteIds, { withPayload: true, withVector: false })
  }, [noteIds])

  return points.map(p => <Text key={p.id}>{p.payload?.text}</Text>)
}

`useScroll`

import { useScroll } from 'react-native-qdrant-edge'

function AllNotes({ shard }) {
  const { points, nextOffset, scroll } = useScroll(shard)

  useEffect(() => { scroll({ limit: 50, with_payload: true }) }, [])

  const loadMore = () => {
    if (nextOffset) scroll({ offset: nextOffset, limit: 50, with_payload: true })
  }

  return (
    <FlatList
      data={points}
      onEndReached={loadMore}
      renderItem={({ item }) => <Text>{item.payload?.text}</Text>}
    />
  )
}

`useCount`

import { useCount } from 'react-native-qdrant-edge'

function Stats({ shard }) {
  const { count, refresh } = useCount(shard)
  // count auto-refreshes when shard changes

  // Count with filter:
  const activeCount = () => refresh({ must: [{ key: 'active', match: { value: true } }] })

  return <Text>{count} points</Text>
}

`useShardInfo`

import { useShardInfo } from 'react-native-qdrant-edge'

function ShardStats({ shard }) {
  const { info, refresh } = useShardInfo(shard)

  return (
    <Text>
      {info?.points_count} points, {info?.segments_count} segments
    </Text>
  )
}

Multiple shards with hooks

function App() {
  const notes = useShard({
    path: `${dataDir}/notes`,
    config: { vectors: { '': { size: 384, distance: 'Cosine' } } },
  })

  const photos = useShard({
    path: `${dataDir}/photos`,
    config: { vectors: { '': { size: 512, distance: 'Dot' } } },
  })

  useEffect(() => {
    notes.open()
    photos.open()
  }, [])

  // Search across both
  const noteResults = useSearch({
    shard: notes.shard,
    request: { vector: queryVec384, limit: 5, with_payload: true },
  })

  const photoResults = useSearch({
    shard: photos.shard,
    request: { vector: queryVec512, limit: 10, with_payload: true },
  })

  return (
    <>
      <Section title="Notes" results={noteResults.results} />
      <Section title="Photos" results={photoResults.results} />
    </>
  )
}

Multiple shards

Each shard is independent with its own storage, index, and config:

import { createShard, loadShard } from 'react-native-qdrant-edge'

// Separate shards for different data types
const documents = createShard(`${dataDir}/documents`, {
  vectors: { '': { size: 768, distance: 'Cosine' } },
})

const images = createShard(`${dataDir}/images`, {
  vectors: { '': { size: 512, distance: 'Dot' } },
})

// Insert into each independently
documents.upsert([
  { id: 1, vector: docEmbedding, payload: { title: 'Getting started', category: 'docs' } },
  { id: 2, vector: docEmbedding2, payload: { title: 'API reference', category: 'docs' } },
])

images.upsert([
  { id: 1, vector: imgEmbedding, payload: { filename: 'photo.jpg', album: 'vacation' } },
])

// Search each shard separately
const docResults = documents.search({ vector: queryVec768, limit: 5, with_payload: true })
const imgResults = images.search({ vector: queryVec512, limit: 10, with_payload: true })

// Persist both
documents.flush()
images.flush()

// Later, reload from disk
const docs = loadShard(`${dataDir}/documents`)
const imgs = loadShard(`${dataDir}/images`)

Building from source

Only needed if you're contributing or the prebuilt binaries don't cover your target.

Requirements

Rust
Xcode (iOS)
Android NDK (Android)

Build

# iOS (device + simulator xcframework)
npm run rust:build:ios

# Android (arm64 + x86_64)
npm run rust:build:android

# Both
npm run rust:build

Architecture

TypeScript API
  -> Nitro HybridObject (C++, near-zero overhead)
    -> extern "C" FFI
      -> qdrant-edge (Rust)
        -> HNSW index, WAL, segment storage

All search operations are synchronous and run on the JS thread via JSI -- no bridge, no serialization overhead for the call itself. Vector data is passed as JSON strings across the FFI boundary and deserialized in Rust.

Future work

ArrayBuffer for vectors -- pass vector data as raw Float32Array / ArrayBuffer instead of JSON strings across the FFI boundary. JSON parse overhead is negligible for search (HNSW lookup dominates), but matters for bulk upsert (1000+ points). Hybrid approach: ArrayBuffer for vectors, JSON for metadata (filter, payload, config).
Async operations -- offload heavy operations (optimize, bulk upsert) to a background thread via Nitro async methods.
Snapshot import/export -- expose EdgeShard snapshot API for syncing with server Qdrant.
Named vector search helpers -- typed API for multi-vector search (e.g. search text vectors and image vectors separately).

License

MIT