LATEST VERSION: 8.2.5 - CHANGELOG
Pivotal GemFire® v8.2

Colocate Data from Different Partitioned Regions

Colocate Data from Different Partitioned Regions

By default, GemFire allocates the data locations for a partitioned region independent of the data locations for any other partitioned region. You can change this policy for any group of partitioned regions, so that cross-region, related data is all hosted by the same member. This colocation speeds queries and other operations that access data from the regions.

Note: If you are colocating data between regions and custom partitioning the data in the regions, all colocated regions must use partitioning mechanisms that return the same routing object. The most common approach, though not the only one, is for all colocated regions to use the same custom PartitionResolver. See Custom-Partition Your Region Data.

Data colocation between partitioned regions generally improves the performance of data-intensive operations. You can reduce network hops for iterative operations on related data sets. Compute-heavy applications that are data-intensive can significantly increase overall throughput. For example, a query run on a patient's health records, insurance, and billing information is more efficient if all data is grouped in a single member. Similarly, a financial risk analytical application runs faster if all trades, risk sensitivities, and reference data associated with a single instrument are together.

Prerequisites
Procedure
  1. Identify one region as the central region, with which data in the other regions is explicitly colocated. If you use persistence for any of the regions, you must persist the central region.
    1. Create the central region before you create the others, either in the cache.xml or your code. Regions in the XML are created before regions in the code, so if you create any of your colocated regions in the XML, you must create the central region in the XML before the others. GemFire will verify its existence when the others are created and return IllegalStateException if the central region is not there. Do not add any colocation specifications to this central region.
    2. For all other regions, in the region partition attributes, provide the central region's name in the colocated-with attribute. Use one of these methods:
      • XML:
        <cache> 
            <region name="trades"> 
                <region-attributes> 
                    <partition-attributes>  
                        ...
                    <partition-attributes> 
                </region-attributes> 
            </region> 
            <region name="trade_history"> 
                <region-attributes> 
                    <partition-attributes colocated-with="trades">   
                        ...
                    <partition-attributes> 
                </region-attributes> 
            </region> 
        </cache> 
      • Java:
        PartitionAttributes attrs = ...
        Region trades = new RegionFactory().setPartitionAttributes(attrs).create("trades");
        ...
        attrs = new PartitionAttributesFactory().setColocatedWith(trades.getFullPath()).create();
        Region trade_history = new RegionFactory().setPartitionAttributes(attrs).create("trade_history");
      • gfsh:
        gfsh>create region --name="trades" type=PARTITION
        gfsh> create region --name="trade_history" --colocated-with="trades"
  2. For each of the colocated regions, use the same values for these partition attributes related to bucket management:
    • recovery-delay
    • redundant-copies
    • startup-recovery-delay
    • total-num-buckets
  3. If you custom partition your region data, provide the same custom resolver to all colocated regions:
    • XML:
      <cache> 
          <region name="trades"> 
              <region-attributes> 
                  <partition-attributes>  
                  <partition-resolver name="TradesPartitionResolver"> 
                      <class-name>myPackage.TradesPartitionResolver
                      </class-name>
                  <partition-attributes> 
              </region-attributes> 
          </region> 
          <region name="trade_history"> 
              <region-attributes> 
                  <partition-attributes colocated-with="trades">   
                  <partition-resolver name="TradesPartitionResolver"> 
                      <class-name>myPackage.TradesPartitionResolver
                      </class-name>
                  <partition-attributes> 
              </region-attributes> 
          </region> 
      </cache> 
    • Java:
      PartitionResolver resolver = new TradesPartitionResolver();
      PartitionAttributes attrs = 
      	new PartitionAttributesFactory()
      	.setPartitionResolver(resolver).create();
      Region trades = new RegionFactory().setPartitionAttributes(attrs).create("trades");
      attrs = new PartitionAttributesFactory()
          .setColocatedWith(trades.getFullPath()).setPartitionResolver(resolver).create();
      Region trade_history = new RegionFactory().setPartitionAttributes(attrs).create("trade_history");
    • gfsh:

      You cannot specify a partition resolver using gfsh.

  4. If you want to persist data in the colocated regions, persist the central region and then persist the other regions as needed. Use the same disk store for all of the colocated regions that you persist.