Fuse Documentation

Updated 2016/04/01
Q-Sensei Fuse is a platform for building search and analytics applications.The technology at the core of Fuse is Q-Sensei’s patented index. Unique in its ability to process structured data quickly and efficiently, Fuse is a powerful catalyst for building most any data-intensive application.
This documentation provides examples, tutorials, implementation details, and an API reference to help you get started with Fuse quickly. We’ve focused on building a solution that is simple, adaptable, and powerful. If you have any thoughts or comments on how we can improve, please send us your feedback. We’d love to hear from you.

Fuse Guide

Tutorials

Fuse makes working with data simple - really simple. But even simple things require some know-how. These tutorials should give you a solid foundation in Fuse. They are the best way to learn our simple API and understand the concepts behind our index.

Prerequisites to Run Fuse Locally

Install everything needed to run Fuse anywhere in a virtual machine.

Tutorial Link
Install Prerequisites for Fuse
Approximate Time
15 minutes
Level of Difficulty
Easy

Installing Fuse

System Requirements

Fuse server requirements are variably dependent on use-case and scale. While the platform is highly optimized to be hardware efficient, keep in mind that the index is purely in-memory. We’ve outlined our recommended minimum requirements for production use below.

  • 64bit Operating System that supports Docker (at least version 1.6)
  • 16GB RAM
  • 500 GB of hard-disk space
  • quad-core processor (Intel Ivy Bridge at 3.4GHz or equivalent)

For testing purposes and smaller projects, you can get along with much less than that though: While the actual hard-disk space needed depends on the size of your data the minimum system requirements for Fuse to work are 2GB of RAM and a 64bit capable dual-core processor.

Feel free to contact us if you’d like to discuss requirements for your scenario.

Installing Docker

The only dependency of Fuse is Docker (at least version 1.6). To install Docker in one command, there is a publicly and securely downloadable all-in-one shellscript maintained by the Docker team.

curl -sSL https://get.docker.com | sh

See the docker documentation for full instructions.

Hint

If you use docker-machine with the virtualbox driver or something similar, make sure to assign at least 2GB of memory to the docker-machine which you want to use for Fuse (with --virtualbox-memory "2048").

See Install Prerequisites for Fuse for a more indepth description for these scenarios.

Pull Fuse Docker Image

We provide you with a ready built Docker image, which you can pull from our private registry. All you need is an access token to be able to login to this registry.

Navigate to https://www.qsensei.com/member-download-page to register. With your registration an access token will be created for you, which you can retrieve on the same URL. Once you have your access token, use the following command to login to our Docker registry (replacing $ACCESSTOKEN with your access token).

docker login -u 'token' -p $ACCESSTOKEN -e 'me@company.com' docker.qsensei.com

Next, pull the latest image of Fuse.

For Fuse Free:

docker pull docker.qsensei.com/fuse-free

For Fuse Professional:

docker pull docker.qsensei.com/fuse-professional

Run Fuse Docker Container

Once you pulled the Docker image for Fuse, you can now start a Fuse container. In the simplest form, this can be done with the following command:

docker run -p 8000:8000 docker.qsensei.com/fuse-free

Note

For Fuse Professional, the image name is docker.qsensei.com/fuse-professional, respectively. This also applies to the examples below.

However, to keep your data across several invocations of docker-run, it is adviseable to create a so called “data-container” first:

docker run --name fuse-data docker.qsensei.com/fuse-free echo 'Fuse data container'

You can now start a Fuse container which stores all data inside the data-container:

docker run --volumes-from fuse-data -p 8000:8000 docker.qsensei.com/fuse-free

This way you are able to start a new container after the original one exits and have the new container access the data of the original one. Otherwise the new container would start without any data and you would have to setup, ingest and index everything all over again.

To run the docker container detached in the background, add the -d flag and to make sure, the container is restarted after a restart of the host, add --restart=unless-stopped.

The full command to start the Fuse container is:

docker run --volumes-from fuse-data -p 8000:8000 --restart=unless-stopped -d docker.qsensei.com/fuse-free

For more in-depth information about the options and usage patterns of docker run see the Docker run documentation.

Hint

You can also make use of docker-compose (see Docker Compose) and this docker-compose.yml file to simplify the process:

Just copy it somewhere (make sure to name it docker-compose.yml) and run docker-compose up within that directory. In this case, docker-compose will create the data-container for you.

Read the section about the Management Interface to learn how to configure Fuse and how to add Data to it. Our Athlete Search will guide you through this process using a simple example.

Upgrade to new Fuse version

If a new version of Fuse is available, upgrading is just a matter of pulling the new Docker image and starting a new container.

Pull the Fuse image again:

docker pull docker.qsensei.com/fuse-free  # this will pull the latest version
# or
docker pull docker.qsensei.com/fuse-free:1.2.1  #this will pull the specified version (1.2.1 in this case)

You can now stop the old container and start a new one, just like before (given you created a data container named “fuse-data” as outlined above):

docker run --volumes-from fuse-data -p 8000:8000 docker.qsensei.com/fuse-free

Schema

When creating a Fuse instance, two files are used to describe your data and the indexes derived from it:

  • contentschema.json: Describes the data model/objects that populate Fuse.
  • indexschema.json: Defines the indexes/facets that organize your data.

These schemas are required to setup the fuse instance (either using the Management Interface or directly with the API with PUT /admin/instance).

Content Schema

The content schema is used to define the objects that represent your data - often a simpler, de-normalized view of your data. It is a JSON representation of your data model, which basically lists all of the object types along with their attributes.

The content schema consists of two base-level keys; one an array of object types, the other an object of meta information related to the content schema.

Type Descriptions

Each type in your data model is described by one entry (TypeDescription) in the types array. At a high level, you give the type a name (i.e. Document) and provide attributes that describe objects of that type (i.e. filename).

Here is an example of a Document type:

Below is the full list of options for TypeDescription objects.

TypeDescription
AttributeDescription

Schema Meta Information

The meta object may contain any information you like about the content-schema. This may include a version number, a description, or the date when the schema was created. Currently, there is no structure enforced on the data within this section.

Example:

Index Schema

The index schema defines what indices/facets are available, which attributes are used to populate the indices/facets, how the values are pre-processed before indexing and some general behavior of the indexes/facets.

The index schema is split in several sections:

Indexes

Each index or facet of your application is described by an entry (Index) within the indexes array. To define an index, just add a JSON object like the following to your indexes section:

{
    "name": "folder"
},

Below is the full list of options for these Index objects.

Index
phrase_max integer optional Maximum phrase supported.
phrase_min integer optional Minimum phrase supported.
phrase_tolerance integer optional

Note

Attributes starting with phrase_ are used to configure phrase search for Fuse. This functionality is part of Fuse Professional and not available in Fuse Free. Click here to learn more about the different editions of Fuse.

Sources

The sources section defines, which attributes of the content objects are used to populate the different facets/indices.

To define that a given attribute should be used as a source for an index, add a JSON object (Source) to your sources section like this one:

{
    "index": "name",
    "fuse:type": "person",
    "attribute": "fullname"
},
Source

Components

The components sections defines components that may be used on different places of the index-schema.

To define a component so that it can be used, add a JSON object (IndexSchemaComponent) to your sources section.

IndexSchemaComponent
params object optional Additional parameters for the factory of the component.

Note

Either component or factory are mandatory. If both are given, factory has precedence.

Example: If your index uses the LowerCase transformer, your components section needs to contain this entry:

You can then refer to this transformer in the sources section with its name (lower in this example):

See Components for a list of all bundled components that may be used in the index-schema.

Index Schema Defaults

This section gives default values for several options, some of them which might be overriden by index-options or during a query.

IndexSchemaDefaults
ResultSorting
index string required The index to sort by.

Schema Meta Information

The meta object may contain any information you like about the index schema. That might be a version number, a description or the date when the schema was created. Currently, there is no structure enforced on the data whithin this section.

Sample Index Schema

Adding Data

Overview

Data can be inserted, updated, or deleted from Fuse via the ReSTful API using the POST /tasks/types/update resource and a JSON body

When you have the content-schema alreay defined (see Content Schema) and uploaded to Fuse (see Setup a Fuse Schema), you can start adding content entries to Fuse.

Example: You can add an object of type document, use the following format:

That’s it. Fuse will immediately add this object to its internal databases and start indexing.

JSON Document Structure

To add, edit or delete objects to Fuse you upload a JSON document with the following structure:

Content Data

The actual objects are sent within the items section of the JSON document. This consists of an array of JSON objects, each mapping the attribute names of a content object to its values.

The attributes and values must conform to the Content Schema. Otherwise the result-document will report an error for this object and it will not be imported/updated.

Special Attributes

For each object sent, there are a couple of attributes that are special and always have the prefix fuse. These are:

  • fuse:type
  • fuse:id
  • fuse:action
  • fuse:keep_version
fuse:type

