---
title: "Deploy Typesense Filtering"
description: "filter_by, facets, and pinned hits"
category: "Analytics"
url: https://railway.com/deploy/typesense-filtering
---

# Deploy Typesense Filtering

filter_by, facets, and pinned hits

**[Deploy Typesense Filtering on Railway](https://railway.com/template/typesense-filtering)**

Machine-readable deploy manifest (JSON, validated by TemplateCI): https://railway.com/deploy/typesense-filtering/manifest.json

- **Creator:** onepush
- **Category:** Analytics

## Template content

### typesense-railway

- **Source:** Shinyduo/typesense-railway
- **Public domain:** Yes

## Documentation

# Deploy and Host self hosted Typesense Filtering (Search Filtering) on Railway
The first time I wired up faceted search on Railway, I stared at zero facet counts because I forgot `facet: true` in the schema. Filtering requires declaring filterable and facetable fields at index time. Typesense handles it with `filter_by`, `facet_by`, and `pinned_hits`, but only when the schema, API key, CORS, and volume are set right. On Railway, pin `typesense/typesense:30.2`, mount `/data` on a volume, and start with `--data-dir /data --api-key=$TYPESENSE_API_KEY --enable-cors`. Lose the API key and every request fails until you rotate it and update clients. Pinned hits that don’t match the current filter are silently dropped — a gotcha you learn by running it.
## About Hosting Typesense Filtering open-source software on Railway (self hosted Typesense template)
This Railway template runs a single-node Typesense instance with the official Docker image. It’s not a cluster; horizontal scaling needs a separate Typesense cluster and load balancer. You get a search server on port 8108, a persistent volume for `/data`, the API key as an env var, and CORS for browser InstantSearch. The template assumes you know filtering and faceting are core, not add-ons.
Operational sweet spot: a dataset that fits in RAM. Typesense is in-memory, so `filter_by` and facet counts are computed in RAM, not disk. That keeps filtered queries fast — often under 10 ms for tens of thousands of records — but RAM must exceed index size plus overhead. 512 MB handles ~100k–200k small docs; 2 GB handles a few hundred thousand. Exceed RAM and latency collapses. The healthcheck on 8108 restarts a hung process, but the index only survives if the volume is intact. Keep that volume.
## Why Deploy Typesense Filtering, the Algolia alternative on Railway (Railway Free Trial)
Algolia is SaaS-only; you can’t self-host it. You pay per search request and per stored record, which gets expensive with heavy `filter_by` traffic. Typesense is GPL-3.0 open source, and Typesense Cloud bills dedicated RAM/vCPU hourly plus bandwidth — no per-search fee. A 0.5 GB burst node costs about $21.60/month; 2 GB burst is $43–$51/month. Self-hosting on Railway costs only compute + volume, typically single-digit to low-teens USD/month, with the $5 GitHub trial credit covering early experiments.
The tradeoff: Algolia’s dashboard is more polished and you skip ops. But for pinning hits per query, complex boolean filters, or keeping data in your own infrastructure, Typesense gives you control without metered per-request pricing. Railway’s free trial lets you test the self-hosted path with zero commitment.
Railway is a singular platform to deploy your infrastructure stack. Railway will host your infrastructure so you don't have to deal with configuration, while allowing you to vertically and horizontally scale it.
By deploying Typesense Filtering on Railway, you are one step closer to supporting a complete full-stack application with minimal burden. Host your servers, databases, AI agents, and more on Railway.
### Railway vs Other Hosting Providers and VPS for Typesense Filtering self hosting
| Provider | Pricing model | Setup effort | Best for |
|----------|---------------|--------------|----------|
| Railway | Usage-based compute + volume; $5 free trial | Very low — one-click template, managed volume | Fast iteration, no VPS management |
| DigitalOcean | Fixed droplet ($6–$48/mo) | Medium — install Docker, configure volume | Predictable monthly cost, root access |
| AWS | Pay-as-you-go (EC2, EBS) | High — VPC, security groups, IAM | Teams already inside AWS |
| Hetzner | Cheap VPS (€3–€10/mo) | Medium — manual Docker setup | Budget self-hosters in Europe |
Railway wins on iteration speed and built-in snapshots. DigitalOcean and Hetzner give fixed bills but you manage OS and Docker. AWS is overkill for a single node. None change Typesense behavior — performance comes from RAM and SSD.
## Common Use Cases for hosted Typesense Filtering
E-commerce faceted navigation: mark `category`, `brand`, `price`, `in_stock` as `facet: true`, then query `filter_by=category:=shoes && price:<100` and get facet counts. Documentation search with tag filters: filter by version or language, pin getting-started guides. Internal dashboards: filter tickets by status and priority, pin oldest unassigned. Geospatial filtering with `filter_by=location:(48.8566,2.3522,5 km)` needs a geo field. Design the schema around actual filters; adding a facet later requires reindexing.
## Dependencies for Typesense Filtering Docker hosted on Railway
x
### Deployment Dependencies for Managed Typesense Filtering Service (Search Filtering)
Minimal: one Docker container, a volume at `/data`, and env var `TYPESENSE_API_KEY`. No external DB or queue. Outbound network only needed for browser calls — enable CORS with `--enable-cors`. Railway manages the volume; deleting the service but keeping the volume allows reattach. Deleting the volume deletes your index.
### Implementation Details for Typesense Filtering (Using Typesense official docker image)
Use `typesense/typesense:30.2` — never `latest`. Start command:
```
--data-dir /data --api-key=$TYPESENSE_API_KEY --enable-cors
```
`--data-dir` points to the volume; `--api-key` sets the admin key; `--enable-cors` lets browser InstantSearch call directly. Port 8108 is the only exposed port. Healthcheck hits `/health`. The container runs as non-root; if you see permission errors, mount an empty volume and let Typesense initialize it.
## How does Typesense Filtering compare against other search filtering and facets platforms
Typesense’s `filter_by` uses boolean expressions (`&&`, `||`, parentheses, ranges). Facets auto-compute for `facet: true` fields. `pinned_hits` overrides ranking per query. Simple and fast, but lacks Elasticsearch’s aggregation depth or Solr’s custom analyzers.
### Typesense Filtering vs Algolia (Algolia Alternative)
Algolia has a similar `filters` parameter and better dashboard for testing. But Algolia is SaaS-only and charges per search — every filtered query costs money. Typesense gives the same boolean syntax with no per-query fee and per-request `pinned_hits`. For high-traffic filtering, self-hosted Typesense on Railway is often 5–10x cheaper. Algolia wins for zero ops and polished UI.
### Typesense Filtering vs Elasticsearch (Elasticsearch Alternative)
Elasticsearch filter context and aggregations are far more expressive (nested, scripted, multi-bucket). But it needs 1–2 GB heap just to start; Typesense runs in 256 MB. For simple boolean filters and facet counts, Typesense is faster to set up and cheaper. Elasticsearch wins for cross-index joins or complex aggregations. `pinned_hits` has no direct Elasticsearch equivalent; you’d use function score or manual boost.
### Typesense Filtering vs Meilisearch (Meilisearch Alternative)
Meilisearch has `filter` and `facets` parameters; syntax differs (`filter=category = shoes AND price < 100`). Custom ranking rules pin documents at index time, not per query. Typesense `pinned_hits` works per request — better for hourly promotions. Both open source, but Typesense’s GPL-3.0 is stricter than Meilisearch’s MIT if you embed search in proprietary code. Meilisearch is simpler for basic search; Typesense edges ahead for numeric ranges and geospatial.
### Typesense Filtering vs Solr (Solr Alternative)
Solr has done faceting since 2006; `fq` and facet counts are battle-tested. Query elevation can pin results. But Solr is Java with XML config and heavier ops. Typesense gives the same core filtering in a single binary with an easy REST API. Solr wins for custom analyzers, spellcheck, or more-like-this; Typesense wins for a RAM-based filter engine deployed in five minutes.
## How to use Typesense Filtering (the OSS Search Filtering)?
Create a collection schema marking filterable/facetable fields:
```json
{"name":"products","fields":[{"name":"title","type":"string"},{"name":"category","type":"string","facet":true},{"name":"price","type":"float","facet":true}]}
```
Then query:
```bash
curl -H "X-TYPESENSE-API-KEY: $TYPESENSE_API_KEY" "http://localhost:8108/collections/products/documents/search?q=*&filter_by=category:=shoes%20%26%26%20price:%3C100&facet_by=category&pinned_hits=123,456"
```
`filter_by` URL-encodes `&&` as `%20%26%26`. `facet_by` returns counts respecting the filter. `pinned_hits` pins IDs only if they match the filter. For browser use, point `typesense-instantsearch-adapter` at the Railway URL with CORS on; API key goes in adapter config.
## How to self host Typesense Filtering on other VPS Services (Typesense Filtering self hosting guide)
### Clone the Repository
No repo to clone if using Docker — pull `typesense/typesense:30.2` directly. To build from source, clone `https://github.com/typesense/typesense` and follow README. Docker is simpler.
### Install Dependencies
Install Docker and Docker Compose (`sudo apt install docker.io docker-compose` on Ubuntu). Create a volume directory: `mkdir -p /var/lib/typesense` and ensure write permissions.
### Configure Environment Variables
Set `TYPESENSE_API_KEY` to a long random string (`openssl rand -hex 32`). Store in `.env` or export. Add `--enable-cors` for browser calls. Never commit the key.
### Start the Typesense Filtering Application
```bash
docker run -d -p 8108:8108 -v /var/lib/typexsense:/data -e TYPESENSE_API_KEY=your_key typesense/typesense:30.2 --data-dir /data --api-key=$TYPESENSE_API_KEY --enable-cors
```
Test with `curl http://localhost:8108/health`. Same config works on Railway — map volume and env var.
## Official Pricing of Typesense Filtering (Typesense Filtering pricing)
Open source is free (GPL-3.0). Typesense Cloud: dedicated RAM/vCPU hourly + bandwidth, no per-search fees. 0.5 GB bu

## Similar templates

- [Typesense vs Meilisearch](https://railway.com/deploy/typesense-vs-meilisearch) — self-hosted Typesense vs Meilisearch
- [Betterlytics](https://railway.com/deploy/betterlytics) — Betterlytics is a cookieless analytics platform GDPR-compliant.
- [Finance Tracker](https://railway.com/deploy/finance-tracker-1) — Private multi-user household finance ledger with budgets and CSV import.

Open this page in a browser: https://railway.com/deploy/typesense-filtering