lz4

Documentation

Overview

Package lz4 provides LZ4 compression for the Cassandra Native Protocol.

LZ4 compresses Native Protocol frame payloads as defined in the Cassandra Native Protocol specification. The protocol supports both compressed and uncompressed frame formats, with compression applied to frame payloads containing CQL envelopes.

Basic Usage

To enable LZ4 compression:

import (
	"github.com/apache/cassandra-gocql-driver/v2"
	"github.com/apache/cassandra-gocql-driver/v2/lz4"
)

cluster := gocql.NewCluster("127.0.0.1")
cluster.Compressor = &lz4.LZ4Compressor{}

Native Protocol Compression

According to the Cassandra Native Protocol specification, compression operates on frame payloads containing streams of CQL envelopes. Each frame payload is compressed independently with no compression context between frames.

Protocol and Cassandra Version Support

LZ4 compression is supported across all Native Protocol versions that support compression, with corresponding Cassandra version support:

• Protocol v2 (Cassandra 2.0.x): LZ4 and Snappy supported
• Protocol v3 (Cassandra 2.1.x): LZ4 and Snappy supported
• Protocol v4 (Cassandra 2.2.x, 3.0.x, 3.x): LZ4 and Snappy supported
• Protocol v5 (Cassandra 4.0+): Only LZ4 supported (Snappy removed)

LZ4 is supported from Cassandra 2.0+ through current versions. In Cassandra 4.0+, LZ4 became the only supported compression algorithm.

Performance Characteristics

LZ4 generally provides a good balance of compression speed and compression ratio, making it a solid default choice for most applications. The effectiveness of compression depends on the specific CQL query patterns, result set sizes, and frame payload characteristics in your application.

For optimal performance, benchmark both LZ4 and Snappy with your specific workload, though LZ4 is typically a good starting point.

Index

• type LZ4Compressor
  • func (s LZ4Compressor) AppendCompressed(dst, src []byte) ([]byte, error)
  • func (s LZ4Compressor) AppendCompressedWithLength(dst, src []byte) ([]byte, error)
  • func (s LZ4Compressor) AppendDecompressed(dst, src []byte, uncompressedLength uint32) ([]byte, error)
  • func (s LZ4Compressor) AppendDecompressedWithLength(dst, src []byte) ([]byte, error)
  • func (s LZ4Compressor) Name() string

Types

type LZ4Compressor

type LZ4Compressor struct{}

LZ4Compressor implements the gocql.Compressor interface and can be used to compress incoming and outgoing frames. According to the Cassandra docs the LZ4 protocol should be preferred over snappy. (For details refer to https://cassandra.apache.org/doc/latest/operating/compression.html)

Implementation note: Cassandra prefixes each compressed block with 4 bytes of the uncompressed block length, written in big endian order. But the LZ4 compression library github.com/pierrec/lz4/v4 does not expect the length field, so it needs to be added to compressed blocks sent to Cassandra, and removed from ones received from Cassandra before decompression.

func (LZ4Compressor) AppendCompressed

func (s LZ4Compressor) AppendCompressed(dst, src []byte) ([]byte, error)

func (LZ4Compressor) AppendCompressedWithLength

func (s LZ4Compressor) AppendCompressedWithLength(dst, src []byte) ([]byte, error)

func (LZ4Compressor) AppendDecompressed

func (s LZ4Compressor) AppendDecompressed(dst, src []byte, uncompressedLength uint32) ([]byte, error)

func (LZ4Compressor) AppendDecompressedWithLength

func (s LZ4Compressor) AppendDecompressedWithLength(dst, src []byte) ([]byte, error)

func (LZ4Compressor) Name

func (s LZ4Compressor) Name() string