fix: missing dot . in PHRASE searches

Author: hp4k1h5

README.md

@@ -4,16 +4,18 @@
 ##### !! warning !! experimental and unstable
 
 ## overview
-ArangoSearch provides a high-level API for interacting with Arango Search Views
+ArangoSearch provides a low-level API for interacting with Arango Search Views
 through the Arango Query Language (AQL). This library aims to provide a query
 parser and AQL query builder to enable full boolean search operations across
 all available Arango Search View capabilities, including, `PHRASE` and
 `TOKENS` operations. With minimal syntax overhead the user can generate
-multi-lingual and language-specific, complex phrase, proximity and tokenized
+multi-lingual and language-specific, complex phrase, (proximity... TBD) and tokenized
 search terms.
 
 For example, passing a search phrase like: `+mandatory -exclude ?"optional
-phrase"` to `buildAQL`, will produce the following query:
+phrase"` to `buildAQL`'s query object as the `term` key, will produce the
+following query:
+
 ```aql
 FOR doc IN search_view
 
@@ -26,7 +28,7 @@ FOR doc IN search_view
       ANALYZER(
         TOKENS(@value0, @value1)
         ALL IN doc.@value2, @value1),
-    @value3) AND @value4)
+    @value3) AND @value4) <--------------- @value4 here is the PHRASE search
 
      AND
 
@@ -50,7 +52,7 @@ documents.
 
 ## setup
 
-1) running generated AQL queries will require a working arangodb instance. in
+1) running generated AQL queries will require a working arangodb instance. In
 the future, it is hoped that this package can be imported and used in the
 `arangosh`, as well as client and server side. Currently there is only limited
 support for server-side use.
@@ -61,39 +63,42 @@ support for server-side use.
 !! significantly in the short-term
 1) clone this repository in your es6 compatible project.
 2) run `yarn install` from the project directory.
+3) unless you are importing into a typescript project, i believe you will have
+to run `yarn tsc` from the project directory, and possibly change the compile
+target in `tsconfig.json`
 
 ## usage
-for better documentation, run `yarn doc && serve docs/` from the project
-  directory root.
+__for up-to-date documentation, run `yarn doc && serve docs/` from the project
+  directory root.__
 
-AQLqueryBuilder aims to provide collection-agnostic and language-agnostic
-boolean search capabilities to the library's user. Currently, this library
-makes a number of assumptions about the way your data is stored and indexed,
-but these are hopefully compatible with a wide range of setups.
+AQLqueryBuilder aims to provide cross-collection and cross-language boolean
+search capabilities to the library's user. Currently, this library makes a
+number of assumptions about the way your data is stored and indexed, but these
+are hopefully compatible with a wide range of setups.
 
 The primary assumption this library makes is that the data you are trying to
 query against is indexed by an ArangoSearch View, and that all documents index
-the same exact field. This field can be indexed by any number of analyzers,
-and the search be will run against all supplied collections simultaneously. This
-allows for true multi-language search provided that each collection is
-restricted to just one language and all documents index the same key as all
-other documents in the view. While there are plans to expand on this
-functionality to provide multi-key search, this library is primarily built for
-academic and textual searches, and is ideally suited for documents like books,
-articles, and other media where most of the data resides in a single place.
+the same exact field. This field, passed to the builder as a key on the
+`query` object passed to e.g. `buildAQL()`, can be indexed by any number of
+analyzers, and the query will target all supplied collections simultaneously.
+This allows for true multi-language search provided all documents index the
+same key as all other documents in the view. While there are plans to expand
+on this functionality to provide multi-key search, this library is primarily
+built for academic and textual searches, and is ideally suited for documents
+like books, articles, and other media where most of the data resides in a
+single place, i.e. document `key`, or `field`.
 
 This works best as a document query tool. Leveraging ArangoSearch's built-in
 language stemming analyzers allows for complex search phrases to be run
 against any number of language-specific collections simultaneously.
 
-For an example of a multi-lingual document ingest/parser, please see
+For an example of a multi-lingual document ingest/parser/indexer, please see
 [ptolemy's curator](https://gitlab.com/HP4k1h5/nineveh/-/tree/master/ptolemy/dimitri/curator.js)
 
 __Example:__
 ```javascript
 import {buildAQL} from 'path/to/AQLqueryBuilder'
