NewYour coding agent can read the release notes before it upgrades.Set up the MCP server →
NuGet
NuGet, #1725 most downloaded on NuGet
A Lucene.Net search and indexing implementation for Examine
Latest stable
4.0.1
Last release 1 months ago
07 Oct 2026
Release timing varies
gaps range from 3 weeks to 1.1 years
Most releases are documented
notes for 50 of 57 stable releases
11 versions withdrawn
withdrawn after publishing
127 years old
76 releases · first in 1900
Drag across the ruler to compare, or tap a release to open it.
[perf-improver] perf: eliminate LINQ Select+ToArray allocation in OrderedDictionary.Values by @github-actions[bot] in https://github.com/Shazwazza/Exa
Full Changelog: https://github.com/Shazwazza/Examine/compare/v4.0.0...v4.0.1
If you're on v3, most of your code will keep compiling. There are breaking changes and they're all listed below, but the ones that bite are mostly con…
Your coding agent can read these notes before it upgrades. Set up the MCP server →
Examine v4 has been in beta for a very long time - the first beta went out in October 2023 - and it's finally done. The headline feature is native faceting with proper taxonomy index support, but there's a pile of other work in here too: nullable reference types everywhere, .NET 8/9/10 targets, a much more robust replicator, and a fair amount of API cleanup.
If you're on v3, most of your code will keep compiling. There are breaking changes and they're all listed below, but the ones that bite are mostly constructors and a couple of types that went internal.
This is the big one. Examine can now do faceted search natively, with or without a Lucene taxonomy index.
You declare facet fields the same way you declare any other field, using new entries in FieldDefinitionTypes:
FacetDouble, FacetFloat, FacetInteger, FacetLongFacetFullText, FacetFullTextSortableFacetDateTime, FacetDateYear, FacetDateMonth, FacetDateDay, FacetDateHour, FacetDateMinuteFacetTaxonomyThen you ask for facets on a query with WithFacets(...) and read them back off the results with GetFacet() / GetFacets(). Range faceting is supported through three new immutable structs - DoubleRange, FloatRange and Int64Range - and IFacetOperations gives you FacetString, FacetDoubleRange, FacetFloatRange and FacetLongRange.
There's also LuceneFacetSamplingQueryOptions for random sampling if you're faceting over something enormous and don't need exact counts.
Taxonomy support started life as a separate TaxonomyIndex type and ended up merged into LuceneIndex. You turn it on per index with LuceneIndexOptions.UseTaxonomyIndex, and the taxonomy data is stored in a taxonomy subdirectory alongside the main index.
It's optional, which matters more than it sounds - a lot of the beta cycle was spent making sure that indexes without a taxonomy directory behave correctly, particularly around replication. New surface for this includes ITaxonomyDirectoryFactory, ILuceneTaxonomySearcher, ITaxonomySearchContext and ITaxonomySearcherReference, plus LuceneIndex.IsTaxonomyEnabled and LuceneIndex.TaxonomySearcher.
SearchAfterOptions lets you page deep into a result set without Lucene having to materialize everything up to your offset. It works for faceted queries too. ShardIndex is now a non-nullable int.
IExamineValueBoosted and a WithBoost() extension so you can weight individual search values.SearchExtensions.Phrase(), backed by a new Examineness.Phrase.Examineness.Default - for when you want the analyzer's default behavior rather than picking one explicitly.ExamineValue.Create() - static factory methods replace the old parameterless constructor.ValueSet can now hold a mix of single objects and enumerables in the same dictionary (#340).ExamineReplicator took a beating during the beta and came out considerably better:
SyncedFileSystemDirectoryFactory no longer ends up with a main index and taxonomy directory that disagree with each other (#465).IsReplicationHealthy and MaxConsecutiveReplicationFailures (#461).If you're running Examine on App Service or anywhere else with a network file system, this is the section worth reading twice.
The whole codebase is <Nullable>enable</Nullable> with TreatWarningsAsErrors, and every public API is annotated. If you're building with nullable enabled you'll probably get some new warnings on upgrade. They're real - the annotations are telling you something that was always true.
| v3.10.0 | v4.0.0 | |
|---|---|---|
| Targets | net6.0, net8.0 | net8.0, net9.0, net10.0 |
| .NET Standard | dropped in v3 | not present |
| Lucene.NET | 4.8.0-beta00018 | 4.8.0-beta00018 |
| Microsoft.Extensions.* | 8.x/9.x | 10.0.11 |
.NET 6 support is gone. Package versions are now managed centrally through Directory.Packages.props, and every public API is tracked with the Microsoft.CodeAnalysis.PublicApiAnalyzers shipped/unshipped files - which is how the breaking change list below was generated rather than guessed at.
266 public APIs were added and 33 were removed or changed. About a third of the removals are just nullable re-annotations of the same member, so the list that actually matters is shorter than the number suggests.
Types
Examine.Lucene.Providers.LuceneSearcher is now internal. Use BaseLuceneSearcher if you were deriving from it, or resolve ISearcher from DI if you were consuming it.Constructors replaced by the options pattern
BaseLuceneSearcher and MultiIndexSearcher now take IOptionsMonitor<LuceneSearcherOptions> and IOptionsMonitor<LuceneMultiSearcherOptions> respectively. The old Analyzer-taking constructors are gone.
SearchContext, LuceneSearchResults and ExamineReplicator all have new constructor signatures - the replicator now takes a source directory and an optional destination taxonomy directory.
SyncedFileSystemDirectoryFactory and TempEnvFileSystemDirectoryFactory constructors changed to accept taxonomy directory factories. FileSystemDirectoryFactory and LuceneQueryOptions had their old constructors reintroduced during the beta for compatibility (#573, #550).
Members
LuceneIndex.IsCancellationRequested removed.MultiIndexSearcher.Searchers returns IEnumerable<BaseLuceneSearcher> instead of IEnumerable<LuceneSearcher>.SearchAfterOptions.ShardIndex is int, not int?.ExamineValue's parameterless constructor is gone - use ExamineValue.Create().BaseLuceneSearcher.Dispose() is abstract, so derived searchers have to implement it.FileSystemDirectoryFactory.CreateDirectory and GenericDirectoryFactory.CreateDirectory overrides changed with nullable annotations.ReaderStatus was deleted (#336).DI registration
AddExamineLuceneIndex and AddExamineLuceneMultiSearcher gained options-based overloads. The old parameter-list overloads still exist with nullable annotations applied.
FacetFullTextField.MaxCount defaults to int.MaxValue instead of 10, so you get all your facet values back by default (#435).Single values index as a SingleField rather than a DoubleField.SearchableFields from a brand new index aren't cached any more, which fixes searches against an index that was queried before it was first populated.FacetsConfig.Build is always called for non-taxonomy indexes.AddExamineLuceneIndex (#424).FieldDefinitionCollection and turn on UseTaxonomyIndex if you want taxonomy-backed ones.Everything else should just work. If it doesn't, open an issue and I'll take a look.
Faceting and taxonomy support are almost entirely the work of @nzdev and @nikcio, who kept at it across a very long beta. @kjac found and fixed the compatibility problems that would have bitten Umbraco users. Thanks also to @bjarnef, @callumbwhyte, @andrewmckaskill and @vivekBoii.
Full Changelog: https://github.com/Shazwazza/Examine/compare/v3.10.0...v4.0.0
Fix agentic workflow failures: work around gh-aw toolcache cache-hit leaving copilot CLI unavailable by @Shazwazza in https://github.com/Shazwazza/Exa
Full Changelog: https://github.com/Shazwazza/Examine/compare/v3.10.0...v3.10.1
This one's mostly a performance release, plus a Lucene.NET bump.
This one's mostly a performance release, plus a Lucene.NET bump.
The headline change. Examine now runs on the latest Lucene.NET beta (#523) - Lucene.Net.QueryParser and Lucene.Net.Replicator are both bumped from beta00017 to beta00018. If you're pinning Lucene.NET versions yourself, you'll want to update to match.
Most of the rest of this release came out of agentic workflows running on a schedule, hunting for allocations and wasted work in the hot paths. Nothing here changes behavior - it's all the same results, just cheaper to get:
GroupedAnd/Or/Not in both the fluent and Lucene query builders (#515, #518), added a single-field range query overload so Field<T> stops allocating a string[1] (#531), lazy-init the sort field list so unsorted queries don't allocate one (#536), cached the category filter query (#537), and replaced reflection with pattern matching for NumericRangeQuery (#517).AddDocument loop (#522, #516), used StringComparison.Ordinal in the AddDocument hot path (#521), dropped a redundant ToLower in GenerateHash and cut allocations in RemoveStopWords (#519), and removed LINQ allocations from the ValueSet constructors (#541).FullText factory and the sortable field names (#520, #533), cached the searcher array in MultiIndexSearcher so it stops running LINQ per search (#529), removed the Lazy<T> and inner closure per SearchResult (#532), killed a closure allocation in FieldValueTypeCollection.GetValueType (#527), and tidied up SearchContext.SearchableFields and ReadOnlyFieldDefinitionCollection (#545, #546).Values fallback in SearchResult.GetValues (#526).New benchmarks for the managed query and typed Field<T> hot paths (#524, #535), the #487 benchmark results are now published in the QueryBuilder/ValueSetCtor class comments (#525), an agentic workflow update (#558), and a dependabot bump for the docs site (#552).
Full Changelog: https://github.com/Shazwazza/Examine/compare/v3.9.0...v3.10.0
Fixes: A single locked file in ClearDirectory permanently breaks index initialisation (no retry)
Full Changelog: https://github.com/Shazwazza/Examine/compare/v3.8.0...v3.9.0
Change license from Ms-PL to MIT by @Copilot in https://github.com/Shazwazza/Examine/pull/422
Full Changelog: https://github.com/Shazwazza/Examine/compare/v3.7.1...v3.8.0
Improved logging output for better debugging issues with SyncedFileSystemDirectoryFactory
Full Changelog:
The recent change to the latest Lucene.NET seemed to 'just work' with Examine but there were some unnoticed nuances that needed to be fixed including
The recent change to the latest Lucene.NET seemed to 'just work' with Examine but there were some unnoticed nuances that needed to be fixed including handling disposals of the replicator when using the SyncedFileSystemDirectoryFactory. During the investigation, it was also noticed that the disposal ordering of some components wasn't done in an optimum order.
This should resolve the dreaded "invalid deletion count" index corruption issue.
This release has been tested in Prod and fixes have been confirmed by our good friend @readingdancer, thank you 🙌
Full Changelog: https://github.com/Shazwazza/Examine/compare/v3.6.0...v3.7.0
Adds new options for LuceneQueryOptions to work around limitations imposed by version 3.4.0 where the maximum data set size that can be paged is 10k w
Adds new options for LuceneQueryOptions to work around limitations imposed by version 3.4.0 where the maximum data set size that can be paged is 10k when using Skip/Take.
If paging over data sets larger than 10k items is required and is not possible without using the more efficient SearchAfter feature, than these new options will allow Skip/Take to work but will have some performance implications.
The reason the default 10K limit is imposed is because if this number is exceeded than additional memory and performance overheads will be incurred due to what Lucene allocates under the hood. Even Elastic Search has this limitation. For paging over large data sets, it is recommended to use the SearchAfter feature.
Examples have been added to the FluentApiTests.Paging_With_Skip_Take test for a reference on how to use these new options.
Full Changelog: https://github.com/Shazwazza/Examine/compare/v3.5.0...v3.6.0
Updates dependencies, especially to latest Lucene.Net 4.8.0-beta00017
Full Changelog: https://github.com/Shazwazza/Examine/compare/v3.4.0...v3.5.0
BREAKING - the default max results are now 100 instead of 500. This is a performance update since the larger max docs returned for any given query wil
QueryOptions to specify page size.Full Changelog: https://github.com/Shazwazza/Examine/compare/v3.3.0...v3.4.0
Release notes: https://shazwazza.com/post/an-examine-fix-for-umbraco-index-corruption/
Release notes: https://shazwazza.com/post/an-examine-fix-for-umbraco-index-corruption/
Bump nokogiri from 1.15.4 to 1.16.3 in /docs by @dependabot in https://github.com/Shazwazza/Examine/pull/380
Full Changelog: https://github.com/Shazwazza/Examine/compare/v3.2.0...v3.2.1
Migrate docs site to docfx by @nzdev in https://github.com/Shazwazza/Examine/pull/322
Full Changelog: https://github.com/Shazwazza/Examine/compare/v3.1.0...v3.2.0
Some great work from @nikcio 🎉 Examine now targets .NET 6, NetStandard 2.1 and NetStandard 2.0. This release comes with some bug fixes and features:
Some great work from @nikcio 🎉 Examine now targets .NET 6, NetStandard 2.1 and NetStandard 2.0. This release comes with some bug fixes and features:
DateOnly support to RangeQuery (#314 & #307) by @nikcio in https://github.com/Shazwazza/Examine/pull/315Full Changelog: https://github.com/Shazwazza/Examine/compare/v3.0.1...v3.1.0
Handle filtered items by @Zeegaan in https://github.com/Shazwazza/Examine/pull/289
Full Changelog: https://github.com/Shazwazza/Examine/compare/v3.0.0...v3.0.1
Nothing published for this version
See milestone for details: https://github.com/Shazwazza/Examine/milestone/36?closed=1
See milestone for details: https://github.com/Shazwazza/Examine/milestone/36?closed=1
> dotnet add package Examine --version 2.1.0
Full Changelog: https://github.com/Shazwazza/Examine/compare/v2.0.1...v2.1.0
See milestone for details: https://github.com/Shazwazza/Examine/milestone/34?closed=1
See milestone for details: https://github.com/Shazwazza/Examine/milestone/34?closed=1
> dotnet add package Examine --version 2.0.1
Full Changelog: https://github.com/Shazwazza/Examine/compare/v2.0.0...v2.0.1
Examine 2.0.0 is the .NET Standard (2.0) compatible version running on Lucene.Net 4.8
Examine 2.0.0 is the .NET Standard (2.0) compatible version running on Lucene.Net 4.8
The major changes are how indexes are created and modified. The 2.0 way is all done during composition and modifications happen using the IOptions pattern. The search and indexing APIs haven't changed very much.
There's new 2.0 documentation published too: https://shazwazza.github.io/Examine/
Some of the issues/tasks for this milestone can be found here: https://github.com/Shazwazza/Examine/milestone/32?closed=1
> dotnet add package Examine --version 2.0.0
Nothing published for this version
Nothing published for this version
Nothing published for this version
See milestone for full details: https://github.com/Shazwazza/Examine/milestone/33?closed=1
See milestone for full details: https://github.com/Shazwazza/Examine/milestone/33?closed=1
Install via Nuget:
Install-Package Examine -Version 1.2.2
See milestone for full details: https://github.com/Shazwazza/Examine/milestone/31?closed=1
See milestone for full details: https://github.com/Shazwazza/Examine/milestone/31?closed=1
Install via Nuget:
Install-Package Examine -Version 1.2.1
2 enhancements & 1 bug fix addressing stability and performance.
2 enhancements & 1 bug fix addressing stability and performance.
See milestone for full details: https://github.com/Shazwazza/Examine/milestone/29?closed=1
SkipTake methods for better performance when paging which saves allocations for any skipped results, see https://github.com/Shazwazza/Examine/pull/184NOTE: :These new features (among other things) need documentation. If you have any time to assist with documentation, the docs site is here and the code for it is in this repository.
Thanks to the community members: @nzdev development and testing help.
Install via Nuget:
Install-Package Examine -Version 1.2.0
Nothing published for this version
Quite a big release, 4 enhancements & 5 bug fixes addressing both stability and performance.
Quite a big release, 4 enhancements & 5 bug fixes addressing both stability and performance.
See milestone for full details: https://github.com/Shazwazza/Examine/milestone/25?closed=1
SelectFields methods for ensuring only the selected fields are returned in search results which saves allocations, see https://github.com/Shazwazza/Examine/pull/178NOTE: :These new features (among other things) need documentation. If you have any time to assist with documentation, the docs site is here and the code for it is in this repository.
Thanks to the community members: @nzdev, @callumbwhyte, @timeverts and @deekoulos for development and testing help.
Install via Nuget:
Install-Package Examine -Version 1.1.0
Issue fixed that may prevent unhandled exceptions occurring, see milestone for details:
Issue fixed that may prevent unhandled exceptions occurring, see milestone for details:
https://github.com/Shazwazza/Examine/milestone/27
Install via Nuget:
Install-Package Examine -Version 1.0.6
Couple of issues fixed, see milestone for full details: https://github.com/Shazwazza/Examine/milestone/24?closed=1
Couple of issues fixed, see milestone for full details: https://github.com/Shazwazza/Examine/milestone/24?closed=1
Install via Nuget:
Install-Package Examine -Version 1.0.5
Couple of issues fixed, see milestone for full details: https://github.com/Shazwazza/Examine/milestone/23?closed=1
Couple of issues fixed, see milestone for full details: https://github.com/Shazwazza/Examine/milestone/23?closed=1
Install via Nuget:
Install-Package Examine -Version 1.0.4
Couple of issues fixed, see milestone for full details: https://github.com/Shazwazza/Examine/milestone/22?closed=1
Couple of issues fixed, see milestone for full details: https://github.com/Shazwazza/Examine/milestone/22?closed=1
Install via Nuget:
Install-Package Examine -Version 1.0.3
Couple of issues fixed, see milestone for full details: https://github.com/Shazwazza/Examine/milestone/21?closed=1
Couple of issues fixed, see milestone for full details: https://github.com/Shazwazza/Examine/milestone/21?closed=1
Install via Nuget:
Install-Package Examine -Version 1.0.2
A few issues fixed based on fixes in 0.1.90
A few issues fixed based on fixes in 0.1.90
Install via Nuget:
Install-Package Examine -Version 1.0.1
Nothing published for this version
2 enhancements & 1 bug fixes addressing both stability and performance.
2 enhancements & 1 bug fixes addressing both stability and performance.
See milestone for full details: https://github.com/Shazwazza/Examine/milestone/26?closed=1
SelectFields methods for ensuring only the selected fields are returned in search results which saves allocations, see https://github.com/Shazwazza/Examine/pull/173NOTE: :These new features (among other things) need documentation. If you have any time to assist with documentation, the docs site is here and the code for it is in this repository.
Thanks to the community members: @nzdev for development and testing help.
Install via Nuget:
Install-Package Examine -Version 0.2.0
Nothing published for this version
Issue fixed that may prevent unhandled exceptions occurring, see milestone for details:
Issue fixed that may prevent unhandled exceptions occurring, see milestone for details:
https://github.com/Shazwazza/Examine/milestone/27
Install via Nuget:
Install-Package Examine -Version 0.1.92
Couple of issues fixed, these fixes may prevent unhandled exceptions occurring:
Couple of issues fixed, these fixes may prevent unhandled exceptions occurring:
Install via Nuget:
Install-Package Examine -Version 0.1.91
A few issues fixed, see milestone for full details: https://github.com/Shazwazza/Examine/milestone/19?closed=1
A few issues fixed, see milestone for full details: https://github.com/Shazwazza/Examine/milestone/19?closed=1
Install via Nuget:
Install-Package Examine -Version 0.1.90
Nothing published for this version
Nothing published for this version
A regression issue was found in the previous release so that has been reverted and code has been added to work around the proposed functionality with
A regression issue was found in the previous release so that has been reverted and code has been added to work around the proposed functionality with docs added to the issue in this milestone. If you require rewriting wildcard queries see https://github.com/Shazwazza/Examine/issues/90
https://github.com/Shazwazza/Examine/milestone/18?closed=1
Install via Nuget:
Install-Package Examine
Release containing one important bug fix for queries containing wildcards and improperly scoring the results (if sorting by Score). See milestone for
Release containing one important bug fix for queries containing wildcards and improperly scoring the results (if sorting by Score). See milestone for details:
https://github.com/Shazwazza/Examine/milestone/17?closed=1
Install via Nuget:
Install-Package Examine
This has been changed to v0.1.87 https://github.com/Shazwazza/Examine/releases/tag/v0.1.87
This has been changed to v0.1.87 https://github.com/Shazwazza/Examine/releases/tag/v0.1.87
Release containing one regression bug fix based on the 0.1.84 release (oops). Also check out the changes in 0.1.84 since you probably haven't upgraded
Release containing one regression bug fix based on the 0.1.84 release (oops). Also check out the changes in 0.1.84 since you probably haven't upgraded to that yet: https://github.com/Shazwazza/Examine/releases/tag/v0.1.84
Install via Nuget:
Install-Package Examine
see milestone for details:
https://github.com/Shazwazza/Examine/milestone/16?closed=1
Release containing one new feature request and some minor performance improvements for SearchResult, see milestone for details:
Release containing one new feature request and some minor performance improvements for SearchResult, see milestone for details:
https://github.com/Shazwazza/Examine/milestone/15?closed=1
Install via Nuget:
Install-Package Examine
See milestone for details: https://github.com/Shazwazza/Examine/milestone/14?closed=1
3 new enhancements
See milestone for details: https://github.com/Shazwazza/Examine/milestone/14?closed=1
Install via Nuget:
Install-Package Examine
Some bug fixes regarding SyncDirectory
Some bug fixes regarding SyncDirectory
See milestone for details: https://github.com/Shazwazza/Examine/milestone/13?closed=1
Install via Nuget:
Install-Package Examine
3 very important perf enhancements - these are small updates that have large perf implications
3 very important perf enhancements - these are small updates that have large perf implications
See milestone for details: https://github.com/Shazwazza/Examine/milestone/12?closed=1
Install via Nuget:
Install-Package Examine
See milestone for details: https://github.com/Shazwazza/Examine/milestone/11?closed=1
7 great enhancements!
See milestone for details: https://github.com/Shazwazza/Examine/milestone/11?closed=1
Install via Nuget:
Install-Package Examine
Nothing published for this version
Nothing published for this version
Nothing published for this version
Fixes 4 issues and adds 1 enhancement
Fixes 4 issues and adds 1 enhancement
See milestone for details: https://github.com/Shazwazza/Examine/milestone/10?closed=1
Install via Nuget:
Install-Package Examine
Fixes 6 issues and adds 6 features
Fixes 6 issues and adds 6 features
See milestone for details: https://github.com/Shazwazza/Examine/milestone/9?closed=1
Install via Nuget:
Install-Package Examine
Nothing published for this version
Nothing published for this version
Fixes a single issue with an unfortunate Stack Overflow issue from 0.1.67
Fixes a single issue with an unfortunate Stack Overflow issue from 0.1.67 (https://github.com/Shazwazza/Examine/releases/tag/v0.1.67)
See milestone for details: https://github.com/Shazwazza/Examine/issues?q=milestone%3Av0.1.68
Install via Nuget:
Install-Package Examine
Updates the logic for closing readers when searchers are finished with them. Updates logic for rebuilding indexes so that searchers can continue searc
Updates the logic for closing readers when searchers are finished with them. Updates logic for rebuilding indexes so that searchers can continue searching during this time.
Install via Nuget:
Install-Package Examine
One column per quarter.