Javascript API Reference

appbase-js is a universal Javascript client library for working with the appbase.io database.

INSTANTIATION

new Appbase()

Returns a new Appbase object (refered to as appbaseRef in all the following examples) using the url, appname and username:password credentials.

var appbaseRef = new Appbase({
	"url": "https://scalr.api.appbase.io",
	"appname": <YOUR_APP_NAME>,
	"username": <APP_CREDENTIAL>,
	"password": <APP_SECRET>
})

Usage

new Appbase(appData)

  • appData Object
    A Javascript object containing the following fields and values

    • url String
      URL with the API version, always https://scalr.api.appbase.io
    • appname String
      name of the app as displayed in the dashboard
    • username String
      username as displayed in the app dashboard
    • password String
      password as displayed in the app dashboard

Returns

Object appbaseRef Appbase reference object - has index(), update(), delete(), bulk(), search(), get(), getTypes(), getStream(), searchStream() and searchStreamToURL() methods.

WRITING DATA

index()

Writes a JSON data object at a given type and id location, or replaces if an object already exists.

appbaseRef.index({
  type: "tweet",
  id: "aX12c5",
  body: {
    "msg": "writing my first tweet!",
    "by": "jack",
    "using": ["appbase.io", "javascript", "streams"],
    "test": true
  }
}).on('data', function(res) {
  console.log("successfully indexed: ", res);
}).on('error', function(err) {
  console.log("indexing error: ", err);
})

Usage

appbaseRef.index(params)

  • params Object
    A Javascript object containing the type, id and the JSON data to be indexed

    • type String
      The type (aka collection) under which the data will be indexed
    • body Object
      Data to be indexed, a valid JSON object
    • id String
      Unique ID for the JSON data. id is auto generated if not specified

update()

Partially updates an existing document at a given type and id location. The important difference with the index() method is that the latter replaces the existing data values wholesale, while update() only replaces the values that are specified in the body.doc field.

appbaseRef.update({
  type: "tweet",
  id: "aX12c5",
  body: {
    doc: {
      "msg": "editing my first tweet!",
      "by": "ev"
    }
  }
}).on('data', function(res) {
  console.log("successfully updated: ", res);
}).on('error', function(err) {
  console.log("update document error: ", err);
})

Usage

appbaseRef.update(params)

  • params Object
    A Javascript object containing the type, id, and the partial JSON data to be updated

    • type String
      The type (aka collection) under which the data will be indexed
    • body.doc Object
      Partial doc JSON to be updated (all the JSON data can only reside under the body.doc field)
    • id String
      Unique ID of the JSON document to be updated. id here is mandatory and should match an existing object.

delete()

Delete a JSON data object by id.

appbaseRef.delete({
  type: "tweet",
  id: "aX12c5"
}).on('data', function(res) {
  console.log("successfully deleted: ", res);
}).on('error', function(err) {
  console.log("deletion error: ", err);
})

Usage

appbaseRef.delete(params)

  • params Object
    A Javascript object containing the type and id of the JSON object to be deleted

    • type String
      The type (aka collection) of the object to be deleted
    • id String
      Unique ID for the JSON data

bulk()

Apply many index / delete operations together, useful when importing data for the first time.

appbaseRef.bulk({
  type: "tweet",
  body: [
    // action#1 description
    { index: { _id: 2 } },
    // the JSON data to index
    { "msg": "writing my second tweet!",
      "by": "Ev",
      "using": ["appbase.io", "javascript", "streams"],
      "test": true
    },
    // action#2 description
    { delete: { _id: 2 } },
    // deletion doesn't any further input
  ]
}).on('data', function(res) {
  console.log("successful bulk: ", res);
}).on('error', function(err) {
  console.log("bulk failed: ", err);
})

Usage

appbaseRef.bulk(params)

  • params Object
    A Javascript object containing the body and optionally a default type to be used for actions

    • body Array
      A Javascript array of actions to be performed written as a sequence of action#1, data#1, action#2, data#2, … action#n, data#n
    • type String
      Default document type for actions that don’t provide one

GETTING DATA

get()

Get the JSON document from a particular type and id. For subscribing to realtime updates on a document, check out getStream().

appbaseRef.get({
  "type": "tweet",
  "id": "aX12c5"
}).on('data', function(res) {
  console.log("The document data: ", res);
}).on('error', function(err) {
  console.log("get() method failed with: ", err);
})

Usage

appbaseRef.get(params)

  • params Object
    A Javascript object containing the type and id of the document to retrieve.

    • type String
      Document Type
    • id String
      Unique ID of the JSON document

Returns the document at the given type and id.

getTypes()

Get all the types of an appname.

appbaseRef.getTypes().on('data', function(res) {
  console.log("All app types: ", res);
}).on('error', function(err) {
  console.log("getTypes() failed: ", err);
})

Usage

appbaseRef.getTypes()

Returns all the types as an array.

Search for matching documents in a type. It’s a convenience method for ElasticSearch’s /_search endpoint. For subscribing to realtime updates on the search query, check out searchStream().