This is the document type defined in the content schema (see TypeDescription.id). This key is mandatory.

fuse:id

This is a unique key for the object.

The fuse:id must be unique among all object types, not just the one it is used for. Providing a fuse:id is optional (if fuse:action is create or update_or_create, see below), it may be useful to later edit or delete the object, though. If no fuse:id is given, one will be created (something like fuse:cid:123).

You can use any string as fuse:id as long as it is globally unique.

Examples: “contact:358”, “doc:/some/dir/paper.pdf”, “45a8f233ec190”

fuse:action

This defines the action as an create, update, create or update, or delete for the object defined by the fuse:id. This is optional but can have the following values.

update_or_create
default object is inserted if exists and updated if it does not.
create
Object is created unless it already exists. Error if object exists.
update
Object is updated unless it does not exist. Error if object does not exist.
replace
Object is overwritten. Error if object does not exist.
delete
Object is deleted. Error if object does not exist.
fuse:keep_version

If the Fuse instance does versioning of data (not supported in this version of Fuse), setting this value to true prevents creation of a new version for this document.

Attribute Types

In general, JSON does support most types we will need for import. These are:

  • strings
  • integers
  • floating point numbers
  • booleans

In addition to the above, Fuse also supports

  • dates
  • datetimes
Dates and Datetimes

The non-standard object types can be sent with the following syntax:

"mydatetime": {"_datetime": "2014-07-24T20:23:34"}

or similarly for dates:

"mydate": {"_date": "2014-07-24"}

In a request, this would look like:

Type Conversion Rules

As an alternative to the above, conversion rules can be sent along with the request. These rules can either define rules for all objects sent in the request or on an object type basis. For example, the following will convert all attributes named created to a datetime object.

To define this for each fuse:type, use an array instead and include the fuse:type in the object.

In addition to datetime and date, other object types can be converted from the original JSON input. The full list is:

  • int, integer
  • str, string
  • float
  • date
  • datetime
  • bool, boolean
  • object, dict

Conversion rules may also apply to nested objects in documents.

Conversion Parameters

Some converters accept parameters for deserialization:

datetime and date Converters
format
date and time string format
boolean Converters
as_string

If true, the strings “1”, “yes”, “true”, and “one” are converted to true. Anything else is converted to false.

If false, values null, 0, [], {}, and false are converted to false. All other values are true.

Default Settings

The update document may contain a defaults section as well, which allows for the following entries. These will define default behavior and may allow for other fields to be left blank.

fuse:type
Gives a fuse:type for any item that does not specify it.
fuse:action
This will set the default of fuse:action. By default, this is update_or_create.
fuse:keep_version
This will set the default of fuse:keep_version. By default, this value is set to false.
date_format
Date format for conversion rules with type date. This can be overridden if another format is specified within the conversion rule.
datetime_format
Datetime format used for conversions rules with type datetime. This can be overridden if another format is specified within the conversion rule.

For example, sending the following request will default all object types in that request to document.

Change existing Data

To update an existing object, you just have specify its fuse:type and fuse:id. The following will update the above created example with the tags attribute.

Adding fuse:action is optional but gives you more control of the result.

If you want to update an existing object, you only need to include the changed attributes within the JSON document (and use action update). All other attributes will stay unchanged.

Overwriting an Object

In case you want to completely replace an existing object with a new one, use the fuse:action replace.

Deleting a Field

To delete a field, just set the field to null.

Deleting Objects

Deleting objects is done in a similar fashion - just specify the fuse:action field as delete.

Patching Objects

Object fields can also be updated via the json-patch specification (see RFC6902). Let’s say the following request has already been made.

These fields can be patched using the json-patch API.

To patch a document, the following request is made. Note the content-type.

This will add the value temporary at the beginning of the tags array.

The values supported for op are:

op Description
add Add a value to a field.
remove Remove a value from a field. Not valid for scalar values.
replace Replace a value in a field.
test Test if a value matches. If not, the patch request will revert.

Path, in general, follows the following form for objects:

/custom/owner

and the following form for arrays:

/tags/3

An index of - can be used to append to the end of an array:

/tags/-

Patch Examples

Replace the Value of an Object

This replaces the value of custom.owner attribute with Jack Smith.

Remove the Last Value of an Array

This removes the last value of the tags array.

Remove the First Value of the Array if the value is limited

This uses a combination of test and remove to delete the first value of the array if it is limited.

Setting filename if custom.owner is John Smith

This sets a scalar value (filename) if custom.owner is John Smith.

Deleting Objects by Query

Objects can also be deleted by a query using the POST /tasks/types/qdelete resource. For example, to delete all documents that have a filename starting with test-, use:

POST /tasks/types/qdelete HTTP/1.1
Content-Type: application/json

{
    "q" : "filename:\"test-*\""
}

Querying Fuse

We’ve built our search query language with the following goals in mind.

  • Built for multi-faceted search. Search multiple facets with less characters.
  • the query should be part of the URL.
  • equals / greater than / less than support.
  • AND / OR of several query expressions.

Searches are done through the GET /search resource with a query parameter q with the following syntax.

GET /search?q=facet:"value" HTTP/1.1

Where facet is the facet to search though and value is the value to look for.

Simple Facet is Value Query

For example, if you want to search the author index for the value Ward Phillips:

GET /search?q=author:"Ward+Phillips" HTTP/1.1

Less Than and Greater Than

Fuse also supports less than and greater than searches. Just use the following syntax:

GET /search?q=publishyear:gt:"1921" HTTP/1.1

Adding the gt tells Fuse to do a greater than search. The following values also work:

Value Meaning
eq equals (default)
lt less than
gt greater than
lte less than or equal
gte greater than or equal

Combining Multiple Terms

OR of Terms

Fuse is built for very complicated multifaceted queries. To construct an OR query, just use the following syntax:

GET /search?q=|(author:"Ward+Phillips"+author:"Lewis+Theobald") HTTP/1.1

This will search for documents with authors Ward Phillips or Lewis Theobald.

AND of Terms

Similarly for AND:

GET /search?q=%26(author:"Ward+Phillips"+publishyear:gt:"1921") HTTP/1.1

This will search for documents with author Ward Phillips published after 1921.

Combination of AND and OR

Of course, a combination of these can be used.

GET /search?q=%26(genre:"horror"+|(author:"Ward+Phillips"+author:"Lewis+Theobald")) HTTP/1.1

This will search for documents with written by Ward Phillips or Lewis Theobald in the horror genre.

Note

& is used in URLs to separate parameters. You may have to use %26 instead to get this to work in your browser. However, most HTTP request libraries are smart enough to parse them as proper query parameters.

Fulltext Query Operators

The query-value of the fulltext index undergoes some additional processing.

Boolean Keywords

The fulltext query may contain the keywords OR AND and NOT to combine the terms with the respective boolean operators.

Example: A query like tx:”foo or bar” is equivalent to |(tx:”foo” tx:”bar”) and tx:”foo and not bar” is eqivalent to *&(tx:”foo” !tx:”bar”).

This way, you can enter complex queries into the fulltext search-box of your application (Just try it with the bundled Search Interface).

Wildcards

The fulltext query may also contain the wildcard character “*”. With it, you can do a prefix-search.

Example: The query tx:”sport*” will find entries with the term “sport”, “sportive”, “sportsperson” etc.

Query Extensions

Macros for queries can be created using the GET /my/settings/(setting) API.

Storing Queries

To store a query to be used as a macro, use PUT /my/settings/(setting).

Using Stored Queries

Stored queries can be used by using the query_ext query parameter with the GET /search, GET /contents, GET /facets, or GET /queries resources.

GET /search?q=type:"document"&query_ext=special HTTP/1.1
X-User-ID: kate

This is identical using the following query:

&(type:"document" tx:"special")

Front End

Fuse provides several tools out of the box to get a user interface for any purpose up and running with minimal effort.

Management Interface

Fuse comes bundled with a simple management interface meant to assist you with configuration and management tasks of your Fuse instance.

_images/manager_lite.png

See Management Interface to learn more.

Search Interface

Out of the box, Fuse provides a generic search interface that is fully customizable.

_images/frontend-screenshot.png

See Search Interface to learn more.

Usage Statistics

Fuse Statistics Instance

Instead of setting up Fuse with manually created schemas to import your own data it also possible to set it up as a statistics instance. This is a special kind of instance that uses predefined schemas. It automatically imports statistical data from one or more other Fuse instances while behaving like a standard Fuse instance that provides the complete set of API functionality outlined in this documentation (API Reference).

See Usage Statistics to learn more.

Note

This functionality is part of Fuse Professional and not available in Fuse Free. Click here to learn more about the different editions of Fuse.

Extension Services

The core Fuse engine handles the indexing and querying of the documents ingested via its RESTful API. In addition to the index, Fuse has additional extension services to handle other common tasks that are needed for document search and analytics such as keyword extraction and automatic upload from a file system.

