Class: DuckDB::Value

Inherits:
Object
  • Object
show all
Extended by:
Converter
Defined in:
lib/duckdb/value.rb,
ext/duckdb/value.c

Constant Summary

Constants included from Converter

Converter::EPOCH, Converter::EPOCH_UTC, Converter::HALF_HUGEINT, Converter::HALF_HUGEINT_BIT, Converter::LOWER_HUGEINT_MASK, Converter::RANGE_DECIMAL_WIDTH, Converter::RANGE_HUGEINT, Converter::RANGE_INT16, Converter::RANGE_INT32, Converter::RANGE_INT64, Converter::RANGE_INT8, Converter::RANGE_UHUGEINT, Converter::RANGE_UINT16, Converter::RANGE_UINT32, Converter::RANGE_UINT64, Converter::RANGE_UINT8

Class Method Summary collapse

Instance Method Summary collapse

Methods included from Converter

_decimal_to_unscaled, _decimal_width, _hugeint_lower, _hugeint_upper, _parse_date, _parse_deciaml, _parse_time, _to_date, _to_decimal_from_hugeint, _to_decimal_from_value, _to_hugeint_from_vector, _to_infinity, _to_interval_from_vector, _to_query_progress, _to_time, _to_time_from_duckdb_time, _to_time_from_duckdb_time_ns, _to_time_from_duckdb_time_tz, _to_time_from_duckdb_timestamp_ms, _to_time_from_duckdb_timestamp_ns, _to_time_from_duckdb_timestamp_s, _to_time_from_duckdb_timestamp_tz, decimal_to_hugeint, default_timezone_utc?, format_timestamp_with_micro, format_timezone_offset, integer_to_hugeint

Class Method Details

.create_array(child_type, values) ⇒ DuckDB::Value

Creates a DuckDB::Value of ARRAY type. The array size is the number of elements given. The first argument is the element type: a Symbol (e.g. :integer) or a DuckDB::LogicalType. The second argument is an Array of DuckDB::Value elements.

values = [1, 2, 3].map { |i| DuckDB::Value.create_int32(i) }
array = DuckDB::Value.create_array(:integer, values)

Parameters:

Returns:

Raises:

  • (DuckDB::Error) —

    if child_type cannot be resolved to a DuckDB::LogicalType.

  • (ArgumentError) —

    if values is not an Array of DuckDB::Value.



522
523
524
525
526
 
# File 'lib/duckdb/value.rb', line 522

def create_array(child_type, values)
  check_value_array!(values)

  _create_array(DuckDB::LogicalType.resolve(child_type), values)
end

.create_bignum(value) ⇒ DuckDB::Value

Creates a DuckDB::Value of BIGNUM (arbitrary-precision integer) type.

value = DuckDB::Value.create_bignum(2**200)

Parameters:

  • value (Integer) —

    the integer value, of arbitrary size.

Returns:

Raises:

  • (ArgumentError) —

    if value is not an Integer.



479
480
481
482
483
484
485
 
# File 'lib/duckdb/value.rb', line 479

def create_bignum(value)
  check_type!(value, Integer)

  hex = value.abs.to_s(16)
  hex = "0#{hex}" if hex.length.odd?
  _create_bignum([hex].pack('H*'), value.negative?)
end

.create_bit(value) ⇒ DuckDB::Value

Creates a DuckDB::Value of BIT (bitstring) type.

value = DuckDB::Value.create_bit('0101')

Parameters:

  • value (String) —

    the bitstring: '0'/'1' characters, MSB first.

Returns:

Raises:

  • (ArgumentError) —

    if value is not a non-empty String of '0' and '1' characters.



463
464
465
466
467
468
469
 
# File 'lib/duckdb/value.rb', line 463

def create_bit(value)
  check_type!(value, String)
  raise ArgumentError, "expected a String of '0'/'1' characters" unless value.match?(/\A[01]+\z/)

  pad = -value.length % 8
  _create_bit("#{pad.chr}#{[('1' * pad) + value].pack('B*')}".b)
end

.create_blob(value) ⇒ DuckDB::Value

Creates a DuckDB::Value of BLOB type.

value = DuckDB::Value.create_blob("\x00\x01\x02".b)

Parameters:

  • value (String) —

    the binary string value.

Returns:

Raises:

  • (ArgumentError) —

    if value is not a BINARY encoded String.



188
189
190
191
192
 
# File 'lib/duckdb/value.rb', line 188

def create_blob(value)
  check_type!(value, String)
  check_binary!(value)
  _create_blob(value)
