{"id":18016,"library":"xlucene-translator","title":"xLucene Query Translator","description":"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.","status":"active","version":"2.5.3","language":"javascript","source_language":"en","source_url":"https://github.com/terascope/teraslice","tags":["javascript","typescript"],"install":[{"cmd":"npm install xlucene-translator","lang":"bash","label":"npm"},{"cmd":"yarn add xlucene-translator","lang":"bash","label":"yarn"},{"cmd":"pnpm add xlucene-translator","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"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.","wrong":"const Translator = require('xlucene-translator');","symbol":"Translator","correct":"import { Translator } from 'xlucene-translator';"},{"note":"TypeScript interface for configuring translator options, such as the target database dialect and field mappings, crucial for accurate query conversion.","symbol":"QueryConfig","correct":"import { QueryConfig } from 'xlucene-translator';"},{"note":"A utility function for quick, stateless xLucene query translations without needing to explicitly instantiate the `Translator` class. It is exposed as a named export.","wrong":"import translate from 'xlucene-translator';","symbol":"translate","correct":"import { translate } from 'xlucene-translator';"}],"quickstart":{"code":"import { Translator } from 'xlucene-translator';\n\ninterface MyDocumentMapping {\n  field1: { type: 'keyword' };\n  age: { type: 'integer' };\n  isActive: { type: 'boolean' };\n}\n\n// Example field mapping, mimicking an Elasticsearch index mapping\nconst fieldMapping: MyDocumentMapping = {\n  field1: { type: 'keyword' },\n  age: { type: 'integer' },\n  isActive: { type: 'boolean' },\n};\n\nasync function runTranslation() {\n  try {\n    // Initialize the translator for the 'elasticsearch' dialect\n    // The fieldMapping is essential for correct type inference and query generation\n    const translator = new Translator<MyDocumentMapping>('elasticsearch', fieldMapping);\n\n    const xluceneQuery1 = 'field1:\"value example\" AND age:>25 AND isActive:true';\n    const translatedQuery1 = translator.translate(xluceneQuery1);\n\n    console.log('xLucene Query 1:', xluceneQuery1);\n    console.log('Translated Elasticsearch Query 1:', JSON.stringify(translatedQuery1, null, 2));\n\n    const xluceneQuery2 = 'field1:test* OR age:[10 TO 20]';\n    const translatedQuery2 = translator.translate(xluceneQuery2);\n    console.log('\\n-----------------------------------\\n');\n    console.log('xLucene Query 2:', xluceneQuery2);\n    console.log('Translated Elasticsearch Query 2:', JSON.stringify(translatedQuery2, null, 2));\n\n  } catch (error: any) {\n    console.error('Translation failed:', error.message);\n  }\n}\n\nrunTranslation();","lang":"typescript","description":"Demonstrates initializing an Elasticsearch translator with a field mapping object and translating two different xLucene queries into their corresponding Elasticsearch Query DSL representations."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=3.4.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-23T00:00:00.000Z","next_check":"2026-07-22T00:00:00.000Z","problems":[{"fix":"Verify the dialect string against the package's documentation for a list of supported database dialects (e.g., 'elasticsearch', 'opensearch').","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.","error":"Error: Unknown dialect: 'mongoDB'"},{"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.","cause":"The xLucene query string provided to the `translate` method contains syntax errors, making it impossible for the parser to interpret correctly.","error":"Error: Invalid xLucene query syntax near 'my_field:badly-formatted:'"},{"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' }`).","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.","error":"TypeError: Cannot read properties of undefined (reading 'type') at Translator.translate"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}