A behaviour to compress and decompress binary data.

Modules implementing this behaviour can be used to compress and decompress data using one of the compression algorithms supported by Cassandra (see below).

Supported algorithms and implementations

Native protocol versions v4 and earlier support two compression algorithms: LZ4 and Snappy.

Native protocol versions v5 and later only support LZ4.

LZ4

If you implement a compressor module for the LZ4 algorithm, then:

• The compress/1 callback must return the compressed payload preceded by a 32-bit big-endian unsigned integer representing the length (in bytes) of the uncompressed body.

• Xandra will call the decompress/1 callback with the compressed payload, also preceded by the uncompressed body size (in bytes) as a 32-bit big-endian unsigned integer.

That is, the result of compression when using the LZ4 algorithm must look like this:

<<uncompressed_payload_length::32-big-unsigned, compressed_payload::binary>>

Snappy is self-sufficient so it doesn't need the prepended uncompressed-payload size.

Example

Let's imagine you implemented the LZ compression algorithm in your application:

defmodule MyApp.LZ4 do
  def compress(binary), do: # ...
  def decompress(binary, uncompressed_size), do: # ...
end

You can then implement a module that implements the Xandra.Compressor behaviour and can be used to compress and decompress data flowing through the connection to Cassandra:

defmodule LZ4XandraCompressor do
  @behaviour Xandra.Compressor

  @impl true
  def algorithm(), do: :lz4

  @impl true
  def compress(body) do
    [<<IO.iodata_length(body)::4-unit(8)-integer>>, MyApp.LZ4.compress(body)]
  end

  @impl true
  def decompress(<<uncompressed_size::4-unit(8)-integer, compressed_body::binary>>) do
    MyApp.LZ4.decompress(compressed_body, uncompressed_size)
  end
end

Now, this module can be passed as the value of the :compressor option to many functions in Xandra:

Xandra.start_link(compressor: LZ4XandraCompressor)

For more information on compression, see the "Compression" section in the documentation for Xandra.