Last pre-dry run checkpoint commit, exercises everywhere

erikhatcher · erikhatcher · commit 562265ef99b9 · 2025-01-31T07:08:33.000-05:00
diff --git a/docs/10_About_workshop/8_Exercises/1_.mdx b/docs/10_About_workshop/8_Exercises/1_.mdx
@@ -1,17 +1,17 @@
 # Exercise: Fix me
 
-<Playground pid="6782aea0667feaaf06324b87">Fix me</Playground>
+Here's a gentle first exercise to get you started with the playground.
+You'll see an index configuration and an aggregation pipeline stage that
+hasn't been introduced yet, but no worries - 
+we'll get there next. See if you can solve it with what you already know or expect.
 
-  Here's a gentle first exercise to get you started with the playground.
-  You'll see an index configuration and an aggregation pipeline stage that
-  hasn't been introduced yet, but no worries - 
-  we'll get there next. See if you can solve it with what you already know or expect.
+1. Navigate to this Playground snapshot linked above.
+2. Press "Run"
+3. Notice the empty array `[]` of results
 
-  1. Navigate to this Playground snapshot linked above.
-  2. Press "Run"
-  3. Notice the empty array `[]` of results
+The objective with this exercise is to adjust the `FIX_ME` in the `$search` aggregation pipeline stage so that the document (in the Data Source pane) matches the query and appears in the Results pane.
 
-  The objective with this exercise is to adjust the `FIX_ME` in the `$search` aggregation pipeline stage so that the document (in the Data Source pane) matches the query and appears in the Results pane.
+* <Playground url="https://search-playground.corp.mongodb.com/tools/code-sandbox/snapshots/6782aea0667feaaf06324b87">Playground: Fix me</Playground>
 
   [![Playground intro exercise](/img/playground_intro_exercise.png)](/img/playground_intro_exercise.png)
 
diff --git a/docs/10_About_workshop/8_Exercises/2_.mdx b/docs/10_About_workshop/8_Exercises/2_.mdx
@@ -1,6 +1,6 @@
 # Exercise: My very first playground
 
-Create a <Playground pid="new">new playground</Playground>.
+Create a <Playground url="https://search-playground.mongodb.com/tools/code-sandbox/snapshots/new">new playground</Playground>.
 
 Clear the data box in the lower left (select-all, delete), and then type, paste, or import an array of a few documents. You could copy/paste the below, for example:
 
