Scylla Documentation Logo Documentation
  • Server
    • Scylla Open Source
    • Scylla Enterprise
    • Scylla Alternator
  • Cloud
    • Scylla Cloud
    • Scylla Cloud Docs
  • Tools
    • Scylla Manager
    • Scylla Monitoring Stack
    • Scylla Operator
  • Drivers
    • CQL Drivers
    • DynamoDB Drivers
Download
Menu

Caution

You're viewing documentation for a previous version of Scylla Python Driver. Switch to the latest stable version.

Scylla Python Driver API Documentation cassandra.protocol - Protocol Features

cassandra.protocol - Protocol Features¶

Custom Payloads¶

Native protocol version 4+ allows for a custom payload to be sent between clients and custom query handlers. The payload is specified as a string:binary_type dict holding custom key/value pairs.

By default these are ignored by the server. They can be useful for servers implementing a custom QueryHandler.

See Session.execute(), :Session.execute_async(), ResponseFuture.custom_payload.

class cassandra.protocol._ProtocolHandler¶

_ProtocolHander handles encoding and decoding messages.

This class can be specialized to compose Handlers which implement alternative result decoding or type deserialization. Class definitions are passed to cassandra.cluster.Cluster on initialization.

Contracted class methods are _ProtocolHandler.encode_message() and _ProtocolHandler.decode_message().

message_types_by_opcode = {default mapping}¶
classmethod encode_message(msg, stream_id, protocol_version, compressor, allow_beta_protocol_version)¶

Encodes a message using the specified frame parameters, and compressor

Parameters
  • msg – the message, typically of cassandra.protocol._MessageType, generated by the driver

  • stream_id – protocol stream id for the frame header

  • protocol_version – version for the frame header, and used encoding contents

  • compressor – optional compression function to be used on the body

classmethod decode_message(protocol_version, user_type_map, stream_id, flags, opcode, body, decompressor, result_metadata)¶

Decodes a native protocol message body

Parameters
  • protocol_version – version to use decoding contents

  • user_type_map – map[keyspace name] = map[type name] = custom type to instantiate when deserializing this type

  • stream_id – native protocol stream id from the frame header

  • flags – native protocol flags bitmap from the header

  • opcode – native protocol opcode from the header

  • body – frame body

  • decompressor – optional decompression function to inflate the body

Returns

a message decoded from the body and frame attributes

Faster Deserialization¶

When python-driver is compiled with Cython, it uses a Cython-based deserialization path to deserialize messages. By default, the driver will use a Cython-based parser that returns lists of rows similar to the pure-Python version. In addition, there are two additional ProtocolHandler classes that can be used to deserialize response messages: LazyProtocolHandler and NumpyProtocolHandler. They can be used as follows:

from cassandra.protocol import NumpyProtocolHandler, LazyProtocolHandler
from cassandra.query import tuple_factory
s.client_protocol_handler = LazyProtocolHandler   # for a result iterator
s.row_factory = tuple_factory  #required for Numpy results
s.client_protocol_handler = NumpyProtocolHandler  # for a dict of NumPy arrays as result

These protocol handlers comprise different parsers, and return results as described below:

  • ProtocolHandler: this default implementation is a drop-in replacement for the pure-Python version. The rows are all parsed upfront, before results are returned.

  • LazyProtocolHandler: near drop-in replacement for the above, except that it returns an iterator over rows, lazily decoded into the default row format (this is more efficient since all decoded results are not materialized at once)

  • NumpyProtocolHander: deserializes results directly into NumPy arrays. This facilitates efficient integration with analysis toolkits such as Pandas.

PREVIOUS
cassandra.pool - Hosts and Connection Pools
NEXT
cassandra.encoder - Encoders for non-prepared Statements
  • 3.22.3
    • 3.25.4
    • 3.24.8
    • 3.22.3
    • 3.21.0
  • API Documentation
    • cassandra - Exceptions and Enums
    • cassandra.cluster - Clusters and Sessions
    • cassandra.policies - Load balancing and Failure Handling Policies
    • cassandra.auth - Authentication
    • cassandra.graph - Graph Statements, Options, and Row Factories
    • cassandra.metadata - Schema and Ring Topology
    • cassandra.metrics - Performance Metrics
    • cassandra.query - Prepared Statements, Batch Statements, Tracing, and Row Factories
    • cassandra.pool - Hosts and Connection Pools
    • cassandra.protocol - Protocol Features
    • cassandra.encoder - Encoders for non-prepared Statements
    • cassandra.decoder - Data Return Formats
    • cassandra.concurrent - Utilities for Concurrent Statement Execution
    • cassandra.connection - Low Level Connection Info
    • cassandra.util - Utilities
    • cassandra.timestamps - Timestamp Generation
    • cassandra.io.asyncioreactor - asyncio Event Loop
    • cassandra.io.asyncorereactor - asyncore Event Loop
    • cassandra.io.eventletreactor - eventlet-compatible Connection
    • cassandra.io.libevreactor - libev Event Loop
    • cassandra.io.geventreactor - gevent-compatible Event Loop
    • cassandra.io.twistedreactor - Twisted Event Loop
    • cassandra.cqlengine.models - Table models for object mapping
    • cassandra.cqlengine.columns - Column types for object mapping models
    • cassandra.cqlengine.query - Query and filter model objects
    • cassandra.cqlengine.connection - Connection management for cqlengine
    • cassandra.cqlengine.management - Schema management for cqlengine
    • cassandra.cqlengine.usertype - Model classes for User Defined Types
    • cassandra.datastax.graph - Graph Statements, Options, and Row Factories
    • cassandra.datastax.graph.fluent
    • cassandra.datastax.graph.fluent.query
    • cassandra.datastax.graph.fluent.predicates
  • Installation
  • Getting Started
  • Scylla Specific Features
  • Upgrading
  • Execution Profiles
  • Performance Notes
  • Paging Large Queries
  • Lightweight Transactions (Compare-and-set)
  • Security
  • User Defined Types
  • Object Mapper
    • Upgrade Guide
    • Models
    • Making Queries
    • Batch Queries
    • Connections
    • Third party integrations
    • Frequently Asked Questions
  • Working with Dates and Times
  • Scylla Cloud
  • Frequently Asked Questions
  • Create an issue
  • Edit this page

On this page

  • cassandra.protocol - Protocol Features
    • Custom Payloads
    • Faster Deserialization
Logo
Docs Contact Us About Us
Mail List Icon Slack Icon
© ScyllaDB 2021 and © DataStax 2013-2017
Powered by Sphinx 4.3.2 & ScyllaDB Theme 1.2.2