end

.create_bool(value) ⇒ DuckDB::Value

Creates a new DuckDB::Value with a boolean value.

require 'duckdb'
value = DuckDB::Value.create_bool(true)

Parameters:

  • value (TrueClass, FalseClass) —

    the boolean value

Returns:

Raises:

  • (ArgumentError) —

    if value is not a boolean



18
19
20
21
22
 
# File 'lib/duckdb/value.rb', line 18

def create_bool(value)
  check_type!(value, [TrueClass, FalseClass])

  _create_bool(value)
end

.create_date(value) ⇒ DuckDB::Value

Creates a DuckDB::Value of DATE type. The argument is parsed leniently: a Date, a Time, or a String accepted by Date.parse, matching Appender#append_date.

value = DuckDB::Value.create_date(Date.new(2026, 7, 12))
value = DuckDB::Value.create_date('2026-07-12')

Parameters:

  • value (Date, Time, String) —

    the date value.

Returns:

Raises:

  • (ArgumentError) —

    if value cannot be parsed to a Date.



251
252
253
254
 
# File 'lib/duckdb/value.rb', line 251

def create_date(value)
  date = _parse_date(value)
  _create_date(date.year, date.month, date.day)
end

.create_decimal(value) ⇒ DuckDB::Value

Creates a DuckDB::Value of DECIMAL type.

value = DuckDB::Value.create_decimal(BigDecimal('12345.678'))

Parameters:

  • value (BigDecimal) —

    the decimal value.

Returns:

Raises:

  • (ArgumentError) —

    if value is not a BigDecimal or its width is out of range (1..38).



231
232
233
234
235
236
237
238
239
 
# File 'lib/duckdb/value.rb', line 231

def create_decimal(value)
  check_type!(value, BigDecimal)

  width = _decimal_width(value)
  check_range!(width, RANGE_DECIMAL_WIDTH, 'DECIMAL width')

  lower, upper = decimal_to_hugeint(value)
  _create_decimal(lower, upper, width, value.scale)
end

.create_double(value) ⇒ DuckDB::Value

Creates a DuckDB::Value of DOUBLE type.

value = DuckDB::Value.create_double(1.5)

Parameters:

  • value (Numeric) —

    the numeric value.

Returns:

Raises:

  • (ArgumentError) —

    if value is not a Numeric.



163
164
165
166
 
# File 'lib/duckdb/value.rb', line 163

def create_double(value)
  check_type!(value, [Integer, Float])
  _create_double(value)
end

.create_enum(enum_type, member) ⇒ DuckDB::Value

Creates a DuckDB::Value of ENUM type. The first argument is the enum type: an Array of member names (as accepted by DuckDB::LogicalType.create_enum) or an ENUM DuckDB::LogicalType. The second argument is the member: its name (String or Symbol) or its 0-based index (Integer).

value = DuckDB::Value.create_enum(%w[happy sad neutral], 'sad')

# equivalent, with an explicit ENUM logical type:
enum_type = DuckDB::LogicalType.create_enum('happy', 'sad', 'neutral')
value = DuckDB::Value.create_enum(enum_type, 'sad')

Parameters:

  • enum_type (Array<String>, DuckDB::LogicalType) —

    the member names or ENUM logical type.

  • member (String, Symbol, Integer) —

    the member name or 0-based index.

Returns:

Raises:

  • (ArgumentError) —

    if enum_type is not an Array or an ENUM DuckDB::LogicalType, or member is not a member of the enum.



412
413
414
415
416
417
418
 
# File 'lib/duckdb/value.rb', line 412

def create_enum(enum_type, member)
  enum_type = DuckDB::LogicalType.create_enum(*enum_type) if enum_type.is_a?(Array)
  check_type!(enum_type, DuckDB::LogicalType)
  raise ArgumentError, "expected ENUM LogicalType, got #{enum_type.type}" unless enum_type.type == :enum

  _create_enum(enum_type, enum_member_index(enum_type, member))
end

.create_float(value) ⇒ DuckDB::Value

Creates a DuckDB::Value of FLOAT type.

value = DuckDB::Value.create_float(1.5)

Parameters:

  • value (Numeric) —

    the numeric value.

Returns:

Raises:

  • (ArgumentError) —

    if value is not a Numeric.



151
152
153
154
 
# File 'lib/duckdb/value.rb', line 151

def create_float(value)
  check_type!(value, [Integer, Float])
  _create_float(value)
end

.create_hugeint(value) ⇒ DuckDB::Value

Creates a DuckDB::Value of HUGEINT type.

