Elastic-graph NPM

elastic-graph

A lightweight query builder for Elastic Search and OpenSearch. You can convert a simple JSON Rule built with the popular JSON Rule Engine library and turn into a valid Elastic Search query. Supports And / OR conditions Nested conditions Offsets / pagination Basic Aggregations Custom operators Custom Aggregators and more

Inspired By: json-rules-engine elastic-builder

Basic Example

use toJson function to convert the query to the json

import QueryBuilder from 'elastic-graph'

// Initialize the class
const queryBuilder = new QueryBuilder()

// Usage
queryBuilder.setRule({
  all:[
    any:[
      {fact:"field-1",operator:"equal",value:"value-1"}
      {fact:"field-2",operator:"nonEqual",value:"value-2"}
    ],
    all:[
      {fact:"field-3",operator:"lessThanRelative",value:"3",additionalProperties:{
        format:"X" // format uses the luxon time formate
      }}
    ]
  ]
}).toJson()

Methods

constructor

import QueryBuilder from "elastic-graph";

const queryBuilder = new QueryBuilder();

addOperator(operatorName:string,callback:Function)

queryBuilder.addOperator(
  "newOperator",
  (fact: string, value: any, additionalProperties: DynamicObject) => {
    return elasticBuilder.matchQuery(fact, value);
  }
);

removeOperator(operatorName:string)

queryBuilder.addOperator(
  "newOperator",
  (fact: string, value: any, additionalProperties: DynamicObject) => {
    return elasticBuilder.matchQuery(fact, value);
  }
);

queryBuilder.removeOperator("newOperator");

addAggregator(aggregatorName:string,callback:Function)

queryBuilder.addAggregator(
  "newAggregator",
  (name: string, fieldName: any, additionalProperties: DynamicObject) => {
    return elasticBuilder.sumAggregation(name, fieldName);
  }
);

removeAggregator(aggregatorName:string)

queryBuilder.addAggregator(
  "newAggregator",
  (name: string, fieldName: any, additionalProperties: DynamicObject) => {
    return elasticBuilder.sumAggregation(name, fieldName);
  }
);

queryBuilder.removeAggregator("newAggregator");

setRoutingValue(value:string|number)
setRouting set the query routing value

queryBuilder.setRoutingValue("user1");

setRule(rule:TopLevelCondition)

queryBuilder.setRule({
  all: [{ fact: "field", operator: "equal", value: "value" }],
});

offset(value:number)
skips the give value of records from the query result

queryBuilder.offset(10);

limit(value:number)
gets the given number of records

queryBuilder.limit(10);

toJson()
convert the query to json

queryBuilder.setRoutingValue("user1").offset(10).limit(10)setRule({
  all: [{ fact: "field", operator: "equal", value: "value" }],
}).toJson();

setAggregator(value:AggregatorRule[])

queryBuilder.setAggregator([
  { name: "aggregator1", aggregator: "sum", fieldName: "field-1" },
]);

sum(aggregatorName:string,fieldName:string) or sum(value:AggregatorInput[])

queryBuilder.sum("aggregator-sum", "field-2");
// or
queryBuilder.sum([{ name: "aggregator-sum", fieldName: "field-2" }]);

avg(aggregatorName:string,fieldName:string) or avg(value:AggregatorInput[])

queryBuilder.avg("aggregator-avg", "field-2");
// or
queryBuilder.avg([{ name: "aggregator-avg", fieldName: "field-2" }]);

max(aggregatorName:string,fieldName:string) or max(value:AggregatorInput[])

queryBuilder.max("aggregator-max", "field-2");
// or
queryBuilder.max([{ name: "aggregator-max", fieldName: "field-2" }]);

min(aggregatorName:string,fieldName:string) or min(value:AggregatorInput[])

queryBuilder.min("aggregator-min", "field-2");
// or
queryBuilder.min([{ name: "aggregator-min", fieldName: "field-2" }]);

sort(fieldName:string,order:"asc"|"desc" = "asc") or sort(value:Sort[])

queryBuilder.sort("field-2", "desc").sort("field-3", "desc");
// or
queryBuilder.sort([
  { name: "field-2", order: "desc" },
  { name: "field-3", order: "desc" },
]);

json format

setRule
json structure

{
  "fact": "field-name",
  "operator": "operator Identifier",
  "value": "value",
  "additionalProperties": {
    // Additional properties for the query
  }
}

setRule

queryBuilder.setRule({
  all:[
    {{
  "fact":"field-name",
  "operator":"operator Identifier",
  "value":"value",
  "additionalProperties":{
    // Additional properties for the query
  }
}}
  ]
})

setAggregator json format

{
  "name": "aggregator name",
  "aggregator": "aggregator identifier",
  "fieldName": "name of the field aggregation to be performed",
  "additionalProperties":{
    // Additional Properties for the aggregator
  }
}

Default operators

equal

sample Rule object

{
  "fact": "fieldName",
  "operator": "equal",
  "value": "value"
}

equal uses term query

