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:

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();

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