algoliasearch 1.6.1

Setup

To setup your project, follow these steps:

1. Install AlgoliaSearch using pip: pip install algoliasearch.

2. Initialize the client with your ApplicationID and API-Key. You can find all of them on your Algolia account.

from algoliasearch import algoliasearch

client = algoliasearch.Client("YourApplicationID", 'YourAPIKey')

Quick Start

In 30 seconds, this quick start tutorial will show you how to index and search objects.

Without any prior configuration, you can start indexing 500 contacts in the contacts index using the following code:

index = client.init_index("contact")
batch = json.load(open('contacts.json'))
index.add_objects(batch)

You can now search for contacts using firstname, lastname, company, etc. (even with typos):

# search by firstname
print index.search("jimmie")
# search a firstname with typo
print index.search("jimie")
# search for a company
print index.search("california paint")
# search for a firstname & company
print index.search("jimmie paint")

Settings can be customized to tune the search behavior. For example, you can add a custom sort by number of followers to the already great built-in relevance:

index.set_settings({"customRanking": ["desc(followers)"]})

You can also configure the list of attributes you want to index by order of importance (first = most important):

index.set_settings({"attributesToIndex": ["lastname", "firstname", "company",
                                         "email", "city", "address"]})

Since the engine is designed to suggest results as you type, you’ll generally search by prefix. In this case the order of attributes is very important to decide which hit is the best:

print index.search("or")
print index.search("jim")

Notes: If you are building a web application, you may be more interested in using our JavaScript client to perform queries. It brings two benefits: * Your users get a better response time by not going through your servers * It will offload unnecessary tasks from your servers

<script src="//cdn.jsdelivr.net/algoliasearch/3/algoliasearch.min.js"></script>
<script>
var client = algoliasearch('ApplicationID', 'apiKey');
var index = client.initIndex('indexName');

// perform query "jim"
index.search('jim', searchCallback);

// the last optional argument can be used to add search parameters
index.search(
  'jim', {
    hitsPerPage: 5,
    facets: '*',
    maxValuesPerFacet: 10
  },
  searchCallback
);

function searchCallback(err, content) {
  if (err) {
    console.error(err);
    return;
  }

  console.log(content);
}
</script>

Add a new object to the Index

Each entry in an index has a unique identifier called objectID. There are two ways to add en entry to the index:

1. Using automatic objectID assignment. You will be able to access it in the answer.

2. Supplying your own objectID.

You don’t need to explicitly create an index, it will be automatically created the first time you add an object. Objects are schema less so you don’t need any configuration to start indexing. If you wish to configure things, the settings section provides details about advanced settings.

Example with automatic objectID assignment:

res = index.add_object({"firstname": "Jimmie",
                       "lastname": "Barninger"})
print "ObjectID=%s" % res["objectID"]

Example with manual objectID assignment:

res = index.add_object({"firstname": "Jimmie",
                       "lastname": "Barninger"}, "myID")
print "ObjectID=%s" % res["objectID"]

Update an existing object in the Index

You have three options when updating an existing object:

1. Replace all its attributes.

2. Replace only some attributes.

3. Apply an operation to some attributes.

Example on how to replace all attributes of an existing object:

index.save_object({"firstname": "Jimmie",
                  "lastname": "Barninger",
                  "city": "New York",
                  "objectID": "myID"})

You have many ways to update an object’s attributes:

1. Set the attribute value

2. Add an element to an array

3. Remove an element from an array

4. Add an element to an array if it doesn’t exist

5. Increment an attribute

6. Decrement an attribute

Example to update only the city attribute of an existing object:

index.partial_update_object({"city": "San Francisco",
                           "objectID": "myID"})

Example to add a tag:

index.partial_update_object({"_tags": { "value": "MyTag", "_operation": "Add"},
                           "objectID": "myID"})

Example to remove a tag:

index.partial_update_object({"_tags": { "value": "MyTag", "_operation": "Remove"},
                           "objectID": "myID"})

Example to add a tag if it doesn’t exist:

index.partial_update_object({"_tags": { "value": "MyTag", "_operation": "AddUnique"},
                           "objectID": "myID"})

Example to increment a numeric value:

index.partial_update_object({"price": { "value": 42, "_operation": "Increment"},
                           "objectID": "myID"})

Example to decrement a numeric value:

index.partial_update_object({"price": { "value": 42, "_operation": "Decrement"},
                           "objectID": "myID"})

Search

Notes: If you are building a web application, you may be more interested in using our JavaScript client to perform queries. It brings two benefits: * Your users get a better response time by not going through your servers * It will offload unnecessary tasks from your servers.

To perform a search, you only need to initialize the index and perform a call to the search function.

The search query allows only to retrieve 1000 hits, if you need to retrieve more than 1000 hits for seo, you can use Backup / Retrieve all index content