_images/services.png

See Services for a full list of extension services and instructions on creating them.

Note

This functionality is part of Fuse Professional and not available in Fuse Free. Click here to learn more about the different editions of Fuse.

API Reference

All of Fuse’s functionality is available via an intuitive REST API. This API is exposed at http://fusehost/api by default.

Queries

Building a Query

GET
/queries

Build a query.

This method has several options. For options, see Build Single Facet Queries and Combining Search Clauses.

Build Single Facet Queries

GET
/queries?facet={string:facet}&value={string:value}
Query Parameters
  • facet string optional Facet to search through.
  • negate boolean optional Negate the resulting query expression.
Response JSON Object
  • expression object optional Current query expression.
  • negate object optional GET /queries with the negative of current query.
  • search object optional GET /search with the current query.
  • facets object optional GET /facets with the current query.
  • contents object optional GET /contents with the current query.

Request Example

Build a query that will search for filename Alice in Wonderland.pdf.

curl -iXGET $FUSEURL'/api/queries?facet=filename&value=Alice+in+Wonderland.pdf'
var http = new XMLHttpRequest();
var url = fuseurl + "/api/queries?facet=filename&value=Alice+in+Wonderland.pdf";
http.open("GET", url);
http.onreadystatechange = function() {
    console.log(this.responseText);
}
http.send();

Response

Combining Search Clauses

GET
/queries?q={string:q}&part={string:part1}&part={string:part2}
Query Parameters
  • q required optional First query.
Response JSON Object
  • expression object optional Current query expression.
  • negate object optional GET /queries with the negative of current query.
  • search object optional GET /search with the current query.
  • facets object optional GET /facets with the current query.
  • contents object optional GET /contents with the current query.

Request Example

Combine the search clause

curl -iXGET $FUSEURL'/api/queries?q=%7C%28filename%3A%22Alice+in+Wonderland.pdf%22+filename%3A%22Metamorphosis.epub%22%29&part=type%3Adocument&op=and'
var http = new XMLHttpRequest();
var url = fuseurl + "/api/queries?q=%7C%28filename%3A%22Alice+in+Wonderland.pdf%22+filename%3A%22Metamorphosis.epub%22%29&part=type%3Adocument&op=and";
http.open("GET", url);
http.onreadystatechange = function() {
    console.log(this.responseText);
}
http.send();

Response

|(filename:"Alice in Wonderland.pdf" filename:"Metamorphosis.epub")

with

"type:document".

Facets

Query All Facets

GET
/facets
Query Parameters
  • highlight boolean optional Highlight matches.
  • query_ext string optional Query extension to use. See query-extensions.
Response JSON Object
  • query object optional query resource for the current query.
  • items object optional List of Facet objects in the query scope.
  • @id object optional URL of this resource.
  • meta object optional SearchMeta object.

Request Example

Getting facets with a full-text match for ‘egypt’. We are limiting the results to only ‘filename’ and ‘created’ facets, to maintain readability.

curl -iXGET $FUSEURL'/api/facets?q=tx%3Aegypt&facets=filename%2Ccreated'
var http = new XMLHttpRequest();
var url = fuseurl + "/api/facets?q=tx%3Aegypt&facets=filename%2Ccreated";
http.open("GET", url);
http.onreadystatechange = function() {
    console.log(this.responseText);
}
http.send();

Response

Query a Single Facet

GET
/facets/{string:facet}
URL Parameters
  • facet string optional Facet to query.
Query Parameters
  • q string optional Fuse query.
  • value string optional Facet value to search for.
  • highlight boolean optional Highlight matches.
  • limit integer optional Limit of the number of returned values.
  • query_ext string optional Query extension to use. See query-extensions.
Response JSON Object

Request Example

Search within the filename index for value pre. Using similar technique, autocomplete can be implemented. If the url wasn’t scoped to ‘filename’ facet, matches from all facets would be listed.

curl -iXGET $FUSEURL'/api/facets/filename?value=pre'
import requests
requests.get(
    FUSEURL + '/api/facets/filename',
    params={
        "value": "pre"
    },
)
var http = new XMLHttpRequest();
var url = fuseurl + "/api/facets/filename?value=pre";
http.open("GET", url);
http.onreadystatechange = function() {
    console.log(this.responseText);
}
http.send();

Response

Contents

Query for documents only.

Query all Content

GET
/contents

Search for content and retrieve content details

Query Parameters
  • q string required The search query.
  • limit integer optional Number of search results returned.
  • offset integer optional Offset of search results.
  • highlight boolean optional Turn on/off highlighting of search terms.
  • query_ext string optional Query extension to use. See query-extensions.
Response JSON Object
  • limit int optional Limit in use.
  • offset int optional Offset in use.
  • total int optional Total number of entries that match the current query.
  • next object optional URL to next page of results for the current query.
  • prev object optional URL to previous page of results for the current query.
  • query object optional URL to the GET /queries resource for the current query.
  • items object optional List of Content objects.
  • @id object optional URL of the current resource.

Request Example

Query for full text search ‘egypt’ within the contents, while not returning facets matched. To maintain readability, we are limiting the number of results as well as attributes that is returned.

curl -iXGET $FUSEURL'/api/contents?q=tx%3Aegypt&attributes=fuse%3Aid%2Ccreated%2Cpath&limit=1'
var http = new XMLHttpRequest();
var url = fuseurl + "/api/contents?q=tx%3Aegypt&attributes=fuse%3Aid%2Ccreated%2Cpath&limit=1";
http.open("GET", url);
http.onreadystatechange = function() {
    console.log(this.responseText);
}
http.send();

Response

Query Content by ID

GET
/contents/{string:key}

Return content details about a specific result as a Content object.

Query Parameters
  • q string optional The search query (only used for highlighting).
  • highlight boolean optional Turn on/off highlighting of search terms.
Response JSON Object
  • . object optional A Content object.

Request Example

Fetch contents by fuse id ‘document:/docs/The Prince.epub’. We are only selecting filename, path and created object for brevity.

curl -iXGET $FUSEURL'/api/contents/document:/docs/The Prince.epub?attributes=fuse%3Aid%2Ccreated%2Cpath'
import requests
requests.get(
    FUSEURL + '/api/contents/document:/docs/The Prince.epub',
    params={
        "attributes": "fuse:id,created,path"
    },
)
var http = new XMLHttpRequest();
var url = fuseurl + "/api/contents/document:/docs/The Prince.epub?attributes=fuse%3Aid%2Ccreated%2Cpath";
http.open("GET", url);
http.onreadystatechange = function() {
    console.log(this.responseText);
}
http.send();

Response

Histories

Get Histories Endpoints

GET
/histories

Retrieve URLs to the available global histories.

Response JSON Object
  • @id object optional The current resource's URL.
  • searches object optional URL to the global search history.
  • views object optional URL to the global item view history.
  • errors object optional URL to the global runtime error history.
  • monitoring object optional URL to the global monitoring data access.

Request Example

Retrieve global histories URLs.

curl -iXGET $FUSEURL'/api/histories'
import requests
requests.get(
    FUSEURL + '/api/histories',
)
var http = new XMLHttpRequest();
var url = fuseurl + "/api/histories";
http.open("GET", url);
http.onreadystatechange = function() {
    console.log(this.responseText);
}
http.send();

Response

Retrieve Global Search History

GET
/histories/searches

Retrieves all calls to the GET /search and GET /contents methods.

URL Parameters
  • limit integer optional Maximum number of items received.
  • offset integer optional Offset used.
  • with_keys boolean optional Optionally return database keys.
Response JSON Object
  • @id object optional The current resource's URL.
  • batch_key string optional The identifier for batch iteration.
  • limit integer optional The limit used on the request.
  • offset integer optional The offset used on the request.

Request Example

Retrieve global search history.

curl -iXGET $FUSEURL'/api/histories/searches?limit=1'
import requests
requests.get(
    FUSEURL + '/api/histories/searches',
    params={
        "limit": 1
    },
)
var http = new XMLHttpRequest();
var url = fuseurl + "/api/histories/searches?limit=1";
http.open("GET", url);
http.onreadystatechange = function() {
    console.log(this.responseText);
}
http.send();

Response

Clear Global Search History

DELETE
/histories/searches

Delete old history information.

Note

This also deletes user history entries.

URL Parameters
Status Codes

Request Example

curl -iXDELETE $FUSEURL'/api/histories/searches?before=2015-03-12'
import requests
requests.delete(
    FUSEURL + '/api/histories/searches',
    params={
        "before": "2015-03-12"
    },
)
var http = new XMLHttpRequest();
var url = fuseurl + "/api/histories/searches?before=2015-03-12";
http.open("DELETE", url);
http.onreadystatechange = function() {
    console.log(this.responseText);
}
http.send();

Get Global View History

GET
/histories/views

Retrieves all calls to the GET /contents/(key) method.

