sajari

sajari-sdk-js

Sajari JavaScript SDK for integration into web and nodejs applications

Sajari Search is a hosted search and recommendation service supporting instant search, faceted search, recommendations and custom matching algorithms

This module is to interact with the raw API. If you want automated indexing, profiling and convenience functions for rendering HTML, please check out sajari-website instead.

This library is UMD compatible, you can use it with any module loader. It can be used with nodejs, or integrated into browser applications (read requests).

To install:

NPM, Browserify, webpack, node.js

npm install sajari --save

Quick start for browsers (read requests only):

Note: browsers use the "jsonp" option to make cross domain AJAX requests. A key-secret is not required, the companyId-collectionId combination will check for allowed domains and authorize accordingly. If you get 401 errors, make sure the calling domain is added in your control panel for this collection.

var sajari = require('sajari');
api = new sajari('companyId', 'collectionId', {
	jsonp: true
});

var args = {
  q : "something"
};

api.search(args, function success(res) {
  console.log(res);
}, function failure(err) {
  console.log(err);
});

Quick start for server side:

Note: server side integrations can use the private key-secret combination to access both read and write requests. Do NOT use your private key-secret in a browser based application.

var sajari = require('sajari');
api = new sajari('companyId', 'collectionId', {
	basicauth : {
	  user : 'key',
	  pass : 'secret'
  }
);

var args = {
  q : "something"
};

api.search(args, function success(res) {
  console.log(res);
}, function failure(err) {
  console.log(err);
});

Notes:

• You don't need to keep initializing the api, you only need to do this once unless you want to change config, collection, etc.
• The args object is very generic and supports anything in our API spec
• Some of our parameters are more complex, the query object helps encode args

Args

Creating a new query object from the initialized API is very simple:

var query = api.query(opts);

opts can be a query string:

var query = api.query('something');

opts also allows an object of args to be passed directly:

var query = api.query({
  q : 'something',
  custom1 : 'group A',
  cols: ['title', 'description', 'url']
});

Sajari has many supported attributes. Many have convenience wrappers as per below, these can also be chained:

var query = api.query('something')
  .filter("this", "~", "that")
  .scale("lat", 50, 5, 1, 0)
  .scale("lng", 100, 5, 1, 0)
  .filter("location", "contains", "usa")
  .meta("category", "electronics")
  .attr("custom1", "abc")
  .page(3)
  .maxresults(5)
  .cols(["title", "description", "url"]);
	
api.search(query, function success(res) {
  console.log(res);
}, function failure(err) {
  console.log(err);
});

In the above case, the query is passed directly to the search function, which will decode it automatically into args.

Search

Sajari supports multiple types of searches, which are all relatively interchangeable and use the same API endpoint:

• instant - used for "as you type" style keyword searches. Partial words are extended to full queries. Spelling errors are corrected if the query cannot be extended as is, etc.
• match - keyword queries are augmented with meta data, which is used to boost results in various ways. Unlike filters, this does not exclude any results, but rather changes their ranking.
• document - full documents can be used as queries themselves.
• faceted - generally used with keyword style searches to get aggregate information about matching results meta

All searches can also be filtered, scaled (based on numeric meta).

Instant search example (should be triggered as people type):

var query = api.query('di');
	
api.search(query, function success(res) {
  console.log(res);
}, function failure(err) {
  console.log(err);
});

Match example (search must have "jaguar", prefer color="red" & category="cars"):

var query = api.query('jaguar')
  .meta("color", "red")
  .meta("category", "cars");
	
api.search(query, function success(res) {
  console.log(res);
}, function failure(err) {
  console.log(err);
});

Field Facet example (top 10 categories and colors for docs matching the "jaguar" query):

var query = api.query('jaguar')
  .facetfields(['category', 'color'], 10);
	
api.search(query, function success(res) {
  console.log(res);
}, function failure(err) {
  console.log(err);
});

Metric Facet example (get the count for price brackets of 10,000 from 0 - 200,000 for all docs matching the "jaguar" query):

var query = api.query('jaguar')
  .filter("color", "=", "red")
  .metricfacet('price', 0, 200000, 10000);
	
api.search(query, function success(res) {
  console.log(res);
}, function failure(err) {
  console.log(err);
});

Recommendations

Sajari supports two main groups types of recommendations:

1. Website recommendations - Typically they require information from the current web page, visitor profile, etc. So although they are very analogous to the "search" function, we would advise those looking for website recommendations to use sajari-website instead, as that module integrates into the DOM, handles user profile cookies, etc.

2. Custom recommendations - These typically use the "search" function, but include "meta" parameters to help power the recommendation. The way information is used in the recommendation algorithm is highly configurable.

Example below:

var query = api.query()
  .meta("category", "electronics")
  .meta("price", 25.00)
  .meta("segment", "luxury")
  .meta("brand", "samsung")
  .meta("tags", ["phone", "oled", "silver"])
  .filter("sku", "!=", "J12345")
  .maxresults(5);
  
api.search(query, function success(res) {
  console.log(res);
}, function failure(err) {
  console.log(err);
});