Partial and eager loading of app fields

When working with API for retrieving a list of items, it is possible to set rules for fetching app fields.
To add a fetching rule, use the fields structure:

{
  "fields": {
  }
}

There are two 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 all app fields are loaded.
  
• "Field_Name_N": false indicates the fields that are 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:

• "*": falseis skipped becasue falseis the default value.
  
• "Field_Name_N": true indicates 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

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

You can load nested fields of the following types:

• App.
  
• Users.
  
• Role.
  
• Table.
  
  

The content of the App, Users and Rolefields is sorted by the creation date (the __createdAt field)/ Content of the Table type is sorted according to the order of items 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 nested fileds of several of them

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

In this example, the field F1 is loaded eagerly, with all its nested 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 nested fileds of several 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.

Loading fields with 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

Eager loading of app fields is carried out according to their access permissions. For example, F1 is a field of the App type:

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

If the user does not have access to the application from field F1, it will be empty in the results.
To retrieve the identifiers of the elements the user does not have access to, explicitly include the __id field in the query:
To get the identifiers of items 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
      }
    }
  }
}