[DOCS-12068] [Server] Add more detailed section/page on field paths Created: 21/Sep/18  Updated: 14/Nov/23

Status: External Review
Project: Documentation
Component/s: Server
Affects Version/s: None
Fix Version/s: None

Type: Task Priority: Major - P3
Reporter: Nick Brewer Assignee: Unassigned
Resolution: Unresolved Votes: 1
Labels: query, server-docs-bug-bash
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Issue Links:
Related
related to SERVER-37246 $arrayElemAt aggregation, referencing... Closed
Participants:
Days since reply: 12 weeks, 2 days ago
Story Points: 2

 Description   

Notes 2.0

Repurposing this ticket to add more information on field paths and array behavior. Suggestion is to link the field path section in the aggregation quick reference page to a larger section on field paths (potentially a new page). Then, link the new field paths section/page to operator pages that might have use cases for field paths . 

Notes 1.0

See below. It seems like we could highlight this behavior by linking to https://www.mongodb.com/docs/manual/tutorial/query-array-of-documents/, perhaps in an admonition.

Description

Currently the $arrayElemAt documentation does not include an example of how it behaves when dot notation is used to reference a nested field name within an array.

A simplified example:

With the following data:

{
	"_id" : ObjectId("5ba53172ce6fa2fcfc58e0ac"),
	"example" : [
		{
			"apples" : [
				"macintosh",
				"golden delicious",
				"fuji",
				"gala"
			]
		},
		{
			"oranges" : [
				"mandarin",
				"navel",
				"clementine"
			]
		},
		{
			"apples" : [
				"braeburn",
				"honeycrisp",
				"red"
			]
		}
	]
}

You can include the nested field "apples", and the index value will determine whether you get the first entry in the "example" array, or the third:

db.fruits.aggregate([
   {
      "$project": {
         "apples2": {
            "$arrayElemAt": ["$example.apples", 1]
         }
            }
   }
])

This returns the second array that matches the "apples" field name:

{
	"_id" : ObjectId("5ba53172ce6fa2fcfc58e0ac"),
	"apples2" : [
		"braeburn",
		"honeycrisp",
		"red"
	]
}

Instead of simply returning the second nested field in the "example" array ("oranges"), which would be returned if the 1 index was used without specifying a nested field:

db.fruits.aggregate([
   {
      "$project": {
         "apples2": {
            "$arrayElemAt": ["$example", 1]
         }
            }
   }
])

returns:

{
	"_id" : ObjectId("5ba53172ce6fa2fcfc58e0ac"),
	"apples2" : {
		"oranges" : [
			"mandarin",
			"navel",
			"clementine"
		]
	}
}

Scope of changes

Impact to Other Docs

MVP (Work and Date)

Resources (Scope or Design Docs, Invision, etc.)



 Comments   
Comment by Asya Kamsky [ 13/Nov/23 ]

Echoing david.storch@mongodb.com - this is about how using a nested array in path expression and is not at all specific to `$arrayElemAt`.   In the given example, "$inventory.apples" returns an array with two elements, that's the key here, not how `$arrayElemAt` works, which is exactly as expected.

 

Comment by Raman Gupta [ 14/Oct/22 ]

Just ran into this issue and it took a while to figure out why `arrayElement` at index 1 did not actually refer to the value at index 1. Please do update the docs to explain this behavior.

Comment by David Storch [ 21/Sep/18 ]

I'm not sure that I agree with the suggestion of adding documentation like this to the page for $arrayElemAt. This is a consequence of the behavior of the field path expression "$example.apples". Instead, the documentation for field path expressions should be augmented to describe array behavior.

All I could find related to field path expressions was https://docs.mongodb.com/manual/meta/aggregation-quick-reference/#agg-quick-ref-field-paths. Should we have a dedicated page in the "Aggregation Pipeline Operators" section describing the behavior of the expression "$my.field.path"?

Generated at Thu Feb 08 08:04:19 UTC 2024 using Jira 9.7.1#970001-sha1:2222b88b221c4928ef0de3161136cc90c8356a66.