value = DuckDB::Value.create_hugeint(1_234_567_890_123_456_789_012_345)

Parameters:

  • value (Integer) —

    the integer value (-(2127)..(2127 - 1))

Returns:

Raises:

  • (ArgumentError) —

    if value is not an Integer or out of range.



201
202
203
204
205
206
207
 
# File 'lib/duckdb/value.rb', line 201

def create_hugeint(value)
  check_type!(value, Integer)
  check_range!(value, RANGE_HUGEINT, 'HUGEINT')

  lower, upper = integer_to_hugeint(value)
  _create_hugeint(lower, upper)
end

.create_int16(value) ⇒ DuckDB::Value

Creates a new DuckDB::Value with an INT16 (SMALLINT) value.

require 'duckdb'
value = DuckDB::Value.create_int16(32_767)

Parameters:

  • value (Integer) —

    the integer value (-32768..32767)

Returns:

Raises:

  • (ArgumentError) —

    if value is not an Integer or out of range



47
48
49
50
51
52
 
# File 'lib/duckdb/value.rb', line 47

def create_int16(value)
  check_type!(value, Integer)
  check_range!(value, RANGE_INT16, 'INT16')

  _create_int16(value)
end

.create_int32(value) ⇒ DuckDB::Value

Creates a new DuckDB::Value with an INT32 (INTEGER) value.

require 'duckdb'
value = DuckDB::Value.create_int32(2_147_483_647)

Parameters:

  • value (Integer) —

    the integer value (-2147483648..2147483647)

Returns:

Raises:

  • (ArgumentError) —

    if value is not an Integer or out of range



62
63
64
65
66
67
 
# File 'lib/duckdb/value.rb', line 62

def create_int32(value)
  check_type!(value, Integer)
  check_range!(value, RANGE_INT32, 'INT32')

  _create_int32(value)
end

.create_int64(value) ⇒ DuckDB::Value

Creates a new DuckDB::Value with an INT64 (BIGINT) value.

require 'duckdb'
value = DuckDB::Value.create_int64(9_223_372_036_854_775_807)

Parameters:

  • value (Integer) —

    the integer value (-9223372036854775808..9223372036854775807)

Returns:

Raises:

  • (ArgumentError) —

    if value is not an Integer or out of range



77
78
79
80
81
82
 
# File 'lib/duckdb/value.rb', line 77

def create_int64(value)
  check_type!(value, Integer)
  check_range!(value, RANGE_INT64, 'INT64')

  _create_int64(value)
end

.create_int8(value) ⇒ DuckDB::Value

Creates a new DuckDB::Value with an INT8 (TINYINT) value.

require 'duckdb'
value = DuckDB::Value.create_int8(127)

Parameters:

  • value (Integer) —

    the integer value (-128..127)

Returns:

Raises:

  • (ArgumentError) —

    if value is not an Integer or out of range



32
33
34
35
36
37
 
# File 'lib/duckdb/value.rb', line 32

def create_int8(value)
  check_type!(value, Integer)
  check_range!(value, RANGE_INT8, 'INT8')

  _create_int8(value)
end

.create_interval(value) ⇒ DuckDB::Value

Creates a DuckDB::Value of INTERVAL type. Unlike the other temporal creators, the input is strict: it must be a DuckDB::Interval.

interval = DuckDB::Interval.new(interval_months: 14, interval_days: 3, interval_micros: 12_000_000)
value = DuckDB::Value.create_interval(interval)

Parameters:

Returns:

Raises:

  • (ArgumentError) —

    if value is not a DuckDB::Interval.



388
389
390
391
392
 
# File 'lib/duckdb/value.rb', line 388

def create_interval(value)
  check_type!(value, DuckDB::Interval)

  _create_interval(value.interval_months, value.interval_days, value.interval_micros)
end

.create_list(child_type, values) ⇒ DuckDB::Value

Creates a DuckDB::Value of LIST type. The first argument is the element type: a Symbol (e.g. :integer) or a DuckDB::LogicalType. The second argument is an Array of DuckDB::Value elements.

values = [1, 2, 3].map { |i| DuckDB::Value.create_int32(i) }
list = DuckDB::Value.create_list(:integer, values)

Parameters:

Returns:

Raises:

  • (DuckDB::Error) —

    if child_type cannot be resolved to a DuckDB::LogicalType.

  • (ArgumentError) —

    if values is not an Array of DuckDB::Value.



501
502
503
504
505
 
# File 'lib/duckdb/value.rb', line 501

