Telerik OpenAccess Classic

Telerik OpenAccess ORM Send comments on this topic.
See Also
Programmer's Guide > OpenAccess ORM Classic (Old API) > Programming With OpenAccess > FetchPlans and FetchGroups > FetchPlans

Glossary Item Box

This documentation article is a legacy resource describing the functionality of the deprecated OpenAccess Classic only. The contemporary documentation of Telerik OpenAccess ORM is available here.

A FetchPlan specifies fields to be loaded for all of the instances in an object graph. Using FetchPlans, users can control, which fields are to be fetched from the database. A FetchPlan consists of a number of FetchGroups that are combined additively for each affected class. FetchPlans are used to activate and control FetchGroups dynamically by name. FetchGroups are used to identify the list of fields and their associated field recursion-depth, which will be retrieved together if the FetchGroup name is part of the actual FetchPlan configuration.

You can use the FetchPlan Browser Dialog to see the object graph that will be retrieved from the database, using the specified fetch plan.

This dialog provides you with a good overview of the fields that are being fetched using the specified fetch plan. There by, helping you in defining an optimized fetch plan, which would retrieve exactly those fields that are required by your application.

You can open the FetchPlan Browser Dialog from the Telerik > OpenAccess menu in Visual Studio. For more information about the FetchPlan Browser Dialog, read here.

A FetchPlan is directly associated with the ObjectScope - the ObjectScope and the FetchPlan have a one-to-one relationship. Since the scope holds the actual FetchPlan, you can make use of the FetchPlan multiple times, as long as you are using the same scope (until the IObjectScope object is disposed).

FetchPlans Advantages

The following are the most important advantages of the FetchPlans:

  • FetchPlans can be used to define as many FetchGroups as you want, and use them according to your varying use cases. FetchGroups allow you to restrict the fields loaded for an instance; to exactly those fields that are required, and avoid loading related instances for queries, thereby fetching is optimized.
  • FetchPlans not only allow you to define the fields that are included in a single fetch, but they also make it possible to control the recursion depth, the maximum number of objects that can be fetched together and other, similar fetching issues.
  • Using a FetchPlan allows to dynamically control the fetch behavior with the help of named FetchGroups, which are defined at compile-time.

FetchPlan API

FetchPlans are used to specify the set of active FetchGroups. By specifying the set of active FetchGroups at runtime, you control the persistent fields that are populated immediately, versus those that are populated lazily. FetchPlan defines several methods for manipulating the set of active FetchGroups, which have been described below:

FetchPlan Fields

The FetchPlan is an array of strings. Every string identifies a FetchGroups. The FetchGroups are defined on class and field level. There are some special FetchGroups, which are described below:

  • FetchPlan.Default - this is the default fetching mechanism that is defined over the field types and by using [DefaultFetchGroup(true|false)] attribute. Refer to the Default FetchGroup topic for more information.

    The FetchPlan.Default string is always part of the FetchPlan unless you remove it explicitly or call the Clear method.

  • FetchPlan.All - this FetchPlan will retrieve all the fields of an object, including referenced objects, up to one level deep. Therefore, FetchPlan.All should be used very carefully.
  • FetchPlan.DefaultLimit - sets the number of objects that can be retrieved in one fetch operation and this is the initial value of the Limit property. The default value of this property is set to "50" or to the MaxResultCount value if that is set.
  • FetchPlan.DefaultMaxDepth - sets the default maximum tree depth that is fetched together, and its value is set to "3". This controls the initial value of the MaxDepth property.
  • FetchPlan.NoLimit - sets no restriction on the number of objects that can be fetched together - unlimited retrieval of objects in one fetch operation.

