This release contains new features, enhancements, performance improvements, bug fixes and important API changes for synonyms, curation rules and analytics rules.

New Features

• Diversify Search Results: Using Maximum Marginal Relevance (MMR), you can now diversify the top 250 hits on a pre-defined similarity metric. (Docs)
• Global Synonyms: Synonyms are now top-level resources, and can be shared between collections. (Docs)
• Global Curation Rules: Curations are also top-level resources now, and can be shared between multiple collections. (Docs)
• New features in JOINs:
  • facet_by now supports JOINed reference fields. (Docs)
  • Fetch related docs count for a document in a joined collection with the include_fields param. (Docs)
  • Support sorting and limit on joined fields with include_fields parameter. (Docs)
  • Support for altering reference fields in the collection schema.
  • New cascade_delete: false JOIN parameter for a reference field, to override the default behavior of document being cascade deleted in case all the documents it references are deleted. Requires async_reference parameter to be true. (Docs)
• New features in Union Search:
  • Support for group_by with Union search. (Docs)
  • Support for the pinned_hits search parameter in Union search.
  • Support for filtering out duplicates when using Union search with a new flag called remove_duplicates. (Docs)
• Facet Sampling: Make facet sampling dynamic using the new facet_sample_slope search parameter. (Docs)
• IPv6 Support: Typesense now supports binding to and serving requests over IPv6 addresses, enabling seamless integration and connectivity in modern IPv6-only or dual-stack networks.

Enhancements

• Support for (optionally) copying documents when cloning collections. (Docs)
• Support for ! as a standalone negation operator in filters, allowing field:![value] syntax as an alternative to field:!=[value].
• Support for Azure OpenAI models in Natural Language Search. (Docs)
• Support for GCP service account authentication in Natural Language Search models. (Docs)
• Support for GCP service account authentication for auto-embedding with GCP models. (Docs)
• Configurable token truncation for string fields to improve exact match filtering on long strings, using the new truncate parameter in the collection schema. (Docs)
• Return an error message when a field is declared that references another field of the same collection.
• New group_max_candidates search parameter which overrides the behavior of group_by queries introduced in v29.0 where value is an approximation. When is passed, will be accurate up until its value.

Bug Fixes

• Fix parsing of _eval() expressions when backticks are used to wrap strings containing parentheses.
• Ensure unique analytics IDs are generated when queries differ by filter_by or analytics_tag metadata to prevent aggregation issues.
• Fix search highlighting to use field-specific token separators instead of collection-level ones for consistent behavior.
• Return 201 status code when creating conversational models, personalization models, or natural language search models to follow REST conventions.
• Fix custom OpenAI-compatible endpoint URLs not being used for auto-embedding.
• Fix schema updates with embedding fields incorrectly requiring api_key validation for local models.
• Fix console logging to output info messages to stdout and warnings/errors to stderr instead of all to stderr.
• Fix phrase query highlighting to highlight only exact phrase matches instead of every individual keyword occurrence.
• Set user agent when initializing HTTP client for external API calls.
• Fix hyphen handling in negation searches to only apply special treatment when token starts with -.
• Fix query sub-tokenization to respect field-level symbols_to_index and token_separators configuration.
• Fix union search pagination bug where global pagination parameters were not passed to individual queries.
• Fix missing groups in case of high cardinality fields.
• Fix various deadlock scenarios related to async reference fields.
• Fix an edge case in group_by query along with infix search.
• Fix non-deterministic bucketing order when combining group_by with text match score bucketing, ensuring stable group pagination.
• Support id:![...] negation syntax for id filters.
• Fix remote embedder cache key handling for matryoshka models with different num_dim values to prevent dimension mismatches.
• Fix nested array highlights to respect highlight_affix_num_tokens for single-token matches.
• Fix phrase highlighting in nested array fields to return all matching snippets.
• Fix a crash while searching when updates are happening in parallel.
• Fixed the override matching for wildcard queries, dynamic filter, dynamic sort, and placeholders.
• Fix sort using _eval() for id fields.
• Fix missing vector distance in results when doing hybrid search with union search.
• Fix missing results when querying a stemmed field with set.

Deprecations / behavior changes

• Synonyms are no longer nested under Collections. We now have a top-level resource called a "Synonym Set" which is a list of synonyms that can be attached to one or more collections, or can be dynamically sent as a search parameter. Existing synonyms will be auto-migrated to synonym sets automatically on upgrading. (Docs)
• Overrides (aka Curation Rules) are no longer nested under Collections. Similar to synonym sets, we now have a top-level resource called a "Curation Set" that can be attached to one or more collections, or can be dynamically sent as a search parameter. Existing overrides will be auto-migrated to curation sets automatically on upgrading. The override_tags parameter has also been renamed to curation_tags. (Docs)
• The structure of Analytics Rules has changed. Old rules will be automatically migrated to the new structure internally. Read more here. (Docs)
• The export endpoint doesn't stop streaming the response if an error is encountered while loading a document from disk. The error is logged and is also returned in the response stream.
• Collections having references to each other are not allowed. If mutual reference is detected, the reference field will not be indexed.

Upgrading

Before upgrading your existing Typesense cluster to v30.0, please review the behavior changes above to prepare your application for the upgrade.

Please make sure to update your client libraries to the latest version, review the specific documentation links provided above and make any required changes to your code base if you programmatically create these resources using the API, before upgrading to this version.

We'd recommend testing on your development / staging environments before upgrading.

Typesense Cloud

If you're on Typesense Cloud:

1. Go to https://cloud.typesense.org/clusters.
2. Click on your cluster
3. Click on "Cluster Configuration" on the left-side pane, and then click on "Modify"
4. Select a new Typesense Server version in the dropdown
5. Schedule a time for the upgrade.

Self Hosted

If you're self-hosting Typesense, here are instructions on how to upgrade: Docs

⚠️ IMPORTANT: When self-hosting, please initiate a snapshot before upgrading, for the Synonyms & Overrides to be migrated to v30.

Downgrading

If you use synonyms, overrides (curation rules) or analytics rules in previous versions of Typesense, we will auto-migrate them to the new resources (Synonym Sets, Curation Sets and the new format for analytics rules) on upgrading. However, if you make any changes to these resources, and then downgrade later, those changes will NOT be ported back to the old version after downgrade.

Besides the above caveat, you can downgrade to any version above v27.

Documentation

View the complete API documentation for this release here: https://typesense.org/docs/30.0/api/