Hi Cory,
FilterToUse
FilterToUse is the IRelationalPredicateBucket (IPredicateExpression + IRelationCollection) used to filter the main collection. To sort or filter on related entities/entitycollections, the relationCollection is needed to build the WHERE clause correctly.
For example: you want to retrieve all OrderDetails whose related products are discounted... Note that you don't want to prefetch (fetch additional entity/entitycollection and attach it to OrderDetails results):
EntityCollection<OrderDetailEntity> details = new EntityCollection<OrderDetailEntity>();
IRelationPredicateBucket filter = new RelationPredicateBucket();
// needed to relate customers and products
filter.Relations.Add(OrderDetailEntity.Relations.ProductEntityUsingProductId);
// To be able to reach products in the filter, the above relation is needed
filter.PredicateExpression.Add(ProductFields.Discounted == true);
PrefetchPath
When you prefetch, a different query is performed. So it is another history. Including a prefetchPath doesn't necessarily means that you want to include relations (JOINS) in your query. Indeed, you may want to perform additional filter/sort on the attached prefetchPath.
For example, you want to retrieve all Customers and their orders (just that, you don't want to filter or sort):
EntityCollection<CustomerEntity> customers = new EntityCollection<CustomerEntity>();
IPrefetchPath2 path = new PrefetchPath2((int) EntityType.CustomerEntity);
path.Add(CustomerEntity.PrefetchPathOrders);
You of course, could filter/sort the customer collection, you also could filter/sort the orders path. However they are different retrievals