diff --git a/help/en/docs/images/references-lookups/families-final-2.png b/help/en/docs/images/references-lookups/families-final-2.png new file mode 100644 index 000000000..fb8603cda Binary files /dev/null and b/help/en/docs/images/references-lookups/families-final-2.png differ diff --git a/help/en/docs/images/references-lookups/students-final-2.png b/help/en/docs/images/references-lookups/students-final-2.png new file mode 100644 index 000000000..fe0ef1f61 Binary files /dev/null and b/help/en/docs/images/references-lookups/students-final-2.png differ diff --git a/help/en/docs/references-lookups.md b/help/en/docs/references-lookups.md index 938c3aa07..f684e065e 100644 --- a/help/en/docs/references-lookups.md +++ b/help/en/docs/references-lookups.md @@ -115,6 +115,33 @@ The entire formula would be `Sponsors.lookupOne(Contact_Email=$Registration_Emai Now, we have the Sponsor Level listed in the All Registrations table for those attendees whose emails also appear on the sponsor list. +## lookupOne and sort_by ## + +When the `lookupOne` function encounters multiple matching results, it returns the first one by row ID. The optional `sort_by` parameter can be used to sort these results by another field, to determine which one would be returned as the first match. You can also prefix the column ID with "-" to reverse the order. + +For instance, consider this example from the [Class Enrollment](https://templates.getgrist.com/doc/afterschool-program) template. This template tracks enrollment for extracurricular and other classes - logging information for students, families, and staff. + +On this page, we have a list of students and their respective information. + +*![student-table](images/references-lookups/students-final-2.png)* + +Additionally, we have a Families page that outlines the parent of each student and we’d like to find which student in each family is the oldest. So, we would create an oldest student column. + +*![family-table](images/references-lookups/families-final-2.png)* + + +Then, the following formula would look at the Students table, find the specific students associated with each family, sort them by their birthday, and return the one student with the earliest birthday: + +`Students.lookupOne(Family=$id, sort_by="Birthday")` + +In this case, this would return: Raddon, Brockie. + +Alternatively, if we want to find the youngest student, the formula would include "-": + +`Students.lookupOne(Family=$id, sort_by="-Birthday”)` + +In this case, this would return: Raddon, Care. + ## Understanding record sets Sometimes a record may reference multiple records in another table. Multiple references can be made with a Reference List Column.