Range Assignment Policy
The range policy is designed for use with Tiered Storage Range Partitions described in Range Partitions. It uses a range index value to decide which forest a document should be assigned to. When setting the range policy, you specify a range index for use as the partition key and configure each forest attached to the database with a range that defines a lower and upper end.
Note
Avoid using the range policy to manage documents that might have more than one value for a range index, as the behavior in such a circumstance is undefined.
There may be multiple forests that cover the same range, but two forests cannot have partially overlapped ranges. For example, it is valid for both ForestA and ForestB to cover (1 to 10) but not valid for ForestA to cover (1 to 6) while ForestB covers (4 to 10). It is also not valid for ForestA to cover (1 to 10) while ForestB covers (4 to 9). Among those forests that cover the same range, documents are assigned to the forests based on their document count, following a similar mapping process as the statistical policy described in Statistical Assignment Policy.
Note
In order to accommodate range “gaps” and documents that do not contain an element used as the partition key, you should always configure a default forest, as described below.
If a document has been processed by the Content Processing Framework (CPF), the property documents associated with the document may have a partition key value that is different from that in the document. When using the range policy, you may want to use the xdmp:document-add-properties or xdmp:document-set-properties function to put the same partition key value as specified in the document into the property documents to ensure that they are moved to the same forest as the original document. For example, the partition key is creation-date and the example.xml document has a creation-date of 2010-01-02, but its associated property documents contain no creation-date element. You could then use the xdmp:document-add-properties function as follows to add a matching creation-date element to the example.xml property documents.
xdmp:document-add-properties( "example.xml", (<creation-date>2010-01-02</creation-date>))
A forest with no range value behaves as the default forest, which means that documents that do not fit into any of the ranges set on the other forests are moved to the default forest. You cannot retire a forest unless there is another forest for the documents to move to, which means that there must either be another forest with the same range as the retired forest or that there is a default forest (no range set) attached to the database. If a database contains no default forest, an attempt to retire a forest containing documents with partition key values that do not match the ranges in the other forests will not be successful.
Note
You should always define a default forest when configuring the range assignment policy.
For example, as shown in the figure below, you have documents that are organized into 6 volumes and each document contains a <creation-date> element that indicates when that document was created. You can create an element range index, named creation-date, of type date and identify creation-date as the partition key for the range policy. If you have four forests, you can set the lower bound of the range on the ForestA to 2010-01-02 and the upper bound to 2011-01-01; on ForestB, the lower bound to 2011-01-02 and the upper bound to 2012-01-01, and on ForestC, the lower bound to 2012-01-02 and the upper bound to 2013-04-01. The fourth forest, ForestD, is designated as the default forest by not specifying a range. Any documents that have dates that fall outside of the date ranges set for the other forests and directed to the default forest.