def create_list(child_type, values)
  check_value_array!(values)

  _create_list(DuckDB::LogicalType.resolve(child_type), values)
end

.create_map(map_type, entries) ⇒ DuckDB::Value

Creates a DuckDB::Value of MAP type. The first argument is the type spec: a one-pair Hash of key type to value type (each a Symbol or a DuckDB::LogicalType, as accepted by DuckDB::LogicalType.create_map) or a MAP DuckDB::LogicalType. The second argument is a Hash of DuckDB::Value keys to DuckDB::Value values.

entries = {
DuckDB::Value.create_varchar('a') => DuckDB::Value.create_int32(1),
DuckDB::Value.create_varchar('b') => DuckDB::Value.create_int32(2)
}
map = DuckDB::Value.create_map({ varchar: :integer }, entries)

# equivalent, with an explicit MAP logical type:
map_type = DuckDB::LogicalType.create_map(:varchar, :integer)
map = DuckDB::Value.create_map(map_type, entries)

Parameters:

Returns:

Raises:

  • (DuckDB::Error) —

    if a type in the Hash spec cannot be resolved to a DuckDB::LogicalType.

  • (ArgumentError) —

    if map_type is not a one-pair Hash or a MAP DuckDB::LogicalType, or entries is not a Hash of DuckDB::Value to DuckDB::Value.



590
591
592
593
594
595
596
597
 
# File 'lib/duckdb/value.rb', line 590

def create_map(map_type, entries)
  map_type = resolve_map_type(map_type)
  check_type!(entries, Hash)
  check_value_array!(entries.keys)
  check_value_array!(entries.values)

  _create_map(map_type, entries.keys, entries.values)
end

.DuckDB::Value.create_null ⇒ DuckDB::Value

Creates a new DuckDB::Value representing SQL NULL.

require 'duckdb'
value = DuckDB::Value.create_null

Returns:



309
310
311
312
 
# File 'ext/duckdb/value.c', line 309

static VALUE value_s_create_null(VALUE klass) {
    duckdb_value value = duckdb_create_null_value();
    return rbduckdb_value_new(value);
}

.create_struct(struct_type, values) ⇒ DuckDB::Value

Creates a DuckDB::Value of STRUCT type. The first argument is the field spec: a Hash of field name to field type (a Symbol or a DuckDB::LogicalType, as accepted by DuckDB::LogicalType.create_struct) or a STRUCT DuckDB::LogicalType. The second argument is an Array of DuckDB::Value field values, positional, matching the struct's field order.

values = [DuckDB::Value.create_int32(1), DuckDB::Value.create_varchar('x')]
struct = DuckDB::Value.create_struct({ a: :integer, b: :varchar }, values)

# equivalent, with an explicit STRUCT logical type:
struct_type = DuckDB::LogicalType.create_struct(a: :integer, b: :varchar)
struct = DuckDB::Value.create_struct(struct_type, values)

Parameters:

Returns:

Raises:

  • (DuckDB::Error) —

    if a field type in the Hash cannot be resolved to a DuckDB::LogicalType.

  • (ArgumentError) —

    if struct_type is not a Hash or a STRUCT DuckDB::LogicalType, values is not an Array of DuckDB::Value, or values.size does not match the struct's field count.



550
551
552
553
554
555
556
557
558
559
560
561
562
563
 
# File 'lib/duckdb/value.rb', line 550

def create_struct(struct_type, values)
  struct_type = DuckDB::LogicalType.create_struct(**struct_type) if struct_type.is_a?(Hash)
  check_type!(struct_type, DuckDB::LogicalType)
  raise ArgumentError, "expected STRUCT LogicalType, got #{struct_type.type}" unless struct_type.type == :struct

  check_value_array!(values)
  # The C API's duckdb_create_struct_value reads exactly child_count
  # values from the buffer with no count argument, so a size mismatch
  # here would cause an out-of-bounds read in C.
  n = struct_type.child_count
  raise ArgumentError, "expected #{n} values for STRUCT, got #{values.size}" unless values.size == n

  _create_struct(struct_type, values)
end

.create_time(value) ⇒ DuckDB::Value

Creates a DuckDB::Value of TIME type (microsecond precision). The argument is parsed leniently: a Time or a String accepted by Time.parse, matching Appender#append_time.

value = DuckDB::Value.create_time(Time.now)
value = DuckDB::Value.create_time('12:34:56.789')

Parameters:

  • value (Time, String) —

    the time value.

Returns:

Raises:

  • (ArgumentError) —

    if value cannot be parsed to a Time.



266
267
268
269
 
