Interface HnswIndex

Readonlydim

Readonlysize

applyDiff

• applyDiff(
      removeLabels: readonly number[],
      addPoints: readonly { label: number; vector: Float32Array }[],
  ): { added: number; removed: number }

  v3.9.0-rc.2 — apply a live-update diff to the in-memory index. The watcher calls this after embedDb.upsertNoteWithCanonicalVectors() returns its { oldIds, newIds, newVectors }, and passes the DB-canonical newVectors, so search reflects the exact persisted numeric generation immediately (pre-3.9.0, search was stale until the next serve restart rebuilt the index from the freshly upserted embed-db).

  Semantics:

  1. Each id in removeLabels is markDelete'd. Missing labels (e.g. a stale watcher tracking a label that was already evicted) are silently skipped.
  2. Each entry in addPoints is addPoint'd with replaceDeleted = true so deleted-but-allocated slots are reused before the index grows. Throws (wrapped) if capacity is exhausted AND the caller didn't pre-grow via resize.

  Atomicity: the SDK's underlying mutations are synchronous, but applyDiff does not wrap them in a transaction. A throw mid-loop leaves the index in a partial-update state (some labels removed, some new points added, others not). Callers MUST treat throws as "rebuild required" — there's no rollback path in hnswlib. The method also throws before its first native mutation if a persistence snapshot is in flight, so writeIndex can never race C++ graph mutation.

  Parameters

  • removeLabels: readonly number[]
  • addPoints: readonly { label: number; vector: Float32Array }[]

  Returns { added: number; removed: number }

  the number of labels removed + the number of points added (for logging / instrumentation). Sum should equal removeLabels.length + addPoints.length on success.

capacity

• capacity(): { currentCount: number; maxElements: number }

  v3.9.0-rc.2 — capacity introspection. currentCount is the number of live points (deleted points still count toward this); maxElements is the pre-allocated cap. Caller uses these to decide whether resize is needed before applyDiff.

  Returns { currentCount: number; maxElements: number }

resize

• resize(newMaxElements: number): void

  v3.9.0-rc.2 — grow the index to at least newMaxElements. No-op if already large enough. Used by the watcher before applyDiff when the live-update would push us past current capacity. Native call is synchronous (in-place re-allocation). Throws before resizing if a persistence snapshot is in flight.

  Parameters

  • newMaxElements: number

  Returns void

saveTo

• saveTo(
      file: string,
      rowsByLabel: ReadonlyMap<
          number,
          {
              chunk_index: number;
              kind: "md"
              | "pdf";
              line_end: number;
              line_start: number;
              rel_path: string;
              text_preview: string;
          },
      >,
      signature: string,
      dbGeneration?: Readonly<HnswDbGenerationAuthority>,
      persistenceScopes?: PersistenceFamilyScopes,
      publication?: HnswPublicationReceiptSink,
  ): Promise<boolean>

  v2.16.0 — persist the index to disk for fast reload on next serve start. Writes an immutable <file>.<nonce>.bin generation, then atomically publishes <file>.meta.json last as its basename + SHA-256 pointer. Returns true once that pointer commits; prior-generation cleanup is best-effort and cannot turn a committed save into a reported failure.

  file must use the exact lowercase .hnsw suffix so separate configured bases cannot collide with one another's generated artifacts. A missing parent is requested via recursive mode-0700 mkdir subject to a more-restrictive umask; an existing/custom parent is never path-chmod'd. Saves on one wrapped index serialize in invocation order. A queued save whose graph epoch changed before it starts rejects without publishing; live native mutation is mutually excluded while writeIndex is in flight. Compact pointer metadata larger than 64 KiB or a native generation larger than 1 GiB is refused before pointer publication; the already-built in-memory graph remains usable. Precommit orphan cleanup is best-effort: a failed cleanup may leave a strict generated residue that explicit clear/prune covers.

  Parameters

  • file: string

    Exact lowercase .hnsw persistence base.

  • rowsByLabel: ReadonlyMap<
        number,
        {
            chunk_index: number;
            kind: "md"
            | "pdf";
            line_end: number;
            line_start: number;
            rel_path: string;
            text_preview: string;
        },
    >

    Exact DB-owned live-label metadata manifest. It is validated against the graph but is not copied into the compact pointer.

  • signature: string

    Embed-database generation signature bound into the pointer.

  • OptionaldbGeneration: Readonly<HnswDbGenerationAuthority>

    Exact DB UUID/epoch. Optional only for legacy source compatibility; current receipt signatures carry the same fields.

  • OptionalpersistenceScopes: PersistenceFamilyScopes

    Pinned primary EmbedDb family scopes. Custom HNSW basenames require this authority; only default hash basenames may use the legacy fresh-resolution fallback.

  • Optionalpublication: HnswPublicationReceiptSink

    Optional caller-owned receipt slot. It is cleared at invocation and populated before the meta-last commit attempt, so it also remains available when a later publisher-lease release throws.

  Returns Promise<boolean>

  true after the meta-last pointer commits.

  Throws

  If file is outside the exact HNSW namespace.

  Throws

  If the graph changes before snapshot, overlaps mutation, or publication fails.

searchKnn

• searchKnn(
      queryVec: Float32Array,
      k: number,
      opts?: HnswQueryOptions,
  ): { distances: number[]; labels: number[] }

  k-NN search. Returns labels + distances (cosine distance, smaller = more similar). Caller maps labels back to source rows via the same LabeledVector.label they used at build time.

  Parameters

  • queryVec: Float32Array
  • k: number
  • Optionalopts: HnswQueryOptions

  Returns { distances: number[]; labels: number[] }