URL Parameters
  • limit integer optional The number of items that should be retrieved.
  • offset integer optional The offset for the items that should be retrieved.
  • with_keys boolean optional Optionally return database keys.
Response JSON Object
  • batch_key string optional Identifier for batch iteration.
  • limit integer optional Limed used.
  • offset integer optional Offset used.
  • next object optional Link to next batch.
  • prev object optional Link to previous batch.

Request Example

Retrieve global view history.

curl -iXGET $FUSEURL'/api/histories/views?with_attributes=True&limit=1'
var http = new XMLHttpRequest();
var url = fuseurl + "/api/histories/views?with_attributes=True&limit=1";
http.open("GET", url);
http.onreadystatechange = function() {
    console.log(this.responseText);
}
http.send();

Response

Clear Global View History

DELETE
/histories/views

Delete old history information.

Note

This also deletes user history entries.

URL Parameters
Status Codes

Request Example

curl -iXDELETE $FUSEURL'/api/histories/views?before=2015-03-12'
import requests
requests.delete(
    FUSEURL + '/api/histories/views',
    params={
        "before": "2015-03-12"
    },
)
var http = new XMLHttpRequest();
var url = fuseurl + "/api/histories/views?before=2015-03-12";
http.open("DELETE", url);
http.onreadystatechange = function() {
    console.log(this.responseText);
}
http.send();

Get Error Information

GET
/histories/errors

Retrieves collected information about errors that happened during runtime.

URL Parameters
  • limit integer optional The number of items that should be retrieved.
  • offset integer optional The offset for the items that should be retrieved.
  • with_keys boolean optional Optionally return database keys.
Response JSON Object
  • @id object optional The current resource's URL.
  • batch_key string optional Identifier for batch iteration.
  • limit integer optional Limed used.
  • offset integer optional Offset used.
  • next object optional Link to next batch.

Request Example

Retrieve error information.

curl -iXGET $FUSEURL'/api/histories/views?with_attributes=True&limit=1'
var http = new XMLHttpRequest();
var url = fuseurl + "/api/histories/views?with_attributes=True&limit=1";
http.open("GET", url);
http.onreadystatechange = function() {
    console.log(this.responseText);
}
http.send();

Response

Clear Error Information

DELETE
/histories/errors

Delete old error information.

URL Parameters
Status Codes

Request Example

curl -iXDELETE $FUSEURL'/api/histories/errors?before=2015-03-12'
import requests
requests.delete(
    FUSEURL + '/api/histories/errors',
    params={
        "before": "2015-03-12"
    },
)
var http = new XMLHttpRequest();
var url = fuseurl + "/api/histories/errors?before=2015-03-12";
http.open("DELETE", url);
http.onreadystatechange = function() {
    console.log(this.responseText);
}
http.send();

Get Monitoring Information

GET
/histories/monitoring

Retrieves collected information about server metrics and index statistics.

URL Parameters
  • limit integer optional The number of items that should be retrieved.
  • offset integer optional The offset for the items that should be retrieved.
  • with_keys boolean optional Optionally return database keys.
Response JSON Object
  • @id object optional The current resource's URL.
  • batch_key string optional Identifier for batch iteration.
  • limit integer optional Limed used.
  • offset integer optional Offset used.
  • next object optional Link to next batch.

Request Example

Retrieve monitoring information.

curl -iXGET $FUSEURL'/api/histories/monitoring?with_attributes=True&limit=1'
var http = new XMLHttpRequest();
var url = fuseurl + "/api/histories/monitoring?with_attributes=True&limit=1";
http.open("GET", url);
http.onreadystatechange = function() {
    console.log(this.responseText);
}
http.send();

Response

Clear Monitoring Information

DELETE
/histories/monitoring

Delete old monitoring information.

URL Parameters
Status Codes

Request Example

curl -iXDELETE $FUSEURL'/api/histories/monitoring?before=2015-03-12'
import requests
requests.delete(
    FUSEURL + '/api/histories/monitoring',
    params={
        "before": "2015-03-12"
    },
)
var http = new XMLHttpRequest();
var url = fuseurl + "/api/histories/monitoring?before=2015-03-12";
http.open("DELETE", url);
http.onreadystatechange = function() {
    console.log(this.responseText);
}
http.send();

Users

User relevant API functionality.

Specifying the User

Almost all methods under the GET /users resource are user based.

The name/ID of the current user is taken from the X-User-ID header.

You can specify the user with one of two methods:

/my Resource

The /my resource always refers to the current user.

For example, to retrieve settings for user name michael, use:

GET /my/settings HTTP/1.1
X-User-ID: michael

/users/(name) Resource

The user can be specified using the full URL path. This method requires that the user specified by the X-User-ID matches the user given in the URL path.

For example, to get settings for user name michael, use:

GET /users/michael/settings HTTP/1.1
X-User-ID: michael

Users Summary

GET
/users
Request Headers
  • X-User-ID string optional The id of the current user.
Response JSON Object
  • @id object optional The current resource's URL.

Request Example

curl -iXGET $FUSEURL'/api/users/michael' \
    -H "X-User-Id:michael"
import requests
requests.get(
    FUSEURL + '/api/users/michael',
    headers={
        "X-User-Id": "michael"
    },
)

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
    "@id": "http://fuse:8000/api/users",
    "user": "http://fuse:8000/api/users/michael"
}

Retrieve a User

GET
/users/{string:userid}
URL Parameters
  • userid string optional The unique identifier of the user.
Request Headers
Response JSON Object
  • @id object optional The current resource's URL.
  • savedsearches object optional Link to this user's saved searches.
  • histories object optional Link to this user's search and view history.
  • settings object optional Link to this user's saved settings.
  • user_id object optional The current user's id.

Request Example

curl -iXGET $FUSEURL'/api/users/michael' \
    -H "X-User-Id:michael"
import requests
requests.get(
    FUSEURL + '/api/users/michael',
    headers={
        "X-User-Id": "michael"
    },
)

Response

Settings

The User/Settings API allows you to save arbitrary JSON-structures on the server which can be used for tasks like saving user settings. These settings are per user.

Retrieve all Settings

GET
/users/{string:userid}/settings
GET
/my/settings
Request Headers
  • X-User-Id string required Unique ID of user.
Request Example

Retrieve a list of all the settings stored to a particular user.

curl -iXGET $FUSEURL'/api/my/settings' \
    -H "X-User-Id:michael"
import requests
requests.get(
    FUSEURL + '/api/my/settings',
    headers={
        "X-User-Id": "michael"
    },
)

Response

Set a User Setting

PUT
/users/{string:userid}/settings/{string:setting}
PUT
/my/settings/{string:setting}
URL Parameters
  • setting string required Unique key of the setting.
Request Headers
  • X-User-Id string required Unique ID of user.
Request Example

Store a setting named preferences.

Response

HTTP/1.1 201 CREATED
Content-Type: text/html

Retrieve a User Setting

Retrieve a user setting stored using PUT /my/settings/(setting).

GET
/users/{string:userid}/settings/{string:setting}
GET
/my/settings/{string:setting}
URL Parameters
  • setting string required Unique key of setting.
Request Headers
  • X-User-Id string required Unique ID of user.
Request Example

Retrieve the JSON stored in the example above

curl -iXGET $FUSEURL'/api/my/settings/preferences' \
    -H "X-User-Id:michael"
import requests
requests.get(
    FUSEURL + '/api/my/settings/preferences',
    headers={
        "X-User-Id": "michael"
    },
)

Response

Delete a Setting

DELETE
/users/{string:userid}/settings/{string:setting}
DELETE
/my/settings/{string:setting}
URL Parameters
  • setting string required Unique ID of setting.
Request Headers
  • X-User-ID string required Unique ID of user.

Delete All Settings

DELETE
/users/{string:userid}/settings
DELETE
/my/settings
Request Headers
  • X-User-ID string required Unique ID of user.

User History

The GET /users/(userid)/histories resource allows access to a user’s search and view history in the same way the GET /histories resource allows access to the global history. In addition a user’s history can also be deleted.

Retrieve User History Endpoints

GET
/users/{string:userid}/histories
GET
/my/histories
Request Headers
  • X-User-Id string required User ID of current user.
Response JSON Object
  • @id object optional The current resource's URL.
  • searches object optional Link to this user' search history.
  • views object optional Link to this user's view history.
Request Example

curl -iXGET $FUSEURL'/api/my/histories' \
    -H "X-User-Id:michael"
import requests
requests.get(
    FUSEURL + '/api/my/histories',
    headers={
        "X-User-Id": "michael"
    },
)

Response

Get User Search History

GET
/users/{string:userid}/histories/searches
GET
/my/histories/searches
URL Parameters
  • limit integer optional The number of items that should be retrieved.
  • offset integer optional The offset for the items that should be retrieved.
  • with_keys boolean optional Optionally return database keys.
Request Headers
  • X-User-ID string required Current user ID.