# File 'lib/duckdb/value.rb', line 266

def create_time(value)
  time = _parse_time(value)
  _create_time(time.hour, time.min, time.sec, time.usec)
end

.create_time_ns(value) ⇒ DuckDB::Value

Creates a DuckDB::Value of TIME_NS type (nanosecond precision). The argument is parsed leniently: a Time or a String accepted by Time.parse. Nanoseconds are preserved.

value = DuckDB::Value.create_time_ns(Time.now)
value = DuckDB::Value.create_time_ns('12:34:56.123456789')

Parameters:

  • value (Time, String) —

    the time value.

Returns:

Raises:

  • (ArgumentError) —

    if value cannot be parsed to a Time.



281
282
283
284
 
# File 'lib/duckdb/value.rb', line 281

def create_time_ns(value)
  time = _parse_time(value)
  _create_time_ns(time.hour, time.min, time.sec, time.nsec)
end

.create_time_tz(value) ⇒ DuckDB::Value

Creates a DuckDB::Value of TIMETZ type (time with UTC offset). The argument is parsed leniently: a Time (the offset is taken from the Time) or a String accepted by Time.parse.

value = DuckDB::Value.create_time_tz(Time.now)
value = DuckDB::Value.create_time_tz('12:34:56.789012+05:30')

Parameters:

  • value (Time, String) —

    the time value.

Returns:

Raises:

  • (ArgumentError) —

    if value cannot be parsed to a Time.



296
297
298
299
300
 
# File 'lib/duckdb/value.rb', line 296

def create_time_tz(value)
  time = _parse_time(value)
  micros = (((((time.hour * 60) + time.min) * 60) + time.sec) * 1_000_000) + time.usec
  _create_time_tz(micros, time.utc_offset)
end

.create_timestamp(value) ⇒ DuckDB::Value

Creates a DuckDB::Value of TIMESTAMP type (microsecond precision). The argument is parsed leniently: a Time, a Date, or a String accepted by Time.parse, matching Appender#append_timestamp.

value = DuckDB::Value.create_timestamp(Time.now)
value = DuckDB::Value.create_timestamp('2026-07-12 12:34:56.789')

Parameters:

  • value (Time, Date, String) —

    the timestamp value.

Returns:

Raises:

  • (ArgumentError) —

    if value cannot be parsed to a Time.



312
313
314
315
 
# File 'lib/duckdb/value.rb', line 312

def create_timestamp(value)
  time = to_time(value)
  _create_timestamp(time.year, time.month, time.day, time.hour, time.min, time.sec, time.usec)
end

.create_timestamp_ms(value) ⇒ DuckDB::Value

Creates a DuckDB::Value of TIMESTAMP_MS type (millisecond precision). The argument is parsed leniently: a Time, a Date, or a String accepted by Time.parse. Sub-millisecond input is truncated.

value = DuckDB::Value.create_timestamp_ms(Time.now)
value = DuckDB::Value.create_timestamp_ms('2026-07-12 12:34:56.789')

Parameters:

  • value (Time, Date, String) —

    the timestamp value.

Returns:

Raises:

  • (ArgumentError) —

    if value cannot be parsed to a Time.



342
343
344
345
 
# File 'lib/duckdb/value.rb', line 342

def create_timestamp_ms(value)
  time = to_time(value)
  _create_timestamp_ms(time.year, time.month, time.day, time.hour, time.min, time.sec, time.usec)
end

.create_timestamp_ns(value) ⇒ DuckDB::Value

Creates a DuckDB::Value of TIMESTAMP_NS type (nanosecond precision). The argument is parsed leniently: a Time, a Date, or a String accepted by Time.parse. Nanoseconds are preserved.

value = DuckDB::Value.create_timestamp_ns(Time.now)
value = DuckDB::Value.create_timestamp_ns('2026-07-12 12:34:56.123456789')

Parameters:

  • value (Time, Date, String) —

    the timestamp value.

Returns:

Raises:

  • (ArgumentError) —

    if value cannot be parsed to a Time.



357
358
359
360
 
# File 'lib/duckdb/value.rb', line 357

def create_timestamp_ns(value)
  time = to_time(value)
  _create_timestamp_ns(time.year, time.month, time.day, time.hour, time.min, time.sec, time.nsec)
end

.create_timestamp_s(value) ⇒ DuckDB::Value

Creates a DuckDB::Value of TIMESTAMP_S type (second precision). The argument is parsed leniently: a Time, a Date, or a String accepted by Time.parse. Sub-second input is truncated to seconds.

