Property Indexes

ScaleOut Software NamedCache API

When objects are stored in StateServer, they are serialized into opaque blobs and are not directly queryable. However, the NamedCache subsystem now allows you to identify specific object properties that you want to be able to use in queries by annotating those properties in your code with the SossIndexAttribute. Once you've annotated properties within your code, the NamedCache automatically ensures that the current values of those properties are placed into StateServer's property index whenever an instance of the annotated type is created or updated.

In addition to property values, the NamedCache automatically writes type signature information into the property index for annotated Types, allowing you to query for objects of a given type or subtype. The details about type signatures are described below.

Annotating properties with SossIndexAttribute

Consider the following class definitions:

Example classes
 1[Serializable]
 2class Stock
 3{
 4    [SossIndex]
 5    public string Ticker { get; set; }
 6    [SossIndex]
 7    public DateTime DelistingDate { get; set; }
 8
 9    public decimal TotalShares { get; set; }
10    public decimal Price { get; set; }
11}
12
13[Serializable]
14class SmallCapStock : Stock
15{
16}

Because the Ticker property is annotated with SossIndexAttribute, when instances of Stock or SmallCapStock are created or updated in StateServer, Stock and SmallCapStock type signatures and the values of the objects' Ticker and DelistingDate properties are automatically updated in the StateServer's property index as well.

Since the property TotalShares is not annotated with SossIndexAttribute, values from the TotalShares property are not updated in the StateServer's property index when Stock instances are written to the store.

The technical limit to the number of type signatures and property values that may be stored in the property index for a single object is 65,535. Like traditional databases, there is a tradeoff between the performance advantages of including the property in an index vs. the cost of the additional memory required to hold the property index data and the network bandwidth required to transmit the data. In general, you should annotate properties you want to use in queries so that they appear in the property index, but do not annotate properties you do not intend to query against (querying against properties is covered in the topic Using LINQ).

Annotating Types with SossIndexAttribute

If you don't need to query against any of a type's properties but do want to be able to retrieve objects of that type (or any subtype) you may apply the SossIndexAttribute to the class or struct definition itself. By doing so, only the type signature corresponding to the type and its subtypes will automatically be stored in the StateServer property index when instances of the type are created or udpated.

The SossIndexAttribute may also be applied to properties defined on interfaces. In that case, the properties of any type that implements the annotated interface that correspond to annotated properties in the interface are implicitly annotated on the type. For example, the ITaggable interface annotates TagHolder with the SossIndexAttribute. Even though the BlogEntry class defined below has no properties annotated with the SossIndexAttribute because it implements ITaggable, the TagHolder property will be saved in the property index when instances of BlogEntry are created or updated.

[Serializable]
class BlogEntry : ITaggable
{
    public string Title { get; set; }
    public string Content { get; set; }

    SparseBitmap ITaggable.TagHolder { get; set; }
    NamedCache ITaggable.NamedCache
    {
        get { return CacheFactory.GetCache("BlogData"); }
    }
}

Type Signatures

When the NamedCache subsystem writes information for an instance of a type to StateServer's property index, it always includes a key corresponding to the instance's type so that StateServer can distinguish objects according to their Types. This key is referred to as a type signature.

The type signature is essentially a hash of the type name together with an ordered list of all properties declared within that type that are annotated with SossIndexAttribute together with the return type of those properties. If a type has a base type with indexed properties the base type's type signature is also written to the property index. If a type has no indexed properties but a base class does, then the base class' property signature and the subtype's property signature are both written to the property index.

Once instances of a type have been persisted in StateServer, you may continue to modify the code that implements that type and successfully query for the previoulsy-persisted objects as long as your changes don't alter the type signature for the type. You will alter the type signature if you:

  • change which properties are annotated with SossIndexAttribute,
  • change the name of the type,
  • change the name of an annotated property,
  • change the return type of an annotated property,
  • change the inheritance hierarchy of the type.

See Also

Reference

Other Resources