diff --git a/reference/operator/evaluation-query/expr.yml b/reference/operator/evaluation-query/expr.yml new file mode 100644 index 0000000..4b6d7a8 --- /dev/null +++ b/reference/operator/evaluation-query/expr.yml @@ -0,0 +1,228 @@ +type: operator +category: evaluation-query +name: $expr +description: |- + The $expr operator allows the use of aggregation expressions within the query language, enabling complex field comparisons and calculations. +summary: |- + The `$expr` operator allows the use of aggregation expressions within the query language, which enables us to compare fields from the same document, perform calculations, and use aggregation operators in find operations. The `$expr` operator is useful for complex field comparisons that can't be achieved with traditional query operators. +syntax: |- + { + $expr: { } + } +parameters: +- name: + required: true + description: |- + Any valid aggregation expression that evaluates to a boolean value. The expression includes field comparisons, arithmetic operations, conditional expressions, and other aggregation operators. +examples: + sample: >- + { + "_id": "0fcc0bf0-ed18-4ab8-b558-9848e18058f4", + "name": "First Up Consultants | Beverage Shop - Satterfieldmouth", + "location": { + "lat": -89.2384, + "lon": -46.4012 + }, + "staff": { + "totalStaff": { + "fullTime": 8, + "partTime": 20 + } + }, + "sales": { + "totalSales": 75670, + "salesByCategory": [ + { + "categoryName": "Wine Accessories", + "totalSales": 34440 + }, + { + "categoryName": "Bitters", + "totalSales": 39496 + }, + { + "categoryName": "Rum", + "totalSales": 1734 + } + ] + }, + "promotionEvents": [ + { + "eventName": "Unbeatable Bargain Bash", + "promotionalDates": { + "startDate": { + "Year": 2024, + "Month": 6, + "Day": 23 + }, + "endDate": { + "Year": 2024, + "Month": 7, + "Day": 2 + } + }, + "discounts": [ + { + "categoryName": "Whiskey", + "discountPercentage": 7 + }, + { + "categoryName": "Bitters", + "discountPercentage": 15 + }, + { + "categoryName": "Brandy", + "discountPercentage": 8 + }, + { + "categoryName": "Sports Drinks", + "discountPercentage": 22 + }, + { + "categoryName": "Vodka", + "discountPercentage": 19 + } + ] + }, + { + "eventName": "Steal of a Deal Days", + "promotionalDates": { + "startDate": { + "Year": 2024, + "Month": 9, + "Day": 21 + }, + "endDate": { + "Year": 2024, + "Month": 9, + "Day": 29 + } + }, + "discounts": [ + { + "categoryName": "Organic Wine", + "discountPercentage": 19 + }, + { + "categoryName": "White Wine", + "discountPercentage": 20 + }, + { + "categoryName": "Sparkling Wine", + "discountPercentage": 19 + }, + { + "categoryName": "Whiskey", + "discountPercentage": 17 + }, + { + "categoryName": "Vodka", + "discountPercentage": 23 + } + ] + } + ] + } + items: + - title: Compare full-time and part-time staff + description: |- + The example retrieves stores with the number of part-time employees greater than full-time employees. + query: |- + db.stores.find({_id: "40d6f4d7-50cd-4929-9a07-0a7a133c2e74", + $expr: { + $gt: ["$staff.employeeCount.partTime", "$staff.employeeCount.fullTime"] + } + }) + output: + value: |- + { + "_id": "40d6f4d7-50cd-4929-9a07-0a7a133c2e74", + "name": "Proseware, Inc. | Home Entertainment Hub - East Linwoodbury", + "location": { + "lat": 70.1272, + "lon": 69.7296 + }, + "staff": { + "contractorCount": 5, + "employeeCount": { "fullTime": 19, "partTime": 20 } + }, + "sales": { + "totalSales": 151864, + "salesByCategory": [ + { + "categoryName": "Sound Bars", + "totalSales": 2120 + }, + { + "categoryName": "Home Theater Projectors", + "totalSales": 45004 + } + }, + "storeOpeningDate": ISODate("2024-09-23T13:45:01.480Z"), + "lastUpdated": ISODate("2025-06-11T11:06:57.922Z"), + "status": "active", + "category": "high-volume", + "priority": 1, + "reviewDate": ISODate("2025-06-11T11:10:50.276Z") + } + ] + - title: Conditional logic with store location + description: |- + The example demonstrates the conditional logic usage with `$expr` pulling stores in the southern hemisphere where the staff efficiency ratio (sales per employee) exceeds 2000. + query: |- + db.stores.find({_id: "40d6f4d7-50cd-4929-9a07-0a7a133c2e74", + $expr: { + $and: [ + { $gte: ["$location.lat", 70.1272] }, + { + $gt: [ + { + $divide: [ + "$sales.totalSales", + { $add: ["$staff.employeeCount.fullTime", "$staff.employeeCount.partTime"] } + ] + }, + 2000 + ] + } + ] + } + }).limit(1) + output: + value: |- + [ + { + "_id": "40d6f4d7-50cd-4929-9a07-0a7a133c2e74", + "name": "Proseware, Inc. | Home Entertainment Hub - East Linwoodbury", + "location": { + "lat": 70.1272, + "lon": 69.7296 + }, + "staff": { + "totalStaff": { + "fullTime": 19, + "partTime": 20 + } + }, + "sales": { + "totalSales": 151864, + "salesByCategory": [ + { + "categoryName": "Sound Bars", + "totalSales": 2120 + }, + { + "categoryName": "Home Theater Projectors", + "totalSales": 45004 + } + ] + }, + "storeOpeningDate": ISODate("2024-09-23T13:45:01.480Z"), + "lastUpdated": ISODate("2025-06-11T11:06:57.922Z"), + "status": "active", + "category": "high-volume", + "priority": 1, + "reviewDate": ISODate("2025-06-11T11:10:50.276Z") + } + ] +related: [] diff --git a/reference/operator/evaluation-query/jsonschema.yml b/reference/operator/evaluation-query/jsonschema.yml new file mode 100644 index 0000000..403ae11 --- /dev/null +++ b/reference/operator/evaluation-query/jsonschema.yml @@ -0,0 +1,228 @@ +type: operator +category: evaluation-query +name: $jsonSchema +description: |- + The $jsonSchema operator validates documents against a JSON Schema definition for data validation and structure enforcement. Discover supported features and limitations. +summary: |- + The `$jsonSchema` operator is used to validate documents against a JSON Schema specification. It ensures that documents conform to a predefined structure, data types, and validation rules. +syntax: |- + db.createCollection("collectionName", { + validator: { + $jsonSchema: { + bsonType: "object", + required: ["field1", "field2"], + properties: { + field1: { + bsonType: "string", + description: "Description of field1 requirements" + }, + field2: { + bsonType: "int", + minimum: 0, + description: "Description of field2 requirements" + } + } + } + }, + validationLevel: "strict", // Optional: "strict" or "moderate" + validationAction: "error" // Optional: "error" or "warn" + }) +parameters: +- name: bsonType + required: true + description: |- + Specifies the Binary JSON (BSON) types that the field must match. Accepts string aliases used by the $type operator. +- name: properties + required: true + description: |- + Object defining validation rules for specific fields. +- name: minimum/maximum + required: true + description: |- + Numeric constraints for number fields. +- name: minLength/maxLength + required: true + description: |- + String length constraints. +- name: minItems/maxItems + required: true + description: |- + Array length constraints. +- name: pattern + required: true + description: |- + Regular expression pattern for string validation. +- name: items + required: true + description: |- + Schema validation for array elements. +- name: uniqueItems + required: true + description: |- + Boolean indicating if array items must be unique. +examples: + sample: >- + { + "_id": "2cf3f885-9962-4b67-a172-aa9039e9ae2f", + "name": "First Up Consultants | Bed and Bath Center - South Amir", + "location": { + "lat": 60.7954, + "lon": -142.0012 + }, + "staff": { + "totalStaff": { + "fullTime": 18, + "partTime": 17 + } + }, + "sales": { + "totalSales": 37701, + "salesByCategory": [ + { + "categoryName": "Mattress Toppers", + "totalSales": 37701 + } + ] + } + } + items: + - title: Basic Structure Validation + description: |- + This query retrieves all stores with names between 5 and 100 characters long, and that geographic coordinates fall within valid ranges: latitude between -90 and 90, and longitude between -180 and 180. + query: |- + db.stores.find({ + $jsonSchema: { + bsonType: "object", + properties: { + _id: { + bsonType: "string" + }, + name: { + bsonType: "string", + minLength: 5, + maxLength: 100 + }, + location: { + bsonType: "object", + properties: { + lat: { + bsonType: "double", + minimum: -90, + maximum: 90 + }, + lon: { + bsonType: "double", + minimum: -180, + maximum: 180 + } + } + } + } + } + }).limit(1) + - title: Sales Validation with Array Items + description: |- + This query retrieves all store documents where the sales field is a valid object containing a non-negative totalSales value and a salesByCategory array with at least one item. + query: |- + db.stores.find({ + $jsonSchema: { + bsonType: "object", + properties: { + sales: { + bsonType: "object", + properties: { + totalSales: { + bsonType: "int", + minimum: 0 + }, + salesByCategory: { + bsonType: "array", + minItems: 1, + items: { + bsonType: "object", + properties: { + categoryName: { + bsonType: "string", + minLength: 1 + }, + totalSales: { + bsonType: "int", + minimum: 0 + } + } + } + } + } + } + } + } + }).limit(1) + output: + value: |- + [ + { + _id: 'new-store-001', + name: 'Adatum Corporation - Downtown Branch', + sales: { totalSales: 5000 }, + createdDate: ISODate('2025-06-11T11:11:32.262Z'), + status: 'new', + staff: { totalStaff: { fullTime: 0, partTime: 0 } }, + version: 1, + storeOpeningDate: ISODate('2025-06-11T11:11:32.262Z'), + storeFeatures: 213 + } + ] + - title: Combining with Query Operators + description: |- + This query retrieves all store documents where the staff field is a valid object that includes a totalStaff subobject with at least one full-time staff member (fullTime ≥ 1) and sales.totalSales greater than 10,000. + query: |- + db.stores.find({ + $and: [ + { + $jsonSchema: { + properties: { + staff: { + bsonType: "object", + properties: { + totalStaff: { + bsonType: "object", + properties: { + fullTime: { + bsonType: "int", + minimum: 1 + } + } + } + } + } + } + } + }, + // Additional query constraints + { + "sales.totalSales": { $gt: 10000 } + } + ] + }).limit(1) + output: + value: |- + [ + { + _id: 'future-electronics-001', + address: { city: 'New Tech City' }, + name: 'Boulder Innovations - Future Electronics Hub', + sales: { totalSales: 25000 }, + establishedDate: ISODate('2025-06-11T11:14:23.147Z'), + categories: [ 'electronics', 'gadgets', 'smart-home' ], + promotionEvents: [], + ratings: { average: 0, count: 0, reviews: [] }, + inventory: { + lastUpdated: ISODate('2025-06-11T11:14:23.147Z'), + totalItems: 0, + lowStockAlerts: [] + }, + storeOpeningDate: ISODate('2025-06-11T11:11:32.262Z'), + storeFeatures: 120 + } + ] +related: [] diff --git a/reference/operator/evaluation-query/mod.yml b/reference/operator/evaluation-query/mod.yml new file mode 100644 index 0000000..8943379 --- /dev/null +++ b/reference/operator/evaluation-query/mod.yml @@ -0,0 +1,257 @@ +type: operator +category: evaluation-query +name: $mod +description: |- + The $mod operator performs a modulo operation on the value of a field and selects documents with a specified result. +summary: |- + The `$mod` operator performs a modulo operation on the value of a field and selects documents with a specified result. This operator is useful for finding documents where a numeric field value, when divided by a divisor, leaves a specific remainder. It commonly serves for pagination, sampling data, or finding patterns in numeric sequences. +syntax: |- + { + : { $mod: [ , ] } + } +parameters: +- name: + required: true + description: |- + The field to perform the modulo operation on. The field must contain numeric values. +- name: + required: true + description: |- + The number to divide the field value by. Must be a positive number. +- name: + required: true + description: |- + The expected remainder after the modulo operation. Must be a non-negative number less than the divisor. +examples: + sample: >- + { + "_id": "0fcc0bf0-ed18-4ab8-b558-9848e18058f4", + "name": "First Up Consultants | Beverage Shop - Satterfieldmouth", + "location": { + "lat": -89.2384, + "lon": -46.4012 + }, + "staff": { + "totalStaff": { + "fullTime": 8, + "partTime": 20 + } + }, + "sales": { + "totalSales": 75670, + "salesByCategory": [ + { + "categoryName": "Wine Accessories", + "totalSales": 34440 + }, + { + "categoryName": "Bitters", + "totalSales": 39496 + }, + { + "categoryName": "Rum", + "totalSales": 1734 + } + ] + }, + "promotionEvents": [ + { + "eventName": "Unbeatable Bargain Bash", + "promotionalDates": { + "startDate": { + "Year": 2024, + "Month": 6, + "Day": 23 + }, + "endDate": { + "Year": 2024, + "Month": 7, + "Day": 2 + } + }, + "discounts": [ + { + "categoryName": "Whiskey", + "discountPercentage": 7 + }, + { + "categoryName": "Bitters", + "discountPercentage": 15 + }, + { + "categoryName": "Brandy", + "discountPercentage": 8 + }, + { + "categoryName": "Sports Drinks", + "discountPercentage": 22 + }, + { + "categoryName": "Vodka", + "discountPercentage": 19 + } + ] + }, + { + "eventName": "Steal of a Deal Days", + "promotionalDates": { + "startDate": { + "Year": 2024, + "Month": 9, + "Day": 21 + }, + "endDate": { + "Year": 2024, + "Month": 9, + "Day": 29 + } + }, + "discounts": [ + { + "categoryName": "Organic Wine", + "discountPercentage": 19 + }, + { + "categoryName": "White Wine", + "discountPercentage": 20 + }, + { + "categoryName": "Sparkling Wine", + "discountPercentage": 19 + }, + { + "categoryName": "Whiskey", + "discountPercentage": 17 + }, + { + "categoryName": "Vodka", + "discountPercentage": 23 + } + ] + } + ] + } + items: + - title: Find stores with sales divisible by 1000 + description: |- + This query retrieves stores where the total sales are divisible by 1000 (useful for identifying round sales figures). + query: |- + db.stores.find({ + "sales.totalSales": { $mod: [1000, 0] } + }).limit(2) + output: + value: |- + [ + { + "_id": "new-store-001", + "name": "TechWorld Electronics - Downtown Branch", + "sales": { + "totalSales": 5000 + }, + "createdDate": "2025-06-11T11:11:32.262Z", + "status": "new", + "staff": { + "totalStaff": { + "fullTime": 0, + "partTime": 0 + } + }, + "version": 1 + }, + { + "_id": "gaming-store-mall-001", + "name": "Gaming Paradise - Mall Location", + "location": { + "lat": 35.6762, + "lon": 139.6503 + }, + "createdDate": "2025-06-11T11:13:27.180Z", + "status": "active", + "staff": { + "totalStaff": { + "fullTime": 8, + "partTime": 12 + }, + "manager": "Alex Johnson", + "departments": [ + "gaming", + "accessories", + "repairs" + ] + }, + "sales": { + "totalSales": 0, + "salesByCategory": [] + }, + "operatingHours": { + "weekdays": "10:00-22:00", + "weekends": "09:00-23:00" + }, + "metadata": { + "version": 1, + "source": "store-management-system" + } + } + ] + - title: Pagination-style querying + description: |- + This query retrieves stores where the part-time employee count leaves a remainder of 0 when divided by 4 (useful for creating data subsets). + query: |- + db.stores.find({ + "staff.totalStaff.partTime": { $mod: [4, 0] } + }) + output: + value: |- + [ + { + "_id": "new-store-001", + "name": "TechWorld Electronics - Downtown Branch", + "sales": { + "totalSales": 5000 + }, + "createdDate": "2025-06-11T11:11:32.262Z", + "status": "new", + "staff": { + "totalStaff": { + "fullTime": 0, + "partTime": 0 + } + }, + "version": 1 + }, + { + "_id": "gaming-store-mall-001", + "name": "Gaming Paradise - Mall Location", + "location": { + "lat": 35.6762, + "lon": 139.6503 + }, + "createdDate": "2025-06-11T11:13:27.180Z", + "status": "active", + "staff": { + "totalStaff": { + "fullTime": 8, + "partTime": 12 + }, + "manager": "Alex Johnson", + "departments": [ + "gaming", + "accessories", + "repairs" + ] + }, + "sales": { + "totalSales": 0, + "salesByCategory": [] + }, + "operatingHours": { + "weekdays": "10:00-22:00", + "weekends": "09:00-23:00" + }, + "metadata": { + "version": 1, + "source": "store-management-system" + } + } + ] +related: [] diff --git a/reference/operator/evaluation-query/regex.yml b/reference/operator/evaluation-query/regex.yml index 262febf..c2394e6 100644 --- a/reference/operator/evaluation-query/regex.yml +++ b/reference/operator/evaluation-query/regex.yml @@ -2,115 +2,288 @@ type: operator category: evaluation-query name: $regex description: |- - The `$regex` operator is used to perform pattern matching with regular expressions. + The $regex operator provides regular expression capabilities for pattern matching in queries, allowing flexible string matching and searching. summary: |- - This operator is useful for querying string fields for matches that fit specific patterns. Common use cases include searching for documents where a field contains a substring, starts with a certain prefix, or matches a complex pattern. + The `$regex` operator provides regular expression capabilities for pattern matching in queries. It allows you to search for documents where a field matches a specified regular expression pattern. This operator is useful for flexible string searching, pattern validation, and complex text filtering operations. syntax: |- { - "field": { - $regex: /pattern/, - $options: '' - } + : { $regex: , $options: } } parameters: - - name: field - type: string - required: true - description: |- - The field in the document to apply the regular expression to. This should be a string field that you want to match against the provided pattern. - - name: $regex - type: pattern - required: true - description: |- - The regular expression pattern to match. - - name: $options - type: string - required: false - description: |- - Flags to modify the behavior of the regex. Common options include, but are not limited to `i` for case-insensitive matching, `m` for multiline matching, etc. +- name: + required: true + description: |- + The field to search in. Must contain string values. +- name: + required: true + description: |- + The regular expression pattern to match against. +- name: + required: false + description: |- + Optional. Regular expression options such as case-insensitive matching. Common options include 'i' (case insensitive), 'm' (multiline), 's' (dot all), and 'x' (extended). examples: - sample: |- - [ - { - "_id": "00000000-0000-0000-0000-000000003001", - "name": "Proseware, Inc. | Home Entertainment Hub - East Linwoodbury", - "promotionEvents": [ + sample: >- + { + "_id": "39acb3aa-f350-41cb-9279-9e34c004415a", + "name": "First Up Consultants | Bed and Bath Pantry - Port Antone", + "location": { + "lat": 87.2239, + "lon": -129.0506 + }, + "staff": { + "employeeCount": { + "fullTime": 8, + "partTime": 7 + } + }, + "sales": { + "salesByCategory": [ + { "categoryName": "Towel Sets", "totalSales": 520 }, + { "categoryName": "Bath Accessories", "totalSales": 41710 }, + { "categoryName": "Drapes", "totalSales": 42893 }, + { "categoryName": "Towel Racks", "totalSales": 30773 }, + { "categoryName": "Hybrid Mattresses", "totalSales": 39491 }, + { "categoryName": "Innerspring Mattresses", "totalSales": 6410 }, + { "categoryName": "Bed Frames", "totalSales": 41917 }, + { "categoryName": "Mattress Protectors", "totalSales": 44124 }, + { "categoryName": "Bath Towels", "totalSales": 5671 }, + { "categoryName": "Turkish Towels", "totalSales": 25674 } + ], + "revenue": 279183 + }, + "promotionEvents": [ + { + "eventName": "Discount Derby", + "promotionalDates": { + "startDate": { "Year": 2023, "Month": 12, "Day": 26 }, + "endDate": { "Year": 2024, "Month": 1, "Day": 5 } + }, + "discounts": [ + { "categoryName": "Microfiber Towels", "discountPercentage": 6 }, + { "categoryName": "Bath Sheets", "discountPercentage": 16 }, + { "categoryName": "Towels", "discountPercentage": 10 }, + { "categoryName": "Hand Towels", "discountPercentage": 11 }, + { "categoryName": "Kitchen Towels", "discountPercentage": 21 }, + { "categoryName": "Placemat", "discountPercentage": 11 }, + { "categoryName": "Bath Accessories", "discountPercentage": 11 }, + { "categoryName": "Bedspreads", "discountPercentage": 21 }, + { "categoryName": "Shower Curtains", "discountPercentage": 24 }, + { "categoryName": "Pillow Top Mattresses", "discountPercentage": 10 } + ] + }, + { + "eventName": "Big Bargain Blitz", + "promotionalDates": { + "startDate": { "Year": 2024, "Month": 3, "Day": 25 }, + "endDate": { "Year": 2024, "Month": 4, "Day": 3 } + }, + "discounts": [ + { "categoryName": "Mattress Toppers", "discountPercentage": 24 }, + { "categoryName": "Pillow Cases", "discountPercentage": 14 }, + { "categoryName": "Soap Dispensers", "discountPercentage": 20 }, + { "categoryName": "Beach Towels", "discountPercentage": 18 }, + { "categoryName": "Bath Mats", "discountPercentage": 22 }, + { "categoryName": "Blankets", "discountPercentage": 12 }, + { "categoryName": "Kitchen Towels", "discountPercentage": 8 }, + { "categoryName": "Memory Foam Mattresses", "discountPercentage": 14 }, + { "categoryName": "Placemat", "discountPercentage": 17 }, + { "categoryName": "Bed Frames", "discountPercentage": 23 } + ] + }, + { + "eventName": "Massive Markdown Mania", + "promotionalDates": { + "startDate": { "Year": 2024, "Month": 6, "Day": 23 }, + "endDate": { "Year": 2024, "Month": 6, "Day": 30 } + }, + "discounts": [ + { "categoryName": "Bed Skirts", "discountPercentage": 17 }, + { "categoryName": "Shower Curtains", "discountPercentage": 23 }, + { "categoryName": "Bath Towels", "discountPercentage": 21 }, + { "categoryName": "Memory Foam Mattresses", "discountPercentage": 11 }, + { "categoryName": "Bathrobes", "discountPercentage": 19 }, + { "categoryName": "Bath Accessories", "discountPercentage": 5 }, + { "categoryName": "Box Springs", "discountPercentage": 21 }, + { "categoryName": "Hand Towels", "discountPercentage": 13 }, + { "categoryName": "Tablecloths", "discountPercentage": 19 }, + { "categoryName": "Duvet Covers", "discountPercentage": 23 } + ] + }, + { + "eventName": "Unbeatable Bargain Bash", + "promotionalDates": { + "startDate": { "Year": 2024, "Month": 9, "Day": 21 }, + "endDate": { "Year": 2024, "Month": 9, "Day": 30 } + }, + "discounts": [ + { "categoryName": "Adjustable Beds", "discountPercentage": 19 }, + { "categoryName": "Mattress Toppers", "discountPercentage": 23 }, + { "categoryName": "Washcloths", "discountPercentage": 7 }, + { "categoryName": "Comforters", "discountPercentage": 24 }, + { "categoryName": "Kitchen Towels", "discountPercentage": 7 }, + { "categoryName": "Pillows", "discountPercentage": 13 }, + { "categoryName": "Bath Sheets", "discountPercentage": 25 }, + { "categoryName": "Napkins", "discountPercentage": 25 }, + { "categoryName": "Bath Towels", "discountPercentage": 15 }, + { "categoryName": "Beach Towels", "discountPercentage": 15 } + ] + } + ], + "company": "First Up Consultants", + "city": "Port Antone", + "storeOpeningDate": { "$date": "2024-09-19T17:31:59.665Z" }, + "lastUpdated": { "$timestamp": { "t": 1729359119, "i": 1 } } + } + items: + - title: Find stores by name pattern + description: |- + This query retrieves all the stores containing "Consultants" in their name (case-insensitive). + query: |- + db.stores.find( + { name: { $regex: "Consultants", $options: "i" } }, + { _id: 1, name: 1, storeOpeningDate: 1 } + ).limit(3) + output: + value: |- + [ { - "eventName": "Unbeatable Bargain Bash" + "_id": "39acb3aa-f350-41cb-9279-9e34c004415a", + "name": "First Up Consultants | Bed and Bath Pantry - Port Antone", + "storeOpeningDate": "2024-09-19T17:31:59.665Z" }, { - "eventName": "Steal of a Deal Days" + "_id": "26afb024-53c7-4e94-988c-5eede72277d5", + "name": "First Up Consultants | Microphone Bazaar - South Lexusland", + "storeOpeningDate": "2024-09-10T13:43:51.209Z" + }, + { + "_id": "62438f5f-0c56-4a21-8c6c-6bfa479494ad", + "name": "First Up Consultants | Plumbing Supply Shoppe - New Ubaldofort", + "storeOpeningDate": "2024-09-19T08:27:44.268Z" } ] - }, - { - "_id": "00000000-0000-0000-0000-000000003002", - "name": "Fabrikam, Inc. | Home Accessory Outlet - West Adele", - "promotionEvents": [ + - title: Advanced pattern matching for category names + description: |- + This query retrieves stores selling products with a category name that starts with a vowel. + query: |- + db.stores.find( + { + "sales.salesByCategory.categoryName": { $regex: "^[AEIOUaeiou]" } + }, + { _id: 1, name: 1, "sales.salesByCategory.categoryName": 1 } + ).limit(2) + output: + value: |- + [ { - "eventName": "Incredible Discount Days" + "_id": "e6410bb3-843d-4fa6-8c70-7472925f6d0a", + "name": "Relecloud | Toy Collection - North Jaylan", + "sales": { + "salesByCategory": [ + { "categoryName": "Educational Toys" } + ] + } }, { - "eventName": "Steal of a Deal Days" + "_id": "4e064f0a-7e30-4701-9a80-eff3caf46ce8", + "name": "Fourth Coffee | Outdoor Furniture Deals - Lucianohaven", + "sales": { + "salesByCategory": [ + { "categoryName": "Outdoor Swings" }, + { "categoryName": "Hammocks" } + ] + } } - ], - "location": { - "lat": -89.2384, - "lon": -46.4012 - } - }, - { - "_id": "00000000-0000-0000-0000-000000003003", - "name": "Wide World Importers | Fitness Equipment Outlet - Reillyborough", - "promotionEvents": [ + ] + - title: Find stores with specific naming conventions + description: |- + This query retrieves stores with names containing a pipe character (|) separator. + query: |- + db.stores.find( + { name: { $regex: "\\|" }}, + { _id: 1, name: 1, "sales.salesByCategory.categoryName": 1}).limit(2) + output: + value: |- + [ { - "eventName": "Incredible Discount Days" - } - ], - "location": { - "lat": -2.4111, - "lon": 72.1041 - } - } - ] - items: - - title: Find documents with a specific substring - explanation: |- - Use the `$regex` operator to find all documents that match a specific pattern. - description: |- - In this example, the operator filters to documents that contain the exact phrase `Home` in its name. - query: |- - db.stores.find({ "name": { "$regex": /Home/ }}, { name: 1 }) - output: - value: |- - [ - { - _id: '00000000-0000-0000-0000-000000003001', - name: 'Proseware, Inc. | Home Entertainment Hub - East Linwoodbury' - }, - { - _id: '00000000-0000-0000-0000-000000003002', - name: 'Fabrikam, Inc. | Home Accessory Outlet - West Adele' + "_id": "905d1939-e03a-413e-a9c4-221f74055aac", + "name": "Trey Research | Home Office Depot - Lake Freeda", + "sales": { + "salesByCategory": [ + { "categoryName": "Desk Lamps" } + ] } - ] - - title: Find documents using a case-insensitive match - explanation: |- - The `$regex` operator includes options like case-insensitive search. - description: |- - In this example, the operator filters to documents that contain the case-insensitive phrase `outlet` in its name. - query: |- - db.stores.find({ "name": { $regex: /outlet/, $options: "i" }}, { name: 1 }) - output: - value: |- - [ - { - _id: '00000000-0000-0000-0000-000000003002', - name: 'Fabrikam, Inc. | Home Accessory Outlet - West Adele' - }, - { - _id: '00000000-0000-0000-0000-000000003003', - name: 'Wide World Importers | Fitness Equipment Outlet - Reillyborough' + }, + { + "_id": "a715ab0f-4c6e-4e9d-a812-f2fab11ce0b6", + "name": "Lakeshore Retail | Holiday Supply Hub - Marvinfort", + "sales": { + "salesByCategory": [ + { "categoryName": "Stockings" } + ] } - ] -related: - - reference: /command/aggregation/count + } + ] + - title: Complex pattern for discount categories + description: |- + This query retrieves stores with categories containing both "Bath" and ending with "s". + query: |- + db.stores.aggregate([ + { $match: { "promotionEvents.discounts.categoryName": { $regex: "Bath.*s$", $options: "i" } } }, + { $project: { "_id": 1, "name": 1, "promotionEvents.discounts.categoryName":1 }}, + { $match: {"promotionEvents.discounts.categoryName": { $ne: [] }} }, + { $limit: 2 }]) + output: + value: |- + [ + { + "_id": "39acb3aa-f350-41cb-9279-9e34c004415a", + "name": "First Up Consultants | Bed and Bath Pantry - Port Antone", + "promotionEvents": [ + { + "discounts": [ + { "categoryName": "Bath Sheets", "discountPercentage": 16 }, + { "categoryName": "Bath Accessories", "discountPercentage": 11 } + ] + }, + { + "discounts": [ + { "categoryName": "Bath Mats", "discountPercentage": 22 } + ] + }, + { + "discounts": [ + { "categoryName": "Bath Towels", "discountPercentage": 21 }, + { "categoryName": "Bathrobes", "discountPercentage": 19 }, + { "categoryName": "Bath Accessories", "discountPercentage": 5 } + ] + }, + { + "discounts": [ + { "categoryName": "Bath Sheets", "discountPercentage": 25 }, + { "categoryName": "Bath Towels", "discountPercentage": 15 } + ] + } + ] + }, + { + "_id": "27ef6004-70fa-4217-8395-0eabc4cc9841", + "name": "Fabrikam, Inc. | Bed and Bath Store - O'Connerborough", + "promotionEvents": [ + { + "discounts": [ + { "categoryName": "Bath Accessories", "discountPercentage": 24 } + ] + }, + { + "discounts": [ + { "categoryName": "Bathrobes", "discountPercentage": 18 }, + { "categoryName": "Bath Towels", "discountPercentage": 14 }, + { "categoryName": "Bath Accessories", "discountPercentage": 20 } + ] + } + ] + } + ] +related: [] diff --git a/reference/operator/evaluation-query/text.yml b/reference/operator/evaluation-query/text.yml new file mode 100644 index 0000000..fffd3f2 --- /dev/null +++ b/reference/operator/evaluation-query/text.yml @@ -0,0 +1,482 @@ +type: operator +category: evaluation-query +name: $text +description: |- + The $text operator performs text search on the content of indexed string fields, enabling full-text search capabilities. +summary: |- + The `$text` operator performs text search on the content of indexed string fields. It enables full-text search capabilities by searching for specified words or phrases across text-indexed fields. The `$text` operator requires at least one text index on the collection and provides features like stemming, stop word removal, and relevance scoring. +syntax: |- + { + $text: { + $search: , + $language: , + $caseSensitive: , + $diacriticSensitive: + } + } +parameters: +- name: $search + required: true + description: |- + Required. The search string containing the terms to search for. Multiple terms are treated as an OR operation unless enclosed in quotes for phrase matching. +- name: $language + required: false + description: |- + Optional. Language for the text search, which determines the stemming rules and stop words, though the system uses the index's default language if you don't specify one +- name: $caseSensitive + required: false + description: |- + Optional. Boolean flag to enable case-sensitive search. Default is false (case-insensitive). +- name: $diacriticSensitive + required: false + description: |- + Optional. Boolean flag to enable diacritic-sensitive search. Default is false (diacritic-insensitive). +examples: + sample: >- + { + "_id": "39acb3aa-f350-41cb-9279-9e34c004415a", + "name": "First Up Consultants | Bed and Bath Pantry - Port Antone", + "location": { + "lat": 87.2239, + "lon": -129.0506 + }, + "staff": { + "employeeCount": { + "fullTime": 8, + "partTime": 7 + } + }, + "sales": { + "salesByCategory": [ + { "categoryName": "Towel Sets", "totalSales": 520 }, + { "categoryName": "Bath Accessories", "totalSales": 41710 }, + { "categoryName": "Drapes", "totalSales": 42893 }, + { "categoryName": "Towel Racks", "totalSales": 30773 }, + { "categoryName": "Hybrid Mattresses", "totalSales": 39491 }, + { "categoryName": "Innerspring Mattresses", "totalSales": 6410 }, + { "categoryName": "Bed Frames", "totalSales": 41917 }, + { "categoryName": "Mattress Protectors", "totalSales": 44124 }, + { "categoryName": "Bath Towels", "totalSales": 5671 }, + { "categoryName": "Turkish Towels", "totalSales": 25674 } + ], + "revenue": 279183 + }, + "promotionEvents": [ + { + "eventName": "Discount Derby", + "promotionalDates": { + "startDate": { "Year": 2023, "Month": 12, "Day": 26 }, + "endDate": { "Year": 2024, "Month": 1, "Day": 5 } + }, + "discounts": [ + { "categoryName": "Microfiber Towels", "discountPercentage": 6 }, + { "categoryName": "Bath Sheets", "discountPercentage": 16 }, + { "categoryName": "Towels", "discountPercentage": 10 }, + { "categoryName": "Hand Towels", "discountPercentage": 11 }, + { "categoryName": "Kitchen Towels", "discountPercentage": 21 }, + { "categoryName": "Placemat", "discountPercentage": 11 }, + { "categoryName": "Bath Accessories", "discountPercentage": 11 }, + { "categoryName": "Bedspreads", "discountPercentage": 21 }, + { "categoryName": "Shower Curtains", "discountPercentage": 24 }, + { "categoryName": "Pillow Top Mattresses", "discountPercentage": 10 } + ] + }, + { + "eventName": "Big Bargain Blitz", + "promotionalDates": { + "startDate": { "Year": 2024, "Month": 3, "Day": 25 }, + "endDate": { "Year": 2024, "Month": 4, "Day": 3 } + }, + "discounts": [ + { "categoryName": "Mattress Toppers", "discountPercentage": 24 }, + { "categoryName": "Pillow Cases", "discountPercentage": 14 }, + { "categoryName": "Soap Dispensers", "discountPercentage": 20 }, + { "categoryName": "Beach Towels", "discountPercentage": 18 }, + { "categoryName": "Bath Mats", "discountPercentage": 22 }, + { "categoryName": "Blankets", "discountPercentage": 12 }, + { "categoryName": "Kitchen Towels", "discountPercentage": 8 }, + { "categoryName": "Memory Foam Mattresses", "discountPercentage": 14 }, + { "categoryName": "Placemat", "discountPercentage": 17 }, + { "categoryName": "Bed Frames", "discountPercentage": 23 } + ] + }, + { + "eventName": "Massive Markdown Mania", + "promotionalDates": { + "startDate": { "Year": 2024, "Month": 6, "Day": 23 }, + "endDate": { "Year": 2024, "Month": 6, "Day": 30 } + }, + "discounts": [ + { "categoryName": "Bed Skirts", "discountPercentage": 17 }, + { "categoryName": "Shower Curtains", "discountPercentage": 23 }, + { "categoryName": "Bath Towels", "discountPercentage": 21 }, + { "categoryName": "Memory Foam Mattresses", "discountPercentage": 11 }, + { "categoryName": "Bathrobes", "discountPercentage": 19 }, + { "categoryName": "Bath Accessories", "discountPercentage": 5 }, + { "categoryName": "Box Springs", "discountPercentage": 21 }, + { "categoryName": "Hand Towels", "discountPercentage": 13 }, + { "categoryName": "Tablecloths", "discountPercentage": 19 }, + { "categoryName": "Duvet Covers", "discountPercentage": 23 } + ] + }, + { + "eventName": "Unbeatable Bargain Bash", + "promotionalDates": { + "startDate": { "Year": 2024, "Month": 9, "Day": 21 }, + "endDate": { "Year": 2024, "Month": 9, "Day": 30 } + }, + "discounts": [ + { "categoryName": "Adjustable Beds", "discountPercentage": 19 }, + { "categoryName": "Mattress Toppers", "discountPercentage": 23 }, + { "categoryName": "Washcloths", "discountPercentage": 7 }, + { "categoryName": "Comforters", "discountPercentage": 24 }, + { "categoryName": "Kitchen Towels", "discountPercentage": 7 }, + { "categoryName": "Pillows", "discountPercentage": 13 }, + { "categoryName": "Bath Sheets", "discountPercentage": 25 }, + { "categoryName": "Napkins", "discountPercentage": 25 }, + { "categoryName": "Bath Towels", "discountPercentage": 15 }, + { "categoryName": "Beach Towels", "discountPercentage": 15 } + ] + } + ], + "company": "First Up Consultants", + "city": "Port Antone", + "storeOpeningDate": { "$date": "2024-09-19T17:31:59.665Z" }, + "lastUpdated": { "$timestamp": { "t": 1729359119, "i": 1 } } + } + items: + - title: Simple text search + description: |- + This query retrieves stores containing the word "Microphone" in indexed text fields. + query: |- + // First create a text index + db.stores.createIndex({ "name": "text", "sales.salesByCategory.categoryName": "text" }) + + // Then perform the search + db.stores.find( + { $text: { $search: "Microphone" }}, + { _id: 1, name: 1, "sales.salesByCategory.categoryName": 1 }).limit(2) + output: + value: |- + [ + { + "_id": "26afb024-53c7-4e94-988c-5eede72277d5", + "name": "First Up Consultants | Microphone Bazaar - South Lexusland", + "sales": { + "salesByCategory": [ + { "categoryName": "Lavalier Microphones" }, + { "categoryName": "Wireless Microphones" } + ] + } + }, + { + "_id": "7cecdb2d-33c2-434c-ad55-bf529f68044b", + "name": "Contoso, Ltd. | Microphone Haven - O'Connellside", + "sales": { + "salesByCategory": [ + { "categoryName": "Microphone Accessories" }, + { "categoryName": "Wireless Microphones" } + ] + } + } + ] + - title: Multiple term search + description: |- + The query retrieves stores related to "Home Decor" (multiple terms treated as `OR` by default). + query: |- + // First create a text index + db.stores.createIndex({ "name": "text", "sales.salesByCategory.categoryName": "text" }) + + // Then perform the search + db.stores.find( + { $text: { $search: "Home Decor" }}, + { _id: 1, name: 1, "sales.salesByCategory.categoryName": 1 }).limit(5) + output: + value: |- + [ + { + "_id": "905d1939-e03a-413e-a9c4-221f74055aac", + "name": "Trey Research | Home Office Depot - Lake Freeda", + "sales": { + "salesByCategory": [ + { "categoryName": "Desk Lamps" } + ] + } + }, + { + "_id": "923d2228-6a28-4856-ac9d-77c39eaf1800", + "name": "Lakeshore Retail | Home Decor Hub - Franciscoton", + "sales": { + "salesByCategory": [ + { "categoryName": "Lamps" }, + { "categoryName": "Rugs" } + ] + } + }, + { + "_id": "1a2c387b-bb43-4b14-a6cd-cc05a5dbfbd5", + "name": "Contoso, Ltd. | Smart Home Device Vault - Port Katarina", + "sales": { + "salesByCategory": [ + { "categoryName": "Smart Locks" }, + { "categoryName": "Smart Home Hubs" } + ] + } + }, + { + "_id": "15e9ca57-ebc1-4191-81c2-5dc2f4ebd973", + "name": "Trey Research | Gardening Supply Stop - Port Saul", + "sales": { + "salesByCategory": [ + { "categoryName": "Garden Decor" }, + { "categoryName": "Pruning Shears" } + ] + } + }, + { + "_id": "dda2a7d2-6984-40cc-bbea-4cbfbc06d8a3", + "name": "Contoso, Ltd. | Home Improvement Closet - Jaskolskiview", + "sales": { + "salesByCategory": [ + { "categoryName": "Lumber" }, + { "categoryName": "Windows" } + ] + } + } + ] + - title: Phrase search + description: |- + This query searches for the exact phrase "Home Theater" using quotes. + query: |- + db.stores.find( + { $text: { $search: "\"Home Theater\"" }}, + { _id: 1, name: 1, "sales.salesByCategory.categoryName": 1 }).limit(2) + output: + value: |- + [ + { + "_id": "0bc4f653-e64e-4342-ae7f-9611dfd37800", + "name": "Tailwind Traders | Speaker Bazaar - North Mireyamouth", + "sales": { + "salesByCategory": [ + { "categoryName": "Home Theater Speakers" } + ] + } + }, + { + "_id": "28bb05ed-d516-4186-9144-b9eeee30917a", + "name": "Adatum Corporation | Home Entertainment Market - East Bennettville", + "sales": { + "salesByCategory": [ + { "categoryName": "Media Players" }, + { "categoryName": "Home Theater Projectors" }, + { "categoryName": "Projector Accessories" }, + { "categoryName": "Sound Bars" }, + { "categoryName": "Blu-ray Players" } + ] + } + } + ] + - title: Exclude terms with negation + description: |- + This query searches for stores with "Audio" but exclude the ones with "Wireless". + query: |- + db.stores.find( + { $text: { $search: "Audio -Wireless" }}, + { _id: 1, name: 1, "sales.salesByCategory.categoryName": 1 }).limit(2) + output: + value: |- + [ + { + "_id": "32afe6ec-dd3c-46b3-a681-ed041b032c39", + "name": "Relecloud | Audio Equipment Gallery - Margretshire", + "sales": { + "salesByCategory": [ + { "categoryName": "Audio Receivers" }, + { "categoryName": "Portable Bluetooth Speakers" } + ] + } + }, + { + "_id": "a3d3e59f-54bd-44be-943c-50dca5c4d667", + "name": "Contoso, Ltd. | Audio Equipment Shop - West Darrion", + "sales": { + "salesByCategory": [ + { "categoryName": "Soundbars" } + ] + } + } + ] + - title: Case-sensitive search + description: |- + The example allows performing a case-sensitive search for "BAZAAR". + query: |- + db.stores.find( + { $text: { $search: "BAZAAR", $caseSensitive: true } }, + { _id: 1, name: 1, "sales.salesByCategory.categoryName": 1 } + ).limit(2) + output: + value: |- + [ + { + "_id": "future-electronics-001", + "name": "Future Electronics Hub", + "sales": { "totalSales": 25000 } + }, + { + "_id": "40d6f4d7-50cd-4929-9a07-0a7a133c2e74", + "name": "Proseware, Inc. | Home Entertainment Hub - East Linwoodbury", + "sales": { + "salesByCategory": [ + { "categoryName": "Sound Bars" }, + { "categoryName": "Game Controllers" }, + { "categoryName": "Remote Controls" }, + { "categoryName": "VR Games" } + ], + "totalSales": 160000 + } + } + ] + - title: Get text search scores + description: |- + This query retrieves text search results with relevance scores for ranking. + query: |- + db.stores.find( + { $text: { $search: "Hub" } }, + { score: { $meta: "textScore" } } + ).sort({ score: { $meta: "textScore" } }).limit(5) + output: + value: |- + [ + { "_id": "511c9932-d647-48dd-9bd8-baf47b593f88", "score": 2 }, + { "_id": "a0a2f05c-6085-4c99-9781-689af759662f", "score": 2 }, + { "_id": "fb5aa470-557c-43cb-8ca0-5915d6cae34b", "score": 2 }, + { "_id": "1a2c387b-bb43-4b14-a6cd-cc05a5dbfbd5", "score": 1 }, + { "_id": "40d6f4d7-50cd-4929-9a07-0a7a133c2e74", "score": 1 } + ] + - title: Search across multiple categories + description: |- + First, create a comprehensive text index to search across all text fields. + query: |- + // Create comprehensive text index + db.stores.createIndex({ + name: "text", + "sales.salesByCategory.categoryName": "text", + "promotionEvents.eventName": "text", + "promotionEvents.discounts.categoryName": "text" + }) + + // Search across all indexed fields + db.stores.find( + { $text: { $search: "\"Home Theater\"" }}, + { name: 1, "sales.salesByCategory.categoryName": 1, "promotionEvents.eventName": 1, "promotionEvents.discounts.categoryName": 1}).limit(2) + output: + value: |- + [ + { + "_id": "40d6f4d7-50cd-4929-9a07-0a7a133c2e74", + "name": "Proseware, Inc. | Home Entertainment Hub - East Linwoodbury", + "sales": { + "salesByCategory": [ + { "categoryName": "Sound Bars" }, + { "categoryName": "Game Controllers" }, + { "categoryName": "Remote Controls" }, + { "categoryName": "VR Games" } + ] + }, + "promotionEvents": [ + { + "eventName": "Massive Markdown Mania", + "discounts": [ + { "categoryName": "DVD Players" }, + { "categoryName": "Projector Lamps" }, + { "categoryName": "Media Players" }, + { "categoryName": "Blu-ray Players" }, + { "categoryName": "Home Theater Systems" }, + { "categoryName": "Televisions" } + ] + }, + { + "eventName": "Fantastic Deal Days", + "discounts": [ + { "categoryName": "TV Mounts" }, + { "categoryName": "Game Accessories" }, + { "categoryName": "Portable Projectors" }, + { "categoryName": "Projector Screens" }, + { "categoryName": "Blu-ray Players" }, + { "categoryName": "DVD Players" } + ] + }, + { + "eventName": "Discount Delight Days", + "discounts": [ + { "categoryName": "Game Controllers" }, + { "categoryName": "Home Theater Projectors" }, + { "categoryName": "Sound Bars" }, + { "categoryName": "Media Players" }, + { "categoryName": "Televisions" }, + { "categoryName": "Projector Lamps" } + ] + }, + { + "eventName": "Super Sale Spectacular", + "discounts": [ + { "categoryName": "Laser Projectors" }, + { "categoryName": "Projector Screens" }, + { "categoryName": "PC Games" }, + { "categoryName": "PlayStation Games" }, + { "categoryName": "TV Mounts" }, + { "categoryName": "Mobile Games" } + ] + }, + { + "eventName": "Grand Deal Days", + "discounts": [ + { "categoryName": "Remote Controls" }, + { "categoryName": "Televisions" }, + { "categoryName": "Business Projectors" }, + { "categoryName": "Laser Projectors" }, + { "categoryName": "Projectors" }, + { "categoryName": "Projector Screens" } + ] + }, + { + "eventName": "Major Bargain Bash", + "discounts": [ + { "categoryName": "Sound Bars" }, + { "categoryName": "VR Games" }, + { "categoryName": "Xbox Games" }, + { "categoryName": "Projector Accessories" }, + { "categoryName": "Mobile Games" }, + { "categoryName": "Projector Cases" } + ] + } + ] + }, + { + "_id": "0bc4f653-e64e-4342-ae7f-9611dfd37800", + "name": "Tailwind Traders | Speaker Bazaar - North Mireyamouth", + "sales": { + "salesByCategory": [ + { "categoryName": "Home Theater Speakers" } + ] + }, + "promotionEvents": [ + { + "eventName": "Epic Bargain Bash", + "discounts": [ + { "categoryName": "Bluetooth Speakers" }, + { "categoryName": "Outdoor Speakers" } + ] + }, + { + "eventName": "Fantastic Deal Days", + "discounts": [ + { "categoryName": "Portable Speakers" }, + { "categoryName": "Home Theater Speakers" } + ] + } + ] + } + ] +related: []