API Documentation - Premium v10.2.0

Version:

Introduction

Welcome to the Typesense Premium API documentation. This page will walk you through how to download and start Typesense Premium, and well as the additional API end-points that are available on the Premium version.

This page only covers the additional features of the Premium version. For other features, see our community edition's getting started guide.

Usage

Downloading Typesense Premium

We have pre-built binaries available for Linux (X86_64) and Mac OS X from our downloads page. We also publish official Docker images for Typesense Premium on Docker hub.

Starting the server with the license key

If you had installed Typesense Premium via the DEB/RPM package, you can add the license key to the configuration file at /etc/typesense/typesense-server.ini -- remember to restart Typesense after that. You can verify that Typesense Premium has started fine by checking the log file in the default logging directory (/var/log/typesense).

If you are starting the server from the binary, pass the license key via the license-key argument:

./typesense-server --license-key=XSDUE-SSJUD-DJEUEN-EJDJD \
    --data-dir=/tmp/typesense-data --api-key=$TYPESENSE_API_KEY

NOTE: The master and replica servers have different license keys.

Curation

While Typesense makes it really easy and intuitive to deliver great search results, sometimes you might want to promote certain documents over others. Or, you might want to exclude certain documents from a query's result set.

Using overrides, you can include or exclude specific documents for a given query.

Create or update an override

In the following example, we are overriding the search results by placing the documents with ids 422 and 54 in the first and second positions respectively via the includes condition. Additionally, we're ensuring that the document with id 287 is not returned at all via the excludes condition. You need to specify only one of exclude or include.

Note how we are applying these overrides to an exact match of the query apple. Instead, if we want to match all queries that contained the word apple, we will use the contains match instead.

override = {
  "rule" => {
    "query" => "apple",
    "match" => "exact"
  },
  "includes" => [
    {"id" => "422", "position" => 1},
    {"id" => "54", "position" => 2}
  ],
  "excludes" => [
    {"id" => "287"}
  ]
}

# Creates/updates an override called `customize-apple` in the `companies` collection
client.collections['companies'].overrides.upsert('customize-apple', override)
override = {
  "rule": {
    "query": "apple",
    "match": "exact"
  },
  "includes": [
    {"id": "422", "position": 1},
    {"id": "54", "position": 2}
  ],
  "excludes": [
    {"id": "287"}
  ]
}

# Creates/updates an override called `customize-apple` in the `companies` collection
client.collections['companies'].overrides.upsert('customize-apple', override)
override = {
  "rule": {
    "query": "apple",
    "match": "exact"
  },
  "includes": [
    {"id": "422", "position": 1},
    {"id": "54", "position": 2}
  ],
  "excludes": [
    {"id": "287"}
  ]
}

// Creates/updates an override called `customize-apple` in the `companies` collection
client.collections('companies').overrides().upsert('customize-apple', override)
curl "http://localhost:8108/collections/companies/overrides/customize-apple" -X PUT \
-H "Content-Type: application/json" \
-H "X-TYPESENSE-API-KEY: ${TYPESENSE_API_KEY}" -d '{
  "rule": {
    "query": "apple",
    "match": "exact"
  },
  "includes": [
    {"id": "422", "position": 1},
    {"id": "54", "position": 2}
  ],
  "excludes": [
    {"id": "287"}
  ]
}'
Sample response
{
  "id": "customize-apple",
  "excludes": [
    {
      "id": "287"
    }
  ],
  "includes": [
    {
      "id": "422",
      "position": 1
    },
    {
      "id": "54",
      "position": 2
    }
  ],
  "rule": {
    "match": "exact",
    "query": "apple"
  }
}
Definition

PUT ${TYPESENSE_HOST}/collections/:collection/overrides/:id

Arguments
Parameter Required Description
excludes no List of document ids that should be excluded from the search results.
includes no List of document ids that should be included in the search results with their corresponding positions.
rule.query yes Indicates what search queries should be overridden.
rule.match yes Indicates whether the match on the query term should be exact or contains.

List all overrides

Listing all overrides associated with a given collection.

