{"id":21174191,"url":"https://github.com/bluehalo/elastic-querybuilder","last_synced_at":"2025-06-17T09:02:21.684Z","repository":{"id":57099422,"uuid":"99722803","full_name":"bluehalo/elastic-querybuilder","owner":"bluehalo","description":"A query builder for Elasticsearch.","archived":false,"fork":false,"pushed_at":"2018-03-14T21:29:08.000Z","size":121,"stargazers_count":9,"open_issues_count":0,"forks_count":0,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-06-03T19:10:36.130Z","etag":null,"topics":["elasticsearch","node","query-builder"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bluehalo.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":".github/CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-08-08T18:13:18.000Z","updated_at":"2022-08-01T10:02:46.000Z","dependencies_parsed_at":"2022-08-20T17:31:41.961Z","dependency_job_id":null,"html_url":"https://github.com/bluehalo/elastic-querybuilder","commit_stats":null,"previous_names":["asymmetrik/elastic-querybuilder"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/bluehalo/elastic-querybuilder","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bluehalo%2Felastic-querybuilder","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bluehalo%2Felastic-querybuilder/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bluehalo%2Felastic-querybuilder/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bluehalo%2Felastic-querybuilder/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bluehalo","download_url":"https://codeload.github.com/bluehalo/elastic-querybuilder/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bluehalo%2Felastic-querybuilder/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":259780118,"owners_count":22910144,"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","node","query-builder"],"created_at":"2024-11-20T16:53:42.938Z","updated_at":"2025-06-17T09:02:21.660Z","avatar_url":"https://github.com/bluehalo.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# elastic-querybuilder [![Build Status](https://travis-ci.org/Asymmetrik/elastic-querybuilder.svg?branch=develop)](https://travis-ci.org/Asymmetrik/elastic-querybuilder)\n\u003e A query builder for Elasticsearch.\n\n## Install\n\n```shell\n# Install with Yarn\nyarn add @asymmetrik/elastic-querybuilder\n# Install with npm\nnpm install --save @asymmetrik/elastic-querybuilder\n```\n\n## API\n\u003e For a more comprehensive set of examples, see the [`__tests__`](https://github.com/Asymmetrik/elastic-querybuilder/blob/master/__tests__) directory\n\nFirst you need to create an instance of the query builder class:\n```javascript\nconst QueryBuilder = require('@asymmetrik/elastic-querybuilder');\nconst builder = new QueryBuilder();\n```\n\n### Builder Methods\n\n##### `from`\n\u003e Change the starting point for paging to a new number. Default value is 0.\n\n```javascript\nbuilder.from(from: number): QueryBuilder\n```\n\n##### `size`\n\u003e Change the number of results to a new number. Default value is 15.\n\n```javascript\nbuilder.size(size: number): QueryBuilder\n```\n\n##### `trackScores`\n\u003e Sets the track_scores option.\n\n```javascript\nbuilder.trackScores(trackScores: boolean): QueryBuilder\n```\n\n##### `raw`\n\u003e Allows to set a value on the query object at your path.\n\n```javascript\nbuilder.raw(size: number): QueryBuilder\n```\n\n###### Examples\n```javascript\nconst query = new QueryBuilder()\n  .raw('query.bool.boost', 1.2)\n  .must('match', 'name', 'Kenny')\n  .build();\n\n//- Generates the following query\n{\n  from: 0,\n  size: 15,\n  query: {\n    bool: {\n      boost: 1.2, // was set by raw\n      must: [ { match: { name: 'Kenny' }} ]\n    }\n  }\n}\n\n```\n\n##### `query`\n\u003e Build up a query object. If your last or only argument is a function, it will be passed a builder object that can be used to nest boolean queries or build nested queries. The `must`, `should`, `filter`, and `must_not` all have the same API and can be used in the same way.\n\n```javascript\nbuilder.query(\n  operation: string,\n  field?: string|Object,\n  value?: string,\n  options?: Object,\n  nester?: Function\n): QueryBuilder\n```\n\n###### Examples\nSimple Query\n``` javascript\nconst query = new QueryBuilder()\n  .query('match_all')\n  .build();\n\n//- Generates the following query\n{\n  from: 0,\n  size: 15,\n  query: {\n    match_all: {}\n  }\n}\n```\n\nSimple Query with options\n``` javascript\nconst query = new QueryBuilder()\n  .query('match_all', { boost: 2.4, fuzziness: 'auto' })\n  .build();\n\n//- Generates the following query\n{\n  from: 0,\n  size: 15,\n  query: {\n    match_all: {\n      boost: 2.4,\n      fuzziness: 'auto'\n    }\n  }\n}\n```\n\nSimple Query with field and value\n``` javascript\nconst query = new QueryBuilder()\n  .query('match', 'location', 'South Park')\n  .build();\n\n//- Generates the following query  \n{\n  from: 0,\n  size: 15,\n  query: {\n    match: {\n      location: 'SouthPark'\n    }\n  }\n}\n```\n\nQuery with callback to build nested queries.\n```javascript\nconst query = new QueryBuilder()\n  .should('match', 'firstname', 'Joe')\n  .should('match', 'firstname', 'John')\n  .should(builder =\u003e builder\n    .should('match', 'lastname', 'Smith')\n    .should('match', 'lastname', 'Davis')\n  )\n  .build();\n\n//- Generates the following query  \n{\n  from: 0,\n  size: 15,\n  query: {\n    bool: {\n      should: [\n        { match: { firstname: 'Joe' }},\n        { match: { firstname: 'John' }},\n        {\n          bool: {\n            should: [\n              { match: { lastname: 'Smith' }},\n              { match: { lastname: 'Davis' }}\n            ]\n          }\n        }\n      ]\n    }\n  }\n}\n```\n\n##### `must`\n\u003e Add a must boolean query to your ES query. See `query` above and [`__tests__`](https://github.com/Asymmetrik/elastic-querybuilder/blob/master/__tests__) for examples.\n\n```javascript\nbuilder.must(\n  operation: string,\n  field?: string|Object,\n  value?: string,\n  options?: Object,\n  nester?: Function\n): QueryBuilder\n```\n\n##### `should`\n\u003e Add a should boolean query to your ES query. See `query` above and [`__tests__`](https://github.com/Asymmetrik/elastic-querybuilder/blob/master/__tests__) for examples.\n\n```javascript\nbuilder.should(\n  operation: string,\n  field?: string|Object,\n  value?: string,\n  options?: Object,\n  nester?: Function\n): QueryBuilder\n```\n\n##### `filter`\n\u003e Add a filter boolean query to your ES query. See `query` above and [`__tests__`](https://github.com/Asymmetrik/elastic-querybuilder/blob/master/__tests__) for examples.\n\n```javascript\nbuilder.filter(\n  operation: string,\n  field?: string|Object,\n  value?: string,\n  options?: Object,\n  nester?: Function\n): QueryBuilder\n```\n\n##### `must_not`\n\u003e Add a must_not boolean query to your ES query. See `query` above and [`__tests__`](https://github.com/Asymmetrik/elastic-querybuilder/blob/master/__tests__) for examples.\n\n```javascript\nbuilder.must_not(\n  operation: string,\n  field?: string|Object,\n  value?: string,\n  options?: Object,\n  nester?: Function\n): QueryBuilder\n```\n\n##### `aggs`\n\u003e Generate aggregation type queries. This will build up the `aggs` property on an ES query.\n\n```javascript\nbuilder.aggs(\n  type: string\n  field?: string|Object\n  options?: Object,\n  nester?: Function\n): QueryBuilder\n```\n\n###### Examples\nSimple Aggregation\n```javascript\nconst query = new QueryBuilder()\n  .query('match_all')\n  .raw('explain', true)\n  .aggs('avg', 'count')\n  .build();\n\n//- Generates the following query\n{\n  from: 0,\n  size: 15,\n  explain: true,\n  query: {\n    match_all: {}\n  },\n  aggs: {\n    count: {\n      avg: {\n        field: 'count'\n      }\n    }\n  }\n}\n```\n\nMultiple Aggregations\n```javascript\nconst query = new QueryBuilder()\n  .query('match_all')\n  .aggs('geo_distance', 'location', {\n    origin: '52.3760, 4.894',\n    unit: 'km',\n    ranges: [\n      { to: 100 },\n      { from: 100, to: 300 },\n      { from: 300 }\n    ]\n  })\n  .aggs('max', 'price')\n  .aggs('sum', 'sales')\n  .build()\n\n//- Generates the following query\n{\n  from: 0,\n  size: 15,\n  query: {\n    match_all: {}\n  },\n  aggs: {\n    location: {\n      geo_distance: {\n        field: 'location',\n        origin: '52.3760, 4.894',\n        unit: 'km',\n        ranges: [\n          { to: 100 },\n          { from: 100, to: 300 },\n          { from: 300 }\n        ]\n      }\n    },\n    price: {\n      max: {\n        field: 'price'\n      }\n    },\n    sales: {\n      sum: {\n        field: 'sales'\n      }\n    }\n  }\n}\n\n```\n\nNested Aggregations\n```javascript\nconst query = new QueryBuilder()\n  .query('match_all')\n  .aggs('nested', { path: 'locations' }, builder =\u003e builder\n    .aggs('terms', 'locations.city')\n  )\n  .build()\n\n//- Generates the following query\n{\n  from: 0,\n  size: 15,\n  query: {\n    match_all: {}\n  },\n  aggs: {\n    locations: {\n      nested: {\n        path: 'locations'\n      },\n      aggs: {\n        'locations.city': {\n          terms: {\n            field: 'locations.city'\n          }\n        }\n      }\n    }\n  }\n}\n```\n\n##### `sort`\n\u003e Add sorting options. This method essentially just takes a key and a value for an object.\n\n```javascript\nbuilder.sort(\n  field?: string, // or Type of sort, could be something like _geo_distance\n  value?: string|Object\n)\n```\n\n###### Examples\n\nSimple sort\n```javascript\nconst query = new QueryBuilder()\n  .query( ... )\n  .sort('age', 'desc')\n  .build();\n  \n//- Generates the following query\n{\n  from: 0,\n  size: 15,\n  query: { ... },\n  sort: [\n    { age: 'desc' }\n  ]\n}\n```\n\nGeo distance sort\n```javascript\nconst query = new QueryBuilder()\n  .query( ... )\n  .sort('_geo_distance', {\n    coordinates: [ -70, 40 ],\n    distance_type: 'arc',\n    order: 'asc',\n    unit: 'mi',\n    mode: 'min'\n  })\n  .build();\n  \n//- Generates the following query\n{\n  from: 0,\n  size: 15,\n  query: { ... },\n  sort: [\n    {\n      _geo_distance: {\n        coordinates: [ -70, 40 ],\n        distance_type: 'arc',\n        order: 'asc',\n        unit: 'mi',\n        mode: 'min'\n      }\n    }\n  ]\n}\n```\n\n##### `func`\n\u003e Add functions to be used in function_score queries. This method essentially just takes a key and a value for an object and is only used when calling `buildFunctionScore`.\n\n```javascript\nbuilder.func(\n  field?: string|Object, // or Type of function\n  value?: string|Object\n)\n```\n\n###### Examples\n\nField value factor function\n```javascript\nconst query = new QueryBuilder()\n  .query( ... )\n  .func('field_value_factor', {\n    field: 'number_of_something',\n    modifier: 'ln2p',\n    factor: 1\n  })\n  .buildFunctionScore();\n  \n//- Generates the following query\n{\n  from: 0,\n  size: 15,\n  query: {\n    function_score: {\n      query: { ... },\n      functions: [{\n        field_value_factor: {\n          field: 'number_of_something',\n          modifier: 'ln2p',\n          factor: 1\n        }\n      }]\n    }\n  }\n}\n```\n\nFilter function\n```javascript\nconst query = new QueryBuilder()\n  .query( ... )\n  .func({\n    weight: 100,\n    filter: {\n      match: {\n        state: 'Colorado'\n      }\n    }\n  })\n  .buildFunctionScore();\n  \n//- Generates the following query\n{\n  from: 0,\n  size: 15,\n  query: {\n    function_score: {\n      query: { ... },\n      functions: [{\n        weight: 100,\n        filter: {\n          match: {\n            state: 'Colorado'\n          }\n        }\n      }]\n    }\n  }\n}\n```\n\n### Build Functions\n\n##### `build`\n\u003e Build your basic query. This includes parameters set using `query`, `must`, `should`, `filter`, `must_not`, `aggs`, `from`, `size`, and `raw`. See [`__tests__`](https://github.com/Asymmetrik/elastic-querybuilder/blob/master/__tests__) for more examples.\n\n```javascript\nbuilder.build(\n  options?: {\n    // Name for your filtered aggregations, default is 'all'\n    name?: string,\n    // Add filters to your aggregations, better for accurate facet counts\n    filterAggs?: boolean\n  }\n): Object\n```\n\n##### `buildDisMax`\n\u003e Build your basic query. This includes parameters set using `from`, `size`, and `raw`. See [`__tests__`](https://github.com/Asymmetrik/elastic-querybuilder/blob/master/__tests__) for more examples.\n\n```javascript\nbuilder.buildDisMax(\n  options: {\n    tie_breaker: number,\n    boost: number,\n    queries: Array\u003cObject\u003e,\n    // You can add more parameters that belong on the\n    // top level of a dis_max query. These are directly\n    // passed in so if it is an invalid prop, your \n    // query will fail\n  }\n): Object\n```\n\n###### Examples\nBuilding a `dis_max` query\n```javascript\nconst query = new QueryBuilder()\n  .buildDisMax({\n    queries: [\n      { term: { age: 31 }},\n      { term: { age: 32 }}\n    ],\n    tie_breaker: 1.2,\n    boost: 2\n  })\n//- Generates the following query\n{\n  from: 0,\n  size: 15,\n  query: {\n    dis_max: {\n      queries: [\n        { term: { age: 31 }},\n        { term: { age: 32 }}\n      ],\n      tie_breaker: 1.2,\n      boost: 2\n    }\n  }\n}\n```\n\n##### `buildMultiMatch`\n\u003e Build your basic query. This includes parameters set using `from`, `size`, and `raw`. See [`__tests__`](https://github.com/Asymmetrik/elastic-querybuilder/blob/master/__tests__) for more examples.\n\n```javascript\nbuilder.buildMultiMatch(\n  options: {\n    query: string,\n    fields: Array\u003cstring\u003e,\n    type: string,\n    tie_breaker: number,\n    minimum_should_match: string\n    // You can add more parameters that belong on the\n    // top level of a dis_max query. These are directly\n    // passed in so if it is an invalid prop, your \n    // query will fail\n  }\n): Object\n```\n\n###### Examples\nBuilding a `multi_match` query\n```javascript\nconst query = new QueryBuilder()\n  .buildMultiMatch({\n    query: 'The Coon',\n    fields: ['superhero', 'name', 'alias'],\n    type: 'best_fields',\n    tie_breaker: 0.3,\n    minimum_should_match: '30%'\n  });\n\n//- Generates the following query\n{\n  from: 0,\n  size: 15,\n  query: {\n    multi_match: {\n      query: 'The Coon',\n      fields: ['superhero', 'name', 'alias'],\n      type: 'best_fields',\n      tie_breaker: 0.3,\n      minimum_should_match: '30%'\n    }\n  }\n}\n```\n\n##### `buildFunctionScore`\n\u003e Build your basic query. This includes parameters set using `query`, `must`, `should`, `filter`, `must_not`, `aggs`, `func`, `from`, `size`, and `raw`. See [`__tests__`](https://github.com/Asymmetrik/elastic-querybuilder/blob/master/__tests__) for more examples.\n\n```javascript\nbuilder.buildFunctionScore(\n  options?: {\n    // Name for your filtered aggregations, default is 'all'\n    name?: string,\n    // Add filters to your aggregations, better for accurate facet counts\n    filterAggs?: boolean\n  }\n): Object\n```\n\n## Contributing\nSee our [contributors guide](https://github.com/Asymmetrik/elastic-querybuilder/blob/master/.github/CONTRIBUTING.md).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbluehalo%2Felastic-querybuilder","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbluehalo%2Felastic-querybuilder","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbluehalo%2Felastic-querybuilder/lists"}