Tech Tip: Span Queries

Level 200
DevForce Express

April 18, 2006

Sometimes you want more than just the business objects that match your search criteria; you want their related business objects as well. You want a "span" query.

A span query is a regular query with attached requests for related objects. Every query returns a primary object type. In a span query, we add "span" requests for objects that are linked to the primary object type by one (or more) mapped "relations".

In the query shown below, we retrieve all Orders placed within the last 7 days. We also want the Customers who placed these orders, their OrderDetails, and the Products purchased in those OrderDetails. Accordingly we add two spans, one reaching "upward" from Order to Customer and another reaching "downward", first to OrderDetail then and from OrderDetail to Product. 

C#:

RdbQuery query1 = new RdbQuery(typeof(Order),

  Order.OrderDateEntityColumn, EntityQueryOp.GT,

  DateTime.Today - new TimeSpan(7, 0,0, 0));

query1.AddSpan(EntityRelations.Customer_Order);

query1.AddSpan(EntityRelations.Order_OrderDetail,

  EntityRelations.Product_OrderDetail); 

VB.NET:

Dim query1 As RdbQuery = New RdbQuery(GetType(Order), _

  Order.OrderDateEntityColumn, EntityQueryOp.GT, _

  DateTime.Today - new TimeSpan(7, 0, 0, 0))

query1.AddSpan(EntityRelations.Customer_Order)

query1.AddSpan(EntityRelations.Order_OrderDetail, _   EntityRelations.Product_OrderDetail)

Span queries provide a very effective method of quickly to collect a graph of business objects either for performance reasons or because the user wants to cache objects before going into disconnected mode.