client.collections['companies'].overrides.retrieve
client.collections['companies'].overrides.retrieve()
client.collections('companies').overrides().retrieve
curl -H "X-TYPESENSE-API-KEY: ${TYPESENSE_API_KEY}" \
"http://localhost:8108/collections/companies/overrides"
Sample response
{
  "overrides":[
    {
      "id":"customize-apple",
      "excludes":[
        {
          "id":"287"
        }
      ],
      "includes":[
        {
          "id":"422",
          "position":1
        },
        {
          "id":"54",
          "position":2
        }
      ],
      "rule":{
        "match":"exact",
        "query":"apple"
      }
    }
  ]
}
Definition

GET ${TYPESENSE_HOST}/collections/:collection/overrides


Delete an override

Deleting an override associated with a collection.

client.collections['companies'].overrides['customize-apple'].delete
client.collections['companies'].overrides['customize-apple'].delete()
client.collections('companies').overrides('customize-apple').delete()
curl "http://localhost:8108/collections/companies/overrides/customize-apple" -X DELETE \
-H "X-TYPESENSE-API-KEY: ${TYPESENSE_API_KEY}"
Sample response
{
  "id": "customize-apple"
}
Definition

DELETE ${TYPESENSE_HOST}/collections/:collection/overrides/:id


Collection Alias

An alias is a virtual collection name that points to a real collection. If you're familiar with symbolic links on Linux, it's very similar to that.

Aliases are useful when you want to reindex your data in the background on a new collection and switch your application to it without any changes to your code. Let's take an example.

Let's say we have a collection called companies_june10 and an alias called companies pointing to that collection.

collection ---> companies_june10

On the next day (June 11), we will create a new collection called companies_june11 and start indexing the documents in the background into this collection. When we are done indexing, if we updated the companies alias to point to this new collection, your application would immediately start querying against the freshly indexed collection.

collection ---> companies_june11

Convenient isn't it? Let's now look at how we can create, update and manage aliases.


Create or Update an alias

aliased_collection = {
  'collection_name' => 'companies_june11'
}

# Creates/updates an alias called `companies` to the `companies_june11` collection
client.aliases.upsert('companies', aliased_collection)
aliased_collection = {
  'collection_name': 'companies_june11'
}

# Creates/updates an alias called `companies` to the `companies_june11` collection
client.aliases.upsert('companies', aliased_collection)
aliased_collection = {
  'collection_name': 'companies_june11'
}

// Creates/updates an alias called `companies` to the `companies_june11` collection
client.aliases.upsert('companies', aliased_collection)
curl "http://localhost:8108/aliases/companies" -X PUT \
    -H "Content-Type: application/json" \
    -H "X-TYPESENSE-API-KEY: ${TYPESENSE_API_KEY}" -d '{
        "collection_name": "companies_june11"
    }'
Sample response
{
  "name": "companies",
  "collection_name": "companies_june11",
}
Definition

PUT ${TYPESENSE_HOST}/aliases/:alias

Arguments
Parameter Required Description
collection_name yes Name of the collection you wish to map the alias to.

Retrieve an alias

We can find out which collection an alias points to by fetching it.

client.aliases['companies'].retrieve
client.aliases['companies'].retrieve()
client.aliases('companies').retrieve()
curl -H "X-TYPESENSE-API-KEY: ${TYPESENSE_API_KEY}" \
    "http://localhost:8108/aliases/companies"
Sample response
{
  "name": "companies",
  "collection_name": "companies_june11",
}
Definition

GET ${TYPESENSE_HOST}/aliases/:alias


List all aliases

List all aliases and the corresponding collections that they map to.

client.aliases.retrieve
client.aliases.retrieve()
client.aliases().retrieve()
curl -H "X-TYPESENSE-API-KEY: ${TYPESENSE_API_KEY}" \
     "http://localhost:8108/aliases"
Sample response
{
  "aliases": [
    {
      "name": "companies",
      "collection_name": "companies_june11"
    },
    {
      "name": "employees",
      "collection_name": "employees_june11"
    }
  ]
}
Definition

GET ${TYPESENSE_HOST}/aliases


Delete an alias

client.aliases['companies'].delete
client.aliases['companies'].delete()
client.aliases('companies').delete()
curl "http://localhost:8108/aliases/companies" -X DELETE
    -H "X-TYPESENSE-API-KEY: ${TYPESENSE_API_KEY}"
Sample response
{
  "name": "companies",
  "collection_name": "companies_june11"
}
Definition

DELETE ${TYPESENSE_HOST}/aliases/:alias