value = DuckDB::Value.create_timestamp_s(Time.now)
value = DuckDB::Value.create_timestamp_s('2026-07-12 12:34:56')

Parameters:

  • value (Time, Date, String) —

    the timestamp value.

Returns:

Raises:

  • (ArgumentError) —

    if value cannot be parsed to a Time.



327
328
329
330
 
# File 'lib/duckdb/value.rb', line 327

def create_timestamp_s(value)
  time = to_time(value)
  _create_timestamp_s(time.year, time.month, time.day, time.hour, time.min, time.sec)
end

.create_timestamp_tz(value) ⇒ DuckDB::Value

Creates a DuckDB::Value of TIMESTAMP WITH TIME ZONE type. The argument is parsed leniently: a Time, a Date, or a String accepted by Time.parse. The instant is stored (as microseconds since the Unix epoch), so the input's UTC offset is honored.

value = DuckDB::Value.create_timestamp_tz(Time.now)
value = DuckDB::Value.create_timestamp_tz('2026-07-12 12:34:56.789+05:30')

Parameters:

  • value (Time, Date, String) —

    the timestamp value.

Returns:

Raises:

  • (ArgumentError) —

    if value cannot be parsed to a Time.



373
374
375
376
 
# File 'lib/duckdb/value.rb', line 373

def create_timestamp_tz(value)
  time = to_time(value)
  _create_timestamp_tz((time.to_i * 1_000_000) + time.usec)
end

.create_uhugeint(value) ⇒ DuckDB::Value

Creates a DuckDB::Value of UHUGEINT type.

value = DuckDB::Value.create_uhugeint(340_282_366_920_938_463_463_374_607_431_768_211_455)

Parameters:

  • value (Integer) —

    the integer value (0..(2**128 - 1))

Returns:

Raises:

  • (ArgumentError) —

    if value is not an Integer or out of range.



216
217
218
219
220
221
222
 
# File 'lib/duckdb/value.rb', line 216

def create_uhugeint(value)
  check_type!(value, Integer)
  check_range!(value, RANGE_UHUGEINT, 'UHUGEINT')

  lower, upper = integer_to_hugeint(value)
  _create_uhugeint(lower, upper)
end

.create_uint16(value) ⇒ DuckDB::Value

Creates a new DuckDB::Value with a UINT16 (USMALLINT) value.

require 'duckdb'
value = DuckDB::Value.create_uint16(65_535)

Parameters:

  • value (Integer) —

    the integer value (0..65535)

Returns:

Raises:

  • (ArgumentError) —

    if value is not an Integer or out of range



107
108
109
110
111
112
 
# File 'lib/duckdb/value.rb', line 107

def create_uint16(value)
  check_type!(value, Integer)
  check_range!(value, RANGE_UINT16, 'UINT16')

  _create_uint16(value)
end

.create_uint32(value) ⇒ DuckDB::Value

Creates a new DuckDB::Value with a UINT32 (UINTEGER) value.

require 'duckdb'
value = DuckDB::Value.create_uint32(4_294_967_295)

Parameters:

  • value (Integer) —

    the integer value (0..4294967295)

Returns:

Raises:

  • (ArgumentError) —

    if value is not an Integer or out of range



122
123
124
125
126
127
 
# File 'lib/duckdb/value.rb', line 122

def create_uint32(value)
  check_type!(value, Integer)
  check_range!(value, RANGE_UINT32, 'UINT32')

  _create_uint32(value)
end

.create_uint64(value) ⇒ DuckDB::Value

Creates a new DuckDB::Value with a UINT64 (UBIGINT) value.

require 'duckdb'
value = DuckDB::Value.create_uint64(18_446_744_073_709_551_615)

Parameters:

  • value (Integer) —

    the integer value (0..18446744073709551615)

Returns:

Raises:

  • (ArgumentError) —

    if value is not an Integer or out of range



137
138
139
140
141
142
 
# File 'lib/duckdb/value.rb', line 137

def create_uint64(value)
  check_type!(value, Integer)
  check_range!(value, RANGE_UINT64, 'UINT64')

  _create_uint64(value)
end

.create_uint8(value) ⇒ DuckDB::Value

Creates a new DuckDB::Value with a UINT8 (UTINYINT) value.

require 'duckdb'
value = DuckDB::Value.create_uint8(255)

Parameters:

  • value (Integer) —

    the integer value (0..255)

Returns:

Raises:

  • (ArgumentError) —

    if value is not an Integer or out of range



92
93
94
95
96
97
 