appbaseRef.search({
  type: "tweet",
  body: {
    query: {
      match_all: {}
    }
  }
}).on('data', function(res) {
  console.log("query result: ", res);
}).on('error', function(err) {
  console.log("search error: ", err);
})

Usage

appbaseRef.search(params)

  • params Object
    A Javascript object containing the query type and body.

    • type String
      Document type
    • body Object
      A JSON object specifying a valid query in the ElasticSearch Query DSL format

Returns

stream.Readable Object with

  • 'data' and 'error' event handlers to return the results and any errors.

STREAMING DATA

getStream()

Continuously stream new updates to a specific JSON document. If you wish to only fetch the existing value, get() is sufficient.

appbaseRef.getStream({
  type: "tweet",
  id: "aX12c5",
}).on('data', function(res) {
  console.log("data update: ", res);
}).on('error', function(err) {
  console.log("streaming error: ", err);
})

Usage

appbaseRef.getStream(params)

  • params Object
    A Javascript object containing the type and id of the document to be streamed.

    • type String
      Document type
    • id String
      Document ID (The ID is always a String value)

Note

The streamOnly field parameter is deprecated starting v0.9.0 onwards, and is the default for how getStream() works (previously readStream()).

Returns

stream.Readable Object with

  • 'data' and 'error' event handlers
  • a stop() method to stop the stream
var responseStream = appbaseRef.getStream({
  type: "tweet",
  id: 1,
})

responseStream.on('data', function(res) {
  console.log("data update: ", res);
});

responseStream.stop();

Note

appbase.js lib uses websockets to stream changes to a subscribed method.

searchStream()

Continuously stream results of search query on a given type. Search queries can be a variety of things: from simple monitoring queries, finding an exact set of documents, full-text search queries, to geolocation queries.

searchStream() subscribes to search results on new document inserts, existing search results can be fetched via search() method.

appbaseRef.searchStream({
  type: "tweet",
  body: {
    query: {
      match_all: {}
    }
  }
}).on('data', function(res) {
  console.log("query update: ", res);
}).on('error', function(err) {
  console.log("streaming error: ", err);
})

Usage

appbaseRef.searchStream(params)

  • params Object
    A Javascript object containing the query type and body

    • type String
      Document type
    • body Object
      A JSON object specifying a valid query in the ElasticSearch Query DSL format

Note

The streamOnly field parameter is deprecated starting v0.9.0 onwards, and is the default for how searchStream() works.

Returns

stream.Readable Object with

  • 'data' and 'error' event handlers
  • a stop() method to stop the stream
var responseStream = appbaseRef.searchStream({
  type: "tweet",
  body: {
    query: {
      match_all: {}
    }
  }
})

responseStream.on('data', function(res) {
  console.log("data update: ", res);
});

setTimeout(responseStream.stop, 5000); // stop stream after 5s

searchStreamToURL()

Continuously stream results of search query on a given type to a URL. searchStreamToURL() executes a webhook query on document insertion.

searchStreamToURL() subscribes to search query results on new document inserts.

appbaseRef.searchStreamToURL(
{
  type: "tweet",
  body: {
    query: {
      match_all: {}
    }
  }
}, {
  url: 'http://mockbin.org/bin/0844bdda-24f6-4589-a45b-a2139d2ccc84',
  string_body: {{{_source}}}
}).on('data', function(res) {
  console.log("Webhook registered: ", res);
}).on('error', function(err) {
  console.log("Error in registering webhook: ", err);
})

Usage

appbaseRef.searchStreamToURL(queryParams, urlParams)

  • queryParams Object
    A Javascript object containing the query type and body

    • type String
      Document type
    • body Object
      A JSON object specifying a valid query in the ElasticSearch Query DSL format
  • urlParams Object - A Javascript object containing the url to which data would be streamed on a query match. It supports optional fields to attach JSON (or string) payloads, control the frequency and number of updates.

    • url String
      A URL string
    • body Object
      A JSON object to be sent to the URL (used as an alternative to string_body)
    • string_body String
      A raw string to be sent to the URL (used as an alternative to body)
    • count Number
      # of times the result-request should be sent before terminating the webhook
    • interval Number
      Wait duration in seconds before the next result-request

Note

body and string_body fields support mustache syntax for accessing values inside the matching result object.

Returns

stream.Readable Object with

  • 'data' and 'error' event handlers
  • a change() method to replace the destination URL object
  • a stop() method to de-register the webhook

Note

We recommend using both change() and stop() methods inside the data or error event handlers due to the async nature of the searchStreamToURL() method.

var responseStream = appbaseRef.searchStreamToURL(
{
  type: "tweet",
  body: {
    query: {
      match_all: {}
    }
  }
}, {
  url: "http://mockbin.org/bin/0844bdda-24f6-4589-a45b-a2139d2ccc84"
}
)

responseStream.on('data', function(res) {
  console.log("webhook registered: ", res);
  responseStream.stop().on('data', function(res) {
    console.log("webhook de-registered: ", res);
  });
});