Was this page helpful?
Data types¶
The driver marshals CQL values to and from idiomatic Go values. Common mappings are:
CQL type |
Typical Go type |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
slice or array |
|
|
|
|
|
|
|
|
|
|
|
|
|
slice, array, or struct |
user-defined type |
struct, |
|
|
Integer CQL values can also be unmarshaled into other integer types,
big.Int, or their base-10 string representation when the value fits the
destination.
See the Marshal and Unmarshal API
documentation for
the full conversion matrix and custom marshaling interfaces.
Null values¶
CQL NULL normally becomes the destination type’s zero value. Scan into a
pointer when the application must distinguish a null value from an empty one:
var value *string
if err := query.Scan(&value); err != nil {
return err
}
if value == nil {
// The CQL value was NULL.
}
A null list or set scanned directly into an array returns an error. For a
nullable fixed-size collection, declare a pointer to the array and scan its
address so NULL can be represented by a nil pointer.
var values *[3]int
if err := query.Scan(&values); err != nil {
return err
}
Byte slice memory reuse¶
When scanning a scalar blob, text, varchar, or ascii value into a
[]byte, the driver can reuse the destination slice’s backing memory on the
next scan. Declare a new slice inside the loop when rows must be retained after
scanning:
scanner := query.Iter().Scanner()
var rows [][]byte
for scanner.Next() {
var value []byte
if scanErr := scanner.Scan(&value); scanErr != nil {
_ = scanner.Err() // Close the iterator before returning.
return scanErr
}
rows = append(rows, value)
}
if err := scanner.Err(); err != nil {
return err
}
Collection slices such as []int receive a newly allocated backing array for
each non-null value and can be retained directly.
User-defined types¶
Map a CQL user-defined type to a Go struct with cql tags:
type Address struct {
Street string `cql:"street"`
City string `cql:"city"`
}
var address Address
if err := session.Query(
"SELECT address FROM users WHERE id = ?",
id,
).Scan(&address); err != nil {
return err
}
UDTs can also use map[string]any, gocql.UDTMarshaler, or
gocql.UDTUnmarshaler. Implement gocql.Marshaler and gocql.Unmarshaler
when a type needs complete control over its CQL binary representation.