Bin policy

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, regardless of which bins were 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 not 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 update time (LUT), xdr-write flag (boolean value, 1 means request was by XDR client, 0 means by non-XDR client) and some spare bits.
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. Later, if none of the dc/namespace-level configurations use the above policies (switches to all), the overhead is removed on a subsequent write command as the extra information is no longer necessary.

Interactions

The 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	N/A	no	true
only-changed	yes	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. In both cases, the record state and configuration are as follows:

• The record contains eight bins: bin1, bin2, bin3, bin4, bin5, bin6, bin7, and bin8
• bin1 and bin5 are configured (specified) using ship-bin
• bin2 and bin6 are configured (ignored) using ignore-bin

Case 1

Assume a write comes for bin1, bin2, and bin3. Bins are shipped as follows under different policies.

Case 2

Assume a write comes for bin6, bin7, and bin8. Bins are shipped as follows under different policies.

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
        }
    }
}