You can use the following optional arguments:

index = client.init_index("contacts")
res = index.search("query string")
res = index.search("query string", { "attributesToRetrieve": "fistname,lastname", "hitsPerPage": 20})

{
  "hits": [
    {
      "firstname": "Jimmie",
      "lastname": "Barninger",
      "objectID": "433",
      "_highlightResult": {
        "firstname": {
          "value": "<em>Jimmie</em>",
          "matchLevel": "partial"
        },
        "lastname": {
          "value": "Barninger",
          "matchLevel": "none"
        },
        "company": {
          "value": "California <em>Paint</em> & Wlpaper Str",
          "matchLevel": "partial"
        }
      }
    }
  ],
  "page": 0,
  "nbHits": 1,
  "nbPages": 1,
  "hitsPerPage": 20,
  "processingTimeMS": 1,
  "query": "jimmie paint",
  "params": "query=jimmie+paint&attributesToRetrieve=firstname,lastname&hitsPerPage=50"
}

Multiple queries

You can send multiple queries with a single API call using a batch of queries:

# perform 3 queries in a single API call:
# - 1st query targets index `categories`
# - 2nd and 3rd queries target index `products`
results = self.client.multiple_queries([{"indexName" : "categories", "query" : myQueryString, "hitsPerPage": 3}
  , {"indexName" : "categories", "query" : myQueryString, "hitsPerPage": 3, "tagFilters": "promotion"}
  , {"indexName" : "categories", "query" : myQueryString, "hitsPerPage": 10}])

print results["results"]

The resulting JSON answer contains a results array storing the underlying queries answers. The answers order is the same than the requests order.

You can specify a strategy to optimize your multiple queries: - none: Execute the sequence of queries until the end. - stopIfEnoughMatches: Execute the sequence of queries until the number of hits is reached by the sum of hits.

Get an object

You can easily retrieve an object using its objectID and optionally specify a comma separated list of attributes you want:

# Retrieves all attributes
index.get_object("myID")
# Retrieves firstname and lastname attributes
res = index.get_object("myID", "firstname,lastname")
# Retrieves only the firstname attribute
res = index.get_object("myID", "firstname")

You can also retrieve a set of objects:

res = index.get_objects(["myID1", "myID2"])

Delete an object

You can delete an object using its objectID:

index.delete_object("myID")

Delete by query

You can delete all objects matching a single query with the following code. Internally, the API client performs the query, deletes all matching hits, and waits until the deletions have been applied.

params = {}
index.delete_by_query("John", params)

Index Settings

You can retrieve all settings using the get_settings function. The result will contain the following attributes:

settings = index.get_settings()
print settings

index.set_settings({"customRanking": ["desc(followers)"]})

List indices

You can list all your indices along with their associated information (number of entries, disk size, etc.) with the list_indexes method:

print client.list_indexes()

Delete an index

You can delete an index using its name:

client.delete_index("contacts")

Clear an index

You can delete the index contents without removing settings and index specific API keys by using the clearIndex command:

index.clear_index()

Wait indexing

All write operations in Algolia are asynchronous by design.

It means that when you add or update an object to your index, our servers will reply to your request with a taskID as soon as they understood the write operation.

The actual insert and indexing will be done after replying to your code.

You can wait for a task to complete using the waitTask method on the taskID returned by a write operation.

For example, to wait for indexing of a new object:

res = index.add_object({"firstname": "Jimmie",
                       "lastname": "Barninger"})
index.wait_task(res["taskID"])

If you want to ensure multiple objects have been indexed, you only need to check the biggest taskID.

Batch writes

You may want to perform multiple operations with one API call to reduce latency. We expose four methods to perform batch operations: * add_objects: Add an array of objects using automatic objectID assignment. * save_objects: Add or update an array of objects that contains an objectID attribute. * delete_objects: Delete an array of objectIDs. * partial_update_objects: Partially update an array of objects that contain an objectID attribute (only specified attributes will be updated).

Example using automatic objectID assignment:

res = index.add_objects([{"firstname": "Jimmie",
                         "lastname": "Barninger"},
                        {"firstname": "Warren",
                         "lastname": "Speach"}])

Example with user defined objectID (add or update):

res = index.save_objects([{"firstname": "Jimmie",
                          "lastname": "Barninger",
                           "objectID": "myID1"},
                          {"firstname": "Warren",
                          "lastname": "Speach",
                           "objectID": "myID2"}])

Example that deletes a set of records:

res = index.delete_objects(["myID1", "myID2"])

Example that updates only the firstname attribute:

res = index.partial_update_objects([{"firstname": "Jimmie",
                                   "objectID": "myID1"},
                                  {"firstname": "Warren",
                                   "objectID": "myID2"}])

