Api reference icon

MultiClusters REST API

Last updated 24 December 2017

What the MultiClusters API does

Our MultiClusters API makes transparent the difficulties associated with managing multiple clusters by adding a layer on top of the classical API. Here, we describe the REST API tool behind Agolia’s Multi Cluster Management (MCM) feature.

What is Multi Cluster Management (MCM)?

Normally, all of your data can fit onto one cluster. However, when your data becomes too large for one cluster, Algolia offers a way to logically break up your data so that it spans more than one cluster: some users’ data will go on cluster 1, others on cluster 2, and still others on as many clusters as need be.

To find out more on MCM - an overview and use cases, and how it fits within the Algolia infrastructure, plus a tutorial, go here:

The MCM API Client

We’ve developed an API client for MCM for the most common programming languages and platforms. These clients are advanced wrappers on top of the MCM REST API itself and have been made in order to help you to integrate the service within your apps: for both indexing and search. Everything that can be done using the REST API can be done using those clients.

Limitation v0.1

For v0.1, the assignment of users to clusters won’t be automatic: if a user is not properly assigned, or not found, the call will be rejected.

How to get the feature

MCM needs to be enabled on your cluster. You can contact support@algolia.com for more information.

Quick reference

MultiClusters API

Path Verb Method

/1/clusters

GET List clusters

/1/clusters/mapping/${userID}

GET Get userID

/1/clusters/mapping/top

GET Get top userID

/1/clusters/mapping

GET List userID

/1/clusters/mapping/search

POST Search userID

/1/clusters/mapping

POST Assign or Move userID

/1/clusters/mapping/${userID}

DELETE Remove userID

Multi Cluster API

List clusters

Path

/1/clusters

HTTP Verb GET

Description

List the clusters available in a multi-clusters setup for a single appID

Response

  • clusters (array of object): List of clusters available with an associated number of userIDs, records and data size

Example

curl -X GET \
     -H "X-Algolia-API-Key: ${API_KEY}" \
     -H "X-Algolia-Application-Id: ${APPLICATION_ID}" \
    "https://${APPLICATION_ID}.algolia.net/1/clusters"

Upon success, the response is 200 OK and contains the following clusters

{
  "clusters": [{
    "clusterName": "c1-test",
    "nbRecords": 42,
    "nbUserIDs": 0,
    "dataSize": 0
  },
  
  ]
}

Get userID

Path

/1/clusters/mapping/${userID}

HTTP Verb GET

Description

The userID information takes time to be propagated to the different clusters but the userID is directly usable after a assign userID.

Response

  • userID (string): userID requested
  • clusterName (string): associated cluster
  • nbRecords (integer): number of records of this user
  • dataSize (integer): datasize of this user

Example

curl -X GET \
     -H "X-Algolia-API-Key: ${API_KEY}" \
     -H "X-Algolia-Application-Id: ${APPLICATION_ID}" \
    "https://${APPLICATION_ID}.algolia.net/1/clusters/mapping/${USERID}"

Upon success, the response is 200 OK and contains the following userID data

{
  "userID": "user1",
  "clusterName": "c1-test",
  "nbRecords": 42,
  "dataSize":0
}

Get top userID

Path

/1/clusters/mapping/top

HTTP Verb GET

Description

Returns the top userID with the highest number of records per cluster.

The userID usage takes usually a few seconds to be propagated to the different clusters but the userID is directly usable after assigning a userID to a cluster.

Response

  • topUserIDs (array of object of array): List of clusters with the top userIDs and their associated number of records and data size

Example

curl -X GET \
     -H "X-Algolia-API-Key: ${API_KEY}" \
     -H "X-Algolia-Application-Id: ${APPLICATION_ID}" \
    "https://${APPLICATION_ID}.algolia.net/1/clusters/mapping/top"

Upon success, the response is 200 OK and contains the following array of userIDs and clusters

{
  "topUsers":[{
    "c1-test-1": [
      {
        "userID": "user1",
        "clusterName": "",
        "nbRecords": 42,
        "dataSize": 0
      }
    ],
    ...
  },
  
  ]
}

List userID

Path

/1/clusters/mapping

HTTP Verb GET

Description

The userID information takes usually a few seconds to be propagated to the different clusters but the userID is directly usable after a assign userID to a cluster.

Response

  • userIDs (array of object): List of userIDs assigned with the associated number of records and data size

