fergies-inverted-index

Fergie's Inverted Index

This is an inverted index library. There are many like it, but this one is Fergie's.

Throw JavaScript objects at the index and they will become retrievable by their properties using promises and map-reduce (see examples)

This lib will work in node and also in the browser

Getting started

Initialise and populate an index

import fii from 'fergies-inverted-index'

const db = fii()

db.PUT([ /* my array of objects to be searched */ ]).then(doStuff)

Query the index

// (given objects that contain: { land: <land>, colour: <colour>, population: <number> ... })

// get all object IDs where land=SCOTLAND and colour=GREEN
db.AND('land:SCOTLAND', 'colour:GREEN').then(result)

// the query strings above can alternatively be expressed using JSON objects
db.AND({
  FIELD: 'land'
  VALUE: 'SCOTLAND'
}, {
  FIELD: 'colour',
  VALUE: 'GREEN'
}).then(result)

// as above, but return whole objects
db.AND('land:SCOTLAND', 'colour:GREEN').then(db.OBJECT).then(result)

// Get all object IDs where land=SCOTLAND, and those where land=IRELAND
db.OR('land:SCOTLAND', 'land:IRELAND').then(result)

// queries can be embedded within each other
db.AND(
  'land:SCOTLAND',
  db.OR('colour:GREEN', 'colour:BLUE')
).then(result)

// get all object IDs where land=SCOTLAND and colour is NOT GREEN
db.NOT(
  db.GET('land:SCOTLAND'),                 // everything in this set
  db.GET('colour:GREEN', 'colour:RED').    // minus everything in this set
).then(result)

// Get max population
db.MAX('population').then(result)

(See the tests for more examples.)

API

• fii()
• db.AND()
• db.BUCKET()
• db.BUCKETFILTER()
• db.DELETE()
• db.DISTINCT()
• db.FIELDS()
• db.GET()
• db.MAX()
• db.MIN()
• db.NOT()
• db.OBJECT()
• db.OR()
• db.PUT()
• db.STORE

fii([options[, callback]])

import fii from 'fergies-inverted-index'

// creates a DB called "myDB" using levelDB (node.js), or indexedDB (browser)
const db = fii({ name: 'myDB' })

In some cases you will want to start operating on the database instentaneously. In these cases you can wait for the callback:

import fii from 'fergies-inverted-index'

// creates a DB called "myDB" using levelDB (node.js), or indexedDB (browser)
fii({ name: 'myDB' }, (err, db) => {
  // db is guaranteed to be open and available
})

db.AND([ ...Promise ]).then(result)

db.AND returns a set of object IDs that match every clause in the query.

For example- get the set of objects where the land property is set to scotland, year is 1975 and color is blue

db.AND('land:scotland', 'year:1975', 'color:blue').then(result)

db.BUCKET(keyspace).then(result)

db.BUCKET returns all object ids for objects that contain the given property, aggregated by property

For example- get all objects that have land property set to scotland

db.BUCKET('land:scotland').then(result)

see also GET

db.BUCKETFILTER([ ...bucket ], filter query ).then(result)

The first argument is an array of buckets, the second is an expression that filters each bucket

db.DELETE([ ...id ]).then(result)

Deletes all objects by ID

db.DISTINCT(options).then(result)

db.DISTINCT returns every value in the db that is greater than equal to GTE and less than or equal to LTE (sorted alphabetically)

For example- get all names between h and l:

db.DISTINCT({ GTE: 'h', LTE: 'l' }).then(result)

db.FIELDS(options).then(result)

db.FIELDS returns all available fields

db.FIELDS().then(result) // 'result' is an array containing all available fields

db.GET(options).then(result)

db.GET returns all object ids for objects that contain the given property, aggregated by object id.

For example to get all Teslas do:

db.GET('Tesla').then(result)  // get all documents that contain Tesla, somewhere in their structure

Perhaps you want to be more specific and only return documents that contain Tesla in the make FIELD

db.GET('make:Tesla').then(result)

which is equivalent to:

db.GET({
  FIELD: 'make',
  VALUE: 'Tesla'
}).then(result)

You can get all cars that begin with O to V in which case you could do

db.GET({
  FIELD: 'make',
  VALUE: {
    GTE: 'O',   // GTE == greater than or equal to
    LTE: 'V'    // LTE == less than or equal to
  }
}).then(result)

db.MAX(keyspace).then(result)

Get the highest alphabetical value in a given keyspace

For example- see the highest price:

db.MAX('price')

db.MIN(keyspace).then(result)

Get the lowest alphabetical value in a given keyspace

For example- see the lowest price:

db.MIN('price')

db.NOT(A, B).then(result)

Where A and B are sets, db.NOT Returns the ids of objects that are present in A, but not in B.

db.OBJECT([ ...id ]).then(result)

Given an array of ids, db.OBJECT will return the corresponding objects

db.OR([ ...Promise ]).then(result)

Return ids of objects that are in one or more of the query clauses

db.PUT([ ...Promise ]).then(result)

Add objects to database

db.STORE

Property that points to the underlying level store