Path to the directory where data will be stored on disk.
API key that allows all operations.
API key that allows only searches (i.e. restricted to the
/collections/collection_name/documents/search end-point). Use this to make search requests
Address to which Typesense server binds. Default: 0.0.0.0
Port on which Typesense server listens.. Default: 8108
Starts the server as a read-only replica by defining the master Typesense server's address in http(s)://<master_address>:<master_port> format.
Path to the SSL certificate file. You must also define ssl-certificate-key to enable HTTPS.
Path to the SSL certificate key file. You must also define ssl-certificate to enable HTTPS.
By default, Typesense logs to stdout and stderr. To enable logging to a file, provide a path to a
Installing a client
We recommend that you use our API client if it's available for your language. It's also easy to
interact with Typesense through its simple, RESTful HTTP API.
That's it - we're now ready to start interacting with the Typesense server.
Creating a "books" collection
In Typesense, a collection is a group of related documents that is roughly equivalent to a table in a relational database.
When we create a collection, we give it a name and describe the fields that will be indexed when a document is
added to the collection.
For each field, we define its name, type and whether it's a facet field.
A facet field allows us to cluster the search results into categories and let us drill into each of those categories.
We will be seeing faceted results in action at the end of this guide.
We also define a default_sorting_field that determines how the results must be sorted when no
sort_by clause is provided. In this case, books that have more ratings will be ranked higher.
Adding books to the collection
We're now ready to index some books into the collection we just created.
As we can see in the result below, Typesense handled the typographic error gracefully and fetched the results
correctly. The facet_by clause also gives us a neat break-down of the number of books written
by each author in the returned search results.
We've come to the end of our little example. For a detailed dive into Typesense,
refer to our API documentation.
Ranking and relevance
Typesense ranks search results using a simple tie-breaking algorithm that relies on two components:
User-defined sort_by numerical fields.
Typesense computes a string similarity score based on how much a search query overlaps with the
fields of a given document. Typographic errors are also taken into account here. Let's see how.
When there is a typo in the query, or during prefix search, multiple tokens could match a given token in the query.
For e.g. both “john” and “joan” are 1-typo away from “jofn”. Similarly, in the case of a prefix search,
both “apple” and “apply” would match “app”. In such scenarios, Typesense would use the value of the
default_sorting_field field to decide whether documents containing "john" or "joan" should be ranked first.
When multiple documents share the same string similarity score, user-defined numerical fields are used to break the tie.
You can specify upto two such numerical fields.
For example, let's say that we're searching for books with a query like short story.
If there are multiple books containing these exact words, then all those documents would have the same
string similarity score.
To break the tie, we could specify upto two additional sort_by fields. For instance, we could say,
sort_by=average_rating:DESC,publication_year:DESC. This would sort the results in the following manner:
All matching records are sorted by string similarity score.
If any two records share the same string similarity score, sort them by their average rating.
If there is still a tie, sort the records by year of publication.
You can run one or more Typesense servers as read-only replicas that asynchronously pull data from a master
Typesense server. This way, if your primary Typesense server fails, search requests can be sent to the
To start Typesense as a read-only replica, pass the master Typesense server's address via
the --master argument:
NOTE: The master Typesense server maintains a replication log for 24 hours. If you are pointing the
replica to a master instance that has been running for longer than 24 hours, you need to first stop the master, take
a copy of the data directory and then then start the replica server by pointing to this backup data directory.
Typesense clients would allow you to configure one or more replica nodes during client initialization.
Client libraries will send all writes to the master. Reads will first be sent to the master and if the server
returns a 500 status code or if the connection times out, the reads will be sent in a round-robin
fashion to the read replicas configured.