containsString

sample Rule object

{
  "fact": "fieldName",
  "operator": "containsString",
  "value": "value"
}

containsString uses match query

blank
sample Rule object
```
{
  "fact": "fieldName",
  "operator": "equal",
  "value": "value"
}
```
in value give the null replacement value given in the search Database blank uses term query

notEqual

sample Rule object

{
  "fact": "fieldName",
  "operator": "notEqual",
  "value": "value"
}

notEqual uses term query

notContainsString

sample Rule object

{
  "fact": "fieldName",
  "operator": "notContainsString",
  "value": "value"
}

notContainsString uses match query

notBlank

sample Rule object

{
  "fact": "fieldName",
  "operator": "notBlank",
  "value": "value"
}

check for the field value is not null

greaterThanAbsolute

sample Rule object

{
  "fact": "fieldName",
  "operator": "greaterThanAbsolute",
  "value": "value"
}

greaterThanAbsolute uses the range query

lessThanAbsolute

sample Rule object

{
  "fact": "fieldName",
  "operator": "lessThanAbsolute",
  "value": "value"
}

lessThanAbsolute uses the range query

greaterThanRelative
sample Rule object
```
{
  "fact": "fieldName",
  "operator": "greaterThanRelative",
  "value": "value",
  "additionalProperties": {
    "format": "yyyy"
  }
}
```
greaterThanRelative uses the range query, But there is a preprocessing it convert to the given format(uses luxon time formatting)
lessThanRelative
sample Rule object
```
{
  "fact": "fieldName",
  "operator": "lessThanRelative",
  "value": "value",
  "additionalProperties": {
    "format": "yyyy"
  }
}
```
lessThanRelative uses the range query, But there is a preprocessing it convert to the given format(uses luxon time formatting)
notEqualRelative
sample Rule object
```
{
  "fact": "fieldName",
  "operator": "notEqualRelative",
  "value": "value",
  "additionalProperties": {
    "format": "yyyy"
  }
}
```
notEqualRelative uses the range query, But there is a preprocessing it convert to the given format(uses luxon time formatting)

Default Aggregator

sum

usage sum aggregator is added as native function

//for single sum aggregator
queryBuilder.sum("aggregatorName", "fieldName");
// or
//for multiple sum aggregator
queryBuilder.sum([
  { name: "aggregator-1", fieldName: "field-1" },
  { name: "aggregator-2", fieldName: "field-2" },
]);

max

usage max aggregator is added as native function

//for single max aggregator
queryBuilder.max("aggregatorName", "fieldName");
// or
//for multiple max aggregator
queryBuilder.max([
  { name: "aggregator-1", fieldName: "field-1" },
  { name: "aggregator-2", fieldName: "field-2" },
]);

min

usage sum aggregator is added as native function

//for single min aggregator
queryBuilder.min("aggregatorName", "fieldName");
// or
//for multiple min aggregator
queryBuilder.min([
  { name: "aggregator-1", fieldName: "field-1" },
  { name: "aggregator-2", fieldName: "field-2" },
]);

avg

usage avg aggregator is added as native function

//for single avg aggregator
queryBuilder.avg("aggregatorName", "fieldName");
// or
//for multiple avg aggregator
queryBuilder.avg([
  { name: "aggregator-1", fieldName: "field-1" },
  { name: "aggregator-2", fieldName: "field-2" },
]);

How to Add Custom Operator

To add custom operator user addOperator function it take two argument operator initializer and callback (callback must return the instance of elasticBuilder )

elasticBuilder -> elastic-builder see reference

import QueryBuilder, { DynamicObject, elasticBuilder } from "elastic-graph";

const queryBuilder = new QueryBuilder();

queryBuilder.addOperator(
  "newOperator",
  (fact: string, value: any, additionalProperties: DynamicObject) => {
    return elasticBuilder.matchQuery(fact, value);
  }
);

queryBuilder
  .setRule({
    all: [{ fact: "fieldName", operator: "newOperator", value: "test" }],
  })
  .toJson();

How to Add Custom Aggregator

To add custom aggregator use addAggregator function it take two argument aggregator initializer and callback (callback must return the instance of elasticBuilder )

elasticBuilder -> elastic-builder see reference

import QueryBuilder, { DynamicObject, elasticBuilder } from "elastic-graph";

const queryBuilder = new QueryBuilder();

queryBuilder.addAggregator(
  "newAggregator",
  (name: string, fieldName: any, additionalProperties: DynamicObject) => {
    return elasticBuilder.sumAggregation(name, fieldName);
  }
);

queryBuilder
  .setAggregatorRule([
    {
      name: "aggregatorName",
      aggregator: "newAggregator",
      fieldName: "fieldName",
    },
  ])
  .toJson();

opensearch elasticsearch json-rule-engine elastic query builder elastic search database

elastic-builder json-rules-engine luxon

@infinitebrahmanuniverse/nolb-ela @everything-registry/sub-chunk-1563

2 years ago

2 years ago

2 years ago

2 years ago