If you have one index per user, you may want to perform a batch operations across severals indexes. We expose a method to perform this type of batch:

res = index.batch([
    {"action": "addObject", "indexName": "index1", {"firstname": "Jimmie", "lastname": "Barninger"}},
    {"action": "addObject", "indexName": "index2", {"firstname": "Warren", "lastname": "Speach"}}])

The attribute action can have these values: - addObject - updateObject - partialUpdateObject - partialUpdateObjectNoCreate - deleteObject

Security / User API Keys

The admin API key provides full control of all your indices. You can also generate user API keys to control security. These API keys can be restricted to a set of operations or/and restricted to a given index.

To list existing keys, you can use list_user_keys method:

# Lists global API Keys
client.list_user_keys()
# Lists API Keys that can access only to this index
index.list_user_keys()

Each key is defined by a set of permissions that specify the authorized actions. The different permissions are: * search: Allowed to search. * browse: Allowed to retrieve all index contents via the browse API. * addObject: Allowed to add/update an object in the index. * deleteObject: Allowed to delete an existing object. * deleteIndex: Allowed to delete index content. * settings: allows to get index settings. * editSettings: Allowed to change index settings. * analytics: Allowed to retrieve analytics through the analytics API. * listIndexes: Allowed to list all accessible indexes.

Example of API Key creation:

# Creates a new global API key that can only perform search actions
res = client.add_user_key(["search"])
print res["key"]
# Creates a new API key that can only perform search action on this index
res = index.add_user_key(["search"])
print res["key"]

You can also create an API Key with advanced settings:

• validity: Add a validity period. The key will be valid for a specific period of time (in seconds).

• maxQueriesPerIPPerHour: Specify the maximum number of API calls allowed from an IP address per hour. Each time an API call is performed with this key, a check is performed. If the IP at the source of the call did more than this number of calls in the last hour, a 403 code is returned. Defaults to 0 (no rate limit). This parameter can be used to protect you from attempts at retrieving your entire index contents by massively querying the index.

Note: If you are sending the query through your servers, you must use the enable_rate_limit_forward("TheAdminAPIKey", "EndUserIP", "APIKeyWithRateLimit") function to enable rate-limit.

• maxHitsPerQuery: Specify the maximum number of hits this API key can retrieve in one call. Defaults to 0 (unlimited). This parameter can be used to protect you from attempts at retrieving your entire index contents by massively querying the index.

• indexes: Specify the list of targeted indices. You can target all indices starting with a prefix or ending with a suffix using the ‘*’ character. For example, “dev_*” matches all indices starting with “dev_” and “*_dev” matches all indices ending with “_dev”. Defaults to all indices if empty or blank.

