Partial and eager loading of app fields

When working with API for retrieving a list of app items, it is possible to set rules for fetching app fields.
You can add fetching rules by inserting the fields structure, for example:

{
  "fields": {
  }
}

There are 2 methods of loading app fields:

  1. Partial loading.
  2. Eager loading.

Partial loading of app fields

You can load only the specified fields of the app, ignoring the rest.

This option allows:

  1. Fetching all fields and excluding the specified ones.
  2. Loading only the specified fields.

Fetching all fields and excluding the specified ones

{
  "fields": {
    "*": true,
    "Field_Name_1": false,
    "Field_Name_N": false
  }
}

In this example, "*": true means that by default, all app fields are loaded, and strings of the "Field_Name_N": false type indicate the fields that should be excluded from the fetching results.

Note that the __id field will be loaded in any case.

Fetching only specified fields

{
  "fields": {
    "Field_Name_1": true,
    "Field_Name_N": true
  }
}

In this example, you can skip "*": false, as it is the default value. Strings of the "Field_Name_N": true type indicate the fields that should be included in the fetching results.

Note that the __id field will be loaded in any case.

Eager loading of app fields

Only available for the On-Premise edition, starting with 2023.9.
To use eager loading, enable the collectorEagerLoadEnabled feature flag.

Allows expanding nested app fields of the following types:

  1. App.
  2. User.
  3. Role.
  4. Table.

The content of fields is sorted by the creation date (the __createdAt field), except for the Table type, the content of which is sorted according to the order of elements in the table.

Also, when using eager loading for app fields, users’ access permissions are taken into account.

Let's consider some examples:

  • Loading all app fields and expanding some of them

{
  "fields": {
    "*": true,
    "F1": {
      "*": true
    },
    "F2": {
      "__name": true
    }
  }
}

In this example, the field F1 is loaded eagerly, with all its own fields, while for the field F2, only the name (__name) is loaded.

Example of the resulting object:

{
  "__id": "3a3503d2-52e6-11ee-be56-0242ac120002",
  "__name": "Item",
  "F1": [
    {
      "__id": "bd8bb825-9e86-451f-9028-9aee48adbe20",
      "__name": "Item 2",
      "Z1": 123
    }
  ],
  "F2": [
    {
      "__id": "7bebc2d4-414a-4a4d-8df1-19851dd04fae",
      "__name": "Item 3"
    }
  ]
}
  • Loading all app fields and expanding some of them, while limiting the size of the fetching result

{
  "fields": {
    "*": true,
    "F1": {
      "*": true,
      "$": {
        "first": 20
      }
    },
    "F2": {
      "__name": true,
      "$": {
        "last": 10
      }
    }
  }
}

This example is similar to the previous one, except for the limit and direction of selection for fields F1 and F2, which is set by a construction of the type

"$": {
  "first/last": N
}

where first means loading the first N items, and last means loading the last N items.

If the size and direction of fetching are not explicitly indicated, by default the last 10 items are retrieved. The maximum size of the fetching result depends on the system settings and by default is set at 100 items.

Also, the simultaneous use of first and last within one block is not allowed.

  • Multiple nesting levels

{
  "fields": {
    "*": true,
    "F1": {
      "*": true,
      "Users": {
        "*": true,
        "$": {
          "first": 20
        }
      },
      "$": {
        "last": 10
      }
    }
  }
}

Example of the resulting object:

{
  "__id": "3a3503d2-52e6-11ee-be56-0242ac120002",
  "__name": "Item",
  "F1": [
    {
      "__id": "bd8bb825-9e86-451f-9028-9aee48adbe20",
      "__name": "Item 2",
      "Z1": 123,
      "Users": [
        {
          "__id": "1331b48f-87be-4938-a22c-11cefee30a41",
          "__name": "User1",
          "X1": 123
        },
        {
          "__id": "c2b2325c-d7ce-43ab-ab32-00f698c414eb",
          "__name": "User2",
          "X1": 124
        }
      ]
    }
  ]
}

Impact of access permissions on eager loading of app fields

As mentioned earlier, eager loading of app fields is carried out according to their access permissions. For example, if a user lacks access permissions to the apps stored in the field F1 for a request of the type

{
  "fields": {
    "*": true,
    "F1": {
      "*": true,
      "Users": {
        "*": true
      }
    }
  }
}

then this field will be empty in the fetching results.

In some cases, it is useful to know the identifiers of objects to which access is not available. To instruct the system to return the identifiers of objects to which access is not available, you need to explicitly specify the fetching of the field __id:

{
  "fields": {
    "*": true,
    "F1": {
      "*": true,
      "__id": true,
      "Users": {
        "*": true
      }
    }
  }
}