Synergex.SynergyDE.Select.Sparse

Specify a partial record for network performance

namespace Synergex.SynergyDE.Select
public sealed class Sparse

The Sparse class specifies a partial, or sparse, record.

Constructors

Sparse

public varargs Sparse(field1, ...)

Identifies the field specifications (n) to return in the From record(s). Field1, etc., must be part of a record specified in the From class object. To request all fields, specify “*” (including the quotation marks).

Operators

Sparse supports a logical and operator, which is equivalent to its Synergy counterpart (&& or .AND.), to concatenate Sparse objects at runtime. See Expressions for additional information about this operator.

Discussion

A sparse record is a subset of a record. While the entire record will be read, only the specified fields will be returned, and all other fields will be blanked out. Using Sparse is most effective when you’re using xfServer and only parts of the record(s) are needed. Only those fields specified are transferred across the network, optimizing performance.

Sparse is an alternative to the SparseRecord() method in the Select class. (See SparseRecord.) Select.Sparse differs from Select.SparseRecord() in that Select.Sparse can be constructed dynamically at runtime. Select.Sparse can also be used with fields from multiple records in a JoinSelect and with queries that use a static cursor.

Fields specified in the Sparse constructor must either explicitly or implicitly reference fields in a record specified in a subsequent From object (or From objects if used in a join). If they don’t reference a field in a record, an $ERR_ INVOPER error (“Invalid operation: Field reference not entirely part of a From record”) will be generated.

Specifying a single, alpha parameter consisting of an asterisk in quotation marks ("*") is the equivalent of SELECT * in SQL and selects all fields. It’s also equivalent to not using Sparse at all; however, it can be useful when constructing at runtime. If you specify "*", you can’t specify any other parameters.

Using Sparse with no parameters requests that no fields be returned. This is useful only when using the RowEnumerator.Count() method or when constructing a list of fields dynamically where Sparse is the first or leftmost to be concatenated with the logical and operator.

When Select.Sparse is used in conjunction with IOHooks, Sparse is ignored or disabled until I/O hooks on the channel have been disabled or removed. More specifically, when either read or write I/O hooks have been implemented and are part of the IOHooks creation mask and either the Select has specified a Sparse object on creation or SparseRecord has been issued, sparse data functionality is disabled. To re-enable sparse functionality, both the read and write I/O hooks must be removed.

A Sparse object can be helpful in the following scenarios:

To optimize performance when accessing remote files via xfServer.
To improve performance and reduce memory usage with a query that uses a static cursor (e.g., a Select object with GroupBy or a JoinSelect object with OrderBy).
To eliminate non-group fields in a GroupBy query, since only fields used to group records are meaningful in that context.

To help optimize performance, Sparse objects are required for all static cursor queries (Select objects using GroupBy and all JoinSelect objects using OrderBy). It’s still possible to retrieve all fields in these queries by specifying "*" in the Sparse constructor, but keep in mind that this may decrease performance (and may return irrelevant fields in the case of GroupBy).

Using Select with a Sparse object in other contexts (i.e., to a local file without using OrderBy or GroupBy) provides no real benefit and can negatively affect performance. We recommend using Sparse objects only in the scenarios mentioned above.