This reference describes the JavaScript surface exposed by require("bleve"). The API wraps Bleve's Go types in opaque JavaScript objects and uses builders for mappings, queries, search requests, and indexes.

The reference is written for script authors. It focuses on what each function returns, what the object is used for, and the lifecycle rules that matter when a script runs inside a generated xgoja binary.

Module import

const bleve = require("bleve");

All functions below are properties of that module object.

Top-level factories

MappingBuilder

Create with bleve.mapping() or bleve.indexMapping().

const mapping = bleve.mapping()
  .defaultMapping(docMapping)
  .defaultField("body")
  .defaultAnalyzer("standard")
  .build();

Methods:

Use build() once the mapping is complete. Pass the resulting Mapping to an IndexBuilder.

DocumentMappingBuilder

Create with bleve.docMapping() or bleve.documentMapping().

const doc = bleve.docMapping()
  .field("title", bleve.field().text())
  .field("status", bleve.field().keyword())
  .dynamic(false)
  .build();

Methods:

FieldBuilder

Create with bleve.field().

Field type methods:

Common field options:

Vector methods are available in the API, but vector execution requires a binary built with vector support.

Query and QueryBuilder

Most query factories return a QueryBuilder. A query builder supports:

Query objects are consumed by SearchRequestBuilder.query(...), Boolean queries, conjunctions, and disjunctions.

Examples:

KNN accepts an optional IVF parameter object as its fourth argument, or as its fifth argument after boost. The supported lower-camel fields are ivfNprobePct and ivfMaxCodesPct; both must be finite values from 0 to 100. The module maps them to Bleve's ivf_nprobe_pct and ivf_max_codes_pct request keys.

const request = bleve.search()
  .query(bleve.matchNone())
  .knn("embedding", embedding, 10, 1.0, {
    ivfNprobePct: 100,
    ivfMaxCodesPct: 100,
  })
  .build();

These controls belong to one KNN clause and may also be supplied after the filter argument of knnWithFilter. In a vector-enabled host, bleve.memory() uses an in-memory Scorch index and supports pure KNN without persistence. Use bleve.create(path) when the index must survive process shutdown.

const text = bleve.match("semantic search").field("body").boost(2);
const exact = bleve.term("published").field("status");
const phrase = bleve.matchPhrase("hybrid retrieval").field("title");
const parsed = bleve.queryString("title:bleve +status:published");

BoolQuery

Create with bleve.bool().

Example:

const query = bleve.bool()
  .addMust(bleve.match("search").field("body"))
  .addShould(bleve.match("goja").field("title"))
  .addMustNot(bleve.term("archived").field("status"));

SearchRequestBuilder

Create with bleve.search() or bleve.searchRequest().

Examples:

const request = bleve.search()
  .query(bleve.match("privacy").field("body"))
  .size(10)
  .fields(["title", "status"])
  .build();

Pure KNN:

const request = bleve.search()
  .query(bleve.matchNone())
  .knn("embedding", [0.1, 0.2, 0.3, 0.4], 5, 1.0)
  .build();

Restrict vector candidates before KNN selection. This is appropriate when a RAG index stores several representation kinds and the search must only return one of them:

const summaries = bleve.term("summary").field("representationKind");
const request = bleve.search()
  .query(bleve.matchNone())
  .knnWithFilter("embedding", embedding, 12, summaries, 1.0)
  .fields(["representationKind", "text"])
  .build();

knnWithFilter is different from knnOperator("and"): the filter controls eligibility for this one KNN clause, whereas the operator combines multiple KNN clauses.

Hybrid RRF:

const request = bleve.search()
  .query(bleve.match("migration").field("text"))
  .knn("embedding", embedding, 20, 1.0)
  .score("rrf")
  .scoreRankConstant(60)
  .scoreWindowSize(50)
  .build();

IndexBuilder

Create with bleve.memory(), bleve.create(path), or bleve.open(path).

For open(path), the mapping is already part of the existing index and normally should not be supplied.

Index

Batch

After .execute() succeeds, later mutation or reset calls throw an error. Create a fresh batch for additional work.

SearchResult and SearchHit

index.search(request) returns:

interface SearchResult {
  total: number;
  maxScore: number;
  took: string;
  hits: SearchHit[];
}

interface SearchHit {
  id: string;
  score: number;
  fields: Record<string, unknown>;
  fragments?: unknown;
  locations?: unknown;
  sort?: unknown[];
  explanation?: unknown;
  scoreBreakdown?: unknown;
}

The exact optional properties depend on the request and Bleve's response. Request stored fields with .fields([...]) if you need document values in hit.fields.

TypeScript declaration snapshot

The repository tests a TypeScript declaration snapshot in pkg/testdata/bleve.d.ts.golden. Treat that file as a compact machine-checkable API summary. Update it whenever public JavaScript APIs change.

Troubleshooting

See Also

• goja-bleve-getting-started
• goja-bleve-user-guide