# Typesense API Reference for v0.22.2
This section of the documentation details all the API Endpoints available in Typesense and all the parameters you can use with them.
Use the links on the side navigation bar to get to the appropriate section you're looking for.
To learn how to install and run Typesense, see the Guide section instead.
# What's new
This version v0.22.2
fixes some important bugs in the recently released v0.22.1
.
The changelog below contains aggregates all the changes between v0.21.0
and v0.22.x
.
# New Features
- Customizable word separators: define a list of special characters via the
token_separators
configuration during schema creation. These characters are then used as word separators, in addition to space and new-line characters. - Index and search special characters: define a list of special characters that will be indexed as text via the
symbols_to_index
configuration during schema creation. - Dynamic filtering based on rules: overrides now support a
filter_by
clause that can apply filters dynamically to query rules defined in the override. - Server side caching: cache search requests for a configurable amount of time to improve perceived latencies on heavy queries. Refer to the
use_cache
andcache_ttl
parameters. By default, caching is disabled. - Protection against expensive queries via the use of
search_cutoff_ms
parameter that attempts to return results early when the cutoff time has elapsed. This is not a strict guarantee and facet computation is not bound by this parameter. - Added
precision
sorting option to geo fields. This will bucket geo points into "groups" determined by the given precision value, such that points that fall within the same group are treated as equal, and the next sorting field can be considered for ranking.
# Enhancements
- Reduced memory consumption: 20-30% depending on the shape of your data.
- Improved update performance: updates on string fields are now 5-6x faster.
- Improved search performance: 20-25% faster on a variety of datasets we tested on.
- Improved parallelization for multi-collection writes: collections are now indexed independently, making indexing much faster when you are writing to hundreds of collections at the same time.
- Allow exhaustive searching via the
exhaustive_search
parameter. Setting?exhaustive_search=true
will make Typesense consider all prefixes and typo corrections of the words in the query without stopping early when enough results are found (drop_tokens_threshold
andtypo_tokens_threshold
configurations are ignored). - Exact filtering on strings (using the
:=
operator) no longer requires the field to be facetable. - Make minimum word length for 1-char typo and 2-char typos configurable via
min_len_1typo
andmin_len_2typo
parameters. Defaults are 4 and 7 respectively. - Support filtering by document
id
in filter_by query. - Support API key permission for creating a specific collection: previously, there was no way to generate an API key that allows you to create a collection with a specific name.
- Allow use of type
auto
for a field whose name does not contain a regular expression. - Geosearch filter automatically sorts the geo points for the polygon in the correct order: so you don't have to define them in counter clockwise order anymore.
# Bug Fixes
- Fixed edge cases in import of large documents where sometimes, imports hanged mysteriously or ended prematurely.
- Fixed document with duplicate IDs within an import upsert batch being imported as two separate documents.
- Fixed fields with names that contain a regular expression acting as an
auto
type instead of respecting the schema type. - Fixed a few edge cases in multi-field searching, especially around field weighting and boosting.
- Fixed deletion of collections with slashes or spaces in their names not working: you can now URL encode the names while calling the API.
- Fixed an edge case in exporting of documents using a
filter_by
condition: documents were being duplicated. - Allow a document to contain a dict/hashmap field when a wildcard auto (
.*
) field is present in the collection schema. - [New in v0.22.2] Handle bad geo polygon vertices (e.g. duplicate points).
- [New in v0.22.2] Fixed an edge case in ranking of words that share a prefix during prefix search.
- [New in v0.22.2] Better validation + handling of unexpected data errors during indexing.
- [New in v0.22.2] Fixed a rare but critical bug that manifested during document updates that had performance implications.
# Deprecations / behavior changes
- Once you upgrade your Typesense server to
v0.22
, the data directory cannot be used withv0.21.0
binary again. So, please take a snapshot/backup of the data directory before upgrading. - The
drop_tokens_threshold
andtypo_tokens_threshold
now default to a value of1
. If you were relying on the earlier defaults (10
and100
respectively), please set these parameters explicitly. - Minimum word length for 1-char typo correction has been increased to 4.
Likewise, minimum length for 2-char typo has been increased to 7. This has helped to reduce false fuzzy matches.
You can use the
min_len_1typo
andmin_len_2typo
parameters to customize these default values. - The
id
field cannot be part of the collection schema anymore. You can filter on the implicitid
field (viafilter_by
) but it cannot be queried upon (viaq
andquery_by
). If you wish to search on an identifier, you can define a custom field name like_id
and use that.
# Upgrading
Before upgrading your existing Typesense cluster to v0.22.2, please review the behavior changes above to prepare your application for the upgrade.
# Single node deployment
- Trigger a snapshot to create a backup of your data.
- Stop Typesense server.
- Replace the binary via the tar package or via the DEB/RPM installer.
- Start Typesense server back again.
# Multi-node deployment
To upgrade a multi-node cluster, we will be proceeding node by node.
NOTE: During the upgrade, we have to ensure that the leader of the cluster is using the older Typesense version.
So we will upgrade the leader last. You can determine whether a node is a leader or follower by the value of the state
field in the /debug
end-point response.
State | Role |
---|---|
1 | LEADER |
4 | FOLLOWER |
- Trigger a snapshot to create a backup of your data on the leader node.
- On any follower, stop Typesense and replace the binary via the tar package or via the DEB/RPM installer.
- Start Typesense server back again and wait for node to rejoin the cluster as a follower and catch-up.
- Repeat steps 2 and 3 for the other followers, leaving the leader node alone for now.
- Once all the followers have been upgraded to v0.22.2, stop Typesense on the leader.
- The other nodes will elect a new leader and keep working.
- Replace the binary on the old leader and start the Typesense server back again.
- This node will re-join the cluster as a follower, and we are done.
TIP
This documentation itself is open source. If you find any issues, click on the Edit page button at the bottom of the page and send us a Pull Request.
# Downgrading
If you need to downgrade back to v0.21.0
of Typesense for any reason, we've published a patched version v0.21.1
with some backported changes that allow a v0.21 node to be started on a data directory that was previously upgraded by a v0.22.2
upgrade. The other option is to clear the data directory (which will wipe out all data), install a previous version afresh and then re-index your data.