Backends connect Dataset and Documents to data from a specific ‘Backend’ data source. They provide methods for loading and saving Datasets and individuals Documents as well as for bulk loading via a query API and doing bulk transforms on the backend.

Looking for quickstart tutorial rather than reference documentation? See the Backends Tutorial.

Backends come in 2 flavours:

Examples of the 2 types of backends are provided by the Google docs backend (a “Loader” backend) and the ElasticSearch backend (a Store backend).

Available Backends

You can find a list of the available Backends along with examples of how to use them in the Backends Tutorial.

Note that it’s easy to write your own backend - you just need to implement the Recline Backend API described below.

Backend API

Backend modules must implement the following API:

__type__: 'name-of-backend' // e.g. elasticsearch

// Initial load of dataset including initial set of records
fetch: function(dataset)

// Query the backend for records returning them in bulk.
// This method will be used by the Dataset.query method to search the backend
// for records, retrieving the results in bulk.
query: function(queryObj, dataset)

// Save changes to the backend
save: function(changes, dataset)

Details of each function below. Note that:

fetch: function(dataset)

On success, promise callback must return an object with the following structure:

{
  // (optional) Set of record data
  // Either an array of arrays *or* an array of objects corresponding to initial set of records for this object
  // May not provided if data only returned by query
  records: [...]

  // (optional) Set of field data
  // Either an array of string or an array of objects corresponding to Field specification (see `Field` above)
  fields: { ... } // as per recline.Model.Field

  // (optional) metadata fields to set on the Dataset object
  metadata: { title: ..., id: ... etc }

  // boolean indicating whether to use a local memory store for managing this dataset
  useMemoryStore:
}

query: function(queryObj, dataset)

queryObj: JS object following Query specification above.

Callbacks

On success must return a ‘QueryResult’ object which has the following structure:

{
  // total number of results (can be null)
  total: ...

  // one entry for each result record
  hits: [
    {
      // JS object that can be used to initialize a Record object
    } 
  ],

  // (optional) 
  facets: {
    // facet results (as per <http://www.elasticsearch.org/guide/reference/api/search/facets/>)
  }
}

The QueryResult is partially modelled on ElasticSearch - see this issue for more details.

save: function(changes, dataset)

The save function is still being revised and its API and arguments are subject to change

changes: an object with the following structure:

{
  creates: [ record.toJSON(), record.toJSON(), ... ]
  updates: [ ... ]
  deletes: [ ... ]
}

Each key has an array of records (as simple JS objects resulting from a call to Record.toJSON()) that are in that state.

The backend should take appropriate actions for each case.