Skip to content

Documents ​

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.

Sample Response ​

Definition ​

POST ${TYPESENSE_HOST}/collections/:collection/documents

In Typesense, a search consists of a query against one or more text fields and a list of filters against numerical or facet fields. You can also sort and facet your results.

Due to performance reasons, Typesense limits searches to a maximum of 500 results.

Sample Response ​

When a string[] field is queried, the highlights structure would include the corresponding matching array indices of the snippets. For e.g:

Definition ​

GET ${TYPESENSE_HOST}/collections/:collection/documents/search

Arguments ​

ParameterRequiredDescription
qyesThe 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
query_byyesOne 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.
prefixnoBoolean 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.

Default: true
filter_bynoFilter conditions for refining your search results.

A field can be matched against one or more values.

country: USA
country: [USA, UK]

Separate multiple conditions with the && operator.

For eg: num_employees:>100 && country: [USA, UK]

More examples:

num_employees:10
num_employees:<=10
sort_bynoA list of numerical fields and their corresponding sort orders that will be used for ordering your results. Separate multiple fields with a comma. Up to 2 sort fields can be specified.

E.g. num_employees:desc,year_started:asc

The text similarity score is exposed as a special _text_match field that you can use in the list of sorting fields.

If one or two sorting fields are specified, _text_match is used for tie breaking, as the last sorting field.

Default:

If no sort_by parameter is specified, results are sorted by: _text_match:desc,``default_sorting_field:desc.
facet_bynoA list of fields that will be used for faceting your results on. Separate multiple fields with a comma.
max_facet_valuesnoMaximum number of facet values to be returned.
num_typosnoNumber of typographical errors (1 or 2) that would be tolerated.

Damerau–Levenshtein distance is used to calculate the number of errors.

Default: 2
pagenoResults from this specific page number would be fetched.
per_pagenoNumber of results to fetch per page.

Default: 10
include_fieldsnoComma-separated list of fields from the document to include in the search result.
exclude_fieldsnoComma-separated list of fields from the document to exclude in the search result.
drop_tokens_thresholdnoIf 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.

Default: 10

Retrieve a document ​

Fetch an individual document from a collection by using its id.

Sample Response ​

Definition ​

GET ${TYPESENSE_HOST}/collections/:collection/documents/:id

Delete a document ​

Delete an individual document from a collection by using its id.

Sample Response ​

Definition ​

DELETE ${TYPESENSE_HOST}/collections/:collection/documents/:id

Export documents ​

Sample Response ​

Definition ​

GET ${TYPESENSE_HOST}/collections/:collection/documents/export

Import documents ​

The documents to be imported must be formatted in a newline delimited JSON structure. You can feed the output file from a Typesense export operation directly as import.

Here's an example file:

You can import the above documents.jsonl file like this.

Sample Response ​

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 remaining documents

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:

Definition ​

POST ${TYPESENSE_HOST}/collections/:collection/documents/import