# Search with Typesense

> Add fast, typo-tolerant search-as-you-type to your application.

## 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:

```bash
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.