# File 'lib/duckdb/value.rb', line 92

def create_uint8(value)
  check_type!(value, Integer)
  check_range!(value, RANGE_UINT8, 'UINT8')

  _create_uint8(value)
end

.create_union(union_type, tag, member_value) ⇒ DuckDB::Value

Creates a DuckDB::Value of UNION type. The first argument is the union type: a Hash of member name to member type (as accepted by DuckDB::LogicalType.create_union) or a UNION DuckDB::LogicalType. The second argument is the member tag (String or Symbol), and the third is the member value as a DuckDB::Value of the tagged type.

value = DuckDB::Value.create_union({ num: :integer, str: :varchar }, :num, DuckDB::Value.create_int32(42))
value.to_ruby #=> 42

# equivalent, with an explicit UNION logical type:
union_type = DuckDB::LogicalType.create_union(num: :integer, str: :varchar)
value = DuckDB::Value.create_union(union_type, :num, DuckDB::Value.create_int32(42))

Parameters:

  • union_type (Hash, DuckDB::LogicalType) —

    the member spec or UNION logical type.

  • tag (String, Symbol) —

    the member tag.

  • member_value (DuckDB::Value) —

    the member value.

Returns:

Raises:

  • (ArgumentError) —

    if union_type is not a Hash or a UNION DuckDB::LogicalType, tag is not a member of the union, or member_value is not a DuckDB::Value.

  • (DuckDB::Error) —

    if member_value does not match the tagged member's type.



443
444
445
446
447
448
449
450
451
452
453
 
# File 'lib/duckdb/value.rb', line 443

def create_union(union_type, tag, member_value)
  union_type = DuckDB::LogicalType.create_union(**union_type) if union_type.is_a?(Hash)
  check_type!(union_type, DuckDB::LogicalType)
  raise ArgumentError, "expected UNION LogicalType, got #{union_type.type}" unless union_type.type == :union

  check_type!(member_value, DuckDB::Value)
  tag_index = union_type.each_member_name.find_index(tag.to_s)
  raise ArgumentError, "`#{tag}` is not a member of the union" if tag_index.nil?

  _create_union(union_type, tag_index, member_value)
end

.create_varchar(value) ⇒ DuckDB::Value

Creates a DuckDB::Value of VARCHAR type.

value = DuckDB::Value.create_varchar('hello')

Parameters:

  • value (String) —

    the string value.

Returns:

Raises:

  • (ArgumentError) —

    if value is not a String.



175
176
177
178
179
 
# File 'lib/duckdb/value.rb', line 175

def create_varchar(value)
  check_type!(value, String)
  check_utf8_compatible!(value)
  _create_varchar(value)
end

Instance Method Details

#list_child(index) ⇒ DuckDB::Value

Returns the element at the specified index (0-based) of a LIST value as a DuckDB::Value. Raises IndexError if the index is out of range or the value is not a LIST.

require 'duckdb'
child_type = DuckDB::LogicalType.resolve(:integer)
values = [1, 2, 3].map { |i| DuckDB::Value.create_int32(i) }
list = DuckDB::Value.create_list(child_type, values)
list.list_child(0) # => DuckDB::Value

Returns:



442
443
444
445
446
447
448
449
 
# File 'ext/duckdb/value.c', line 442

static VALUE value_list_child(VALUE self, VALUE vidx) {
    duckdb_value child = duckdb_get_list_child(rbduckdb_get_struct_value(self)->value, (idx_t)NUM2ULL(vidx));

    if (child == NULL) {
        rb_raise(rb_eIndexError, "list index out of range (or the value is not a LIST)");
    }
    return rbduckdb_value_new(child);
}

#list_size ⇒ Integer

Returns the number of elements of a LIST value.

require 'duckdb'
child_type = DuckDB::LogicalType.resolve(:integer)
values = [1, 2, 3].map { |i| DuckDB::Value.create_int32(i) }
list = DuckDB::Value.create_list(child_type, values)
list.list_size # => 3

Returns:

  • (Integer) 


424
425
426
 
# File 'ext/duckdb/value.c', line 424

static VALUE value_list_size(VALUE self) {
    return ULL2NUM(duckdb_get_list_size(rbduckdb_get_struct_value(self)->value));
}

#map_key(index) ⇒ DuckDB::Value

Returns the key at the specified index (0-based) of a MAP value as a DuckDB::Value. Raises IndexError if the index is out of range or the value is not a MAP.

