Add a description of locate_many / locate_many_signed

Author: ideasasylum

README.md

@@ -133,6 +133,33 @@ GlobalID::Locator.locate_signed(#_person_sgid.to_s, for: '#_form')
 # => #<Person:0x007fae94bf6298 @id="1">
 ```
 
+### Retrieving a collection of GlobalIDs
+
+It's possible that you have a collection of Global ID's, perhaps passed as parameters in a controller. Naively, calling `GlobalID::Locator.locate` for each Global ID in a collection will initiate an SQL select query `n` times (which can be a performance hit)
+
+Instead, use `GlobalID::Locator.locate_many` (and its counterpart `GlobalID::Locator.locate_many_signed`) to retrieve a collection using the minimum number of SQL queries necessary. It uses just one query per model class.
+
+```ruby
+ids = (User.first(3) + Student.first(3)).sort_by(&:id).map(&:to_global_id)
+# => [#<GlobalID:0x00007ffd6a8411a0 @uri=#<URI::GID gid://app/User/1>>,
+#<GlobalID:0x00007ffd675d32b8 @uri=#<URI::GID gid://app/Student/1>>,
+#<GlobalID:0x00007ffd6a840b10 @uri=#<URI::GID gid://app/User/2>>,
+#<GlobalID:0x00007ffd675d2c28 @uri=#<URI::GID gid://app/Student/2>>,
+#<GlobalID:0x00007ffd6a840480 @uri=#<URI::GID gid://app/User/3>>,
+#<GlobalID:0x00007ffd675d2598 @uri=#<URI::GID gid://app/Student/3>>]
+
+objects = GlobalID::Locator.locate_many ids
+# SELECT "users".*
+#   FROM "users"
+#   WHERE "users"."id" IN ($1, $2, $3)  [["id", 1], ["id", 2], ["id", 3]]
+# SELECT "students".*
+#   FROM "students"
+#   WHERE "students"."id" IN ($1, $2, $3)  [["id", 1], ["id", 2], ["id", 3]]
+# => [#<User id: 1>, #<Student id: 1>, #<User id: 2>, #<Student id: 2>, #<User id: 3>, #<Student id: 3>]
+```
+
+Notice how using `locate_many` has only used 2 SQL queries (one for all the Users, one for all the Students), and has maintained the order of the items in the collection.
+
 ### Custom App Locator
 
 A custom locator can be set for an app by calling `GlobalID::Locator.use` and providing an app locator to use for that app.