README

Algolia Filters Query Builder

A parser for having a structured way for querying algolia similar to well known ODMs or ORMS.

Installation

npm i algolia-search-builder

Installation
Motivation
Usage
Operators
- Numeric
  - eq
  - ne
  - gt
  - gte
  - lt
  - lte
  - between
  - in
- Logical
  - not
  - or
  - and
Advanced Usage Examples
General Notes

Motivation

Currently Algolia supports string format only for filtering the search results, which doesn't seem very functional for making complex dynamic queries (probably by string concatenation), which requires you to memorize the built in algolia operators. Using the algolia query builder making dynamic filter queries is easier and similar to sequelize and mongoose.

Usage

const algoliaQueryBuilder = new AlgoliaQueryBuilder({
   x:{lt:3, gte:1},
   y:{between:[1,2]} 
});

const filterQuery = algoliaQueryBuilder.exec(); // 'x < 3 AND x >= 1 AND y: 1 TO 2'

const results = algoliaIndex.search("str",{
    filters: filterQuery
});

Operators

Numeric
Operators used with numeric values only
- eq
  
  Checks if a field equals to the given value
```
{ x: { eq: 3 } }
```
- ne
  
  Checks if a field is not equal to the given value
```
{ x: { ne: 3 } }
```
- gt
Checks if a field is greater than the given value
```
{ x: { gt: 3 } }
```
- gte
Checks if a field is greater than or equal the given value
```
{ x: { gt: 3 } }
```
- lt
Checks if a field is less than the given value
```
{ x: { lt: 3 } }
```
- lte
Checks if a field is less than or equal the given value
```
{ x: { lt: 3 } }
```
- between
Checks if a field is between the two given values (inclusive)
```
{ x: { between: [1,2] } }
```

**** - #### in Checks if a field is in the array of given values (can contain strings or number)

{ x: { in: [1,2,3] } }
```
- ### Logical 
- #### not
Negates the given query 
```json
{ x: { not: { between:[ 1 , 2] } } }

returns results that satisfy at least one of the given conditions

{ or:
 [
    { x: { eq:1 } }, 
    { y: { eq:2 } }, 
 ]
}

returns results that satisfy at all of the given conditions

{ and:
 [
    { x: { eq:1 } }, 
    { y: { eq:2 } }, 
 ]
}

Advanced Usage Examples

 // Field don't have to use operators they can be equal to a value right away
 const algoliaQueryBuilder1 = new AlgoliaQueryBuilder({ x:3, y: "str" });

 // An and can contain an or 
 const algoliaQueryBuilder2 = new AlgoliaQueryBuilder({
     and:[
         {x:3},
         {or:[{y:4},{z:5}]}
     ]
 });

 // By default all the provided field queries are anded
  const algoliaQueryBuilder2 = new AlgoliaQueryBuilder({
      x:{
          gt:3,
          lt:6
      }
  }); // Return results with x greater than 3 and less than 6

General Notes

The query builder validates the query after parsing and before returning the query string the limitations and constraints of the query builder are mostly related to the limitations given by algolia
To use _tags for filtering just add the a custom field with name _tags and pass it the value
```
{_tags:"published"}
```

Usage no npm install needed!