Search with Typesense

3 min read Updated 1 day ago

Search with Typesense

Typesense is a fast, typo-tolerant open source search engine. It is built for instant search-as-you-type: results come back as the user types, even for misspelled queries, which makes it a good fit for product search, full-text search over documents, or as a search backend behind something like Laravel Scout.

A Typesense service runs the typesense/typesense image and listens for HTTP traffic on port 8108.

Adding it

  1. Go to your application's Custom services card and open Create service.
  2. Pick Typesense under Search.
  3. Choose how much memory and storage it gets. Typesense keeps its data on persistent storage mounted at /data, defaulting to 10GB, so your indexes survive restarts.
  4. Pick a version. 29.0 is the default; 28.0, 27.1, 27.0 and 26.0 are also available.

That is enough to get it running. Your application cannot reach it until the next deployment picks up the connection variables below.

Connecting your application

The service injects a set of variables your application can read after deployment:

  • TYPESENSE_URL is the full address, http://HOST:8108
  • TYPESENSE_HOST is the hostname of the service
  • TYPESENSE_PORT is 8108
  • TYPESENSE_PROTOCOL is http
  • TYPESENSE_API_KEY is the API key

TYPESENSE_API_KEY is generated for you when the service is created: a 64-character random value. Because it is generated, it is not editable afterwards and does not appear as a field in the panel. Read it from your application's environment variables where it is injected.

Adjusting settings

The editable settings live under Service configuration, with the rest under Advanced settings. Changing any of them restarts the service from the next Update resources (or Edit resources) action.

  • TYPESENSE_ENABLE_CORS enables CORS for browser-based clients. It defaults to true, which is what you want if you query Typesense directly from the browser. Set it to false if you only ever search from the server side.
  • TYPESENSE_LOG_LEVEL controls how much the service logs. It defaults to INFO. Set it to a higher level to quiet things down, or lower to DEBUG when you are investigating a problem.

Searching over HTTP

Typesense is a plain HTTP API, so you can query it with curl using TYPESENSE_HOST and TYPESENSE_API_KEY from your application's environment. The port and protocol are fixed, so you can also use TYPESENSE_URL instead of splitting out the host.

The API key goes in the X-TYPESENSE-API-KEY header. A search against a collection called products looks like this:

curl -X POST "$TYPESENSE_URL/collections/products/documents/search" \
  -H "X-TYPESENSE-API-KEY: $TYPESENSE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "q": "wirelss headphone",
    "query_by": "name,description",
    "per_page": 10
  }'

Try a query with a typo, like wireless spelt wrong above: because Typesense tolerates typos, matching results still come back. You will need to create the products collection and index some documents before a search returns anything; the query above assumes those already exist.

What to watch out for

  • It restarts when you change its settings. Saving a config change restarts the service, so anything querying it at that moment gets dropped. The persistent /data volume keeps your indexes, so they are not lost.
  • Keep the API key secret. It is injected as an environment variable so only your application and its deployment see it. Do not hard-code it in client-side code that ships to browsers; if you need browser-side search, rely on TYPESENSE_ENABLE_CORS and a server-side proxy that adds the key.