[ZDT] document behavior of the fields find option for serverless (#162404)

## Summary

Fix https://github.com/elastic/kibana/issues/153766

Add documentation on the limitation of using the `fields` option of the
`SOR.find` API on managed environments.

packages/core/saved-objects/core-saved-objects-api-server-internal/src/lib/apis/find.ts

@@ -239,11 +239,13 @@ export const performFind = async <T = unknown, A = unknown>(
       total: body.hits.total,
       saved_objects: body.hits.hits.map(
         (hit: estypes.SearchHit<SavedObjectsRawDocSource>): SavedObjectsFindResult => {
-          const savedObject = migrationHelper.migrateStorageDocument(
-            serializerHelper.rawToSavedObject(hit as SavedObjectsRawDoc, {
-              migrationVersionCompatibility,
-            })
-          ) as SavedObject;
+          let savedObject = serializerHelper.rawToSavedObject(hit as SavedObjectsRawDoc, {
+            migrationVersionCompatibility,
+          });
+          // can't migrate a document with partial attributes
+          if (!fields) {
+            savedObject = migrationHelper.migrateStorageDocument(savedObject) as SavedObject;
+          }
           return {
             ...savedObject,
             score: hit._score!,

packages/core/saved-objects/core-saved-objects-api-server/src/apis/find.ts

@@ -56,9 +56,25 @@ export interface SavedObjectsFindOptions {
   /** sort order, ascending or descending */
   sortOrder?: SortOrder;
   /**
-   * An array of fields to include in the results
+   * An array of attributes to fetch and include in the results. If unspecified, all attributes will be fetched.
+   *
+   * The main purpose of this option is to avoid fetching unnecessary heavy fields (e.g blobs) when searching for
+   * savedObjects, for performance purposes.
+   *
+   * Defaults to `undefined` (fetching all fields).
+   *
    * @example
-   * SavedObjects.find({type: 'dashboard', fields: ['attributes.name', 'attributes.location']})
+   * ```ts
+   * SavedObjects.find({type: 'dashboard', fields: ['name', 'description']})
+   * ```
+   *
+   * @remarks When this option is specified, the savedObjects returned from the API will not
+   *          go through the migration process (as we can't migrate partial documents).
+   *          For this reason, all fields provided to this option should already be present
+   *          in the prior model version of the document's SO type.
+   *          Otherwise, it may lead to inconsistencies during hybrid version cohabitation
+   *          (e.g during an upgrade in serverless) where newly introduced / backfilled fields
+   *          may not necessarily appear in the documents returned from the API when the option is used.
    */
   fields?: string[];
   /** Search documents using the Elasticsearch Simple Query String syntax. See Elasticsearch Simple Query String `query` argument for more information */

packages/core/saved-objects/core-saved-objects-server/docs/model_versions.md

@@ -13,6 +13,8 @@
   - [Adding an indexed field without default value](#adding-an-indexed-field-without-default-value)
   - [Adding an indexed field with a default value](#adding-an-indexed-field-with-a-default-value)
   - [Removing an existing field](#removing-an-existing-field)
+- [Particularities of the serverless environment](#particularities-of-the-serverless-environment)
+  - [Using the fields option of the find api](#using-the-fields-option-of-the-find-savedobjects-api)
 
 ## Introduction
 
@@ -866,4 +868,26 @@ const myType: SavedObjectsType = {
     },
   },
 };
-```
+```
+
+## Particularities of the serverless environment
+
+The serverless environment, and the fact that upgrade in such environments are performed in a way
+where, at some point, the old and new version of the application are living in cohabitation, leads 
+to some particularities regarding the way the SO APIs works, and to some limitations / edge case
+that we need to document
+
+### Using the `fields` option of the `find` savedObjects API
+
+By default, the `find` API (as any other SO API returning documents) will migrate all documents before
+returning them, to ensure that documents can be used by both versions during a cohabitation (e.g an old
+node searching for documents already migrated, or a new node searching for documents not yet migrated).
+
+However, when using the `fields` option of the `find` API, the documents can't be migrated, as some
+model version changes can't be applied against a partial set of attributes. For this reason, when the
+`fields` option is provided, the documents returned from `find` will **not** be migrated.
+
+Which is why, when using this option, the API consumer needs to make sure that *all* the fields passed
+to the `fields` option **were already present in the prior model version**. Otherwise, it may lead to inconsistencies
+during upgrades, where newly introduced or backfilled fields may not necessarily appear in the documents returned
+from the `search` API when the option is used.