A list of fields that you wish to index for querying, filtering and faceting.
Apart from specifying the name and type for each field, a field of
type string or string can be declared as a faceted field by
setting its facet property to true.
Faceted fields are indexed verbatim without any tokenization or preprocessing.
For example, if you are building a product search, color and brand could be
defined as facet fields.
The name of an int32 / float field that determines the order in which
the search results are ranked when a sort_by clause is not provided during searching.
This field must indicate some kind of popularity. For example, in a product search
application, you could define num_reviews field as the default_sorting_field.
Additionally, when a word in a search query matches multiple possible words (either because of a typo or
during a prefix search), this parameter is used to rank such equally matching tokens.
For e.g. both "john" and "joan" are 1-typo away from "jofn". Similarly, in a
prefix search, both "apple" and "apply" would match the prefix "app".
Supported search field types
Typesense allows you to index the following types of fields:
You can define an array or multi-valued field by suffixing a  at the end:
Index a document
A document to be indexed in a given collection must conform to the schema of the collection.
If the document contains an `id` field of type `string`, Typesense would use that field as the identifier for the
document. Otherwise, Typesense would assign an identifier of its choice to the document.
The query text to search for in the collection.
Use * as the search string to return all documents. This is typically useful when used in
conjunction with filter_by.
For example, to return all documents that match a filter, use: q=*&filter_by=num_employees:10
One or more string / string fields that should be queried against.
Separate multiple fields with a comma: company_name, country
The order of the fields is important: a record that matches on a field earlier in the list is
considered more relevant than a record matched on a field later in the list.
So, in the example above, documents that match on the company_name field are ranked above
documents matched on the country field.
Boolean field to indicate that the last word in the query should be treated as a prefix, and not as a whole
word. This is necessary for building autocomplete and instant search interfaces.
Filter conditions for refining your search results. Separate multiple conditions
with && operator. Examples:
num_employees:<=100 && country:[USA, UK]
A list of numerical fields and their corresponding sort orders that will be used for ordering your results.
Separate multiple fields with a comma. Currently, upto 2 sort fields can be specified.
If no sort_by parameter is specified, results are sorted by the
default_sorting_field defined during the collection's creation.
A list of fields that will be used for faceting your results on. Separate multiple fields with a comma.
Maximum number of facet values to be returned.
Number of typographical errors (1 or 2) that would be tolerated.
Results from this specific page number would be fetched.
Number of results to fetch per page.
Comma-separated list of fields from the document to include in the search result.
Comma-separated list of fields from the document to exclude in the search result.
If the number of results found for a specific query is less than this number, Typesense will attempt
to drop the tokens in the query until enough results are found. Tokens that have the least individual hits
are dropped first. Set drop_tokens_threshold to 0 to disable dropping of tokens.
Retrieve a document
Fetch an individual document from a collection by using its id.
The response will consist of an items array that indicates the result of each document present in the request
to be imported (in the same order). If the import of a single document fails, it does not affect the
If there is a failure, the response item will include a corresponding error message. For example, the second
document had an import failure in the following response:
You can control the maximum number of facet values returned in the search results
via the max_facet_values parameter of the search end-point.
[Bug] Fix long queries causing highlighter to misbehave and sometimes crash.
[Bug] Fix facet counts not showing up in wildcard searches.
Typesense API uses standard HTTP response codes to indicate the success or failure of a request.
Codes in the 2xx range indicate success, codes in the 4xx range indicate an error given the information provided
(e.g. a required parameter was omitted), and codes in the 5xx range indicate an error with the Typesense service itself.
Bad Request - The request could not be understood due to malformed syntax.
Unauthorized - Your API key is wrong.
Not Found - The requested resource is not found.
Conflict - When a resource already exists.
Unprocessable Entity - Request is well-formed, but cannot be processed.
Service Unavailable - We’re temporarily offline. Please try again later.