FetchPlan Properties

  • Limit - the Limit property defines the maximum number of objects that can be fetched together. The default value is of this property is set to "0", which means that there is no limit. This property is useful while traversing a very big tree, where you can specify a FetchPlan that retrieves the complete tree and only limit the number of objects by the number set against this property.
  • MaxDepth - in case of object models, which have relationship fields, the MaxDepth property helps in controlling the amount of data retrieved from the database. The MaxDepth property defines the maximum tree depth that is fetched together. The MaxDepth is the depth of references (fields of relationship types) to instantiate, starting with the root instances, and by default it is set to "3". This means that, by default, the instances retrieved are the root instances and instances reachable from the root instance, up to "3" levels deep. If you want to load additional data you will have to increase the MaxDepth property. If you would like to fetch greater number of fields or a deeper tree, you will have to set the MaxDepth here and also the Depth argument at the [FetchField] attribute level, i.e., [FetchField(groupName,Depth=number)]. Therefore, the number of reference levels, which will be retrieved from the root instance, depend on both the MaxDepth property and the Depth parameter and the tree depth will be set at the lower value of the two. For example, if the MaxDepth property is set to "4" and the Depth parameter is set to "5", only instances up to "4" levels deep will be retrieved.

    The maximum possible value depends on the database server and the class hierarchy depth and is bound by the number of SQL joins required.

FetchPlan Methods

  • Add - the Add method adds a FetchGroup name to the actual FetchPlan definition. The FetchGroup name should be suggestive of what the FetchPlan does. For example, if we would like to get all the details of an employee, such as employee's first Name, last name, address, date of joining etc, we should name the FetchGroup as "FG_Employee Details Group".

    It is recommended to use symbolic constants for the names of the FetchGroups. This avoids problems occurring from misspelled strings and it also structures the usage of FetchGroups more cleanly.

    The FetchGroup names can be defined as [FetchField(groupName)] at the field of a class that you want to fetch. It is also possible to use the two special FetchGroups: FetchPlan.Default or FetchPlan.All.
  • Clear - the Clear method will provide you with an empty definition of the actual FetchPlan, i.e, it clears the actual FetchPlan definition. It also removes the FetchPlan.Default FetchGroup. If you need the default FetchGroup, you will need to add it again.
  • GetGroupNames - the GetGroupNames method gets the actual FetchPlan definition.
  • Remove - the Remove method removes a FetchGroup name from the actual FetchPlan definition.
  • Set - the Set method replaces the actual FetchPlan either by a single FetchGroup name or by a string array of FetchGroup names.

    You can make a copy of your current FetchPlan definition by calling GetGroupNames; using the Set method you can restore this copy to the actual FetchPlan later. Please note that this approach does not include the Limit and MaxDepth properties.


  • DefaultFetchGroup Attribute - the field attribute [DefaultFetchGroup] specifies whether the field is part of the default fetch group. It defaults to true for non-key fields of simple types and to false for other fields. Simple types are the .NET numeric value types such as int, double, etc., and string, bool, char, System.Decimal, and System.DateTime. Fetch groups represent a grouping of fields that are retrieved from the datastore together. Typically, a datastore associates a number of data values together and efficiently retrieves these values. Other values require extra method calls to retrieve. By default, the default fetch group is used when an object is initially retrieved from the database, for example, as a result of a query or when resolving a reference. All fields of the default fetch group are loaded, fields not in the default fetch group will be loaded on demand when they are accessed for the first time. You might exclude fields from the default fetch group, if you know that they are used very rarely by the application. You might add additional fields to the default fetch group, if you know that your application will always need access to the field. For example, consider a class with a field of type IList, named lines, for storing the line items for the order as instances of type OrderLine. By default, the lines field is not in the default fetch group. However, if your application always accesses the lines list, it might improve the overall performance if you include the lines field in the default fetch group.
    C# Copy Code
    [DefaultFetchGroup( true )]
    IList lines;
  • FetchGroup Attribute - the FetchGroup Attribute can be used to combine various FetchGroup definitions.
  • FetchField Attribute - the [FetchField] attribute is used to mark fields to be included in the named FetchGroup. All the fields that are marked with this attribute will be loaded, along with the object, when it is initially retrieved from the database, as a result of a query or while resolving a reference.

See Also