Skip to main content
Aerospike Vector is now live with LangChain integrationTell me more
Loading

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 ValueExplanation
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-changedOnly 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-specifiedSimilar 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-specifiedSimilar 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 Valueignore-bin honored?write-policy=replace allowed?connector
all (default)yesyesany
no-binsNAnotrue
only-changedyesnoany
only-specifiednonoany
changed-and-specifiednonoany
changed-or-specifiednonoany

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.

b1b2b3b4b5b6b7b8
ship-binship-bin
ignore-binignore-bin
writewritewrite
-----------------------------------------------------------------------------------------------------
allshipsshipsshipsshipsshipsships
only-changedshipsships
only-specifiedshipsships
changed-and-specifiedships
changed-or-specifiedshipsshipsshipsships

Case 2​

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

b1b2b3b4b5b6b7b8
ship-binship-bin
ignore-binignore-bin
writewritewrite
-----------------------------------------------------------------------------------------------------
allshipsshipsshipsshipsshipsships
only-changedshipsships
only-specifiedshipsships
changed-and-specified
changed-or-specifiedshipsshipsshipsshipsships

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
        }  
    }
}
Last updated on