chore: Add FindNearest API to the preview branch

Google APIs · copybara-github · commit d32bd9795d26 · 2024-01-18T13:12:01.000-08:00
docs: Improve the documentation on Document.fields

PiperOrigin-RevId: 599602467
diff --git a/google/firestore/v1/document.proto b/google/firestore/v1/document.proto
@@ -41,23 +41,23 @@ message Document {
   //
   // The map keys represent field names.
   //
-  // A simple field name contains only characters `a` to `z`, `A` to `Z`,
-  // `0` to `9`, or `_`, and must not start with `0` to `9`. For example,
-  // `foo_bar_17`.
-  //
   // Field names matching the regular expression `__.*__` are reserved. Reserved
-  // field names are forbidden except in certain documented contexts. The map
-  // keys, represented as UTF-8, must not exceed 1,500 bytes and cannot be
+  // field names are forbidden except in certain documented contexts. The field
+  // names, represented as UTF-8, must not exceed 1,500 bytes and cannot be
   // empty.
   //
   // Field paths may be used in other contexts to refer to structured fields
-  // defined here. For `map_value`, the field path is represented by the simple
-  // or quoted field names of the containing fields, delimited by `.`. For
-  // example, the structured field
-  // `"foo" : { map_value: { "x&y" : { string_value: "hello" }}}` would be
-  // represented by the field path `foo.x&y`.
+  // defined here. For `map_value`, the field path is represented by a
+  // dot-delimited (`.`) string of segments. Each segment is either a simple
+  // field name (defined below) or a quoted field name. For example, the
+  // structured field `"foo" : { map_value: { "x&y" : { string_value: "hello"
+  // }}}` would be represented by the field path `` foo.`x&y` ``.
+  //
+  // A simple field name contains only characters `a` to `z`, `A` to `Z`,
+  // `0` to `9`, or `_`, and must not start with `0` to `9`. For example,
+  // `foo_bar_17`.
   //
-  // Within a field path, a quoted field name starts and ends with `` ` `` and
+  // A quoted field name starts and ends with `` ` `` and
   // may contain any character. Some characters, including `` ` ``, must be
   // escaped using a `\`. For example, `` `x&y` `` represents `x&y` and
   // `` `bak\`tik` `` represents `` bak`tik ``.
diff --git a/google/firestore/v1/query.proto b/google/firestore/v1/query.proto
@@ -30,6 +30,14 @@ option php_namespace = "Google\\Cloud\\Firestore\\V1";
 option ruby_package = "Google::Cloud::Firestore::V1";
 
 // A Firestore query.
+//
+// The query stages are executed in the following order:
+// 1. from
+// 2. where
+// 3. select
+// 4. order_by + start_at + end_at
+// 5. offset
+// 6. limit
 message StructuredQuery {
   // A selection of a collection, such as `messages as m1`.
   message CollectionSelector {
