diff --git a/changelog.md b/changelog.md index 46c0900..a93c5ab 100644 --- a/changelog.md +++ b/changelog.md @@ -1,5 +1,12 @@ # Changelog +## 2025-04-18 - 5.9.2 - fix(documentation) +Update search API documentation to replace deprecated searchWithLucene examples with the unified search(query) API and clarify its behavior. + +- Replaced 'searchWithLucene' examples with 'search(query)' in the README. +- Updated explanation to detail field-specific exact match, partial word regex search, multi-word literal matching, and handling of empty queries. +- Clarified guidelines for creating MongoDB text indexes on searchable fields for optimized search performance. + ## 2025-04-18 - 5.9.1 - fix(search) Refactor search tests to use unified search API and update text index type casting diff --git a/readme.md b/readme.md index 91b1d9c..dcb3a99 100644 --- a/readme.md +++ b/readme.md @@ -18,7 +18,7 @@ A powerful TypeScript-first MongoDB wrapper that provides advanced features for - **Enhanced Cursors**: Chainable, type-safe cursor API with memory efficient data processing - **Type Conversion**: Automatic handling of MongoDB types like ObjectId and Binary data - **Serialization Hooks**: Custom serialization and deserialization of document properties -- **Powerful Search Capabilities**: Lucene-like query syntax with field-specific search, advanced operators, and fallback mechanisms +- **Powerful Search Capabilities**: Unified `search(query)` API supporting field:value exact matches, multi-field regex searches, case-insensitive matching, and automatic escaping to prevent regex injection ## Requirements @@ -218,43 +218,31 @@ class Product extends SmartDataDbDoc { const searchableFields = getSearchableFields('Product'); // ['name', 'description', 'category'] // Basic search across all searchable fields -const iPhoneProducts = await Product.searchWithLucene('iPhone'); +const iphoneProducts = await Product.search('iPhone'); -// Field-specific search -const electronicsProducts = await Product.searchWithLucene('category:Electronics'); +// Field-specific exact match +const electronicsProducts = await Product.search('category:Electronics'); -// Search with wildcards -const macProducts = await Product.searchWithLucene('Mac*'); +// Partial word search (regex across all fields) +const laptopResults = await Product.search('laptop'); -// Search in specific fields with partial words -const laptopResults = await Product.searchWithLucene('description:laptop'); +// Multi-word literal search +const paperwhite = await Product.search('Kindle Paperwhite'); -// Search is case-insensitive -const results1 = await Product.searchWithLucene('electronics'); -const results2 = await Product.searchWithLucene('Electronics'); -// results1 and results2 will contain the same documents - -// Using boolean operators (requires text index in MongoDB) -const wirelessOrLaptop = await Product.searchWithLucene('wireless OR laptop'); - -// Negative searches -const electronicsNotSamsung = await Product.searchWithLucene('Electronics NOT Samsung'); - -// Phrase searches -const exactPhrase = await Product.searchWithLucene('"high-speed blender"'); - -// Grouping with parentheses -const complexQuery = await Product.searchWithLucene('(wireless OR bluetooth) AND Electronics'); +// Empty query returns all documents +const allProducts = await Product.search(''); ``` The search functionality includes: - `@searchable()` decorator for marking fields as searchable -- `getSearchableFields()` to retrieve all searchable fields for a class -- `search()` method for basic search (requires MongoDB text index) -- `searchWithLucene()` method with robust fallback mechanisms -- Support for field-specific searches, wildcards, and boolean operators -- Automatic fallback to regex-based search if MongoDB text search fails +- `getSearchableFields()` to list searchable fields for a model +- `search(query: string)` method supporting: + - Field-specific exact matches (`field:value`) + - Case-insensitive partial matches across all searchable fields + - Multi-word literal matching + - Empty queries returning all documents +- Automatic escaping of special characters to prevent regex injection ### EasyStore @@ -549,10 +537,10 @@ class Order extends SmartDataDbDoc { ### Search Optimization -- Create MongoDB text indexes for collections that need advanced search operations -- Use `searchWithLucene()` for robust searches with fallback mechanisms -- Prefer field-specific searches when possible for better performance -- Use simple term queries instead of boolean operators if you don't have text indexes +- (Optional) Create MongoDB text indexes on searchable fields to speed up full-text search +- Use `search(query)` for all search operations (field:value, partial matches, multi-word) +- Prefer field-specific exact matches when possible for optimal performance +- Avoid unnecessary complexity in query strings to keep regex searches efficient ### Performance Optimization diff --git a/ts/00_commitinfo_data.ts b/ts/00_commitinfo_data.ts index 4e1b060..a3856b4 100644 --- a/ts/00_commitinfo_data.ts +++ b/ts/00_commitinfo_data.ts @@ -3,6 +3,6 @@ */ export const commitinfo = { name: '@push.rocks/smartdata', - version: '5.9.1', + version: '5.9.2', description: 'An advanced library for NoSQL data organization and manipulation using TypeScript with support for MongoDB, data validation, collections, and custom data types.' }