• referers: Specify the list of referers. You can target all referers starting with a prefix or ending with a suffix using the ‘*’ character. For example, “algolia.com/*” matches all referers starting with “algolia.com/” and “*.algolia.com” matches all referers ending with “.algolia.com”. Defaults to all referers if empty or blank.

• queryParameters: Specify the list of query parameters. You can force the query parameters for a query using the url string format (param1=X&param2=Y…).

• description: Specify a description to describe where the key is used.

# Creates a new index specific API key valid for 300 seconds, with a rate limit of 100 calls per hour per IP and a maximum of 20 hits

params = {
    'validity': 300,
    'maxQueriesPerIPPerHour': 100,
    'maxHitsPerQuery': 20,
    'indexes': ['dev_*'],
    'referers': ['algolia.com/*'],
    'queryParameters': 'typoTolerance=strict&ignorePlurals=false',
    'description': 'Limited search only API key for algolia.com'
}

res = client.add_user_key(params)
print res["key"]

Update the permissions of an existing key:

# Update an existing global API key that is valid for 300 seconds
res = client.update_user_key("myAPIKey", ["search"], 300)
print res["key"]
# Update an existing index specific API key valid for 300 seconds, with a rate limit of 100 calls per hour per IP and a maximum of 20 hits
res = index.update_user_key("myAPIKey", ["search"], 300, 100, 20)
print res["key"]

Get the permissions of a given key:

# Gets the rights of a global key
print client.get_user_key_acl("f420238212c54dcfad07ea0aa6d5c45f")
# Gets the rights of an index specific key
print index.get_user_key_acl("71671c38001bf3ac857bc82052485107")

Delete an existing key:

# Deletes a global key
print client.delete_user_key("f420238212c54dcfad07ea0aa6d5c45f")
# Deletes an index specific key
print index.delete_user_key("71671c38001bf3ac857bc82052485107")

You may have a single index containing per user data. In that case, all records should be tagged with their associated user_id in order to add a tagFilters=user_42 filter at query time to retrieve only what a user has access to. If you’re using the JavaScript client, it will result in a security breach since the user is able to modify the tagFilters you’ve set by modifying the code from the browser. To keep using the JavaScript client (recommended for optimal latency) and target secured records, you can generate a secured API key from your backend:

# generate a public API key for user 42. Here, records are tagged with:
#  - 'user_XXXX' if they are visible by user XXXX
public_key = client.generate_secured_api_key('YourSearchOnlyApiKey', 'tagFilters=user_42')

This public API key can then be used in your JavaScript code as follow:

var client = algoliasearch('YourApplicationID', '<%= public_api_key %>');
client.setExtraHeader('X-Algolia-QueryParameters', 'tagFilters=user_42'); // must be same than those used at generation-time

var index = client.initIndex('indexName')

index.search('something', function(err, content) {
  if (err) {
    console.error(err);
    return;
  }

  console.log(content);
});

You can mix rate limits and secured API keys by setting an extra user_token attribute both at API key generation time and query time. When set, a unique user will be identified by her IP + user_token instead of only by her IP. This allows you to restrict a single user to performing a maximum of N API calls per hour, even if she shares her IP with another user.

# generate a public API key for user 42. Here, records are tagged with:
#  - 'user_XXXX' if they are visible by user XXXX
public_key = client.generate_secured_api_key('YourRateLimitedApiKey', 'tagFilters=user_42', 'user_42')

This public API key can then be used in your JavaScript code as follow:

var client = algoliasearch('YourApplicationID', '<%= public_api_key %>');

// must be same than those used at generation-time
client.setExtraHeader('X-Algolia-QueryParameters', 'tagFilters=user_42');

// must be same than the one used at generation-time
client.setUserToken('user_42');

var index = client.initIndex('indexName')

index.search('another query', function(err, content) {
  if (err) {
    console.error(err);
    return;
  }

  console.log(content);
});

You can also generate secured API keys to limit the usage of a key to a referer. The generation use the same function than the Per user restriction. This public API key can be used in your JavaScript code as follow:

var client = algoliasearch('YourApplicationID', '<%= public_api_key %>');

// must be same than those used at generation-time
client.setExtraHeader('X-Algolia-AllowedReferer', 'algolia.com/*');

var index = client.initIndex('indexName')

index.search('another query', function(err, content) {
  if (err) {
    console.error(err);
    return;
  }

  console.log(content);
});

Copy or rename an index

You can easily copy or rename an existing index using the copy and move commands. Note: Move and copy commands overwrite the destination index.

# Rename MyIndex in MyIndexNewName
print client.move_index("MyIndex", "MyIndexNewName")
# Copy MyIndex in MyIndexCopy
print client.copy_index("MyIndex", "MyIndexCopy")

The move command is particularly useful if you want to update a big index atomically from one version to another. For example, if you recreate your index MyIndex each night from a database by batch, you only need to: 1. Import your database into a new index using batches. Let’s call this new index MyNewIndex. 1. Rename MyNewIndex to MyIndex using the move command. This will automatically override the old index and new queries will be served on the new one.

# Rename MyNewIndex in MyIndex (and overwrite it)
print client.move_index("MyNewIndex", "MyIndex")

Backup / Retrieve of all index content

You can retrieve all index content for backup purposes or for SEO using the browse method. This method can retrieve up to 1,000 objects per call and supports full text search and filters but the distinct feature is not available Unlike the search method, the sort by typo, proximity, geo distance and matched words is not applied, the hits are only sorted by numeric attributes specified in the ranking and the custom ranking.

You can browse the index:

# Iterate with a filter over the index
res = self.index.browse_all({"query": "test", "numericFilters": "i<42"})
for hit in res
    # Do something

# Retrieve the next cursor from the browse method
res = self.index.browse_from({"query": "test", "numericFilters": "i<42"}, None)
print res["cursor"]

Logs

You can retrieve the latest logs via this API. Each log entry contains: * Timestamp in ISO-8601 format * Client IP * Request Headers (API Key is obfuscated) * Request URL * Request method * Request body * Answer HTTP code * Answer body * SHA1 ID of entry

You can retrieve the logs of your last 1,000 API calls and browse them using the offset/length parameters: * *offset*: Specify the first entry to retrieve (0-based, 0 is the most recent log entry). Defaults to 0. * *length*: Specify the maximum number of entries to retrieve starting at the offset. Defaults to 10. Maximum allowed value: 1,000. * *onlyErrors*: Retrieve only logs with an HTTP code different than 200 or 201. (deprecated) * *type*: Specify the type of logs to retrieve: * *query*: Retrieve only the queries. * *build*: Retrieve only the build operations. * *error*: Retrieve only the errors (same as *onlyErrors* parameters).

# Get last 10 log entries
print client.get_logs()
# Get last 100 log entries
print client.get_logs(0, 100)