@@ -29,4 +29,11 @@ stage. Here's one that matches that document with the default configuration:
   }
 ]
   ```
-Press Run!
+Press Run!
+
+## Your playground, your data
+
+At this point, experiment for a moment - click around, adjust the data to something of interest and
+see if you can get a `$search` query to match. 
+
+It's meant to break, without breaking anything else. What happened? Was there an error message or unexpected empty `[]` results? No worries.
diff --git a/docs/20_Intro_to_Atlas_Search/8_Exercises/1_.mdx b/docs/20_Intro_to_Atlas_Search/8_Exercises/1_.mdx
@@ -44,8 +44,4 @@
   </details>
 
   IMPORTANT: Always specify the `index` parameter. Otherwise it uses `default`(?) and if there's no
-             index by that name, you get `[]` not an error. The Playground only has a `default` index.
-             (and you get an error if you use any other name); be explicit.
-
-             "Yes I double checked that the index name matches." (forum user that has been bitten before)
-             - https://www.mongodb.com/community/forums/t/no-documents-retrieved-using-dynamic-false/310123
+             index by that name, you get `[]` not an error. The Playground only has a `default`-named index. (and you get an error if you use any other name); be explicit.
diff --git a/docs/30_Index_configuration/1_index_config.mdx b/docs/30_Index_configuration/1_index_config.mdx
@@ -87,4 +87,5 @@ and options available.
 
 ## Resources
 
-  * https://www.mongodb.com/docs/atlas/atlas-search/define-field-mappings/
+  * <Link to="https://www.mongodb.com/docs/atlas/atlas-search/define-field-mappings/">Define field mappings (docs)</Link>
+  * Type mismatch detail can make or break your pipeline, e.g. https://www.mongodb.com/community/forums/t/no-documents-retrieved-using-dynamic-false/310123/3
diff --git a/docs/30_Index_configuration/3_geo.mdx b/docs/30_Index_configuration/3_geo.mdx
diff --git a/docs/30_Index_configuration/8_Exercises/2_.mdx b/docs/30_Index_configuration/8_Exercises/2_.mdx
@@ -2,15 +2,15 @@
 
 Atlas Search is quite type sensitive. The BSON type of each field is used to determine which index mapping type to use. And at query time, the type of `value` or `query` is used to determine which index to query for a particular field/path name.
 
-Why don't this playground match as expected?
+## boolean
+Why doesn't this playground match as expected?
   * <Playground url="https://search-playground.corp.mongodb.com/tools/code-sandbox/snapshots/67962dfdaa132ffc76719f57">boolean type mismatch</Playground>
-  * <Playground url="https://search-playground.corp.mongodb.com/tools/code-sandbox/snapshots/67962e2faa132ffc76719f5b">number ype mismatch</Playground>
-  * <Playground url="https://search-playground.corp.mongodb.com/tools/code-sandbox/snapshots/67962dc7aa132ffc76719f55">ObjectID type mismatch</Playground>
   
   <details>
   <summary>Explanation</summary>
   <div>
-  Because $search.equals.value is a string of "true", not an actual boolean. 
+  The type of `$search.equals.value` is not an actual boolean (it's a `string` of "true") and thus will be looking for an indexed value corresponding that type (which in this case would be a `token` search type).
+
   Here's a corrected pipeline:
   ```js
   [
@@ -28,5 +28,9 @@ Why don't this playground match as expected?
   </div>
   </details>
 
-IMPORTANT: Type matters. This detail can make or break your pipeline:
-     e.g. https://www.mongodb.com/community/forums/t/no-documents-retrieved-using-dynamic-false/310123/3
+## number
+  * <Playground url="https://search-playground.corp.mongodb.com/tools/code-sandbox/snapshots/67962e2faa132ffc76719f5b">number type mismatch</Playground>
+
+## ObjectID
+  * <Playground url="https://search-playground.corp.mongodb.com/tools/code-sandbox/snapshots/67962dc7aa132ffc76719f55">ObjectID type mismatch</Playground>
+
diff --git a/docs/30_Index_configuration/9_advanced.mdx b/docs/30_Index_configuration/9_advanced.mdx
@@ -1,5 +1,44 @@
 # 🦸 Advanced
 
+## Geo-spatial fields
+
+Dynamic mapping does not support geo-spatial fields, and require a manual/static mapping configuration.
+
+Here's a document with a `Point` field:
+```
+{
+  _id: 1,
+  city: "Charlottesville",
+  location: {
+    type: "Point",
+    coordinates: [-78.47668,38.02931]
+  }
+}
+```
+
+To map that GeoJSON `location` field to a `geo` type in Atlas Search:
+```
+{
+  "mappings": {
+    "dynamic": true,
+    "fields": {
+      "location": {
+        "type": "geo"
+      }
+    }
+  }
+}
+```
+
+
+
+### geo-spatial search operators
+
+  * <Link to="https://www.mongodb.com/docs/atlas/atlas-search/geoWithin/">geoWithin</Link>
+    - <Playground url="https://search-playground.mongodb.com/tools/code-playground/snapshots/669e6b762ce7658e786edbfa">geoWithin playground</Playground>
+  * <Link to="https://www.mongodb.com/docs/atlas/atlas-search/geoShape/">geoShape</Link>
+  * <Link to="https://www.mongodb.com/docs/atlas/atlas-search/near/">near</Link>
+
 ## `near` operator
 
 Operates on numbers and dates, but trickier than `equals`, `in`, and `range`
diff --git a/docs/50_Querying/1_index.mdx b/docs/50_Querying/1_index.mdx
@@ -1,6 +1,35 @@
-# 📘 Query construction
+# 📘 Text search operators
 
 We've already seen and played with the bulk of non-string
-operators, which operate straightforwardly. Let's now turn our attention to the
-two main `string` type operators.
+operators, which operate straightforwardly.
+
+Let's now turn our attention to the various `string` type operators.
+
+## Analysis refresher
+
+Your documents `string` fields are analyzed during indexed. Search operators on string fields navigate the inverted index structure for matches. In order to match the terms as they were indexed, string operators analyze query text, just as field text is analyzed during indexing.
+
+## `text`
+
+To query for individual terms, or words, of a `string` field. 
+
+If the `query` text analyzes to more than one term, the query either makes all terms optional (default) or all terms mandatory (`matchCriteria: "all"`).
+
+### fuzzy matching
+
+The `fuzzy` parameter to the `text` operator allows terms to be matched a bit looser, such that small changes such as a single missing letter, or two letters transcribed, or a letter or two different. 
+
+The easiest way to make a text search fuzzy is by adding `"fuzzy": {}`. There are several nuanced options that can be set within that empty fuzzy document structure, but for now let's just go with the defaults provided by this simple addition.
+
+## `phrase`
+
+The `phrase` operator matches a sequence of words, in proximity to one another. By default,
+the words must match in the same order with no additional words in between, in other words an "exact phrase" match. Again, analysis is performed on the `query` to extract and analyze the terms in the same manner as they were indexed.
+
+### phrase slop
+
+A phrase match can be a bit loose, such that it can match even if there are additional words in between the query terms in the actual documents, or if the query terms are not in the same order, but within a certain proximity. This looseness factor for `phrase` searches is called "slop" (blame Lucene for the terminology). A non-zero, positive, value will allow for that number of additional terms or out of order'ness. The score of a sloppy `phrase` clause is greater when the match is less "sloppy" (the indexed terms are closer to matching the query), and less when the match is "sloppier".
+
+## synonyms
+
 
diff --git a/docs/50_Querying/3_string_operators.mdx b/docs/50_Querying/3_string_operators.mdx
diff --git a/docs/50_Querying/5_wildcard_regex.mdx b/docs/50_Querying/5_wildcard_regex.mdx
@@ -1,11 +1,26 @@
 # 📘 Wildcard and Regex queries
 
+Both of these operators share ...
+
+## Analyzer considerations
+
 Analyzer determines what is matchable. 
 `lucene.keyword` to match across the entire string.
 Any other analyzer to match across the pieces of
 its output.
 
-Prefix matters - index scan, or only prefix-matching
-slice scanned.
+Static prefix matters: index scan, or only prefix-matching slice scanned.
+
+## `wildcard`
+
+The `wildcard` operator supports two *wildcard* characters, `?` and `*` which can be placed anywhere
+in the query string, one or more of them. 
+
+* `?`: Matches any single character
+* `*`: Matches zero or more characters
+
+## `regex`
+
+The `regex` operator supports a robust regular expression syntax, able to match sophisticated patterns against the terms of an inverted index.
 
-https://search-playground.corp.mongodb.com/tools/code-sandbox/snapshots/6798adcc28f1e0d8abe42e83
+* <Link to="https://www.mongodb.com/docs/atlas/atlas-search/regex/#lucene-regular-expression-behavior">Lucene regular expression behavior</Link>
diff --git a/docs/50_Querying/7_compound.mdx b/docs/50_Querying/7_compound.mdx
@@ -1,20 +1,19 @@
 # 📘 `compound` operator
 
-The `compound` is a meta-query operator that serves to combine other search operators to form
-more sophisticated queries, enabling optional and mandatory clauses, excluding clauses, and allowing clauses to match documents without affecting their relevancy score.
+The `compound` is a meta-query operator that serves to combine other search operators into a query of optional and mandatory scoring clauses, excluded clauses, and clauses to match documents without affecting their relevancy score.
 
 A compound operator could be used, for example, to filter for products within the "Toys" category that
 must match the term "lego" (or "legos") in the product description, must not cost greater than $100, and optionally match the products that are `used` (`pre_owned` == false) increasing the relevancy of new (not pre_owned) products.
 
-  * should
+A `compound` operator holds these four sets of clauses, each an array of any other search query operators which could also include `compound`'s themselves nested within `compound`:
+
+  * should: these clauses *should* match the document, but not required
   * must
   * mustNot
   * filter
 
-`minimumShouldMatch`
-
-The key to solid relevancy - match lots of ways, let the best and most matched docs bubble to the top
+## should
 
-## Exercises
+If there's only a single `should` clause in all of a `compound`, it effectively becomes an implicit `must`.
 
-  * 
+TODO: add some blurb about `minimumShouldMatch`
diff --git a/docs/50_Querying/8_Exercises/1_.mdx b/docs/50_Querying/8_Exercises/1_.mdx
@@ -1,3 +1,6 @@
 # Exercises: `text`
+  * Loosen up this query so the document matches: <Playground url="https://search-playground.corp.mongodb.com/tools/code-sandbox/snapshots/679c8e77e97570c2714a07f2">all, or none match</Playground> (<Playground url="https://search-playground.corp.mongodb.com/tools/code-sandbox/snapshots/679c8ef8e97570c2714a07f4">solution</Playground>)
 
-* 
+  * <Playground url="https://search-playground.corp.mongodb.com/tools/code-sandbox/snapshots/679c915dd0df60f0254e5d51">fuzzy to the rescue</Playground>
+
+  * synonyms: TODO
diff --git a/docs/50_Querying/8_Exercises/2_.mdx b/docs/50_Querying/8_Exercises/2_.mdx
@@ -0,0 +1,4 @@
+# Exercises: `phrase`
+  * Fix this <Playground url="https://search-playground.corp.mongodb.com/tools/code-sandbox/snapshots/679c8ff7e97570c2714a07f8">not close enough phrase match</Playground> 
+    * first by adjusting the query itself (<Playground url="https://search-playground.corp.mongodb.com/tools/code-sandbox/snapshots/679c9038d0df60f0254e5d47">solution</Playground>)
+    * Or what could be adjusted with the `phrase` query itself to get the query to match? <Playground url="https://search-playground.corp.mongodb.com/tools/code-sandbox/snapshots/679c909ad0df60f0254e5d49">solution</Playground>
diff --git a/docs/50_Querying/8_Exercises/3_.mdx b/docs/50_Querying/8_Exercises/3_.mdx
@@ -0,0 +1,9 @@
+# Exercises: `wildcard` and `regex`
+
+## `wildcard`
+
+* <Playground url="https://search-playground.mongodb.com/tools/code-sandbox/snapshots/679cab92d0df60f0254e5d64">words that starts-with not matching as expected</Playground> (<Playground url="https://search-playground.mongodb.com/tools/code-sandbox/snapshots/679cac0bd0df60f0254e5d66">solution</Playground>)
+
+## ``regex``
+
+* <Playground url="https://search-playground.corp.mongodb.com/tools/code-sandbox/snapshots/679caa71d0df60f0254e5d60">Full string regex not working as expected</Playground> (<Playground url="https://search-playground.corp.mongodb.com/tools/code-sandbox/snapshots/679caadcd0df60f0254e5d62">solution</Playground>)
diff --git a/docs/50_Querying/8_Exercises/4_.mdx b/docs/50_Querying/8_Exercises/4_.mdx
@@ -0,0 +1,4 @@
+# Exercises: `compound`
+
+## 
+
diff --git a/docs/50_Querying/9_advanced.mdx b/docs/50_Querying/9_advanced.mdx
@@ -0,0 +1,18 @@
+# 🦸 Advanced
+
+## `autocomplete`
+
+This seems an aluring one to run with, but understand that it uses some advanced Lucene analysis
+techniques with shingling and ngramming that apply differently between index and search time. It's recommended to explore and understand the capabilities and limitations with other textual analysis configurations and query constructions and then come back to this one with good understanding of the tradeoffs of hyper-indexing to facilitate direct short query to index lookup to simpler indexing with more complex query-time searches.
+
+## `text.fuzzy` options
+
+A myriad of parameters. Just don't forget about mixing and matching different levels of "fuzzy" or inexact matching into a robust relevance-savvy query. Too fuzzy of a match can be spurious and weird; it can be better to as-they-type guide them if you're reaching for this to compensate for users close but not quite queries. 
+
+## `queryString` 
+
+yeah, why not!  TODO
+
+## `moreLikeThis`
+
+TODO
diff --git a/docs/50_Querying/_category_.json b/docs/50_Querying/_category_.json
@@ -1,5 +1,5 @@
 {
-  "label": "Search operators",
+  "label": "Querying",
   "link": {
       "type": "generated-index"
   }
diff --git a/docs/60_Relevancy/1_index.mdx b/docs/60_Relevancy/1_index.mdx
@@ -5,6 +5,7 @@
 * TF/IDF, BM25
 * compound: additive clause scoring
 * scoreDetails w/ demonstrative lab
+* The key to solid relevancy - match lots of ways, let the best and most matched docs bubble to the top
 
 ## Retrieving score and scoreDetails
 * $addFields `searchScore`
diff --git a/docs/60_Relevancy/8_Exercises.mdx b/docs/60_Relevancy/8_Exercises.mdx
@@ -1,3 +1,16 @@
 # 👐 Exercises
 
-...
+## project the score
+
+Fix this Playground so that the `score` being projected is the relevancy score Atlas Search uses for default sorting.
+
+<Playground url="https://search-playground.corp.mongodb.com/tools/code-sandbox/snapshots/679cb3c3d0df60f0254e5d68">score not projected</Playground> (<Playground url="https://search-playground.mongodb.com/tools/code-sandbox/snapshots/679cb49ce97570c2714a0811">solution</Playground>)
+
+## score/sort by the `weight` field
+* <Playground url="https://search-playground.mongodb.com/tools/code-sandbox/snapshots/679cb652e97570c2714a0813">task: set the search (relevance) score to the value of our custom `weight` field</Playground> (<Playground url="https://search-playground.corp.mongodb.com/tools/code-sandbox/snapshots/679cb6fdd0df60f0254e5d6a">solution</Playground>)
+
+## as-you-type relevancy flexibility
+
+User types "matr": 
+ * How would you do it with the data from the Playgrounds here?
+ * <Playground url="https://search-playground.mongodb.com/tools/code-sandbox/snapshots/66473b744e0a3f240a5de9e1">one way to do it</Playground> (putting `compound` and `score` to heavy use)
diff --git a/docs/70_Data_Modeling/1_index.mdx b/docs/70_Data_Modeling/1_index.mdx
diff --git a/docs/70_Data_Modeling/8_Exercises.mdx b/docs/70_Data_Modeling/8_Exercises.mdx
diff --git a/src/components/Playground/index.js b/src/components/Playground/index.js
