Bin policy

Overview

The bin-policy configuration determines which bins are shipped to a destination datacenter (DC). The available options include shipping all bins, no bins, only changed bins, only specified bins, changed and specified bins, or changed or specified bins. Each option has specific use cases and impacts on overhead.

Values

Configuration Value	Explanation
all (default)	This is the default mode. The entire record is always shipped to the destination.
no-bins	[Introduced in Database 6.0]. Only allowed for connector type DCs. Bins are not shipped, only the record's metadata.
only-changed	Only the changed bins in a write are shipped. Bins that did not change are not shipped.
only-specified	[Removed as of Database 5.3]. Only the bins specified using the ship-bin configuration are shipped no matter which bins got changed as part of the write.
changed-and-specified	Similar to the && operator, the intersection of changed and specified bins. A bin is shipped if it was changed and also is specified using the ship-bin configuration. Bins that are changed but not specified using ship-bin are shipped.
changed-or-specified	Similar to the \|\| operator, the union of changed and specified bins. Both the changed bins in a write and the list of bins specified using the ship-bin configuration are shipped.

note

Aerospike Database 5.0 introduced bin projection functionality with the ship-only-specified-bins configuration parameter. In Database 5.2, ship-only-specified-bins was removed and bin-policy was introduced with the features described on this page.

Overhead

If the XDR bin-policy is set to only-changed, changed-and-specified or changed-or-specified, there is extra overhead.

The overhead is:

1. 6 bytes for each bin to maintain last-updated-time (LUT) and some metadata.
2. Deleted bins become bin tombstones. A bin tombstone requires the same resources as a regular bin with no data. These bin tombstones are cleaned up only on a subsequent write based on the xdr-bin-tombstone-ttl configuration.

Refer to the Capacity Planning Guide for further details.

note

The bin-policy configuration is at the dc/namespace sub-context. If at least one dc/namespace sub-context uses the above policies, there will be extra overhead. At a later point in time, if none of the dc/namespace level configurations use the above policies (switches to all), the overhead is removed on a subsequent write operation as the extra information is no longer necessary.

Interactions

This bin-policy configuration interacts with other configurations like ignore-bins, write-policy and connector.

Some combinations of these are restricted:

• If you choose a bin-policy that picks specified bins using ship-bin, ignore-bin is ignored.
• If you choose a bin-policy that ships changed bins, you cannot set write-policy to replace.
• If you choose the no-bins bin-policy, it is allowed only if connector is set to true.

Configuration Value	ignore-bin honored?	write-policy=replace allowed?	connector
all (default)	yes	yes	any
no-bins	NA	no	true
only-changed	yes	no	any
only-specified	no	no	any
changed-and-specified	no	no	any
changed-or-specified	no	no	any

Examples

The following examples demonstrate the rules and the interactions between bin-policy, ship-bin, and ignore-bin.

If the state of record and configuration are as follows.

• Record has 8 bins : b1, b2, b3, b4, b5, b6, b7, b8
• Bins configured using ship-bin : b1, b5
• Bins configured using ignore-bin : b2, b6

Case 1

Assume a write comes for b1, b2, and b3. The following bins are shipped under different policies.

	b1	b2	b3	b4	b5	b6	b7	b8
	ship-bin				ship-bin
		ignore-bin				ignore-bin
	write	write	write
---------------------	----------	----------	----------	----------	----------	----------	----------	----------
all	ships		ships	ships	ships		ships	ships
only-changed	ships		ships
only-specified	ships				ships
changed-and-specified	ships
changed-or-specified	ships	ships	ships		ships

Case 2

Assume a write comes for b6, b7, and b8. The following bins are shipped under different policies.

	b1	b2	b3	b4	b5	b6	b7	b8
	ship-bin				ship-bin
		ignore-bin				ignore-bin
						write	write	write
---------------------	----------	----------	----------	----------	----------	----------	----------	----------
all	ships		ships	ships	ships		ships	ships
only-changed							ships	ships
only-specified	ships				ships
changed-and-specified
changed-or-specified	ships				ships	ships	ships	ships

Use cases

The following example configurations apply to some common use cases.

Shipping specific bins if they changed

In this example, for namespace someNameSpaceName, only binName1 and binName2 are shipped.

xdr {
    dc dataCenter1 {
        node-address-port someIpAdress1 somePort1
        namespace someNameSpaceName {
           bin-policy changed-and-specified
           ship-bin binName1
           ship-bin binName2
        }  
    }   
}

Excluding specific bins

In this example, for namespace someNameSpaceName, all bins are shipped except binName1 and binName2.

xdr {
    dc dataCenter1 {
        node-address-port someIpAdress1 somePort1
        namespace someNameSpaceName {
           ignore-bin binName1
           ignore-bin binName2
        }  
    }
}       

Ship changed bins

In this example, for namespace someNameSpaceName, all bins that are modified by a write are shipped.

xdr {
    dc dataCenter1 {
        node-address-port someIpAdress1 somePort1
        namespace someNameSpaceName {
           bin-policy only-changed
        }  
    }
}       

Ship changed bins plus some additional bins

In this example, for namespace someNameSpaceName, all bins that are modified by a write plus binName1 and binName2 are shipped.

xdr {
    dc dataCenter1 {
        node-address-port someIpAdress1 somePort1
        namespace someNameSpaceName {
           bin-policy changed-or-specified
           ship-bin binName1
           ship-bin binName2
        }  
    }
}       

Ship changed bins but not some bins

In this example, for namespace someNameSpaceName, all bins that are modified by a write except binName1 and binName2 are shipped.

xdr {
    dc dataCenter1 {
        node-address-port someIpAdress1 somePort1
        namespace someNameSpaceName {
           bin-policy only-changed
           ignore-bin binName1
           ignore-bin binName2
        }  
    }
}