Response JSON Object
  • @id object optional The current resource's URL.
  • batch_key string optional The identifier for batch iteration.
  • limit integer optional The limit used on the request.
  • offset integer optional The offset used on the request.
Request Example

Retrieve a user’s search history.

curl -iXGET $FUSEURL'/api/my/histories/searches?limit=1' \
    -H "X-User-Id:michael"

Response

Retrieve User View History

View access history to GET /contents/(key) by a user.

GET
/users/{string:userid}/histories/views
GET
/my/histories/views
URL Parameters
  • limit integer optional Maximum number of items received.
  • offset integer optional Offset used.
  • with_keys boolean optional Optionally return database keys.
Request Headers
  • X-User-ID string required Current user ID.
Response JSON Object
  • @id object optional The current resource's URL.
  • batch_key string optional Identifier for batch iteration.
  • limit integer optional Limed used.
  • offset integer optional Offset used.
  • next object optional Link to next batch.
Request Example

Retrieve a user’s view history.

curl -iXGET $FUSEURL'/api/my/histories/views?with_attributes=True&limit=1' \
    -H "X-User-Id:michael"

Response

Delete a User’s Search History

DELETE
/users/{string:userid}/histories/searches
DELETE
/my/histories/searches

Delete the search history of the current user.

URL Parameters
  • userid string optional The unique identifier of the user.
Request Headers
  • X-User-Id string required The unique identifier of the user.
Request Example

Delete all search history entries of a particular user.

curl -iXDELETE $FUSEURL'/api/my/histories/searches' \
    -H "X-User-Id:michael"
import requests
requests.delete(
    FUSEURL + '/api/my/histories/searches',
    headers={
        "X-User-Id": "michael"
    },
)

Response

HTTP/1.1 204 NO CONTENT

Delete a User’s View History

DELETE
/users/{string:userid}/histories/views
DELETE
/my/histories/views

Delete the search history of the current user.

URL Parameters
  • userid string optional The unique identifier of the user.
Request Headers
  • X-User-Id string required The unique identifier of the user.
Request Example

Delete all content item views of a particular user.

curl -iXDELETE $FUSEURL'/api/my/histories/views' \
    -H "X-User-Id:michael"
import requests
requests.delete(
    FUSEURL + '/api/my/histories/views',
    headers={
        "X-User-Id": "michael"
    },
)

Response

HTTP/1.1 204 NO CONTENT

Saved Searches

The GET /users/(userid)/savedsearches/(key) resource allows you to save a specific search query for later retrieval and use. The search can be given a title and description and it can be edited or deleted at any time.

Retrieve a specific Saved Searches

GET
/users/{string:userid}/savedsearches/{string:key}
GET
/my/savedsearches/{string:key}

Retrieve a list of a specific user’s saved searches.

URL Parameters
  • userid string optional The unique identifier of the user.
  • key string optional Unique id of the saved search.
Request Headers
  • X-User-Id string optional The unique identifier of the user.
Response JSON Object
  • @id object optional The current resource's URL.
  • key object optional The unique key to identify this saved search.
  • created object optional The date and time this search was saved.
  • query object optional The search query.
  • query.expression object optional The used search expression.
  • query.@id object optional The URL of the query.
  • description object optional Description of the search.
  • title object optional A user given title for this search.
Request Example

Retrieve a user’s saved searches.

curl -iXGET $FUSEURL'/api/users/michael/savedsearches/185152ea55a1e8d949c01eab58d426b6?limit=1' \
    -H "X-User-Id:michael"

Response

Retrieve a list of Saved Searches

GET
/users/{string:userid}/savedsearches
GET
/my/savedsearches

Retrieve a list of a user’s saved searches.

URL Parameters
  • userid string optional The unique identifier of the user.
  • limit integer optional Maximum number of items received.
  • offset integer optional The offset for the retrieved savedsearches.
Request Headers
  • X-User-Id string required The unique identifier of the user.
Response JSON Object
  • @id object optional The current resource's URL.
  • total integer optional The total number of saved searches.
  • limit integer optional The limit used in the request.
  • offset integer optional The offset used in the request.
  • user object optional The link to the current user's resource.
  • items list optional The list of saved searches.
  • key object optional The unique key to identify this saved search.
  • created object optional The date and time this search was saved.
  • query object optional The search query.
  • query.expression object optional The used search expression.
  • query.@id object optional The URL of the query.
  • description object optional Description of the search.
  • title object optional A user given title for this search.
  • item.@id object optional The URL to this saved search.
  • next conditional optional Link to the next batch.
Request Example

Retrieve a user’s saved searches.

curl -iXGET $FUSEURL'/api/users/michael/savedsearches?limit=1' \
    -H "X-User-Id:michael"

Response

Delete All of a User’s Saved Searches

DELETE
/users/{string:userid}/savedsearches
DELETE
/my/savedsearches

Delete all saved searches of a specific user. The user is specified in the request header as “X-User-Id”.

URL Parameters
  • userid string optional The unique identifier of the user.
  • key string optional Unique id of the saved search.
  • userid string optional The unique identifier of the user.
Request Headers
  • X-User-Id string required The unique identifier of the user.
Request Example

Delete all saved search of the user.

curl -iXDELETE $FUSEURL'/api/my/savedsearches/' \
    -H "X-User-Id:michael"
import requests
requests.delete(
    FUSEURL + '/api/my/savedsearches/',
    headers={
        "X-User-Id": "michael"
    },
)

Response

HTTP/1.1 204 NO CONTENT

Controlling Fuse

Start, stop, and setup Fuse.

Get Fuse Status

GET
/admin/instance
Response JSON Object
  • @id object optional The URL of the resource.
  • name object optional The internal ID of the fuse instance.
  • running-services object optional List of running Fuse services.
  • failed-services object optional List of Fuse services that did not start as intended.
  • services object optional Link to services resource.
  • schemas object optional Link to schemas resource.
  • stats object optional Link to stats resource.
  • pkg object optional Link to setup-package resource.
Status Codes

Request Example

curl -iXGET $FUSEURL'/api/admin/instance'
import requests
requests.get(
    FUSEURL + '/api/admin/instance',
)
var http = new XMLHttpRequest();
var url = fuseurl + "/api/admin/instance";
http.open("GET", url);
http.onreadystatechange = function() {
    console.log(this.responseText);
}
http.send();

Response

Setup a Fuse Schema

PUT
/admin/instance

Setup Fuse with a Fuse package file. That is a zip-file containing at least the content schema and index schema for the Fuse instance. See Schema for details on creating a schema.

Request Headers
  • Content-Type string required Must be application/zip.
Response JSON Object
  • @id object optional The URL of the resource.
  • name object optional The internal ID of the fuse instance.
  • running-services object optional List of running Fuse services.
  • failed-services object optional List of Fuse services that did not start as intended.
  • services object optional Link to services resource.
  • schemas object optional Link to schemas.
  • pkg object optional Link to setup-package resource.
Status Codes

Request Example

curl -iXPUT $FUSEURL'/api/admin/instance' \
    -H "Content-Type:application/zip" \
    --data-binary 'ZIP-DATA'

Response

Setup a Fuse Statistics Instance

PUT
/admin/instance

Instead of setting up a Fuse instance with a Fuse package file you can set it into statistics mode where it imports usage statistics from provided Fuse instances using predefined schemas. See Usage Statistics for more information.

Note

This functionality is part of Fuse Professional and not available in Fuse Free. Click here to learn more about the different editions of Fuse.

Request Headers
  • Content-Type string required Must be application/json.
Request JSON Object
  • type string required Must be statistics.
  • target_cluster object optional A cluster to import statistics from.
  • target_cluster.host str optional The host name of the target cluster.
Response JSON Object
  • @id object optional The URL of the resource.
  • name object optional The internal ID of the fuse instance.
  • running-services object optional List of running Fuse services.
  • services object optional Link to services resource.
  • schemas object optional Link to schemas.
  • pkg object optional Link to setup-package resource.
Status Codes

Request Example

Response

Start / Stop / Restart an Instance

POST
/admin/instance

Start or stop an instance.

Request JSON Object
Request Headers
  • Content-Type string required Must be application/json.
Status Codes
  • 202 Accepted – The request was successfully handled and the appropriate action initiated.
  • 409 Conflict – Tried to start a running instance or stop a stopped instance.
  • 400 Bad Request – Invalid request, like unknown action.

Note

The response-status 202 means, that the action is probably not completed, yet and calls to the API might fail. Check the InstanceStatus.status field of GET /admin/instance.

Request Example

curl -iXPOST $FUSEURL'/api/admin/instance' \
    -H "Content-Type:application/json" \
    -d '
        {
            "action": "start"
        }
    '

Reset Fuse

DELETE
/admin/instance

Remove all data and configuration from the Fuse instance.

Note

After using delete you have to setup Fuse again (see setup instance).

