Algolia

The Algolia connector searches one index in your Algolia application: text search with filters and pagination, and suggestions for filter values (facets). Your app sends each search to Algolia directly; Appsanic does not pass the requests on.

It only searches. It cannot create, update or delete records or index settings, so create and fill the index, and configure its searchable facets, in Algolia or your own trusted systems.

The form groups three required fields under Application access and Search content.

Algolia Application ID

Ten capital letters and digits, from your Algolia application under Settings, API Keys.

Search-only API key

A key with only the search permission, restricted to your index. It is a standard 32-character key, and the field hides it until you choose to show it. Admin keys, keys that can change records and per-user secured keys are refused.

Index name

The exact name of the index, including capital letters, up to 128 characters and without URL paths or wildcard characters. Choose an index that holds only records your app's users may read.

1. In Algolia, create an index and add the records your app should search.
2. In Algolia's API Keys, create a key with only the search permission and restrict it to that index.
3. In Appsanic, choose Connect in the rail, then Connect Algolia, and enter the three details under Test details.
4. Choose Check connection, then Connect.

The check asks Algolia about the key first: Search only permissions passes only when the key has the search permission and nothing else. A small search must then succeed. Saving is refused until the check has passed for each set of details you entered (Test, and Live if you added it), and Connect runs it for each. The steps every connector shares are in Connectors.

• query: the search text, up to 512 characters. Empty by default.
• page: the page of results, counting from 0, up to 1,000.
• hitsPerPage: 1 to 100 results. The default is 20.
• filters: an Algolia filter expression, up to 2,048 characters. Filters narrow results; they are not access control.
• facetName: the facet attribute, such as brand, up to 128 characters.
• facetQuery: the text to match in facet values, up to 512 characters.
• maxFacetHits: 1 to 100 values. The default is 10.

Import getConnector from @appsanic/connectors with your connection's id, shown under How to use Algolia in the connection's settings. Each reply is Algolia's JSON as an unknown value. There is no availability to check: search does not need a native build.

import { getConnector } from "@appsanic/connectors";

// Use the id of your own connection, shown under How to use Algolia.
const searchIndex = getConnector("algolia-9c31d6e2");

// Give each search its own AbortController; abort the last one when the text changes.
export async function searchRecords(query: string, page: number, signal: AbortSignal) {
  const result = await searchIndex.request(
    "search",
    { query, page, hitsPerPage: 20 },
    { signal },
  );
  const hits =
    typeof result === "object" && result !== null && "hits" in result ? result.hits : null;
  if (!Array.isArray(hits)) throw new Error("Algolia sent an unexpected reply.");
  const records: unknown[] = hits;
  return records; // Check the fields of each record before showing it.
}

// The brand attribute must be a searchable facet in Algolia.
export function brandSuggestions(text: string) {
  return searchIndex.request("searchFacetValues", {
    facetName: "brand",
    facetQuery: text,
    maxFacetHits: 10,
  });
}

A cancelled request rejects with an error named AbortError, which a search screen can ignore. Other failures throw a readable message, for example when Algolia's rate limit is reached.

On a paid plan, Build with Sanic AI in the connection's settings starts a Sanic AI draft that names this connection, so you can ask for a search screen. Sanic AI never sees the key. See With Sanic AI.

Search works in the browser preview, in Expo Go and in a native build, with the details your app uses (Test or Live). The connection check runs on Appsanic's server, so try the search screen in the preview, then on a phone through Expo Go.

• Test still sends real searches to Algolia and can count against your Algolia allowance. Use a separate index for practice content.
• Index only what your app's users may read: the key is public, and filters in your code do not protect records.
• Check each record's fields before you show it.
• A request that takes more than 15 seconds fails, and a reply larger than 4 MB is refused.