-const queryObject =
-{
+const queryObject = {
   "view": "the_arango-search_view-name",
   "collections": [{
     "name": "collection_name",
@@ -103,6 +108,7 @@ const queryObject =
 }
 const aqlQuery = buildAQL(queryObject)
 // ... const cursor = await db.query(aqlQuery)
+// ... const cursor = await db.query(aqlQuery, {start:20, end:40})
 ```
 `collections` is an array of `collection` objects. This allows searching and
 filtering across collections impacted by the search.
@@ -149,12 +155,7 @@ Example:
       "op": ">",
       "val": 0
     }
-  ],
-  "limit":
-    {
-      "start": 0,
-      "end": 20,
-    }
+  ]
 }
 ```
 
@@ -166,15 +167,15 @@ Quoting [mit's Database Search Tips](https://libguides.mit.edu/c.php?g=175963&p=
 
 #### `+` AND
 * Mandatory terms and phrases. All results MUST INCLUDE these terms and
-* phrases.
+  phrases.
 #### `?` OR
-* Optional terms and phrases. If there are ANDS or NOTS, these serve as
-* match score "boosters". If there are no ANDS or NOTS, ORS become required
-* in results.
+* Optional terms and phrases. If there are ANDS or NOTS, these serve as match
+  score "boosters". If there are no ANDS or NOTS, ORS become required in
+  results.
 #### `-` NOT
 * Search results MUST NOT INCLUDE these terms and phrases. If a result that
-* would otherwise have matched, contains one or more terms or phrases, it
-* will not be included in the result set.
+  would otherwise have matched, contains one or more terms or phrases, it will
+  not be included in the result set.
 
 ### default query syntax
 for more information on boolean search logic see
@@ -199,10 +200,12 @@ follows:
 | PHRASE |      |     | "buckle my shoe" |
 | TOKENS | two  | one |                  |
 
-The generated AQL query, when run will bring back only results that contain
-"two", that do not contain variations on the phrase "buckle my shoe", and that
-optionally contain "one". In this case, documents that contain "one" will be
-likely to score higher than those that do not.
+The generated AQL query, when run, will bring back only results that contain
+"two", that do not contain the phrase "buckle my shoe", and that optionally
+contain "one". In this case, documents that contain "one" will be likely to
+score higher than those that do not.
 
 ## bugs
+plase see [bugs](https://github.com/HP4k1h5/AQLqueryBuilder.js/issues/new?assignees=HP4k1h5&labels=bug&template=bug_report.md&title=basic)
 ## contributing
+plase see [./.github/CONTRIBUTING.md]

src/index.ts

@@ -3,6 +3,9 @@ import { query } from './lib/structs'
 import { buildSearch } from './search'
 import { buildFilters } from './filter'
 
+/** @returns an AQL query object. See @param query for details on required
+ * values. @parm query .terms accepts either a string to be parsed or an array of @param term
+ * */
 export function buildAQL(query: query, limit: any = { start: 0, end: 20 }): any {
   validateQuery(query)
 
@@ -17,7 +20,6 @@ export function buildAQL(query: query, limit: any = { start: 0, end: 20 }): any
       LIMIT ${limit.start}, ${limit.end}
     RETURN doc`
 }
-exports.buildAQL = buildAQL
 
 function validateQuery(query: query) {
   if (!query.view.length) throw Error('query.view must be a valid ArangoSearch View name')

src/lib/structs.ts

@@ -1,27 +1,43 @@
+/**
+* passed to buildAQL, i.e. `let generatedAQL = buildAQL(query)`. Properties
+* mimic or match those familiar to AQL.
+* */
 export interface query {
   /**
-  * the name of the ArangoSearch view the query will be run against
+  * the name of the ArangoSearch View the query will be run against
   * */
   view: string,
   /**
-  * the names of the collections indexed by @view to query
+  * the names of the collections indexed by @param view to query
   * */
   collections: collection[],
   /**
-  * either an array of @term interfaces or a string to be parsed by @parseQuery
+  * either an array of @param term interfaces or a string to be parsed by `parseQuery()`
   * */
   terms: term[] | string,
   /**
-  * the name of the document key to search, must be the same across all
-  * documents 
+  * the name of the document key to search, currently must be the same across
+  * all documents. @default "text"
   * */
   key?: string,
   /**
-  * a list of @filter interfaces
+  * a list of @filter interfaces. All filters are implicitly AND'ed together.
   * */
   filters?: filter[],
 }
 
+/**
+* Each collection referenced by the ArangoSearch that the user wishes to
+* include in the query must be listed as a collection of the following shape.
+*
+* A collection can be referenced by several analyzers and each must have its
+* own entry in `query.collections` in order to be included in the search.  
+* 
+* Alternatively, a document can be stored in several collections.
+*
+* In either case all desired collection/analyzer combinations must be
+* specified.
+* */
 export interface collection {
   /**
   * the name of the collection
@@ -33,14 +49,43 @@ export interface collection {
   analyzer: string,
 }
 
+/**
+* A piece of search query text. Can be a phrase or an individual word, and will
+* belong to one cell or other of the following grid:
+* ```
+*                       **ops**
+*             |        | ANDS | ORS | NOTS  | 
+*             | -----  | ---- | --- | ----- | 
+*  **types**  | PHRASE |      |     |       | 
+*             | TOKENS |      |     |       | 
+*             | PROXIM | TODO | TODO| TODO  | 
+* ```
+* */
 export interface term {
+  /**  
+  * must be one of [ 'phr', 'tok' ], corresponding to `PHRASE` and
+  * `TOKENS` respectively. 
+  **/
   type: string,
+  /**
+  * the search string
+  * */
   val: string,
+  /**
+  * must be one of [ '+', '?', '-' ] corresponding to `ANDS`, `ORS`, and
+  * `NOTS`, respectively.
+  * */
   op: string,
 }
 
+/**
+* passed to AQL `FILTER`
+* */
 export interface filter {
+  /** the arango document field name to filter on */
   field: string,
+  /** the high-level operator to filter by */
   op: string,
+  /** the query string to filter with */
   val: string | number | Date,
 }

src/search.ts

@@ -65,7 +65,7 @@ function buildOPS(collections: collection[], terms: term[], op: string, key:
 
 function buildPhrase(phrase: term, collections: collection[], key: string): any {
   return collections.map(coll => {
-    return aql`PHRASE(doc${key}, ${phrase.val.slice(1, -1)}, ${coll.analyzer})`
+    return aql`PHRASE(doc.${key}, ${phrase.val.slice(1, -1)}, ${coll.analyzer})`
   })
 }
 

tests/search.ts

@@ -6,22 +6,31 @@ describe('search.js', () => {
     expect(buildSearch).to.be.a('function')
   })
 
-  it('should return SEARCH true when terms: is an empty string', () => {
-    const query = { view: 'search_view', collections: [ { name: 'coll', analyzer: 'text_en' } ], terms: '' }
-    const builtSearch = buildSearch(query)
+  it(`should return SEARCH true 
+      when terms: is an empty string or array`, () => {
+
+    /* empty string */
+    let empty_string_query = { view: 'search_view', collections: [ { name: 'coll', analyzer: 'text_en' } ], terms: '' }
+    const builtSearch = buildSearch(empty_string_query)
 
     expect(builtSearch).to.be.an('object')
     expect(Object.keys(builtSearch.bindVars)).to.have.length(2)
     expect(builtSearch.bindVars.value0).to.equal(true)
     expect(builtSearch.bindVars.value1).to.deep.equal({ collections: [ 'coll' ] })
+
+    /* empty array */
+    let empty_array_query = { view: 'search_view', collections: [ { name: 'coll', analyzer: 'text_en' } ], terms: [] }
+    const builtSearch_from_array = buildSearch(empty_array_query)
+
+    expect(builtSearch_from_array.bindVars.value0).to.equal(true)
   })
 
   it('should return an array of aql objects', () => {
     const query = { view: 'search_view', collections: [ { name: 'coll', analyzer: 'text_en' } ], terms: '-a +"query string" ?token' }
     const builtSearch = buildSearch(query)
 
     expect(Object.keys(builtSearch.bindVars)).to.have.length(7)
-    expect(builtSearch.bindVars.value0[ 0 ].query).to.equal('PHRASE(doc.text, @value0, @value1)')
+    expect(builtSearch.bindVars.value0[ 0 ].query).to.equal('PHRASE(doc.@value0, @value1, @value2)')
     expect(builtSearch.bindVars.value1).to.deep.equal('token')
     expect(builtSearch.bindVars.value2).to.deep.equal('text_en')
     expect(builtSearch.bindVars.value3).to.deep.equal('text')
@@ -48,9 +57,9 @@ describe('search.js', () => {
       SORT TFIDF(doc) DESC`)
   })
 
-  it('should return an array of aql objects', () => {
+  it.skip('should return an array of aql objects', () => {
     const query = { view: 'search_view', collections: [ { name: 'coll', analyzer: 'text_en' } ], terms: '+mandatory -exclude ?"optional phrase"' }
     const builtSearch = buildSearch(query)
     expect(builtSearch.query).to.equal(``)
-  }).skip()
+  })
 })