Status Codes
  • 204 No Content – The instance was successfully deleted.
  • 409 Conflict – The instance is running. Stop the instance first before you delete it.

Warning

Note that this can not be undone and there is no additional safety-belt in place. Once you delete the instance (and it is in a stopped state) all data and configuration is gone.

Request Example

curl -iXDELETE $FUSEURL'/api/admin/instance'
import requests
requests.delete(
    FUSEURL + '/api/admin/instance',
)
var http = new XMLHttpRequest();
var url = fuseurl + "/api/admin/instance";
http.open("DELETE", url);
http.onreadystatechange = function() {
    console.log(this.responseText);
}
http.send();

Clear Data From an Instance

DELETE
/admin/instance/data

Delete all data from an instance but keep its configuration.

Status Codes
  • 204 No Content – The instance was successfully deleted.
  • 409 Conflict – The instance is running. Stop the instance first before you delete it.

Warning

Note that this can not be undone and there is no additional safety-belt in place. Once you clear the data of the instance (and it is in a stopped state) all data is gone.

Request Example

curl -iXDELETE $FUSEURL'/api/admin/instance/data'
import requests
requests.delete(
    FUSEURL + '/api/admin/instance/data',
)
var http = new XMLHttpRequest();
var url = fuseurl + "/api/admin/instance/data";
http.open("DELETE", url);
http.onreadystatechange = function() {
    console.log(this.responseText);
}
http.send();

Retrieve Schema Data

Schema Endpoints

GET
/admin/instance/schemas
Response JSON Object
  • @id object optional URL of the resource.
  • contentschema object optional URL of the content schema.
  • indexschema object optional URL of the index schema.
Status Codes
  • 200 OK – Successfully returned the schema overview.
Request Example

curl -iXGET $FUSEURL'/api/admin/instance/schemas'
import requests
requests.get(
    FUSEURL + '/api/admin/instance/schemas',
)
var http = new XMLHttpRequest();
var url = fuseurl + "/api/admin/instance/schemas";
http.open("GET", url);
http.onreadystatechange = function() {
    console.log(this.responseText);
}
http.send();

Response

Retrieve Content Schema

GET
/admin/instance/schemas/contentschema

Retrieve a JSON object which contains the content schema used by this Fuse instance.

Response JSON Object
  • @id object optional URL of current resource.
  • contentschema object optional Current content schema.
Status Codes
Request Example

curl -iXGET $FUSEURL'/api/admin/instance/schemas/contentschema'
import requests
requests.get(
    FUSEURL + '/api/admin/instance/schemas/contentschema',
)
var http = new XMLHttpRequest();
var url = fuseurl + "/api/admin/instance/schemas/contentschema";
http.open("GET", url);
http.onreadystatechange = function() {
    console.log(this.responseText);
}
http.send();

Response

Retrieve Index Schema

GET
/admin/instance/schemas/indexschema

Retrieve a JSON object which contains the index schema used by this Fuse instance.

Response JSON Object
  • @id object optional Resource URL.
  • indeschema object optional Current index schema.
Status Codes
  • 200 OK – Successfully returned the index schema.
Request Example

curl -iXGET $FUSEURL'/api/admin/instance/indexschema'
import requests
requests.get(
    FUSEURL + '/api/admin/instance/indexschema',
)
var http = new XMLHttpRequest();
var url = fuseurl + "/api/admin/instance/indexschema";
http.open("GET", url);
http.onreadystatechange = function() {
    console.log(this.responseText);
}
http.send();

Response

Update Content or Index Schema

PUT
/admin/instance/schemas/contentschema

Update content schema.

Request Headers
  • Content-Type string required Must be application/json.
Request JSON Object Status Codes
PUT
/admin/instance/schemas/indexschema

Update index schema.

Request Headers
  • Content-Type string required Must be application/json.
Request JSON Object Status Codes

Request Example

curl -iXPUT $FUSEURL'/api/admin/instance/indexschema' \
    -H "Content-Type:application/json" \
    -d '
        {
            "indexes": []
        }
    '

Note

When making changes to the content schema note that existing attributes cannot be changed.

After making changes to the index schema, you have to invoke a full re-indexing task manually for the changes to take effect.

Inspect Setup Package

Setup Package Overview

GET
/admin/instance/pkg
Response JSON Object
  • @id object optional URL of the resource.
  • files object optional URL of GET /admin/instance/pkg/files resource.
  • zip object optional URL to retrieve or upload the setup package ZIP file.
Status Codes
  • 200 OK – Successfully returned the schema overview.
Request Example

curl -iXGET $FUSEURL'/api/admin/instance/pkg'
import requests
requests.get(
    FUSEURL + '/api/admin/instance/pkg',
)
var http = new XMLHttpRequest();
var url = fuseurl + "/api/admin/instance/pkg";
http.open("GET", url);
http.onreadystatechange = function() {
    console.log(this.responseText);
}
http.send();

Response

Retrieve List of Contained Files of Setup Package

GET
/admin/instance/pkg/files

Retrieve list of files within setup package (at top level).

Response JSON Object
  • @id object optional URL of the resource.
  • items object optional Files in the package.
Status Codes
  • 200 OK – Successfully returned the setup package listing
Request Example

curl -iXGET $FUSEURL'/api/admin/instance/pkg/files'
import requests
requests.get(
    FUSEURL + '/api/admin/instance/pkg/files',
)
var http = new XMLHttpRequest();
var url = fuseurl + "/api/admin/instance/pkg/files";
http.open("GET", url);
http.onreadystatechange = function() {
    console.log(this.responseText);
}
http.send();

Response

GET
/admin/instance/pkg/files/mystuff

Retrieve list of files within setup package (within ‘mystuff’ sub-directory).

Structure of output is same as above.

GET
/admin/instance/pkg/files/indexschema.json?raw=1

Retrieve raw file contents of a file within the setup package.

Status Codes
  • 200 OK – Successfully returned the contents of the file
Response Headers

Retrieve ZIP File of Setup Package

GET
/admin/instance/pkg/zip
Response Headers Status Codes
  • 200 OK – Successfully returned the ZIP file

Upload ZIP File with Setup Package

PUT
/admin/instance/pkg/zip

This is just an alias for PUT /admin/instance.

Service Information

Service Overview

GET
/admin/instance/services

Get a list of all the services of the Fuse instance and information about their current status.

Response JSON Object
  • @id object optional Resource URL.
  • items object optional List of Service objects.
Status Codes
  • 200 OK – Successfully returned the service overview.
Request Example

curl -iXGET $FUSEURL'/api/admin/instance/services'
import requests
requests.get(
    FUSEURL + '/api/admin/instance/services',
)
var http = new XMLHttpRequest();
var url = fuseurl + "/api/admin/instance/services";
http.open("GET", url);
http.onreadystatechange = function() {
    console.log(this.responseText);
}
http.send();

Response

Single Service Information

GET
/admin/instance/services/{string:service}

Get information about a particular service.

Response JSON Object
  • @id object optional URL of the resource.
  • name object optional Name of the service.
  • name object optional Internal process name.
  • state object optional Detailed information about the service if available.
Status Codes
  • 200 OK – Successfully returned the service information.
Request Example

curl -iXGET $FUSEURL'/api/admin/instance/services/index'
import requests
requests.get(
    FUSEURL + '/api/admin/instance/services/index',
)
var http = new XMLHttpRequest();
var url = fuseurl + "/api/admin/instance/services/index";
http.open("GET", url);
http.onreadystatechange = function() {
    console.log(this.responseText);
}
http.send();

Response

Start, Stop or Restart a Service

POST
/admin/instance/services/{string:service}

Start, stop or restart a single service.

Request Headers
  • Content-Type string required Must be application/json.
Request JSON Object
  • action string required One of start , stop, restart or deactivate.
  • config object optional Override service configuration options.
Status Codes
  • 202 Accepted – Start/Stop/Restart of service was successfully initiated.
  • 409 Conflict – Trying to start a running or trying to stop an already stopped service.
  • 401 Unauthorized – Trying to stop a required service.
  • 400 Bad Request – Got an invalid request - like a unknown action.

Note

Only some services may be stopped (that are statistics, metrics_fetcher). Trying to stop any other service will result in a 401 Unauthorized.

Request Example

curl -iXPOST $FUSEURL'/api/admin/instance/services/api' \
    -H "Content-Type:application/json" \
    -d '
        {
            "action": "restart"
        }
    '

Start metrics_fetcher Service

POST
/admin/instance/services/metrics_fetcher

The metrics_fetcher service is turned off by default and can be started individually. Once it has been started it will start and stop with the instance like any other service. To change the intervals simply stop the service manually and start it again with the new values.

Note

This functionality is part of Fuse Professional and not available in Fuse Free. Click here to learn more about the different editions of Fuse.

Request Headers
  • Content-Type string required Must be application/json.
Request JSON Object
  • action string required Must be start.
Status Codes
Request Example

Deactivate metrics_fetcher Service