Parameters

page
type URL-encoded string
mandatory no
default 0 (start from the beginning)
description

Page to retrieve, the userID per page is by default at 1000 userIDs

Example

curl -X GET \
     -H "X-Algolia-API-Key: ${API_KEY}" \
     -H "X-Algolia-Application-Id: ${APPLICATION_ID}" \
     --data-binary "{ \
     \"page\": 0, \"hitsPerPage\": 20}" \
    "https://${APPLICATION_ID}.algolia.net/1/clusters/mapping"

Upon success, the response is 200 OK and contains the following userIDs data

{
  "userIDs":[{
    "userID": "user1",
    "clusterName":"c1-test",
    "nbRecords":42,
    "dataSize":0
  },
  
  ]
}

Search userID

Path

/1/clusters/mapping/search

HTTP Verb POST

Description

Search for userIDs with typoTolerance based on a prefix. It’s possible to refine on a specific cluster.

The userID information usually takes a few seconds to be propagated to the different clusters but the userID is directly usable after you assign userID to a cluster.

To keep updates moving quicky, the index of userIDs isn’t built synchronously with the mapping. Instead, the index is built once every 12h, at the same time as the update of userID usage.

Response

  • hits (array of object): List of userIDs matching the query with the associated number of records and data size
  • nbHits (integer): Number of userIDs matching the query
  • updatedAt (integer): Timestamp of the last update of the index

Parameters

query
type URL-encoded string
mandatory no
default "" (no fulltext search)
description

query to search inside the userIDs

cluster
type URL-encoded string
mandatory no
default "" (all clusters)
description

Restrict the matching userID to a specific cluster

page
type integer
mandatory no
default 0 (first page)
description

Requested page (zero-based).

histPerPage
type integer
mandatory no
default 20
description

Number of userID to return, the maximum value is 1000.

Example

curl -X POST \
     -H "X-Algolia-API-Key: ${API_KEY}" \
     -H "X-Algolia-Application-Id: ${APPLICATION_ID}" \
     --data-binary "{ \
     \"query\": \"user1\", \"cluster\":\"c1-test\"}" \
    "https://${APPLICATION_ID}.algolia.net/1/clusters/mapping/search"

Upon success, the response is 200 OK and contains the following userIDs data.

{
  "hits": [{
    "userID": "user1",
    "clusterName": "c1-test",
    "nbRecords": 42,
    "nbUserIDs": 0,
    "dataSize": 0
  },
  
  ],
  "nbHits": 3,
  "updatedAt": 1497522462
}

Assign or Move userID

Path

/1/clusters/mapping

HTTP Verb POST

Description

If the userID is unknown, assign a userID to a cluster, otherwise the operation will move the userID and the associated data from the current cluster to the new cluster specified.

If the userID is already moving to another cluster, the move operation will be rejected.

Migrating a user takes a duration proportional to the size of the data linked to this userID.

Response

  • createdAt (string): Date of the assignment

Example

curl -X POST \
     -H "X-Algolia-User-ID: ${USER_ID}" \
     -H "X-Algolia-API-Key: ${API_KEY}" \
     -H "X-Algolia-Application-Id: ${APPLICATION_ID}" \
     --data-binary "{ \
     \"cluster\": \"c1-test\"}" \
    "https://${APPLICATION_ID}.algolia.net/1/clusters/mapping"

Upon success, the response is 200 OK.

A successful response indicates that the operation has been taken into account, and the userID is directly usable.

{
  "createdAt":"2013-01-18T15:33:13.556Z"
}

Remove userID

Path

/1/clusters/mapping/${userID}

HTTP Verb DELETE

Description

If the userID doesn’t exist, the call to remove the userID will still succeed because of the asynchronous handling of the write operations.

Response

  • deletedAt (string): Date of the deletion

Example

curl -X DELETE \
     -H "X-Algolia-USER-ID: ${USER_ID}" \
     -H "X-Algolia-API-Key: ${API_KEY}" \
     -H "X-Algolia-Application-Id: ${APPLICATION_ID}" \
    "https://${APPLICATION_ID}.algolia.net/1/clusters/mapping"

Upon success, the response is 200 OK and a task is created to remove the userID data and mapping

{
  "deletedAt": "$TIMESTAMP"
}
© Algolia - Privacy Policy