xLucene Query Translator

2.5.3 verified Thu Apr 23 auth: no javascript

The `xlucene-translator` package is a core component within the Teraslice monorepo, specifically designed to convert xLucene syntax queries into various target database query formats. This provides a standardized query language layer, abstracting the complexities of different data backend syntaxes. The current stable version, derived from the Teraslice monorepo, is v3.6.1, with frequent updates that align with the active development cadence of the larger Teraslice project. Its primary differentiation lies in offering a flexible and unified translation interface, which is crucial for applications that need to query data across heterogeneous data stores, such as Elasticsearch or OpenSearch. The package is built for Node.js environments (requiring Node.js >=22.0.0) and ships with comprehensive TypeScript type definitions, enhancing developer experience and type safety.

Common errors

error Error: Unknown dialect: 'mongoDB' ↓

cause The `Translator` constructor was called with a database dialect string (e.g., 'mongoDB') that is not recognized or explicitly supported by the `xlucene-translator` package.

fix

Verify the dialect string against the package's documentation for a list of supported database dialects (e.g., 'elasticsearch', 'opensearch').

error Error: Invalid xLucene query syntax near 'my_field:badly-formatted:' ↓

cause The xLucene query string provided to the `translate` method contains syntax errors, making it impossible for the parser to interpret correctly.

fix

Carefully review the xLucene query for any typos, incorrect operators, missing quotes, or malformed field-value pairs. Consult the xLucene specification for correct syntax guidelines.

error TypeError: Cannot read properties of undefined (reading 'type') at Translator.translate ↓

cause This error typically occurs when an xLucene query refers to a field (e.g., `my_missing_field`) that is not defined in the `fieldMapping` object provided during `Translator` instantiation, or the field lacks a `type` property.

fix

Ensure that every field mentioned in your xLucene query string has a corresponding entry in the fieldMapping object, and that each entry includes a valid type property (e.g., { type: 'keyword' }).

Warnings

breaking The `xlucene-translator` package, consistent with its parent Teraslice monorepo, now requires Node.js version 22.0.0 or higher. Running with older Node.js versions will result in environment errors or unpredictable behavior. ↓

fix Upgrade your Node.js runtime to version 22.0.0 or greater. If using pnpm, ensure your `pnpm` version is also updated to >=10.25.0 to meet engine requirements.

gotcha Providing an incorrect or incomplete field mapping configuration to the `Translator` constructor can lead to failed translations or logically incorrect database queries, especially for type-sensitive operations like range queries or full-text searches. ↓

fix Ensure that the `fieldMapping` object accurately mirrors the schema (including data types) of your target database for all fields used in xLucene queries. This is critical for generating valid and effective database queries.

gotcha As a component of the Teraslice monorepo, `xlucene-translator`'s versioning and release cycle are tightly coupled with the broader Teraslice project. Independent updates to this package might introduce compatibility issues if not aligned with the main Teraslice release strategy. ↓

fix Always refer to the official Teraslice release notes and changelogs for coordinated updates across its internal packages. Prioritize updating `xlucene-translator` via Teraslice's recommended upgrade paths.

Install

npm install xlucene-translator

yarn add xlucene-translator

pnpm add xlucene-translator

Imports

Translator
wrong
```
const Translator = require('xlucene-translator');
```
correct
```
import { Translator } from 'xlucene-translator';
```
The primary class for instantiating a query translator for a specific database dialect. Since v3, this package supports modern ESM imports, but typically provides CJS compatibility. Using named imports is recommended for TypeScript and modern Node.js projects.
QueryConfig
```
import { QueryConfig } from 'xlucene-translator';
```
TypeScript interface for configuring translator options, such as the target database dialect and field mappings, crucial for accurate query conversion.
translate
wrong
```
import translate from 'xlucene-translator';
```
correct
```
import { translate } from 'xlucene-translator';
```
A utility function for quick, stateless xLucene query translations without needing to explicitly instantiate the `Translator` class. It is exposed as a named export.

Quickstart

Demonstrates initializing an Elasticsearch translator with a field mapping object and translating two different xLucene queries into their corresponding Elasticsearch Query DSL representations.

import { Translator } from 'xlucene-translator';

interface MyDocumentMapping {
  field1: { type: 'keyword' };
  age: { type: 'integer' };
  isActive: { type: 'boolean' };
}

// Example field mapping, mimicking an Elasticsearch index mapping
const fieldMapping: MyDocumentMapping = {
  field1: { type: 'keyword' },
  age: { type: 'integer' },
  isActive: { type: 'boolean' },
};

async function runTranslation() {
  try {
    // Initialize the translator for the 'elasticsearch' dialect
    // The fieldMapping is essential for correct type inference and query generation
    const translator = new Translator<MyDocumentMapping>('elasticsearch', fieldMapping);

    const xluceneQuery1 = 'field1:"value example" AND age:>25 AND isActive:true';
    const translatedQuery1 = translator.translate(xluceneQuery1);

    console.log('xLucene Query 1:', xluceneQuery1);
    console.log('Translated Elasticsearch Query 1:', JSON.stringify(translatedQuery1, null, 2));

    const xluceneQuery2 = 'field1:test* OR age:[10 TO 20]';
    const translatedQuery2 = translator.translate(xluceneQuery2);
    console.log('\n-----------------------------------\n');
    console.log('xLucene Query 2:', xluceneQuery2);
    console.log('Translated Elasticsearch Query 2:', JSON.stringify(translatedQuery2, null, 2));

  } catch (error: any) {
    console.error('Translation failed:', error.message);
  }
}

runTranslation();