require 'duckdb'
map_type = DuckDB::LogicalType.create_map(:varchar, :integer)
keys = [DuckDB::Value.create_varchar('a')]
values = [DuckDB::Value.create_int32(1)]
map = DuckDB::Value.create_map(map_type, keys, values)
map.map_key(0) # => DuckDB::Value

Returns:



506
507
508
509
510
511
512
513
 
# File 'ext/duckdb/value.c', line 506

static VALUE value_map_key(VALUE self, VALUE vidx) {
    duckdb_value child = duckdb_get_map_key(rbduckdb_get_struct_value(self)->value, (idx_t)NUM2ULL(vidx));

    if (child == NULL) {
        rb_raise(rb_eIndexError, "map index out of range (or the value is not a MAP)");
    }
    return rbduckdb_value_new(child);
}

#map_size ⇒ Integer

Returns the number of entries of a MAP value.

require 'duckdb'
map_type = DuckDB::LogicalType.create_map(:varchar, :integer)
keys = [DuckDB::Value.create_varchar('a')]
values = [DuckDB::Value.create_int32(1)]
map = DuckDB::Value.create_map(map_type, keys, values)
map.map_size # => 1

Returns:

  • (Integer) 


487
488
489
 
# File 'ext/duckdb/value.c', line 487

static VALUE value_map_size(VALUE self) {
    return ULL2NUM(duckdb_get_map_size(rbduckdb_get_struct_value(self)->value));
}

#map_value(index) ⇒ DuckDB::Value

Returns the value at the specified index (0-based) of a MAP value as a DuckDB::Value. Raises IndexError if the index is out of range or the value is not a MAP.

require 'duckdb'
map_type = DuckDB::LogicalType.create_map(:varchar, :integer)
keys = [DuckDB::Value.create_varchar('a')]
values = [DuckDB::Value.create_int32(1)]
map = DuckDB::Value.create_map(map_type, keys, values)
map.map_value(0) # => DuckDB::Value

Returns:



530
531
532
533
534
535
536
537
 
# File 'ext/duckdb/value.c', line 530

static VALUE value_map_value(VALUE self, VALUE vidx) {
    duckdb_value child = duckdb_get_map_value(rbduckdb_get_struct_value(self)->value, (idx_t)NUM2ULL(vidx));

    if (child == NULL) {
        rb_raise(rb_eIndexError, "map index out of range (or the value is not a MAP)");
    }
    return rbduckdb_value_new(child);
}

#struct_child(index) ⇒ DuckDB::Value

Returns the field at the specified index (0-based) of a STRUCT value as a DuckDB::Value. Raises IndexError if the index is out of range or the value is not a STRUCT.

require 'duckdb'
struct_type = DuckDB::LogicalType.create_struct(a: :integer, b: :varchar)
values = [DuckDB::Value.create_int32(1), DuckDB::Value.create_varchar('x')]
struct = DuckDB::Value.create_struct(struct_type, values)
struct.struct_child(0) # => DuckDB::Value

Returns:



465
466
467
468
469
470
471
472
 
# File 'ext/duckdb/value.c', line 465

static VALUE value_struct_child(VALUE self, VALUE vidx) {
    duckdb_value child = duckdb_get_struct_child(rbduckdb_get_struct_value(self)->value, (idx_t)NUM2ULL(vidx));

    if (child == NULL) {
        rb_raise(rb_eIndexError, "struct index out of range (or the value is not a STRUCT)");
    }
    return rbduckdb_value_new(child);
}

#to_ruby ⇒ Object

Converts the DuckDB::Value to a Ruby object. Scalar types are converted to their natural Ruby classes. LIST and ARRAY values are converted to Array recursively. STRUCT and MAP values are converted to Hash recursively (STRUCT keys are Symbols; MAP keys keep their natural Ruby type). ENUM values are converted to the member String. UNION values are converted to the member's Ruby value. BIT values are converted to a String of '0'/'1' characters. BIGNUM values are converted to Integer. BLOB values are converted to a BINARY-encoded String. DECIMAL values are converted to BigDecimal. NULL is converted to nil. Returns nil for unsupported types.

require 'duckdb'
child_type = DuckDB::LogicalType.resolve(:integer)
values = [1, 2, 3].map { |i| DuckDB::Value.create_int32(i) }
list = DuckDB::Value.create_list(child_type, values)
list.to_ruby # => [1, 2, 3]

Returns:

  • (Object) 


762
763
764
 
# File 'ext/duckdb/value.c', line 762

static VALUE value_to_ruby(VALUE self) {
    return rbduckdb_duckdb_value_to_ruby(rbduckdb_get_struct_value(self)->value);
}