{"id":15885757,"url":"https://github.com/toniov/es-builder","last_synced_at":"2025-12-24T10:19:08.036Z","repository":{"id":57226893,"uuid":"69842302","full_name":"toniov/es-builder","owner":"toniov","description":"Elasticsearch query builder for Node.js","archived":false,"fork":false,"pushed_at":"2017-08-07T04:29:49.000Z","size":49,"stargazers_count":21,"open_issues_count":0,"forks_count":2,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-03-12T12:41:39.907Z","etag":null,"topics":["elasticsearch","javascript","query-builder","query-dsl"],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/toniov.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2016-10-03T04:59:32.000Z","updated_at":"2025-02-20T17:11:23.000Z","dependencies_parsed_at":"2022-08-24T15:52:12.146Z","dependency_job_id":null,"html_url":"https://github.com/toniov/es-builder","commit_stats":null,"previous_names":["antonvs2/es-builder"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/toniov%2Fes-builder","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/toniov%2Fes-builder/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/toniov%2Fes-builder/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/toniov%2Fes-builder/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/toniov","download_url":"https://codeload.github.com/toniov/es-builder/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246054146,"owners_count":20716331,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["elasticsearch","javascript","query-builder","query-dsl"],"created_at":"2024-10-06T05:07:23.389Z","updated_at":"2025-12-24T10:19:02.991Z","avatar_url":"https://github.com/toniov.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Elasticsearch Query Builder\n\n[![Build Status](https://travis-ci.org/toniov/es-builder.svg?branch=master)](https://travis-ci.org/toniov/es-builder)\n\nElasticsearch query builder for Node.js, build compatible queries with the Elasticsearch 2.x DSL. Because creating complex queries using the Query DSL is a pain.\n\nIt just builds the `query` element within the search request body, the complex part. This means that fields like `size` or `from` must be added separately, as well as the likes of `sort`.\n\n[Info about Search parameters.](https://www.elastic.co/guide/en/elasticsearch/reference/current/search-request-body.html#_parameters_4)\n\n# Installation\n\nThe package can be installed as a local module, to be required in your code.\n\n```js\nnpm install es-builder\n```\n\nAlso, it can be installed globally, ready to be used through the Node.js REPL.\n\n```js\nnpm install -g es-builder\n```\n\n# Features\n\n- No production dependencies\n- Can be required as a module or used in the command line\n- Chainable methods\n- `built` getter method returns a copy of the object so it can be safely passed to foreign code\n\n# Usage\n\n## Used as a local module\n\nIt is compatible with the [Elasticsearch official client library](https://github.com/elastic/elasticsearch-js):\n\n```js\nconst eb = require('es-builder');\nvar elasticsearch = require('elasticsearch');\n\nvar client = new elasticsearch.Client({\n  host: 'localhost:9200',\n  log: 'trace'\n});\n\nconst query = eb.QueryBuilder()\n  .query(eb.TermQuery('name', 'Kirby'))\n  .query(eb.MatchQuery('description', 'Pink, fluffy and very hungry'))\n  .queryMustNot(eb.TermQuery('name', 'Waddle Dee'));\n\n// stringifying the object will give the following result\n// JSON.stringify(query)\n// {\n//   \"bool\": {\n//     \"must\": [{\n//       \"term\": {\n//         \"name\": \"Kirby\"\n//       }\n//     }, {\n//       \"match\": {\n//         \"description\": {\n//           \"query\": \"Pink, fluffy and very hungry\"\n//         }\n//       }\n//     }],\n//     \"must_not\": {\n//       \"term\": {\n//         \"name\": \"Waddle Dee\"\n//       }\n//     }\n//   }\n// }\n\n// but the created query can be passed without doing stringify, since the Elasticsearch client will stringify it internally after\nclient.search({\n  index: 'games',\n  type: 'dreamland',\n  body: {\n    query: query\n  }\n}, function(err, resp) {\n  // result of the search here\n  ...\n});\n\n```\n\n## Used as a global module (REPL)\n\nAll the query classes have been exposed to the REPL so they can be called directly.\n\n```zsh\n$ es-builder\n\nes-builder\u003e query = QueryBuilder().query(TermQuery('name', 'Kirby')).query(MatchQuery('description', 'Pink, fluffy and very hungry')).queryMustNot(TermQuery('name', 'Waddle Dee'));\n\nes-builder\u003e query.stringified\n'{\"bool\":{\"must\":[{\"term\":{\"name\":{\"value\":\"Kirby\"}}},{\"match\":{\"description\":{\"query\":\"Pink, fluffy and very hungry\"}}}],\"must_not\":{\"term\":{\"name\":{\"value\":\"Waddle Dee\"}}}}}'\n\nes-builder\u003e .exit\n```\n\nCopy the result above and paste it in your curl search request:\n\n```zsh\n$ curl -XGET 'http://localhost:9200/games/dreamland/_search' -d'\n{\n    \"query\" : {\"bool\":{\"must\":[{\"term\":{\"name\":{\"value\":\"Kirby\"}}},{\"match\":{\"description\":{\"query\":\"Pink, fluffy and very hungry\"}}}],\"must_not\":{\"term\":{\"name\":{\"value\":\"Waddle Dee\"}}}}}\n}'\n```\n\n## Filter context\n\nAdding clauses to filter context is possible as well:\n\n```js\nquery.filter(eb.TermQuery('name', 'Kirby'));\n\n// stringifying the object will give the following result\n// JSON.stringify(query)\n// {\n//  \"bool\": {\n//    \"filter\": {\n//      \"term\": {\n//        \"name\": \"Kirby\"\n//      }\n//    }\n//  }\n// }\n```\n\n## Shortcut for leaf query clauses\n\nThere is a shortcut available for leaf query clauses when used as a local module, inspired by [elasticsearch-dsl-py](https://github.com/elastic/elasticsearch-dsl-py):\n\n```js\nconst Q = eb.Q;\nconst TermsQuery = eb.TermsQuery;\n\n// doing this\nQ('terms', 'name', ['Kirby', 'Metaknight']);\n// equals\nTermsQuery('name', ['Kirby', 'Metaknight'])\n\n// both giving the same result:\n// {\n//  \"terms\": {\n//    \"name\": [\"Kirby\", \"Metaknight\"]\n//  }\n// }\n```\n\nAlso, there is a one-to-one mapping relation between the raw query and its equivalent in the DSL, therefore adding directly raw queries as Javascript objects is fine.\n\n```js\nconst eb = require('es-builder');\neb.QueryBuilder().query({ terms: name: ['Kirby', 'Metaknight'] }).built;\n\n// same result:\n//\n// {\n//   bool: {\n//    must: {\n//     terms: {\n//        name: [ 'Kirby', 'Metaknight' ]\n//        }\n//      }\n//    }\n//  }\n// }\n```\n\n## Complex queries\n\nCombined queries can be built nesting compound query clauses.\n\n```js\nconst eb = require('es-builder');\nconst Q = eb.Q;\n\nconst query = eb.QueryBuilder();\n// add a couple of filters\nquery\n  .filter(Q('terms', 'name', ['Kirby', 'Metaknight']))\n  .filter(Q('exists', 'age'));\n\n// create a bool compound query\nconst boolQuery = eb.BoolQuery()\n  .should(Q('range', 'age').gt(20).lt(25))\n  .should(Q('prefix', 'surname', 'Ki'));\n\n// nest it\nquery.filter(boolQuery);\n\n// stringifying the object will give the following result\n// JSON.stringify(query)\n// {\n//   \"bool\": {\n//     \"filter\": {\n//       bool: {\n//         \"must\": [{\n//           \"terms\": {\n//             \"name\": {\n//               \"value\": [\"Kirby\", \"Metaknight\"]\n//             } \n//           }\n//         }, {\n//           \"exists\": {\n//             \"field\": \"age\"\n//           }\n//         }, {\n//           \"bool\": {\n//             \"should\": [{\n//               \"range\": {\n//                 \"age\": { \"gt\": 20, \"lt\": 25 }\n//               }\n//             }, {\n//               \"prefix\": {\n//                 \"surname\": {\n//                   \"value\": \"Ki\"\n//                 }\n//               }\n//             }]\n//           }\n//         }]\n//       }\n//     }\n//   }\n// }\n```\n\n## Aliases\n\nThere are aliases available for some methods.\n\n`const queryBuilder = eb.QueryBuilder();`\n- `queryBuilder.query()` → `queryBuilder.queryAnd()`\n- `queryBuilder.queryMustNot()` → `queryBuilder.queryNot()`\n- `queryBuilder.queryShould()` → `queryBuilder.queryOr()`\n- `queryBuilder.filter()` → `queryBuilder.filterAnd()`\n- `queryBuilder.filterMustNot()` → `queryBuilder.filterNot()`\n- `queryBuilder.filterShould()` → `queryBuilder.filterOr()`\n\n`const boolQuery = eb.BoolQuery();`\n- `boolQuery.must()` → `boolQuery.and()`\n- `boolQuery.mustNot()` → `boolQuery.not()`\n- `boolQuery.should()` → `boolQuery.or()`\n\n# API\n\nComing soon. \n\nAt the moment you can take a look to the tests to see how all the methods work.\n\n# Compatibility\n\n- Compatible with Elasticsearch 2.x search API\n- Node.js version\n  - As a required module: It has been transpiled to ES5 using [Babel](https://babeljs.io/), so it is compatible with old Node.js versions (\u003e 0.12.0)\n  - As a global module (REPL): \u003e 6.0.0\n\n\n# ToDo List\n\n- Add leaf query clauses like `multi_match` or `fuzzy`\n- Add compound query clauses like `constant_score` or `dis_max`\n- Allow passing array of filter objects in compound query clauses\n- Browser compatible\n- And more\n\nPull requests or any comments are more than welcome.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftoniov%2Fes-builder","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftoniov%2Fes-builder","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftoniov%2Fes-builder/lists"}