Skip to content

Add reference Markdown: operators/miscellaneous #54

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
seesharprun wants to merge 1 commit into from
Closed

Add reference Markdown: operators/miscellaneous #54

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
214 changes: 214 additions & 0 deletions reference/operators/miscellaneous/$getfield.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,214 @@
---
title: $getField
description: The $getField operator allows retrieving the value of a specified field from a document.
type: operators
category: miscellaneous
---

# $getField

The `$getField` operator is used to retrieve the value of a specified field from a document. It's useful when working with dynamic field names or when you need to access fields programmatically within aggregation pipelines.

## Syntax

```javascript
{
$getField: {
field: <string>,
input: <document>
}
}
```

Or the shorthand syntax:

```javascript
{
$getField: <string>
}
```

## Parameters

| Parameter | Description |
| --- | --- |
| **`field`** | A string representing the name of the field to retrieve. |
| **`input`** | The document from which the field is retrieved. If not specified, defaults to the current document (`$$ROOT`). |

## Examples

Consider this sample document from the stores collection.

```json
{
"_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
}
]
}
]
}
```

### Example 1: Basic field retrieval

Retrieve the total sales value using `$getField`:

```javascript
db.stores.aggregate([
{ $match: {"_id": "2cf3f885-9962-4b67-a172-aa9039e9ae2f"} },
{
$project: {
name: 1,
totalSalesValue: {
$getField: {
field: "totalSales",
input: "$sales"
}
}
}
}
])
```

This query returns the following result.

```json
[
{
"_id": "2cf3f885-9962-4b67-a172-aa9039e9ae2f",
"name": "First Up Consultants | Bed and Bath Center - South Amir",
"totalSalesValue": 37701
}
]
```

### Example 2: Shorthand syntax

Use the shorthand syntax to retrieve the store name:

```javascript
db.stores.aggregate([
{ $match: {"_id": "2cf3f885-9962-4b67-a172-aa9039e9ae2f"} },
{
$project: {
storeName: { $getField: "name" },
storeLocation: { $getField: "location" }
}
}
])
```

This query returns the following result.

```json
[
{
"_id": "2cf3f885-9962-4b67-a172-aa9039e9ae2f",
"storeName": "First Up Consultants | Bed and Bath Center - South Amir",
"storeLocation": {
"lat": 60.7954,
"lon": -142.0012
}
}
]
```
184 changes: 184 additions & 0 deletions reference/operators/miscellaneous/$samplerate.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,184 @@
---
title: $sampleRate
description: The $sampleRate operator randomly samples documents from a collection based on a specified probability rate, useful for statistical analysis and testing.
type: operators
category: miscellaneous
---

# $sampleRate

The `$sampleRate` operator randomly samples documents from a collection based on a specified probability rate. This operator is useful for statistical analysis, testing with subset data, and performance optimization when working with large datasets where you need a representative sample.

## Syntax

```javascript
{
$match: {
$sampleRate: <number>
}
}
```

## Parameters

| Parameter | Description |
| --- | --- |
| **`number`** | A floating-point number between 0 and 1 representing the probability that a document will be included in the sample. For example, 0.33 means approximately 33% of documents are sampled.

## Examples

Consider this sample document from the stores collection.

```json
{
"_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
}
]
}
]
}
```

### Example 1: Basic random sampling

This query returns one-third of all documents in the stores collection, selected randomly.

```javascript
db.stores.aggregate([{
$match: {
$sampleRate: 0.33
}
}])
```

### Example 2: Sampling with more filters

This query first filters stores with sales above 50,000, then randomly samples 50% of those matching documents.

```javascript
db.stores.aggregate([
{ $match: {
"sales.totalSales": { $gt: 50000 },
$sampleRate: 0.5
}}
])
```

### Example 3: Sampling for statistical analysis

This query samples 25% of stores and calculates statistical measures on the sampled data.

```javascript
db.stores.aggregate([
{ $match: { $sampleRate: 0.25 } },
{ $group: {
_id: null,
averageSales: { $avg: "$sales.totalSales" },
totalStores: { $sum: 1 },
maxSales: { $max: "$sales.totalSales" },
minSales: { $min: "$sales.totalSales" }
}}
])
```

The $sampleRate operator is valuable for statistical analysis and data exploration when working with large datasets where processing all documents would be computationally expensive. It efficiently creates representative samples for performance testing, quality assurance validation, and machine learning dataset generation. The operator is ideal for approximate reporting scenarios where statistical accuracy is acceptable and processing speed is prioritized over exact precision.