Skip to content
Build complex lucene query strings with basic functions
Branch: master
Clone or download
Bas Huis
Bas Huis 1.0.1
Latest commit cc83a9a Dec 6, 2018
Type Name Latest commit message Commit time
Failed to load latest commit information.
dist 1.0.1 Dec 6, 2018
test Throw errors when arguments are incorrect Mar 29, 2018
.eslintrc.json setup workflow and initial code Apr 26, 2016
.gitignore Bower support Apr 26, 2016
.travis.yml Make travis also test on newer version of node Mar 29, 2018
LICENSE Initial commit Apr 26, 2016 Support query string escaping May 8, 2016
bower.json Bower support Apr 26, 2016
index.js Throw errors when arguments are incorrect Mar 29, 2018
package-lock.json 1.0.1 Dec 6, 2018
package.json 1.0.1 Dec 6, 2018

Lucene Query String Builder

Build Status

Easily build your lucene string queries using small and pure functions.

Imagine having an API that leverages lucene for performing queries on the (indexed) database. In that case you might want to generate lucene query strings on the client/front end.

The usage section shows how you can leverage this lib for your purposes.


bower install lucene-query-string-builder --save

# or

npm install lucene-query-string-builder --save


  • escapes lucene special chars when creating a term string
  • contains all the operators lucene uses
  • simple lucene.builder function for defining a lucene query builder


Let's see how you can use lucene query string builder to define lucene query strings with simple JavaScript functions.

Assuming that the lucene global variable contains the lucene functions. This would be the default when loaded into a browser.

var findUserLuceneQueryString = lucene.builder(function(data){

  // just to make the example more readable;
  var _ = lucene;

    _.field('eye-color', _.term(data.eye.color)),
    _.field('age', _.range(data.age.min, data.age.max))


var luceneQueryString = findUserLuceneQueryString({
  eye: { color: 'brown'},
  age: {
    min: 10,
    max: 20

luceneQueryString === '( eye-color: "brown" AND age:{ 10 TO 20 } )' // => true

The functions are based on the lucene specifications found here:

  var _ = lucene;

   * terms or term

  _.term('hello'); // => '"hello"'

  _.terms('hello world'); // => '"hello world"'

   * field

  _.field('hello', _.term('world')); // => 'hello: "world"'

   * or/and/not
   * These functions are variadic and all work the same way. This example only
     shows the or but ot works similar with and and not

  _.or(_.term('hello'), _.term('world')); // => '"hello" OR "world"'

  _.or(_.term('hello'), _.term('you'), _.term('world')); // => '"hello" OR "you" OR "world"'

   * group
   * Is a variadic function too
   */'hello'), _.term('you'), _.term('world')); // => '( "hello" "you" "world" )'

   * range
   * Takes two strings and 2 booleans.

  /* combined with the field function to query for ages between 10 and 20 */
  _.field('age', _.range(10, 20)); // => 'age: { 10 TO 20 }'

   * fuzzy

  _.fuzzy(_.term('hello'), 0.2); // => '"hello"~0.2'

   * proximity

  _.proximity("a", "c", 2); // => '"a b"'~2

   * required

  _.required(_.term('required')); // => '+"required"'


I have not gotten the chance to use this lib in my own projects. Please share your thoughts, issues and improvements.

  • Make sure your dependencies are installed by running: npm run-script setup
  • Then start editing the index.js
  • You should add and/or edit the tests in test/index.js
  • Run your tests and see what happens

When performing pull request make sure to not add the dist files. This is left to the maintainers(s) of the library. They are responsible to version and avoid code breakages.

You can perform your own build with npm run-script build to make a lucine.js and a lucine.min.js


I am currently not using this repository in any of my projects. Therefore I am looking for people that are able to make LQSB more useful for them and others.

Road map

  • split all functions into separate files
  • tasks for running tests on dist/lucene.js and dist/lucene.min.js


The MIT License (MIT)

You can’t perform that action at this time.