POST
/admin/instance/services/metrics_fetcher

The metrics_fetcher service can be controlled individually and thereby deactivated so it wont start or stop with the rest of the instance. Using this command the service will be stopped and set to deactivated.

Note

This functionality is part of Fuse Professional and not available in Fuse Free. Click here to learn more about the different editions of Fuse.

Request Headers
  • Content-Type string required Must be application/json.
Request JSON Object
  • action string required Must be deactivate.
Status Codes
  • 202 Accepted – Deactivation of service was successfully initiated.
  • 409 Conflict – Trying to deactivate an already deactivated service.
Request Example

curl -iXPOST $FUSEURL'/api/admin/instance/services/metrics_fetcher' \
    -H "Content-Type:application/json" \
    -d '
        {
            "action": "deactivate"
        }
    '

Instance Statistics

Statistics Overview

GET
/admin/instance/stats

Get statistics about the Fuse instance.

Response JSON Object
  • @id object optional Resource URL.
  • active_connections object optional HTTP connections to API.
  • index_stats object optional URL to index statistics.
  • content_stats object optional URL to content statistics.
Status Codes
  • 200 OK – Instance statistics were successfully returned.
Request Example

curl -iXGET $FUSEURL'/api/admin/instance/stats'
import requests
requests.get(
    FUSEURL + '/api/admin/instance/stats',
)
var http = new XMLHttpRequest();
var url = fuseurl + "/api/admin/instance/stats";
http.open("GET", url);
http.onreadystatechange = function() {
    console.log(this.responseText);
}
http.send();

Response

Content Statistics

GET
/admin/instance/stats/content

Get statistics about the indexed documents within the Fuse instance.

Response JSON Object
  • @id object optional Resource URL.
Status Codes
  • 200 OK – Content statistics were successfully returned.
Request Example

curl -iXGET $FUSEURL'/api/admin/instance/stats/content'
import requests
requests.get(
    FUSEURL + '/api/admin/instance/stats/content',
)
var http = new XMLHttpRequest();
var url = fuseurl + "/api/admin/instance/stats/content";
http.open("GET", url);
http.onreadystatechange = function() {
    console.log(this.responseText);
}
http.send();

Response

Index Statistics

GET
/admin/instance/stats/index

Get statistics about the indexes of the Fuse instance.

Response JSON Object
  • @id object optional Resource URL.
  • size_byte int optional Size of indexes in bytes.
  • indexes object optional Index statistics.
  • indexes.value object optional Index statistics.
  • indexes.value.total int optional Number of facets.
  • indexes.value.total_document_references int optional Number of document references.
  • indexes.value.total_term_count int optional Total number of terms.
Status Codes
  • 200 OK – Index statistics were successfully returned.
Request Example

curl -iXGET $FUSEURL'/api/admin/instance/stats/index'
import requests
requests.get(
    FUSEURL + '/api/admin/instance/stats/index',
)
var http = new XMLHttpRequest();
var url = fuseurl + "/api/admin/instance/stats/index";
http.open("GET", url);
http.onreadystatechange = function() {
    console.log(this.responseText);
}
http.send();

Response

Fusectl

The fusectl command line tool is used for setup and management tasks related to a Fuse instance. It is located at bin/fusectl within the installation directory.

Most of these action can also be carried out by requests to the control-API (see Controlling Fuse). Sometimes it is however more convenient to use a command line tool to get the job done.

Invocation

The control command is called like:

bin/fusectl [-h] [-c <config>] {command} [command-options]

A short help text for each command is given by:

bin/fusectl {command} -h
Global Options
-h, --help

display a short help text

-c, --configuration <configuration-file>

path to a Fuse configuration-file. If omitted, the file specified by the FUSE_CONFIG environment variable is used, in all other cases default configuration values are used.

Commands

create_config
Interactively create a basic Fuse configuration file
install
Create directories and configuration files for Fuse
check
Check if the configuration of Fuse is all right
show_config
Output configuration of Fuse
setup
Setup Fuse with schema files
setup_stats
Setup this Fuse to serve as a statistics instance for another Fuse instance
start
Start the Fuse instance
stop
Stop the Fuse instance
restart
Restart the Fuse instance
status
Get runtime status of the Fuse instance
run
Shortcut for install and start
info
Get information about the Fuse instance
slist
List all Fuse services
sstatus
Get status of a service of the Fuse instance
srestart
Restart a service of the Fuse instance
sstart
Start a service of the Fuse instance
sstop
Stop a service of the Fuse instance
monitor
Start a basic monitoring interface
import
Import data into the Fuse instance
index
Index all data
clear
Remove all data of a Fuse instance
create_config

Overview:

bin/fusectl create_config [-r] [--more] [-o output-file]

Interactively ask the user for basic configuration parameters and create a simple Fuse configuration file.

-o, --output

Write Fuse configuration file at the given location, defaults to fuse.yml within the current directory.

-r, --allow-root

When asking for ports, allow values to be within the privileged port range 0-1024.

--more

Configure additional parameters. Should not be needed in most cases.

install

Overview:

bin/fusectl [-c fuse.yml] install [-f] [-s] [-p pkg]

Creates necessary directories and configuration files for Fuse. This takes configuration values from the Fuse configuration file given by the -c option and merges them with environment variables starting with FUSE_.

-f, --force

Normally, fusectl will abort and report an error if it finds an existing Fuse installation at the location indicated by the fuse.yml file. Use force option to overwrite any potentially existing configuration files.

-s, --skip

Normally, fusectl will abort and report an error if it finds an existing Fuse installation at the location indicated by the fuse.yml file. Use skip option to use the existing configuration (if any) and not abort with an error.

OPTIONS
-p, --pkg

Also setup Fuse using the given pkg (a ZIP-file or directory containing schema data). This is a shortcut for running fusectl setup {pkg} right after the install. If pkg is - then read ZIP-data from stdin.

check

Overview:

bin/fuseclt [-c fuse.yml] check

Run several checks to see whether the Fuse installation is complete and valid.

show_config

Overview:

bin/fuseclt [-c fuse.yml] show_config [-s selector]

Display expanded configuration of the Fuse instance.

-s, --select

Instead of printing all configuration values, just print the configuration values at or below the given selector.

bin/fuseclt show_config api

Just show the API configuration.

setup

Overview:

bin/fusectl setup {pkg}

Setup Fuse using the given pkg (a ZIP-file or directory containing schema data).

pkg

Directory or ZIP-file containing schema and code of for Fuse. If pkg is - then read ZIP-data from stdin.

A package directory must contain a contentschema.json and indexschema.json.

setup_stats

Overview:

bin/fusectl setup_stats [-s sources-file] [-i import-interval] [-c cluster-address]

Create or update the configuration of a statistics instance.

-s, --sources

A JSON-file containing the sources from where the instance should import statistics:

{
    "items":[{
        "name": "FuseInstance_01",
        "url": "http://fuse_1:8000"
        },{
        "name": "FuseInstance_02",
        "url": "http://fuse_2:8000"
        }
    ]
}
-i, --interval

The interval in seconds after which the instance should again import statistics.

-c, --cluster

The address for the Fuse cluster’s Consul service. This is an alternative to passing sources via a JSON-file as the statistics instance can retrieve the possible sources through the Consul service.

start

Overview:

bin/fusectl start [-b] [-f]

Start the Fuse instance.

Fuse must be setup before it can be started.

-b, --base-only

Start only the basic services.

-f, --foreground

Start the manager as a foreground process.

stop

Overview:

bin/fusectl stop [-b]

Stop the Fuse instance.

-b, --keep-base

Stop only instance services and keep base system running.

restart

Overview:

bin/fusectl restart

Restart the Fuse instance.

status

Overview:

bin/fusectl status [-v]

Output status information for Fuse.

-v, --verbose

Include more detailed information for each service.

run

Overview:

bin/fusectl run [-r] [-p pkg]

Shortcut for combining install and start commands.

-r, --reinstall

Recreate configuration directories and files.

-p {pkg}, --pkg {pkg}

Directory or ZIP-file containing schema and code of for Fuse. If pkg is - then read ZIP-data from stdin.

A package directory must contain a contentschema.json and indexschema.json and may also contain a config.yml. The directory may also contain additional resources and code.

info

Overview:

bin/fusectl info

Get information about the Fuse instance.

slist

Overview:

bin/fusectl slist [-b] [-d]

List all Fuse services.

-b, --with-base

Include base services.

-d, --with-disabled

Include disabled services like metrics_fetcher or statistics_importer.

sstatus

Overview:

bin/fusectl sstatus [-v] {service-name}

Get the status of a specific service.

service-name

The name of the service.

-v, --verbose

Include additional information.

srestart

Overview:

bin/fusectl srestart {service-name}

Restart a service of the Fuse instance.

service-name

The name of the service.

sstart

Overview:

bin/fusectl sstart [-o OVERRIDE] {service-name}

