Algolia Python API Client

Warnings

• breaking Major breaking changes occurred when upgrading from `algoliasearch` v3 to v4. The client initialization method changed significantly from `algoliasearch.client.Client` to `algoliasearch.search.client.SearchClient.create`. Many method signatures were also updated to accept optional arguments via a `request_options` dictionary, instead of individual parameters.
  Fix: Review the official upgrade guide for Python API Client v4. Update client initialization and method calls according to the new `SearchClient` patterns and `request_options` usage.
• breaking Breaking changes related to API schema fixes are introduced in minor versions. For instance, v4.36.0 included changes to `conditions` in composition rules, and v4.35.3 removed field requirements from the Composition API's run response. These can impact client types and expected data structures.
  Fix: Always check the release notes and changelog for each minor version update, especially for mentions of 'BREAKING CHANGES' related to API schema or model updates. Adapt your code to the updated data structures or API parameter requirements.
• gotcha Using the Search-Only API Key for indexing or administrative operations will result in permission errors. These operations require an Admin API Key.
  Fix: Ensure you are using your Algolia Admin API Key (not the Search-Only API Key) when performing operations like `save_object`, `delete_object`, or modifying index settings. The Search-Only API Key should only be used for read operations (e.g., `search`).
• gotcha Users behind corporate firewalls or with strict network configurations might encounter 'Unreachable hosts' errors. This usually indicates a timeout or connection issue preventing the client from reaching Algolia's servers.
  Fix: Configure connection timeouts for the Algolia client. You can create a `SearchConfig` object and pass it to `SearchClient.create_with_config()` to set `connect_timeout`, `read_timeout`, and `write_timeout` to appropriate values for your network environment. Consult your network administrator for allowed outbound connections.
• gotcha Version 4.31.0 introduced a potentially breaking `urllib3` dependency constraint that could conflict with other packages in your environment.
  Fix: If experiencing `urllib3` dependency conflicts, consider pinning `algoliasearch` to a version immediately prior to 4.31.0 (e.g., `algoliasearch==4.30.0`) or explicitly pinning `urllib3` to a compatible version if other libraries permit it. Check your `pip freeze` output for `urllib3` conflicts.

Install

• pip install --upgrade 'algoliasearch>=4.0,<5.0' Install latest v4

Imports

• SearchClient

  from algoliasearch.search.client import SearchClient

  The `algoliasearch.Client` and direct `algoliasearch` module import patterns were used in older major versions (v1/v2). For v3 and v4, `SearchClient` from `algoliasearch.search.client` is the correct entry point.

Quickstart

This quickstart demonstrates how to initialize the Algolia client, initialize an index, add a new object, search for objects, and update an object. Remember to replace placeholder API keys and application IDs with your actual credentials, ideally fetched from environment variables. For indexing operations, always use your Admin API Key.

import os
from algoliasearch.search.client import SearchClient

# Initialize the client with your Application ID and API Key
# Ensure you use your Admin API Key for indexing operations, and Search-Only API Key for search.
APP_ID = os.environ.get('ALGOLIA_APP_ID', 'YOUR_ALGOLIA_APP_ID')
API_KEY = os.environ.get('ALGOLIA_API_KEY', 'YOUR_ALGOLIA_ADMIN_API_KEY') # Use Admin API Key for writes
INDEX_NAME = os.environ.get('ALGOLIA_INDEX_NAME', 'your_index_name')

if not APP_ID or not API_KEY:
    print("Please set ALGOLIA_APP_ID and ALGOLIA_API_KEY environment variables or replace placeholders.")
else:
    try:
        client = SearchClient.create(APP_ID, API_KEY)
        index = client.init_index(INDEX_NAME)

        # Add a new record
        record = {"objectID": "1", "name": "Algolia Search", "category": "Search Engines"}
        save_response = index.save_object(record).wait()
        print(f"Object saved: {save_response.object_ids[0]}")

        # Search for records
        search_results = index.search('Algolia', {
            'attributesToRetrieve': ['name', 'category'],
            'hitsPerPage': 1
        })
        
        print("\nSearch Results:")
        for hit in search_results['hits']:
            print(f"- Name: {hit['name']}, Category: {hit['category']}")

        # Update an existing record
        index.partial_update_object({"objectID": "1", "description": "Fast and relevant search."}).wait()
        print("\nObject updated.")

        # Delete a record (optional, uncomment to run)
        # index.delete_object("1").wait()
        # print("\nObject deleted.")

    except Exception as e:
        print(f"An error occurred: {e}")