Server arguments

Parameter

Required

Description

data-dir

true

Path to the directory where data will be stored on disk.

api-key

true

API key that allows all operations.

search-only-api-key

false

API key that allows only searches (i.e. restricted to the
/collections/collection_name/documents/search end-point). Use this to make search requests
directly from Javascript, without exposing your primary API key.

listen-address

false

Address to which Typesense server binds. Default: 0.0.0.0

listen-port

false

Port on which Typesense server listens.. Default: 8108

master

false

Starts the server as a read-only replica by defining the master Typesense server's address in http(s)://<master_address>:<master_port> format.

ssl-certificate

false

Path to the SSL certificate file. You must also define ssl-certificate-key to enable HTTPS.

ssl-certificate-key

false

Path to the SSL certificate key file. You must also define ssl-certificate to enable HTTPS.

log-dir

false

By default, Typesense logs to stdout and stderr. To enable logging to a file, provide a path to a
logging directory.

Upgrading from v0.8.0

Typesense v0.9.x changes the structure of the highlight field in the search JSON response.

If you are not using the highlighted snippet, upgrading is as simple as stopping
Typesense v0.8.x, and starting Typesense v0.9.1 by pointing it to the same
data directory (--data-dir). Otherwise, read on.

When multiple query_by fields are used in a search, v0.8.0 returns the highlight of only the best
matching field:

"highlight":{"title":"<mark>Jack</mark> <mark>Ryan</mark> and the recruit"}

New structure

In v0.9.x, Typesense returns the highlights of all matching query_by fields. Highlights of fields
that have a better match appear earlier in the array. For e.g. in the example below, title
appears before author as it matches the query "jack ryan" fully, while author
only has a 1-word match with the query.

/*
* Our Javascript client library works on both the client and the browser.
* When using the library on the browser, please be sure to use the
* search-only API Key rather than the master API key since the latter
* has write access to Typesense and you don't want to expose that.
*/letclient=newTypesense.Client({'masterNode':{'host':'master','port':'8108','protocol':'http','apiKey':'<API_KEY>'},'timeoutSeconds':2})

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:

String similarity.

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.

High Availability

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
replicas.

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.

Client configuration

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.