You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@cassandra.apache.org by jo...@apache.org on 2025/10/03 12:38:54 UTC
(cassandra-gocql-driver) branch trunk updated: Update API documentation for 2.0 release
This is an automated email from the ASF dual-hosted git repository.
joaoreis pushed a commit to branch trunk
in repository https://gitbox.apache.org/repos/asf/cassandra-gocql-driver.git
The following commit(s) were added to refs/heads/trunk by this push:
new b25d2811 Update API documentation for 2.0 release
b25d2811 is described below
commit b25d2811e7c4233bd429458f7f055f2979598b30
Author: João Reis <jo...@apache.org>
AuthorDate: Tue Jul 22 17:18:08 2025 +0100
Update API documentation for 2.0 release
This patch updates the existing API documentation and adds new documentation for types and methods that lack it.
Patch by João Reis; reviewed by Bohdan Siryk for CASSGO-78
---
CHANGELOG.md | 1 +
address_translators.go | 1 +
cluster.go | 12 ++++-
compressor.go | 3 ++
conn.go | 3 ++
cqltypes.go | 1 +
errors.go | 24 +++++++++
frame.go | 3 ++
gocqlzap/zap.go | 3 ++
gocqlzerolog/zerolog.go | 5 ++
helpers.go | 69 +++++++++++++++++++++---
logger.go | 9 +++-
marshal.go | 89 +++++-------------------------
metadata.go | 29 ++++++++--
policies.go | 13 +++++
session.go | 140 +++++++++++++++++++++++++++++++++++++++++++++++-
types.go | 4 ++
uuid.go | 3 ++
vector.go | 4 ++
version.go | 4 ++
20 files changed, 328 insertions(+), 92 deletions(-)
diff --git a/CHANGELOG.md b/CHANGELOG.md
index ec7d0861..a8c38812 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -35,6 +35,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
- Add way to create HostInfo objects for testing purposes (CASSGO-71)
- Add missing Context methods on Query and Batch (CASSGO-81)
- Update example and test code for 2.0 release (CASSGO-80)
+- Add API docs for 2.0 release (CASSGO-78)
### Changed
diff --git a/address_translators.go b/address_translators.go
index 8c0f7780..6246c661 100644
--- a/address_translators.go
+++ b/address_translators.go
@@ -36,6 +36,7 @@ type AddressTranslator interface {
Translate(addr net.IP, port int) (net.IP, int)
}
+// AddressTranslatorFunc is a function type that implements AddressTranslator.
type AddressTranslatorFunc func(addr net.IP, port int) (net.IP, int)
func (fn AddressTranslatorFunc) Translate(addr net.IP, port int) (net.IP, int) {
diff --git a/cluster.go b/cluster.go
index 812e459f..aec8be64 100644
--- a/cluster.go
+++ b/cluster.go
@@ -288,6 +288,11 @@ type ClusterConfig struct {
disableControlConn bool
}
+// Dialer is the interface that wraps the DialContext method for establishing network connections to Cassandra nodes.
+//
+// This interface allows customization of how gocql establishes TCP connections, which is useful for:
+// connecting through proxies or load balancers, custom TLS configurations, custom timeouts/keep-alive
+// settings, service mesh integration, testing with mocked connections, and corporate network routing.
type Dialer interface {
DialContext(ctx context.Context, network, addr string) (net.Conn, error)
}
@@ -357,7 +362,10 @@ func (cfg *ClusterConfig) filterHost(host *HostInfo) bool {
}
var (
- ErrNoHosts = errors.New("no hosts provided")
+ // ErrNoHosts is returned when no hosts are provided to the cluster configuration.
+ ErrNoHosts = errors.New("no hosts provided")
+ // ErrNoConnectionsStarted is returned when no connections could be established during session creation.
ErrNoConnectionsStarted = errors.New("no connections were made when creating the session")
- ErrHostQueryFailed = errors.New("unable to populate Hosts")
+ // Deprecated: Never used or returned by the driver.
+ ErrHostQueryFailed = errors.New("unable to populate Hosts")
)
diff --git a/compressor.go b/compressor.go
index a4c305b7..ccb743a6 100644
--- a/compressor.go
+++ b/compressor.go
@@ -24,6 +24,9 @@
package gocql
+// Compressor defines the interface for frame compression and decompression.
+// Implementations provide compression algorithms like Snappy and LZ4 that can be used
+// to reduce network traffic between the driver and Cassandra nodes.
type Compressor interface {
Name() string
diff --git a/conn.go b/conn.go
index bf5a493d..ddf13081 100644
--- a/conn.go
+++ b/conn.go
@@ -68,6 +68,7 @@ func JoinHostPort(addr string, port int) string {
return addr
}
+// Authenticator handles authentication challenges and responses during connection setup.
type Authenticator interface {
Challenge(req []byte) (resp []byte, auth Authenticator, err error)
Success(data []byte) error
@@ -132,6 +133,7 @@ type SslOptions struct {
EnableHostVerification bool
}
+// ConnConfig contains configuration options for establishing connections to Cassandra nodes.
type ConnConfig struct {
ProtoVersion int
CQLVersion string
@@ -150,6 +152,7 @@ type ConnConfig struct {
disableCoalesce bool
}
+// ConnErrorHandler handles connection errors and state changes for connections.
type ConnErrorHandler interface {
HandleError(conn *Conn, err error, closed bool)
}
diff --git a/cqltypes.go b/cqltypes.go
index ce2e1cee..813a3296 100644
--- a/cqltypes.go
+++ b/cqltypes.go
@@ -24,6 +24,7 @@
package gocql
+// Duration represents a Cassandra duration type, which consists of months, days, and nanoseconds components.
type Duration struct {
Months int32
Days int32
diff --git a/errors.go b/errors.go
index d64c4620..2d1c2205 100644
--- a/errors.go
+++ b/errors.go
@@ -111,6 +111,7 @@ const (
ErrCodeUnprepared = 0x2500
)
+// RequestError represents errors returned by Cassandra server.
type RequestError interface {
Code() int
Message() string
@@ -140,6 +141,8 @@ func (e errorFrame) String() string {
return fmt.Sprintf("[error code=%x message=%q]", e.code, e.message)
}
+// RequestErrUnavailable represents an unavailable error returned by Cassandra.
+// This error occurs when there are not enough nodes available to fulfill the request.
type RequestErrUnavailable struct {
errorFrame
Consistency Consistency
@@ -151,8 +154,14 @@ func (e *RequestErrUnavailable) String() string {
return fmt.Sprintf("[request_error_unavailable consistency=%s required=%d alive=%d]", e.Consistency, e.Required, e.Alive)
}
+// ErrorMap maps node IP addresses to their respective error codes for read/write failure responses.
+// Each entry represents a node that failed during the operation, with the key being the node's
+// IP address as a string and the value being the specific error code returned by that node.
type ErrorMap map[string]uint16
+// RequestErrWriteTimeout represents a write timeout error returned by Cassandra.
+// This error occurs when a write request times out after the coordinator
+// has successfully written to some replicas but not enough to satisfy the required consistency level.
type RequestErrWriteTimeout struct {
errorFrame
Consistency Consistency
@@ -161,6 +170,8 @@ type RequestErrWriteTimeout struct {
WriteType string
}
+// RequestErrWriteFailure represents a write failure error returned by Cassandra.
+// This error occurs when a write request fails on one or more replicas.
type RequestErrWriteFailure struct {
errorFrame
Consistency Consistency
@@ -171,10 +182,15 @@ type RequestErrWriteFailure struct {
ErrorMap ErrorMap
}
+// RequestErrCDCWriteFailure represents a CDC write failure error returned by Cassandra.
+// This error occurs when a write to the Change Data Capture log fails.
type RequestErrCDCWriteFailure struct {
errorFrame
}
+// RequestErrReadTimeout represents a read timeout error returned by Cassandra.
+// This error occurs when a read request times out after the coordinator
+// has received some responses but not enough to satisfy the required consistency level.
type RequestErrReadTimeout struct {
errorFrame
Consistency Consistency
@@ -183,17 +199,23 @@ type RequestErrReadTimeout struct {
DataPresent byte
}
+// RequestErrAlreadyExists represents an "already exists" error returned by Cassandra.
+// This error occurs when attempting to create a keyspace or table that already exists.
type RequestErrAlreadyExists struct {
errorFrame
Keyspace string
Table string
}
+// RequestErrUnprepared represents an "unprepared" error returned by Cassandra.
+// This error occurs when a prepared statement is no longer available on the server.
type RequestErrUnprepared struct {
errorFrame
StatementId []byte
}
+// RequestErrReadFailure represents a read failure error returned by Cassandra.
+// This error occurs when a read request fails on one or more replicas.
type RequestErrReadFailure struct {
errorFrame
Consistency Consistency
@@ -204,6 +226,8 @@ type RequestErrReadFailure struct {
ErrorMap ErrorMap
}
+// RequestErrFunctionFailure represents a function failure error returned by Cassandra.
+// This error occurs when a user-defined function fails during execution.
type RequestErrFunctionFailure struct {
errorFrame
Keyspace string
diff --git a/frame.go b/frame.go
index 7e551c23..0ee6a2e1 100644
--- a/frame.go
+++ b/frame.go
@@ -196,6 +196,9 @@ const (
flagBetaProtocol byte = 0x10
)
+// Consistency represents the consistency level for read and write operations.
+// Available levels: Any, One, Two, Three, Quorum, All, LocalQuorum, EachQuorum,
+// Serial, LocalSerial, LocalOne.
type Consistency uint16
// SerialConsistency is deprecated. Use Consistency instead.
diff --git a/gocqlzap/zap.go b/gocqlzap/zap.go
index 14251057..6413cff9 100644
--- a/gocqlzap/zap.go
+++ b/gocqlzap/zap.go
@@ -24,8 +24,11 @@ import (
gocql "github.com/apache/cassandra-gocql-driver/v2"
)
+// DefaultName is the default logger name used when creating a new zap logger.
const DefaultName = "gocql"
+// Logger represents a structured logger that integrates zap logging with gocql.
+// It extends gocql.StructuredLogger with access to the underlying zap logger.
type Logger interface {
gocql.StructuredLogger
ZapLogger() *zap.Logger
diff --git a/gocqlzerolog/zerolog.go b/gocqlzerolog/zerolog.go
index e9435855..7a257a0e 100644
--- a/gocqlzerolog/zerolog.go
+++ b/gocqlzerolog/zerolog.go
@@ -24,9 +24,14 @@ import (
gocql "github.com/apache/cassandra-gocql-driver/v2"
)
+// DefaultName is the default logger name used when creating a new zerolog logger.
const DefaultName = "gocql"
+
+// DefaultNameField is the default field name used to identify the logger in log entries.
const DefaultNameField = "logger"
+// Logger represents a structured logger that integrates zerolog logging with gocql.
+// It extends gocql.StructuredLogger with access to the underlying zerolog logger.
type Logger interface {
gocql.StructuredLogger
ZerologLogger() zerolog.Logger
diff --git a/helpers.go b/helpers.go
index baae5ce0..9cd14cfe 100644
--- a/helpers.go
+++ b/helpers.go
@@ -42,7 +42,7 @@ func dereference(i interface{}) interface{} {
return reflect.Indirect(reflect.ValueOf(i)).Interface()
}
-// TupeColumnName will return the column name of a tuple value in a column named
+// TupleColumnName will return the column name of a tuple value in a column named
// c at index n. It should be used if a specific element within a tuple is needed
// to be extracted from a map returned from SliceMap or MapScan.
func TupleColumnName(c string, n int) string {
@@ -81,8 +81,60 @@ func (iter *Iter) RowData() (RowData, error) {
return rowData, nil
}
-// SliceMap is a helper function to make the API easier to use
-// returns the data from the query in the form of []map[string]interface{}
+// SliceMap is a helper function to make the API easier to use.
+// It returns the data from the query in the form of []map[string]interface{}.
+//
+// Columns are automatically converted to Go types based on their CQL type.
+// The following table shows exactly what Go type to expect when accessing map values:
+//
+// CQL Type | Go Type (Non-NULL) | Go Value for NULL | Type Assertion Example
+// ascii | string | "" | row["col"].(string)
+// bigint | int64 | int64(0) | row["col"].(int64)
+// blob | []byte | []byte(nil) | row["col"].([]byte)
+// boolean | bool | false | row["col"].(bool)
+// counter | int64 | int64(0) | row["col"].(int64)
+// date | time.Time | time.Time{} | row["col"].(time.Time)
+// decimal | *inf.Dec | (*inf.Dec)(nil) | row["col"].(*inf.Dec)
+// double | float64 | float64(0) | row["col"].(float64)
+// duration | gocql.Duration | gocql.Duration{} | row["col"].(gocql.Duration)
+// float | float32 | float32(0) | row["col"].(float32)
+// inet | net.IP | net.IP(nil) | row["col"].(net.IP)
+// int | int | int(0) | row["col"].(int)
+// list<T> | []T | []T(nil) | row["col"].([]string)
+// map<K,V> | map[K]V | map[K]V(nil) | row["col"].(map[string]int)
+// set<T> | []T | []T(nil) | row["col"].([]int)
+// smallint | int16 | int16(0) | row["col"].(int16)
+// text | string | "" | row["col"].(string)
+// time | time.Duration | time.Duration(0) | row["col"].(time.Duration)
+// timestamp | time.Time | time.Time{} | row["col"].(time.Time)
+// timeuuid | gocql.UUID | gocql.UUID{} | row["col"].(gocql.UUID)
+// tinyint | int8 | int8(0) | row["col"].(int8)
+// tuple<T1,T2,...> | (see below) | (see below) | (see below)
+// uuid | gocql.UUID | gocql.UUID{} | row["col"].(gocql.UUID)
+// varchar | string | "" | row["col"].(string)
+// varint | *big.Int | (*big.Int)(nil) | row["col"].(*big.Int)
+// vector<T,N> | []T | []T(nil) | row["col"].([]float32)
+//
+// Special Cases:
+//
+// Tuple Types: Tuple elements are split into separate map entries with keys like "column[0]", "column[1]", etc.
+// Use TupleColumnName to generate the correct key:
+//
+// // For tuple<int, text> column named "my_tuple"
+// elem0 := row[gocql.TupleColumnName("my_tuple", 0)].(int)
+// elem1 := row[gocql.TupleColumnName("my_tuple", 1)].(string)
+//
+// User-Defined Types (UDTs): Returned as map[string]interface{} with field names as keys:
+//
+// udt := row["my_udt"].(map[string]interface{})
+// name := udt["name"].(string)
+// age := udt["age"].(int)
+//
+// Important Notes:
+// - Always use type assertions when accessing map values: row["col"].(ExpectedType)
+// - NULL database values return Go zero values or nil for pointer types
+// - Collection types (list, set, map, vector) return nil slices/maps for NULL values
+// - Migration from v1.x: inet columns now return net.IP instead of string values
func (iter *Iter) SliceMap() ([]map[string]interface{}, error) {
if iter.err != nil {
return nil, iter.err
@@ -104,11 +156,16 @@ func (iter *Iter) SliceMap() ([]map[string]interface{}, error) {
}
// MapScan takes a map[string]interface{} and populates it with a row
-// that is returned from cassandra.
+// that is returned from Cassandra.
//
// Each call to MapScan() must be called with a new map object.
// During the call to MapScan() any pointers in the existing map
-// are replaced with non pointer types before the call returns
+// are replaced with non pointer types before the call returns.
+//
+// Columns are automatically converted to Go types based on their CQL type.
+// See SliceMap for the complete CQL to Go type mapping table and examples.
+//
+// Usage Examples:
//
// iter := session.Query(`SELECT * FROM mytable`).Iter()
// for {
@@ -123,7 +180,7 @@ func (iter *Iter) SliceMap() ([]map[string]interface{}, error) {
// }
// }
//
-// You can also pass pointers in the map before each call
+// You can also pass pointers in the map before each call:
//
// var fullName FullName // Implements gocql.Unmarshaler and gocql.Marshaler interfaces
// var address net.IP
diff --git a/logger.go b/logger.go
index e01bf684..df865c84 100644
--- a/logger.go
+++ b/logger.go
@@ -183,6 +183,9 @@ func writeLogMsg(buf *bytes.Buffer, prefix string, msg string, fields []LogField
writeFields(buf, fields)
}
+// LogLevel represents the level of logging to be performed.
+// Higher values indicate more verbose logging.
+// Available levels: LogLevelDebug, LogLevelInfo, LogLevelWarn, LogLevelError, LogLevelNone.
type LogLevel int
const (
@@ -212,6 +215,8 @@ func (recv LogLevel) String() string {
}
}
+// LogField represents a structured log field with a name and value.
+// It is used to provide structured logging information.
type LogField struct {
Name string
Value LogFieldValue
@@ -277,7 +282,9 @@ type LogFieldValue struct {
any interface{}
}
-// LogFieldValueType is the type of a LogFieldValue.
+// LogFieldValueType represents the type of a LogFieldValue.
+// It is used to determine how to interpret the value stored in LogFieldValue.
+// Available types: LogFieldTypeAny, LogFieldTypeBool, LogFieldTypeInt64, LogFieldTypeString.
type LogFieldValueType int
// It's important that LogFieldTypeAny is 0 so that a zero Value represents nil.
diff --git a/marshal.go b/marshal.go
index 5562d9fd..9252c8c0 100644
--- a/marshal.go
+++ b/marshal.go
@@ -47,6 +47,7 @@ var (
)
var (
+ // Deprecated: Never used or returned by the driver.
ErrorUDTUnavailable = errors.New("UDT are not available on protocols less than 3, please update config")
)
@@ -69,49 +70,7 @@ type Unmarshaler interface {
// If value implements Marshaler, its MarshalCQL method is called to marshal the data.
// If value is a pointer, the pointed-to value is marshaled.
//
-// Supported conversions are as follows, other type combinations may be added in the future:
-//
-// CQL type | Go type (value) | Note
-// varchar, ascii, blob, text | string, []byte |
-// boolean | bool |
-// tinyint, smallint, int | integer types |
-// tinyint, smallint, int | string | formatted as base 10 number
-// bigint, counter | integer types |
-// bigint, counter | big.Int | according to cassandra bigint specification the big.Int value limited to int64 size(an eight-byte two's complement integer.)
-// bigint, counter | string | formatted as base 10 number
-// float | float32 |
-// double | float64 |
-// decimal | inf.Dec |
-// time | int64 | nanoseconds since start of day
-// time | time.Duration | duration since start of day
-// timestamp | int64 | milliseconds since Unix epoch
-// timestamp | time.Time |
-// list, set | slice, array |
-// list, set | map[X]struct{} |
-// map | map[X]Y |
-// uuid, timeuuid | gocql.UUID |
-// uuid, timeuuid | [16]byte | raw UUID bytes
-// uuid, timeuuid | []byte | raw UUID bytes, length must be 16 bytes
-// uuid, timeuuid | string | hex representation, see ParseUUID
-// varint | integer types |
-// varint | big.Int |
-// varint | string | value of number in decimal notation
-// inet | net.IP |
-// inet | string | IPv4 or IPv6 address string
-// tuple | slice, array |
-// tuple | struct | fields are marshaled in order of declaration
-// user-defined type | gocql.UDTMarshaler | MarshalUDT is called
-// user-defined type | map[string]interface{} |
-// user-defined type | struct | struct fields' cql tags are used for column names
-// date | int64 | milliseconds since Unix epoch to start of day (in UTC)
-// date | time.Time | start of day (in UTC)
-// date | string | parsed using "2006-01-02" format
-// duration | int64 | duration in nanoseconds
-// duration | time.Duration |
-// duration | gocql.Duration |
-// duration | string | parsed with time.ParseDuration
-//
-// The marshal/unmarshal error provides a list of supported types when an unsupported type is attempted.
+// For supported Go to CQL type conversions, see Session.Query documentation.
func Marshal(info TypeInfo, value interface{}) ([]byte, error) {
if valueRef := reflect.ValueOf(value); valueRef.Kind() == reflect.Ptr {
if valueRef.IsNil() {
@@ -139,38 +98,7 @@ func Marshal(info TypeInfo, value interface{}) ([]byte, error) {
// If value is a pointer to pointer, it is set to nil if the CQL value is
// null. Otherwise, nulls are unmarshalled as zero value.
//
-// Supported conversions are as follows, other type combinations may be added in the future:
-//
-// CQL type | Go type (value) | Note
-// varchar, ascii, blob, text | *string |
-// varchar, ascii, blob, text | *[]byte | non-nil buffer is reused
-// bool | *bool |
-// tinyint, smallint, int, bigint, counter | *integer types |
-// tinyint, smallint, int, bigint, counter | *big.Int |
-// tinyint, smallint, int, bigint, counter | *string | formatted as base 10 number
-// float | *float32 |
-// double | *float64 |
-// decimal | *inf.Dec |
-// time | *int64 | nanoseconds since start of day
-// time | *time.Duration |
-// timestamp | *int64 | milliseconds since Unix epoch
-// timestamp | *time.Time |
-// list, set | *slice, *array |
-// map | *map[X]Y |
-// uuid, timeuuid | *string | see UUID.String
-// uuid, timeuuid | *[]byte | raw UUID bytes
-// uuid, timeuuid | *gocql.UUID |
-// timeuuid | *time.Time | timestamp of the UUID
-// inet | *net.IP |
-// inet | *string | IPv4 or IPv6 address string
-// tuple | *slice, *array |
-// tuple | *struct | struct fields are set in order of declaration
-// user-defined types | gocql.UDTUnmarshaler | UnmarshalUDT is called
-// user-defined types | *map[string]interface{} |
-// user-defined types | *struct | cql tag is used to determine field name
-// date | *time.Time | time of beginning of the day (in UTC)
-// date | *string | formatted with 2006-01-02 format
-// duration | *gocql.Duration |
+// For supported CQL to Go type conversions, see Iter.Scan documentation.
func Unmarshal(info TypeInfo, data []byte, value interface{}) error {
if v, ok := value.(Unmarshaler); ok {
return v.UnmarshalCQL(info, data)
@@ -1866,6 +1794,8 @@ func (t listSetCQLType) TypeInfoFromString(proto int, name string) (TypeInfo, er
}, nil
}
+// CollectionType represents type information for Cassandra collection types (list, set, map).
+// It provides marshaling and unmarshaling for collection types.
type CollectionType struct {
typ Type
Key TypeInfo // only used for TypeMap
@@ -2542,7 +2472,8 @@ func (t tupleCQLType) TypeInfoFromString(proto int, name string) (TypeInfo, erro
}, nil
}
-// TODO: move to types.go
+// TupleTypeInfo represents type information for Cassandra tuple types.
+// It contains information about the element types in the tuple.
type TupleTypeInfo struct {
Elems []TypeInfo
}
@@ -2882,11 +2813,15 @@ func (u udtCQLType) TypeInfoFromString(proto int, name string) (TypeInfo, error)
return ti, nil
}
+// UDTField represents a field in a User Defined Type.
+// It contains the field name and its type information.
type UDTField struct {
Name string
Type TypeInfo
}
+// UDTTypeInfo represents type information for Cassandra User Defined Types (UDT).
+// It contains the keyspace, type name, and field definitions.
type UDTTypeInfo struct {
Keyspace string
Name string
@@ -3102,6 +3037,7 @@ func (udt UDTTypeInfo) Unmarshal(data []byte, value interface{}) error {
return nil
}
+// MarshalError represents an error that occurred during marshaling.
type MarshalError string
func (m MarshalError) Error() string {
@@ -3112,6 +3048,7 @@ func marshalErrorf(format string, args ...interface{}) MarshalError {
return MarshalError(fmt.Sprintf(format, args...))
}
+// UnmarshalError represents an error that occurred during unmarshaling.
type UnmarshalError string
func (m UnmarshalError) Error() string {
diff --git a/metadata.go b/metadata.go
index a8996f0d..a1e98eda 100644
--- a/metadata.go
+++ b/metadata.go
@@ -135,14 +135,28 @@ type MaterializedViewMetadata struct {
baseTableName string
}
+// UserTypeMetadata represents metadata information about a Cassandra User Defined Type (UDT).
+// This Go struct holds descriptive information about a UDT that exists in the Cassandra schema,
+// including the type name, keyspace, field names, and field types. It is not the UDT itself,
+// but rather a representation of the UDT's schema structure for use within the gocql driver.
+//
+// A Cassandra User Defined Type is a custom data type that allows you to group related fields
+// together. This metadata struct provides the necessary information to marshal and unmarshal
+// values to and from the corresponding UDT in Cassandra.
+//
+// For type information used in marshaling/unmarshaling operations, see UDTTypeInfo.
+// Actual UDT values are typically represented as map[string]interface{}, Go structs with
+// cql tags, or types implementing UDTMarshaler/UDTUnmarshaler interfaces.
type UserTypeMetadata struct {
- Keyspace string
- Name string
- FieldNames []string
- FieldTypes []TypeInfo
+ Keyspace string // The keyspace where the UDT is defined
+ Name string // The name of the User Defined Type
+ FieldNames []string // Ordered list of field names in the UDT
+ FieldTypes []TypeInfo // Corresponding type information for each field
}
-// the ordering of the column with regard to its comparator
+// ColumnOrder represents the ordering of a column with regard to its comparator.
+// It indicates whether the column is sorted in ascending or descending order.
+// Available values: ASC, DESC.
type ColumnOrder bool
const (
@@ -150,12 +164,17 @@ const (
DESC ColumnOrder = true
)
+// ColumnIndexMetadata represents metadata for a column index in Cassandra.
+// It contains the index name, type, and configuration options.
type ColumnIndexMetadata struct {
Name string
Type string
Options map[string]interface{}
}
+// ColumnKind represents the kind of column in a Cassandra table.
+// It indicates whether the column is part of the partition key, clustering key, or a regular column.
+// Available values: ColumnUnkownKind, ColumnPartitionKey, ColumnClusteringKey, ColumnRegular, ColumnCompact, ColumnStatic.
type ColumnKind int
const (
diff --git a/policies.go b/policies.go
index 8db55bf2..8f968087 100644
--- a/policies.go
+++ b/policies.go
@@ -122,6 +122,8 @@ type RetryableQuery interface {
Context() context.Context
}
+// RetryType represents the type of retry that should be performed by the retry policy.
+// Available types: Retry, RetryNextHost, Ignore, Rethrow.
type RetryType uint16
const (
@@ -265,6 +267,9 @@ func (e *ExponentialBackoffRetryPolicy) napTime(attempts int) time.Duration {
return getExponentialTime(e.Min, e.Max, attempts)
}
+// HostStateNotifier is an interface for notifying about host state changes.
+// It allows host selection policies to be informed when hosts are added, removed,
+// or change their availability status.
type HostStateNotifier interface {
AddHost(host *HostInfo)
RemoveHost(host *HostInfo)
@@ -272,6 +277,8 @@ type HostStateNotifier interface {
HostDown(host *HostInfo)
}
+// KeyspaceUpdateEvent represents a keyspace change event.
+// It contains information about which keyspace changed and what type of change occurred.
type KeyspaceUpdateEvent struct {
Keyspace string
Change string
@@ -947,16 +954,22 @@ func (e *ExponentialReconnectionPolicy) GetMaxRetries() int {
return e.MaxRetries
}
+// SpeculativeExecutionPolicy defines the interface for speculative execution policies.
+// These policies determine when and how many speculative queries to execute.
type SpeculativeExecutionPolicy interface {
Attempts() int
Delay() time.Duration
}
+// NonSpeculativeExecution is a policy that disables speculative execution.
+// It implements SpeculativeExecutionPolicy with zero attempts.
type NonSpeculativeExecution struct{}
func (sp NonSpeculativeExecution) Attempts() int { return 0 } // No additional attempts
func (sp NonSpeculativeExecution) Delay() time.Duration { return 1 } // The delay. Must be positive to be used in a ticker.
+// SimpleSpeculativeExecution is a policy that enables speculative execution
+// with a fixed number of attempts and delay.
type SimpleSpeculativeExecution struct {
NumAttempts int
TimeoutDelay time.Duration
diff --git a/session.go b/session.go
index 625dac4a..722161f1 100644
--- a/session.go
+++ b/session.go
@@ -427,6 +427,48 @@ func (s *Session) reconnectDownedHosts(intv time.Duration) {
// Further details of the query may be tweaked using the resulting query
// value before the query is executed. Query is automatically prepared
// if it has not previously been executed.
+//
+// Supported Go to CQL type conversions for query parameters are as follows:
+//
+// Go type (value) | CQL type | Note
+// string, []byte | varchar, ascii, blob, text |
+// bool | boolean |
+// integer types | tinyint, smallint, int |
+// string | tinyint, smallint, int | formatted as base 10 number
+// integer types | bigint, counter |
+// big.Int | bigint, counter | according to cassandra bigint specification the big.Int value limited to int64 size(an eight-byte two's complement integer.)
+// string | bigint, counter | formatted as base 10 number
+// float32 | float |
+// float64 | double |
+// inf.Dec | decimal |
+// int64 | time | nanoseconds since start of day
+// time.Duration | time | duration since start of day
+// int64 | timestamp | milliseconds since Unix epoch
+// time.Time | timestamp |
+// slice, array | list, set |
+// map[X]struct{} | list, set |
+// map[X]Y | map |
+// gocql.UUID | uuid, timeuuid |
+// [16]byte | uuid, timeuuid | raw UUID bytes
+// []byte | uuid, timeuuid | raw UUID bytes, length must be 16 bytes
+// string | uuid, timeuuid | hex representation, see ParseUUID
+// integer types | varint |
+// big.Int | varint |
+// string | varint | value of number in decimal notation
+// net.IP | inet |
+// string | inet | IPv4 or IPv6 address string
+// slice, array | tuple |
+// struct | tuple | fields are marshaled in order of declaration
+// gocql.UDTMarshaler | user-defined type | MarshalUDT is called
+// map[string]interface{} | user-defined type |
+// struct | user-defined type | struct fields' cql tags are used for column names
+// int64 | date | milliseconds since Unix epoch to start of day (in UTC)
+// time.Time | date | start of day (in UTC)
+// string | date | parsed using "2006-01-02" format
+// int64 | duration | duration in nanoseconds
+// time.Duration | duration |
+// gocql.Duration | duration |
+// string | duration | parsed with time.ParseDuration
func (s *Session) Query(stmt string, values ...interface{}) *Query {
qry := &Query{}
qry.session = s
@@ -437,6 +479,8 @@ func (s *Session) Query(stmt string, values ...interface{}) *Query {
return qry
}
+// QueryInfo represents metadata information about a prepared query.
+// It contains the query ID, argument information, result information, and primary key columns.
type QueryInfo struct {
Id []byte
Args []ColumnInfo
@@ -450,6 +494,8 @@ type QueryInfo struct {
// values will be marshalled as part of the query execution.
// During execution, the meta data of the prepared query will be routed to the
// binding callback, which is responsible for producing the query argument values.
+//
+// For supported Go to CQL type conversions for query parameters, see Session.Query documentation.
func (s *Session) Bind(stmt string, b func(q *QueryInfo) ([]interface{}, error)) *Query {
qry := &Query{}
qry.session = s
@@ -1206,6 +1252,8 @@ func (q *Query) Idempotent(value bool) *Query {
// Bind sets query arguments of query. This can also be used to rebind new query arguments
// to an existing query instance.
+//
+// For supported Go to CQL type conversions for query parameters, see Session.Query documentation.
func (q *Query) Bind(v ...interface{}) *Query {
q.values = v
return q
@@ -1291,6 +1339,9 @@ func (q *Query) iterInternal(c *Conn, ctx context.Context) *Iter {
// MapScan executes the query, copies the columns of the first selected
// row into the map pointed at by m and discards the rest. If no rows
// were selected, ErrNotFound is returned.
+//
+// Columns are automatically converted to Go types based on their CQL type.
+// See Iter.SliceMap for the complete CQL to Go type mapping table and examples.
func (q *Query) MapScan(m map[string]interface{}) error {
return q.MapScanContext(q.context, m)
}
@@ -1310,6 +1361,8 @@ func (q *Query) MapScanContext(ctx context.Context, m map[string]interface{}) er
// Scan executes the query, copies the columns of the first selected
// row into the values pointed at by dest and discards the rest. If no rows
// were selected, ErrNotFound is returned.
+//
+// For supported CQL to Go type conversions, see Iter.Scan documentation.
func (q *Query) Scan(dest ...interface{}) error {
return q.ScanContext(q.context, dest...)
}
@@ -1317,6 +1370,8 @@ func (q *Query) Scan(dest ...interface{}) error {
// ScanContext executes the query with the provided context, copies the columns of the first selected
// row into the values pointed at by dest and discards the rest. If no rows
// were selected, ErrNotFound is returned.
+//
+// For supported CQL to Go type conversions, see Iter.Scan documentation.
func (q *Query) ScanContext(ctx context.Context, dest ...interface{}) error {
iter := q.IterContext(ctx)
if err := iter.checkErrAndNotFound(); err != nil {
@@ -1334,6 +1389,8 @@ func (q *Query) ScanContext(ctx context.Context, dest ...interface{}) error {
// As for INSERT .. IF NOT EXISTS, previous values will be returned as if
// SELECT * FROM. So using ScanCAS with INSERT is inherently prone to
// column mismatching. Use MapScanCAS to capture them safely.
+//
+// For supported CQL to Go type conversions, see Iter.Scan documentation.
func (q *Query) ScanCAS(dest ...interface{}) (applied bool, err error) {
return q.ScanCASContext(q.context, dest...)
}
@@ -1346,6 +1403,8 @@ func (q *Query) ScanCAS(dest ...interface{}) (applied bool, err error) {
// As for INSERT .. IF NOT EXISTS, previous values will be returned as if
// SELECT * FROM. So using ScanCAS with INSERT is inherently prone to
// column mismatching. Use MapScanCAS to capture them safely.
+//
+// For supported CQL to Go type conversions, see Iter.Scan documentation.
func (q *Query) ScanCASContext(ctx context.Context, dest ...interface{}) (applied bool, err error) {
q.disableSkipMetadata = true
iter := q.IterContext(ctx)
@@ -1521,6 +1580,8 @@ type Scanner interface {
// when unmarshalling a column into the value in dest an error is returned and the row is invalidated
// until the next call to Next.
// Next must be called before calling Scan, if it is not an error is returned.
+ //
+ // For supported CQL to Go type conversions, see Iter.Scan documentation.
Scan(...interface{}) error
// Err returns the if there was one during iteration that resulted in iteration being unable to complete.
@@ -1645,6 +1706,68 @@ func (iter *Iter) readColumn() ([]byte, error) {
// Scan returns true if the row was successfully unmarshaled or false if the
// end of the result set was reached or if an error occurred. Close should
// be called afterwards to retrieve any potential errors.
+//
+// Supported CQL to Go type conversions are as follows, other type combinations may be added in the future:
+//
+// CQL Type | Go Type (dest) | Note
+// ascii, text, varchar | *string |
+// ascii, text, varchar | *[]byte | non-nil buffer is reused
+// bigint, counter | *int64 |
+// bigint, counter | *int, *int32, *int16, *int8 | with range checking
+// bigint, counter | *uint64, *uint32, *uint16 | with range checking
+// bigint, counter | *big.Int |
+// bigint, counter | *string | formatted as base 10 number
+// blob | *[]byte | non-nil buffer is reused
+// boolean | *bool |
+// date | *time.Time | start of day in UTC
+// date | *string | formatted as "2006-01-02"
+// decimal | *inf.Dec |
+// double | *float64 |
+// duration | *gocql.Duration |
+// duration | *time.Duration | with range checking
+// float | *float32 |
+// inet | *net.IP |
+// inet | *string | IPv4 or IPv6 address string
+// int | *int |
+// int | *int32, *int16, *int8 | with range checking
+// int | *uint32, *uint16, *uint8 | with range checking
+// list<T>, set<T> | *[]T |
+// list<T>, set<T> | *[N]T | array with compatible size
+// map<K,V> | *map[K]V |
+// smallint | *int16 |
+// smallint | *int, *int32, *int8 | with range checking
+// smallint | *uint16, *uint8 | with range checking
+// time | *time.Duration | nanoseconds since start of day
+// time | *int64 | nanoseconds since start of day
+// timestamp | *time.Time |
+// timestamp | *int64 | milliseconds since Unix epoch
+// timeuuid | *gocql.UUID |
+// timeuuid | *time.Time | timestamp of the UUID
+// timeuuid | *string | hex representation
+// timeuuid | *[]byte | 16-byte raw UUID
+// tinyint | *int8 |
+// tinyint | *int, *int32, *int16 | with range checking
+// tinyint | *uint8 | with range checking
+// tuple<T1,T2,...> | *[]interface{} |
+// tuple<T1,T2,...> | *[N]interface{} | array with compatible size
+// tuple<T1,T2,...> | *struct | fields unmarshaled in declaration order
+// user-defined types | gocql.UDTUnmarshaler | UnmarshalUDT is called
+// user-defined types | *map[string]interface{} |
+// user-defined types | *struct | cql tag or field name matching
+// uuid | *gocql.UUID |
+// uuid | *string | hex representation
+// uuid | *[]byte | 16-byte raw UUID
+// varint | *big.Int |
+// varint | *int64, *int32, *int16, *int8 | with range checking
+// varint | *string | formatted as base 10 number
+// vector<T,N> | *[]T |
+// vector<T,N> | *[N]T | array with exact size match
+//
+// Important Notes:
+// - NULL values are unmarshaled as zero values of the destination type
+// - Use **Type (pointer to pointer) to distinguish NULL from zero values
+// - Range checking prevents overflow when converting between numeric types
+// - For SliceMap/MapScan type mappings, see Iter.SliceMap documentation
func (iter *Iter) Scan(dest ...interface{}) bool {
if iter.err != nil {
return false
@@ -1894,7 +2017,9 @@ func (b *Batch) SpeculativeExecutionPolicy(sp SpeculativeExecutionPolicy) *Batch
return b
}
-// Query adds the query to the batch operation
+// Query adds the query to the batch operation.
+//
+// For supported Go to CQL type conversions for query parameters, see Session.Query documentation.
func (b *Batch) Query(stmt string, args ...interface{}) *Batch {
b.Entries = append(b.Entries, BatchEntry{Stmt: stmt, Args: args})
return b
@@ -1903,6 +2028,8 @@ func (b *Batch) Query(stmt string, args ...interface{}) *Batch {
// Bind adds the query to the batch operation and correlates it with a binding callback
// that will be invoked when the batch is executed. The binding callback allows the application
// to define which query argument values will be marshalled as part of the batch execution.
+//
+// For supported Go to CQL type conversions for query parameters, see Session.Query documentation.
func (b *Batch) Bind(stmt string, bind func(q *QueryInfo) ([]interface{}, error)) {
b.Entries = append(b.Entries, BatchEntry{Stmt: stmt, binding: bind})
}
@@ -2025,6 +2152,8 @@ func (b *Batch) WithNowInSeconds(now int) *Batch {
return b
}
+// BatchType represents the type of batch.
+// Available types: LoggedBatch, UnloggedBatch, CounterBatch.
type BatchType byte
const (
@@ -2033,6 +2162,8 @@ const (
CounterBatch BatchType = 2
)
+// BatchEntry represents a single statement within a batch operation.
+// It contains the statement, arguments, and execution metadata.
type BatchEntry struct {
Stmt string
Args []interface{}
@@ -2040,6 +2171,8 @@ type BatchEntry struct {
binding func(q *QueryInfo) ([]interface{}, error)
}
+// ColumnInfo represents metadata about a column in a query result.
+// It contains the keyspace, table, column name, and type information.
type ColumnInfo struct {
Keyspace string
Table string
@@ -2263,6 +2396,7 @@ type ConnectObserver interface {
ObserveConnect(ObservedConnect)
}
+// Deprecated: Unused
type Error struct {
Code int
Message string
@@ -2285,12 +2419,14 @@ var (
ErrNoMetadata = errors.New("no metadata available")
)
+// ErrProtocol represents a protocol-level error.
type ErrProtocol struct{ error }
+// NewErrProtocol creates a new protocol error with the specified format and arguments.
func NewErrProtocol(format string, args ...interface{}) error {
return ErrProtocol{fmt.Errorf(format, args...)}
}
// BatchSizeMaximum is the maximum number of statements a batch operation can have.
-// This limit is set by cassandra and could change in the future.
+// This limit is set by Cassandra and could change in the future.
const BatchSizeMaximum = 65535
diff --git a/types.go b/types.go
index ce8fee0d..a3289a51 100644
--- a/types.go
+++ b/types.go
@@ -622,6 +622,10 @@ var GlobalTypes = func() *RegisteredTypes {
}()
// Type is the identifier of a Cassandra internal datatype.
+// Available types include: TypeCustom, TypeAscii, TypeBigInt, TypeBlob, TypeBoolean, TypeCounter,
+// TypeDecimal, TypeDouble, TypeFloat, TypeInt, TypeText, TypeTimestamp, TypeUUID, TypeVarchar,
+// TypeVarint, TypeTimeUUID, TypeInet, TypeDate, TypeTime, TypeSmallInt, TypeTinyInt, TypeDuration,
+// TypeList, TypeMap, TypeSet, TypeUDT, TypeTuple.
type Type int
const (
diff --git a/uuid.go b/uuid.go
index cc5f1c21..018bc6f8 100644
--- a/uuid.go
+++ b/uuid.go
@@ -40,6 +40,9 @@ import (
"time"
)
+// UUID represents a 16-byte Universally Unique Identifier as defined by RFC 4122.
+// It provides methods for generating, parsing, and manipulating UUIDs, with support
+// for both random (version 4) and time-based (version 1) UUIDs.
type UUID [16]byte
var hardwareAddr []byte
diff --git a/vector.go b/vector.go
index 72a11c2c..4a468b44 100644
--- a/vector.go
+++ b/vector.go
@@ -60,6 +60,10 @@ func (v vectorCQLType) TypeInfoFromString(proto int, name string) (TypeInfo, err
}, nil
}
+// VectorType represents a Cassandra vector type, which stores an array of values
+// with a fixed dimension. It's commonly used for machine learning applications and
+// similarity searches. The SubType defines the element type and Dimensions specifies
+// the fixed size of the vector.
type VectorType struct {
SubType TypeInfo
Dimensions int
diff --git a/version.go b/version.go
index 73484e70..412e5f41 100644
--- a/version.go
+++ b/version.go
@@ -36,8 +36,12 @@ const (
mainPackage = "github.com/apache/cassandra-gocql-driver/v2"
)
+// driverName contains the name of the gocql driver.
+// It is automatically populated during package initialization from build information.
var driverName string
+// driverVersion contains the version of the gocql driver.
+// It is automatically populated during package initialization from build information.
var driverVersion string
func init() {
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@cassandra.apache.org
For additional commands, e-mail: commits-help@cassandra.apache.org