Start a service of the Fuse instance.

service-name

The name of the service

-o, --override
Service configuration overrides.
bin/fuseclt sstart -o fetch_interval=100 metrics_fetcher

Note

Only applies to metrics_fetcher and statistics services since most services are required for the Fuse instance to function and therefore can not be started or stopped individually.

sstop

Overview:

bin/fusectl sstop {service-name}

Stop a single service of an instance.

service-name

The name of the service

-d, --deactivate

Deactivate metrics_fetcher service. When deactivated the service will no longer start/stop with the instance.

Note

Only applies to metrics_fetcher and statistics services since most services are required for the Fuse instance to function and therefore can not be started or stopped individually.

monitor

Overview:

bin/fusectl monitor

Start a simple monitoring interface, that shows continually updating status information for each service of Fuse.

Hint

Stop the monitoring interface with Ctrl-C.

import

Overview:

bin/fusectl import {file}

Import data into Fuse by providing a suitable JSON-file containing data items.

If file is - the command will read from stdin.

index

Overview:

bin/fusectl index

Index all data. Note that indexing large amounts of data can take a long time.

clear

Overview:

bin/fusectl clear [-q]

Remove the data of Fuse (but keep it’s configuration). This will ask for confirmation before actually removing anything.

-q, --quiet

Do not ask for confirmation

Tasks

Create and manage tasks to update and index data.

List All Available Tasks

GET
/tasks/types

List all available tasks via the tasks API such as update and index.

Request Example

Get list of all available tasks

curl -iXGET $FUSEURL'/api/tasks/types'
import requests
requests.get(
    FUSEURL + '/api/tasks/types',
)
var http = new XMLHttpRequest();
var url = fuseurl + "/api/tasks/types";
http.open("GET", url);
http.onreadystatechange = function() {
    console.log(this.responseText);
}
http.send();

Response

Update Contents

POST
/tasks/types/update

Use this resource to update / add / delete objects to the Fuse database.

Query Parameters
Request JSON Object
Request Headers
  • Content-Type string optional Application/json.
Response Headers Status Codes

Request Example

Create a book.

Response

HTTP/1.1 201 Created
Content-Type: application/json
Location: http://fuse:8000/api/tasks/stats/46

Patch Contents

POST
/tasks/types/update

Use this resource to patch objects that exist in Fuse. This resource allows you to directly add and remove values from a list or object fields of a content item.

Query Parameters
Request JSON Object
Request Headers
  • Content-Type string optional Application/json-patch+json.
Response Headers Status Codes

Delete By Query

POST
/tasks/types/qdelete

Query delete allows deletion of content items from fuse via a search query

Request JSON Object
  • q string required Query to delete objects from.
  • index boolean optional Immediately index after content deletion.
Response Headers Status Codes

Request Example

Delete all objects with tag:egypt.

curl -iXGET $FUSEURL'/api/tasks/types/qdelete' \
    -H "Content-Type:application/json" \
    -d '
        {
            "q": "tag:egypt"
        }
    '

Response

HTTP/1.1 201 Created
Location: http://fuse:8000/api/tasks/stats/48

Index All Contents

POST
/tasks/types/index

Run a complete index on all data.

Response Headers Status Codes

Request Example

Re-index all objects in Fuse.

curl -iXPOST $FUSEURL'/api/tasks/types/index'
import requests
requests.post(
    FUSEURL + '/api/tasks/types/index',
)
var http = new XMLHttpRequest();
var url = fuseurl + "/api/tasks/types/index";
http.open("POST", url);
http.onreadystatechange = function() {
    console.log(this.responseText);
}
http.send();

Response

HTTP/1.1 201 Created
Location: http://fuse:8000/api/tasks/stats/47

Retrieve Status of Tasks Started

GET
/tasks/stats

Retrieve all tasks that have been started as a paginated list of TaskStatus objects without additional details. See GET /tasks/stats/(tid) for task details.

Query Parameters
  • limit integer optional Number of search history entries.
  • offset integer optional Offset for search history entries.

Request Example

curl -iXGET $FUSEURL'/api/tasks/stats'
import requests
requests.get(
    FUSEURL + '/api/tasks/stats',
)
var http = new XMLHttpRequest();
var url = fuseurl + "/api/tasks/stats";
http.open("GET", url);
http.onreadystatechange = function() {
    console.log(this.responseText);
}
http.send();

Response

Retrieve Status of a Single Task

GET
/tasks/stats/{string:tid}

Retrieves stats for a specific task as a TaskStatus object with additional details.

Request Example

curl -iXGET $FUSEURL'/api/tasks/stats/45'
import requests
requests.get(
    FUSEURL + '/api/tasks/stats/45',
)
var http = new XMLHttpRequest();
var url = fuseurl + "/api/tasks/stats/45";
http.open("GET", url);
http.onreadystatechange = function() {
    console.log(this.responseText);
}
http.send();

Response

Delete a Specific Completed Task

DELETE
/tasks/stats/{integer:tid}

Removes stats of a specific completed task.

Delete Completed Tasks Statuses

DELETE
/tasks/stats

Removes stats of a specific completed task

Request JSON Object
  • before datetime optional Remove only tasks older than a giver date.

Request Example

Delete all tasks completed before a date.

curl -iXDELETE $FUSEURL'/api/tasks/stats' \
    -H "Content-Type:application/json" \
    -d '
        {
            "before": "2013-08-19T16:46:13Z"
        }
    '

Response

HTTP/1.1 204 No Content

Object Definitions

Clause

This object represents a simple term in the query. Examples are name:"Apple" (twitter name==”Apple”) and year:gt:2000 (year > 2000).
Clause
@type string always Always Clause.
label string always Label value of this facet.
value string always Facet value that this clause is using. For example, this is Apple for the query expression name:“Apple”.
not boolean always Clause negation.

Phrase

This object represents a special variant of the Clause that uses a phrase as search value. A phrase is a sequence of words that exactly need to match together for a result. They can only be used with the fulltext index and need to be defined by putting the phrase terms into double quotation marks. Example would be tx:""Microsoft Windows"".
Phrase
@type string always Always Phrase.
label string always Label value of this facet (usually Full Text ).
not boolean always Phrase negation.

ClauseGroup

This object represents a groups of terms joined by either an AND or an OR operator.
ClauseGroup
@type string always Always Group.
not boolean always Clause group negated.

Content

Content
|
attribute_info
| |
| |
is_single boolean always Field is a not a list.
| |
rendered_value string always HTML safe value.
| |
highlights list always Content match locations.
| |
label string always Label name of the attribute.

Estimation

Estimation

Error

Error
error string always Error name.
message string always Concise description.
time datetime always

Facet

Facet
name string always
label string always Facet label value.
limit integer always Maximum number of facet values.
query string always Current query.
@id string always Current URL.
|
FacetValue
| |
value string always
| |
freq integer always Number of documents that have this facet value.
| |
rendered_value string always HTML friendly FacetValue.value.
| |
rendered_freq string always HTML friendly FacetValue.freq.
| |
| |
and_query string always GET /queries URL to AND this facet value.
| |
or_query string always GET /queries URL to OR this facet value.
| |
| |
| |
refs integer always Number of referenced documents.
| |
docs integer always Number of cid values.
| |

IndexStats

IndexStats

InstanceInfo

This object provides information about the Fuse installation
InstanceInfo
version string optional The version of the Fuse installation.

InstanceStatus

InstancStatus
mem float always Memory percent usage.
mem_bytes integer always Memory usage in bytes.
cpu float always CPU percent usage.
services object always Statistics overview.

LoggedSearch

LoggedSearch
results integer always Number of results returned.
created datetime always UTC datetime of search.
user string always User that conducted search.
search_time float always Search processing time.
total integer always Number of items returned.

LoggedView

LoggedView
@id string always Viewed item's url.
user string always Logged in user.
fuse_id string always Fuse instance ID.
created datetime always Created datetime.

SearchMeta

SearchMeta
search_time float optional Time used to process the request (in seconds).
last_indexing string optional Time of last (partial) indexing.
last_full_indexing string optional Time of last full indexing.

Service

Service
@id string always Resource URL.
name string always Service name.

ServiceStatistics

ServiceStatistics
mem float always Memory percent usage.
mem_bytes integer always Memory usage in bytes.
cpu float always CPU percent usage.
age integer always Process age in seconds.

TaskStatus

All tasks statuses are returned as an instance of this object. Note that some of the attributes are only returned in the detailed version of this object.
TaskStatus
@id string always URI for this task status.
add_time datetime always Datetime that this task was added.
task_id string always Identifier for the task.
|
TaskFile
| |
@id string always URI of the task file.
| |
content_type string always Mimetype of the file.
| |
filename string always The filename of the file.
errors list extended A List object with any errors encountered.
items list always An array of TaskError objects.
user_id string extended Reserved key for future use.
end_time string extended End time of the task.
done boolean extended Task is done.