Changelog
v0.7.0 - Breaking Change: Refresh Behavior Fixed
Released on: 2025-10-14
## ⚠️ BREAKING CHANGE
### Fixed Default Refresh Behavior
Previous versions (0.6.x) had a bug where all CRUD operations were implicitly using refresh=”wait_for” mode, which is not the ElasticSearch default behavior.
In version 0.7.0, this bug is fixed: - Default behavior is now refresh=False (no refresh), matching ElasticSearch default - Changes become visible after the index’s refresh_interval (default 1 second) - This provides significantly better performance for production workloads
Migration Guide:
If your code relied on the previous behavior (implicit wait_for), you need to explicitly add the parameter:
```python # Before (0.6.x - implicit wait_for): await user.save()
# After (0.7.0 - explicit if you need the old behavior): await user.save(wait_for=True) # or await user.save(refresh=”wait_for”) ```
For bulk operations: ```python # Before (0.6.x - implicit wait_for): async with ESBulk() as bulk:
await bulk.save(user)
# After (0.7.0 - explicit if you need the old behavior): async with ESBulk(wait_for=True) as bulk:
await bulk.save(user)
## Major Changes
### Refresh Parameter Support
This release introduces explicit refresh parameter for CRUD operations and bulk operations, providing better control over when changes become visible to search operations.
New Features: - Added refresh parameter to save() and delete() methods
refresh=True: Forces immediate refresh (use for testing or critical visibility needs)
refresh=”wait_for”: Waits for next scheduled refresh (ES API compatible)
Added refresh parameter to ESBulk context manager
Both wait_for=True (Pythonic) and refresh=”wait_for” (ES API compatible) are supported
refresh parameter takes priority if both refresh and wait_for are specified
Performance Considerations: - Default (no parameters): Best performance, changes visible after refresh_interval - `refresh=True`: Can impact performance under heavy load - `wait_for=True` or `refresh=”wait_for”`: Good balance between consistency and performance
Documentation: - Comprehensive README updates with refresh control examples - New test coverage for all refresh parameter scenarios
## Additional Improvements
Updated ElasticSearch test containers to latest versions (ES 8.18.8, ES 9.1.5)
Added connection logging to ElasticSearch connect method
Fixed host configuration in tests (localhost → 127.0.0.1)
Updated .gitignore with macOS (.DS_Store) and MCP files
Updated elasticsearch dependency constraint (<9.0.0 due to ping issues in 8.x)
Code formatting improvements (JSON and INI files)
## Full Changelog
Since v0.6.9: - Add refresh parameter to CRUD operations and bulk operations (BREAKING CHANGE) - Add subfields support with keyword shortcut for TextField - Enhanced aggregation support with new aggregation types - Added count method to ESModel for counting documents - Python 3.13 support confirmed
v0.6.12: Subfields support
Released on: 2025-05-26
## New Features
Subfields Support: Added comprehensive support for Elasticsearch subfields - New parameter for all Field functions to define custom subfields - Convenient shortcut for TextField to add keyword subfield - Supports all Elasticsearch field types (text, numeric, date, etc.)
## Breaking Changes
Removed deprecated parameter from all Field functions (non-functional in Pydantic v2)
## Bug Fixes
Changed parameter to in TextField for Pydantic v2 compatibility
## Documentation
Added comprehensive subfields documentation with examples
Updated type mapping documentation (str → keyword, not text)
## Tests
Added comprehensive test coverage for subfield functionality
v0.6.11
Released on: 2025-05-22
Enhanced aggregation support with new aggregation types
Implemented ESDateHistogramParams with full parameter support (calendar_interval, fixed_interval, format, time_zone, etc.)
Added 7 new aggregation types with TypeDict definitions:
- cardinality: Count distinct values with precision control - percentiles: Calculate value percentiles with configurable algorithms - stats: Basic statistics (count, min, max, avg, sum) - extended_stats: Extended statistics including variance and standard deviation - value_count: Count non-null values in a field - range: Numeric range bucketing - date_range: Date range bucketing with timezone support - Added corresponding response TypeDicts for all new aggregations - Updated ESAggsResponse union type to include all new response types
v0.6.10
Released on: 2025-05-20
Added count method to ESModel for counting documents in the index.
v0.6.9
Released on: 2025-05-15
Updated requeirements and tests to support elasticsearch 9.x.x versions
v0.6.8
Released on: 2025-05-03
Support newer Pydantic versions
dense_vector support
v0.6.7
Released on: 2024-11-23
You can now raise esorm.error.ConflictError to retry in retry_on_conflict decorated functions and methods. It is useful if you want to force retry by your logic not just with an ES conflict.
v0.6.6
Released on: 2024-11-21
Make Sort and Pagination wrapped classes serializable (by pickle)
v0.6.5
Released on: 2024-11-21
Fixed watcher naming
v0.6.4
Released on: 2024-11-20
Auto reload in retry_on_conflict if it decorates a model method
Fixed concurrency check in bulk operations, when _seq_no=0
v0.6.3
Released on: 2024-11-08
Float types no longer show Pydantic warnings on save
Fix index argument of Field
Added tests for ES fields
v0.6.2
Released on: 2024-11-06
Add support for 7.x elasticsearch lib
support Python 3.8 again
v0.6.1
Released on: 2024-10-03
The connect function accepts None in hosts argument. This solves #21.
v0.6.0
Released on: 2024-10-03
Field alias support: you can name a field other than the name in ES
IP addresses (IPvAddressAny) support
Enum field support
v0.5.2
Released on: 2024-08-02
Fixed: list of ES primitives now works
v0.5.1
Released on: 2024-08-02
Support list of primitives
Updated documentation
Added tests
v0.5.0
Released on: 2024-07-31
Improvements
Support for UUID, Path and pydantic_core.Url types
Fixed conversion of basic python types
time is now actually stored as date in the format of 1970-01-01 + time
Improved documentation
More tests
Minor optimizations
Fixes
v0.4.8
Released on: 2024-07-26
Added support for unsigned_long ES field type
Support for newer (Python >= 3.10) union syntax e.g.: int | None
Pydantic’s Annotated type is also supported
v0.4.7
Released on: 2024-06-18
Added index argument to other class methods
v0.4.6
Released on: 2024-06-17
It is possible to add index name as an argument, it is useful, when you use class methods
v0.4.5
Released on: 2024-05-22
Support for typing.Literal
v0.4.4
Released on: 2024-05-18
Fixed index template
The default prefix now really “esorm_”
No more fixed “-” prefix separator
Now it works as it is in the documentation
Replaced the deprecated method for creating index templates in newer ESs
Test for index templates
Improved tests
v0.4.3
Released on: 2024-05-07
Fix: get method is static method, so it is not compatible with model’s __routing__
v0.4.2
Released on: 2024-05-07
Fixed get method when id field is an integer.
Test for integer ids
Test for property ids
v0.4.1
Released on: 2024-05-07
Retry on conflict decorator to automatically retry conflicted operations
Simplified ESModelTimestamp save. The logic is simple now: created_at is filled only if it is a new model instance (created_at is None).
v0.4.0
Released on: 2024-05-07
Support for Optimistic Concurrency Check (OCC)
It uses _primary_term and _seq_no for save operations to ensure consistency
The ES private fields are accessible through the model (_version, _primary_term, _seq_no)
_id and private fields are stored after save
Bulk operations uses OCC too
Bulk operations raise BulkError, which stores all documents which had errors
New documents of ESModelTimestamp with bulk operations will have created_at filled automatically
Reload documents
Fixed routing for delete operation
Improved documentation
v0.3.2
Released on: 2024-05-03
Lazy properties are now work with ESBaseModel too
Lazy properties are now supports nested documents (truly recursive)
Python 3.8 support back
v0.3.1
Released on: 2024-04-29
The most important change is to introduce ESBaseModel.
Full Changelog: https://github.com/wallneradam/esorm/compare/v0.3.0…v0.3.1
v0.3.0
Released on: 2024-01-25
Replaced deprecated datetime.utcnow
.all() method for getting all documents in an index
Reworked lazy properties, which has recursion protection
Improved documentation: - pagination and sorting - added advanced.md, which contains advanced features documentation - Fixed dark mode colors of reference
Improved unit tests
v0.2.1
Released on: 2024-01-22
Aggregation TypeDicts are refactored.